CLI 与 AI Agent
你已经在电脑上使用 Agent，现在也让它用上你的 iPhone。 Handsy CLI（esp32agent）通过蓝牙连接插在手机上的小板子。Agent 可以截图、点按、滑动和输入，再看一眼屏幕，确认操作结果。
Claude Code、Codex 可以通过 MCP 接入；能执行本地命令或使用本地 stdio MCP 的其他 Agent 也可以接入。Agent 在电脑上思考，板子接收 iPhone 的屏幕镜像，并作为鼠标和键盘执行动作。
看一个真实任务
Section titled “看一个真实任务”这个例子里，Claude Code 在 iPhone 上打开 Chrome 无痕模式，进入 Google Maps 网页，搜索纽约 East Broadway 地铁站附近的咖啡店。它读取真实屏幕，逐步操作完成任务。
连接完成后，可以把同一个任务交给你的 Agent：
用 esp32agent 操作我的 iPhone，打开 Chrome 无痕模式，进入 Google Maps 网页，查找纽约 East Broadway 地铁站附近的咖啡店。每做一步都重新截图检查，看到地图和咖啡店结果后停止。
一次安装，交给你的 Agent
Section titled “一次安装，交给你的 Agent”CLI 的公开下载正在准备中。 下面是发布后的一键安装入口；目前这些入口的安装脚本、npm 包和配套板子固件尚未公开可用。
macOS 或 Linux
Section titled “macOS 或 Linux”curl -fsSL https://handsy.tech/install.sh | shWindows PowerShell
Section titled “Windows PowerShell”irm https://handsy.tech/install.ps1 | iex使用 npm
Section titled “使用 npm”npm i -g esp32agent电脑需要支持蓝牙。截图还需要 ffmpeg，安装器可以提示使用系统的包管理器安装。按提示完成后，如果终端找不到 esp32agent，请重新打开终端；Shell 安装器默认使用 ~/.local/bin，这个目录需要在 PATH 中。
1. 找到并配对板子
Section titled “1. 找到并配对板子”按硬件购买指南选择支持的板子，并接好天线。本流程使用即将提供的固件 v0.2.2 与配套新版 CLI，包括新增的 wifi 命令。这些版本正在准备中，当前浏览器安装器尚不代表已经提供配套版本。
不需要进入 iPhone App。 把板子插到 iPhone 上，打开电脑蓝牙，让电脑靠近手机和板子。电脑可以继续使用原来的网络上网。
能使用本地终端的 Agent，可以自己找板子并配对。直接告诉它：
在本机终端帮我设置 esp32agent。先确认配套 CLI 和固件 v0.2.2 已可用，再扫描我的板子，必要时配对，运行 esp32agent wifi，然后指导我在手机上连接板子 Wi-Fi、开启屏幕镜像和辅助触控。截图确认连接并校准指针；找到多块板子时先问我选哪块。不需要打开 iPhone App。
也可以手动运行：
esp32agent devicesesp32agent pair只有一块板子时，pair 会自己发现并完成配对，不需要先到电脑的系统蓝牙设置里配对。找到多块板子时，使用 devices 返回的标识指定设备：esp32agent pair --device <id>。
首次配对需要在板子上电后三分钟内运行 pair。超过窗口时，重新插拔板子，再试一次。
2. 连接 Wi-Fi 并开启屏幕镜像
Section titled “2. 连接 Wi-Fi 并开启屏幕镜像”使用固件 v0.2.2 和配套新版 CLI时，配对成功后读取热点信息：
esp32agent wifi这个即将提供的命令通过已配对的加密蓝牙会话，读取热点名（ESP32Agent-…）和密码，只读、不修改配置。App 正在操作板子时，请等它空闲后再试。
然后在 iPhone 上操作：
- 打开设置 → 无线局域网，使用终端显示的热点名和密码连接板子。
- 打开控制中心 → 屏幕镜像 → ESP32 Agent。
- 开启设置 → 辅助功能 → 触控 → 辅助触控，保持指针可见、手机解锁并竖屏。
手机通过板子的 Wi-Fi 传输镜像，电脑仍通过蓝牙连接板子。板子重启后，需要让手机重新连接 Wi-Fi，再开启屏幕镜像。
检查当前画面并校准：
esp32agent device infoesp32agent screenshotesp32agent calibrate截图命令会在电脑上保存 PNG，并返回 filePath。打开图片，确认是手机的当前画面。指针由 CLI 自己测量；缺少校准数据时，首次指针操作也会自动校准。
画面没有更新时，断开屏幕镜像后重新连接。配对失败时，检查天线并把电脑移近。使用尚无 wifi 命令的旧版本时，见板子 Wi-Fi 密码哪里看。
3. 接入你的 Agent
Section titled “3. 接入你的 Agent”先在终端完成首次配对，或把上面的请求交给能使用本地终端的 Agent。MCP 提供手机操作工具，首次找板子和配对需要通过终端完成。
Claude Code
Section titled “Claude Code”添加本地 MCP 服务：
claude mcp add esp32agent -- esp32agent mcp也可以安装 CLI 附带的 Claude Skill：
esp32agent skill installSkill 安装到 ~/.claude/skills/esp32agent/，提供手机操作流程与命令说明；MCP 提供实际工具。
把同一个 MCP 服务添加到 Codex：
codex mcp add esp32agent -- esp32agent mcp其他 Agent
Section titled “其他 Agent”使用 esp32agent mcp 作为本地 stdio MCP 服务，或让 Agent 直接调用 CLI。Agent 需要能使用这台电脑的蓝牙并读取保存的截图；无法访问这台电脑的远程 Agent，不能自行连接板子。
想把设置任务直接交给 Agent，可以到首页的 CLI 入口复制提示词。Agent 安装指南也提供了纯 Markdown 的安装和验证步骤。
4. 先给它一个小任务
Section titled “4. 先给它一个小任务”在 Agent 中试试：
用 esp32agent 先截取我的 iPhone 屏幕，打开设置，进入无线局域网。每做一步都重新截图检查结果。看到无线局域网页面后停止。
让 Agent 按看屏幕 → 执行一步 → 再看屏幕的节奏操作。第一次运行时在旁观察，走偏了就中断 Agent。更长的任务可以说明目标位置，以及怎样才算完成。
CLI 提供操作能力，电脑上的 Agent 提供推理和 AI 服务。手机 App 内的免费 AI 服务是另一种使用 Handsy 的方式。
下面是单步操作示例。点按、滑动前先从最新截图选择坐标；坐标使用原始截图的像素。
esp32agent screenshotesp32agent io tap 200,400esp32agent io swipe 200,800,200,300esp32agent io text 'hello'esp32agent io keys enteresp32agent io button HOME中文输入使用手机上的拼音键盘，并需要选择正确候选词。先启用拼音键盘，再让 Agent 检查屏幕上的实际输入结果。
App 和 CLI 轮流使用
Section titled “App 和 CLI 轮流使用”App 正在执行的操作优先，可能会中断 CLI 连接。开始 CLI 任务前先停止 App 任务；CLI 提示板子忙时，等一会儿再试。切换后画面停止更新，就重新开启屏幕镜像，再截图确认。
CLI 的历史记录保存在电脑上，可以用 esp32agent history show latest 查看最近一次运行。意图文件（.esp32intent）可以导出，通过「文件」或 AirDrop 在电脑与 App 之间传递。
截图可能会发送到电脑 Agent 使用的模型服务。操作个人账号或含个人信息的页面前，请查看 Agent 的权限、模型服务的数据政策，以及 Handsy 的隐私政策。