CLI 与 AI Agent
你已经在电脑上使用 Agent,现在也让它用上你的 iPhone。 Manina AI CLI(esp32agent)通过蓝牙或家里的 Wi-Fi 连接插在手机上的小板子。Agent 可以截图、点按、滑动和输入,再看一眼屏幕,确认操作结果。
Claude Code、Codex 可以通过 MCP 接入;能执行本地命令或使用本地 stdio MCP 的其他 Agent 也可以接入。Agent 在电脑上思考,板子接收 iPhone 的屏幕镜像,并作为鼠标和键盘执行动作。
Manina AI CLI 以 MIT 许可开源:github.com/onehumanbeing/esp32-iphone-agent,代码在 release-1.0 分支的 cli/ 目录。
看一个真实任务
Section titled “看一个真实任务”这个例子里,Claude Code 在 iPhone 上打开 Chrome 无痕模式,进入 Google Maps 网页,搜索纽约 East Broadway 地铁站附近的咖啡店。它读取真实屏幕,逐步操作完成任务。
连接完成后,可以把同一个任务交给你的 Agent:
用 esp32agent 操作我的 iPhone,打开 Chrome 无痕模式,进入 Google Maps 网页,查找纽约 East Broadway 地铁站附近的咖啡店。每做一步都重新截图检查,看到地图和咖啡店结果后停止。
先完成准备板子,再跟着这段视频安装 CLI、连接你的 Agent。
一次安装,交给你的 Agent
Section titled “一次安装,交给你的 Agent”Manina AI CLI 0.1.2 已发布,支持 macOS、Linux 和 Windows。板子需要固件 v0.2.2 或更新版本(Wi-Fi 通道需要 v0.2.3),可在安装页的 TestFlight 渠道安装;正式版 0.2.1 固件不含 CLI 连接。
macOS 或 Linux
Section titled “macOS 或 Linux”curl -fsSL https://manina.ai/install.sh | shWindows PowerShell
Section titled “Windows PowerShell”irm https://manina.ai/install.ps1 | iexnpm install -g esp32agentnpm 包需要 Node.js 18 或更高版本,会为你的系统下载同一个发布版本。
| 变量 | 作用 |
|---|---|
ESP32AGENT_VERSION |
安装指定版本,例如 0.1.0。默认安装最新版本。 |
ESP32AGENT_BIN_DIR |
esp32agent 的安装目录。默认 ~/.local/bin(Windows 为 ~\.local\bin)。 |
curl -fsSL https://manina.ai/install.sh | ESP32AGENT_VERSION=0.1.0 ESP32AGENT_BIN_DIR=/usr/local/bin sh安装器会先校验下载文件的 SHA-256,再安装。
esp32agent upgrade --check # 当前版本和最新版本esp32agent upgrade # 安装最新发布版本电脑需要支持蓝牙。截图还需要 ffmpeg,安装器可以提示使用系统的包管理器安装。按提示完成后,如果终端找不到 esp32agent,请重新打开终端;Shell 安装器默认使用 ~/.local/bin,这个目录需要在 PATH 中。
1. 找到并配对板子
Section titled “1. 找到并配对板子”按硬件购买指南选择支持的板子,并接好天线。从安装页的 TestFlight 渠道安装固件 v0.2.3;Manina AI CLI 找不到运行 0.2.1 的板子。
配对不需要 iPhone App。 把板子插到 iPhone 上,打开电脑蓝牙,让电脑靠近手机和板子。电脑可以继续使用原来的网络上网。
能使用本地终端的 Agent,可以自己找板子并配对。直接告诉它:
在本机终端帮我设置 esp32agent。我的板子是固件 v0.2.3。扫描我的板子,必要时配对;帮我找到板子热点密码(https://manina.ai/zh/docs/faq#板子-wi-fi-密码哪里看),再指导我在手机上连接板子 Wi-Fi、开启屏幕镜像和辅助触控。截图确认连接并校准指针;找到多块板子时先问我选哪块。
也可以手动运行:
esp32agent devicesesp32agent pair只有一块板子时,pair 会自己发现并完成配对,不需要先到电脑的系统蓝牙设置里配对。找到多块板子时,使用 devices 返回的标识指定设备:esp32agent pair --device <id>。
首次配对需要在板子上电后三分钟内运行 pair。超过窗口时,重新插拔板子,再试一次。
2. 连接 Wi-Fi 并开启屏幕镜像
Section titled “2. 连接 Wi-Fi 并开启屏幕镜像”板子热点名(ESP32Agent-…)和密码可以在 ESP32 Agent App 里查看,或通过 USB 串口读取,见板子 Wi-Fi 密码哪里看。固件为 v0.2.3 时,也可以用 esp32agent net 查看。
然后在 iPhone 上操作:
- 打开设置 → 无线局域网,使用板子的热点名和密码连接。
- 打开控制中心 → 屏幕镜像 → ESP32 Agent。
- 开启设置 → 辅助功能 → 触控 → 辅助触控,保持指针可见、手机解锁并竖屏。
手机通过板子的 Wi-Fi 传输镜像,电脑通过蓝牙连接板子。板子重启后,需要让手机重新连接 Wi-Fi,再开启屏幕镜像。
可选:让板子连家里的 Wi-Fi
Section titled “可选:让板子连家里的 Wi-Fi”板子和电脑在同一个 Wi-Fi 下时,CLI 的命令和画面都走 Wi-Fi:截图几乎实时,点按也不会排在画面后面。蓝牙保持连接,作为备用通道。
esp32agent net join它会询问 Wi-Fi 名称和密码(密码不显示),通过已配对的蓝牙会话发给板子,并逐步提示:让 iPhone 连上同一个 Wi-Fi,再重新打开屏幕镜像到 ESP32 Agent。esp32agent net 显示当前用的是哪条通道(via: wifi 或 ble);esp32agent net hotspot 让板子切回自己的热点。电脑直接连上板子的热点,也会走 Wi-Fi 通道。
需要 CLI 0.1.2,以及板子固件 v0.2.3(安装页的 TestFlight 渠道)。固件仍是 v0.2.2 时,CLI 继续走蓝牙。
检查当前画面并校准:
esp32agent device infoesp32agent screenshotesp32agent calibrate截图命令会在电脑上保存 PNG,并返回 filePath。打开图片,确认是手机的当前画面。指针由 CLI 自己测量;缺少校准数据时,首次指针操作也会自动校准。
画面没有更新时,断开屏幕镜像后重新连接。配对失败时,检查天线并把电脑移近。
3. 接入你的 Agent
Section titled “3. 接入你的 Agent”先在终端完成首次配对,或把上面的请求交给能使用本地终端的 Agent。MCP 提供手机操作工具,首次找板子和配对需要通过终端完成。
Claude Code
Section titled “Claude Code”安装 Manina AI 插件,一步装好 MCP 服务和 Skill。在 Claude Code 里运行:
/plugin marketplace add onehumanbeing/esp32-iphone-agent/plugin install esp32agent@handsy也可以手动设置:先添加本地 MCP 服务,再安装 CLI 附带的 Claude Skill。
claude mcp add esp32agent -- esp32agent mcpesp32agent skill installSkill 安装到 ~/.claude/skills/esp32agent/,提供手机操作流程与命令说明;MCP 提供实际工具。
把同一个 MCP 服务添加到 Codex:
codex mcp add esp32agent -- esp32agent mcpDeepSeek Harness
Section titled “DeepSeek Harness”安装插件,同样包含这个 MCP 服务器和 handsy 技能:
dsh plugin --profile web add dsh-esp32agent重启 dsh web,再给它一个小任务。完整步骤见 DeepSeek Harness,插件源码见 integrations/dsh。
其他 Agent
Section titled “其他 Agent”使用 esp32agent mcp 作为本地 stdio MCP 服务,或让 Agent 直接调用 CLI。Agent 需要能使用这台电脑的蓝牙并读取保存的截图;无法访问这台电脑的远程 Agent,不能自行连接板子。
Skill 也发布在 ClawHub(handsy);MCP 服务已收录于 MCP Registry,名称 io.github.onehumanbeing/esp32agent(npm 包 esp32agent)。Skill 文件采用 MIT-0 协议,仓库其余部分保持原协议。
想把设置任务直接交给 Agent,可以到首页的 CLI 入口复制提示词。Agent 安装指南也提供了纯 Markdown 的安装和验证步骤。
4. 先给它一个小任务
Section titled “4. 先给它一个小任务”在 Agent 中试试:
用 esp32agent 先截取我的 iPhone 屏幕,打开设置,进入无线局域网。每做一步都重新截图检查结果。看到无线局域网页面后停止。
让 Agent 按看屏幕 → 执行一步 → 再看屏幕的节奏操作。第一次运行时在旁观察,走偏了就中断 Agent。更长的任务可以说明目标位置,以及怎样才算完成。
CLI 提供操作能力,电脑上的 Agent 提供推理和 AI 服务。手机 App 内的免费 AI 服务是另一种使用 Manina AI 的方式。
下面是单步操作示例。点按、滑动前先从最新截图选择坐标;坐标使用原始截图的像素。
esp32agent screenshotesp32agent io tap 200,400esp32agent io swipe 200,800,200,300esp32agent io text 'hello'esp32agent io keys enteresp32agent io button HOME中文输入使用手机上的拼音键盘,并需要选择正确候选词。先启用拼音键盘,再让 Agent 检查屏幕上的实际输入结果。
每个命令都输出 JSON:成功是 {"status":"ok","data":...};失败是 {"status":"error","error":"..."},退出码为 1。
| 命令 | 作用 |
|---|---|
devices |
附近的板子。 |
pair、unpair |
配对这台电脑(插上板子三分钟内),或在这台电脑上忘记板子。 |
screenshot [--format png|jpeg] [--quality N] [--scale F] [--max-size N] [--output PATH|-] |
上一个动作稳定后的画面。默认保存到当前目录。 |
io tap X,Y [--aim] [--count N] |
按截图像素点按。--aim 先找到指针再精确点按;--count 2 是双击。 |
io longpress X,Y [--duration MS] |
长按。 |
io swipe X1,Y1,X2,Y2 |
滑动。 |
io text 'TEXT' |
输入 ASCII 文本,中文以拼音输入。 |
io keys COMBO |
enter、esc、tab、backspace、space、方向键、cmd+a、shift+tab 等。 |
io button HOME |
回到主屏幕。HOME 是唯一的按键。 |
screencapture --format h264|mjpeg |
把实时视频输出到 stdout,例如 | ffplay -。 |
device info |
板子状态:镜像、画面是否冻结、App 是否正在使用手机、USB、蓝牙。 |
calibrate |
测量指针。第一次点按时会自动执行。 |
net |
CLI 当前的通道(via:ble 或 wifi)和板子的 Wi-Fi。 |
net join [SSID [PASSWORD]] |
让板子连你的 Wi-Fi;不带参数时会询问名称和密码。 |
net hotspot |
让板子切回自己的热点。 |
net via auto|ble |
ble 让 CLI 保持走蓝牙(也可设 ESP32AGENT_TRANSPORT=ble)。 |
history list、history show RUN|latest、history new |
在手机上做过什么:最近的运行、某次运行的步骤,或开始新的运行。 |
intent list、intent show NAME |
已保存的意图。 |
intent save --name N --prompt P [--hint H ...] [--from-run RUN [--steps 1,3,4]] |
保存意图,可以带上某次运行中可回放的步骤。 |
intent delete NAME |
删除意图。 |
intent export NAME... [--screenshots] [--output FILE] |
生成 iPhone App 可以导入的 .esp32intent 文件。 |
intent import FILE |
导入来自 App 或 export 的 .esp32intent 文件。 |
report --intent NAME [--screenshots] |
准备一封附带脱敏意图的邮件发给开发者。需要交互,由你自己发送。 |
logs [--board] [--save] [--output F] |
CLI 日志;--board 是板子自己的日志;--save 打包成一个文件给支持团队。见下文。 |
upgrade [--check] [--force] |
安装最新发布版本。 |
mcp |
stdio MCP 服务。 |
skill install |
把 Agent Skill 安装到 ~/.claude/skills/esp32agent/。 |
daemon [stop]、version |
后台进程(会自动启动),以及 CLI 版本。 |
附近有多块板子时,加 --device <id>,或设置 ESP32AGENT_DEVICE。
MCP 工具
Section titled “MCP 工具”esp32agent mcp 提供这些工具:screenshot、tap、longpress、swipe、type_text、press_key、press_button、device_info、history、intent_list、intent_show 和 intent_save。配对和 report 只能在终端里使用。
第一个命令会启动后台的 esp32agent daemon,由它保持蓝牙连接;它会在 CLI 的设置目录里写 daemon.log,文件变大后自动滚动。
esp32agent logs # CLI 日志的最后几行esp32agent logs --board # 板子自己的日志(固件 0.2.3 及以后)esp32agent logs --save # CLI 日志、板子日志和板子状态,合成一个文件esp32agent logs --save --output manina-logs.txt--save 会写一个文本文件并打印路径,把它发到 [email protected]。CLI 不会自己发送任何内容。需要在 daemon.log 里记录更多细节时,设置 ESP32AGENT_DEBUG=1:它会记录每条命令的名称、结果和耗时,但不记录输入的文字、截图或按键。
- App 优先。iPhone App 操作手机时,以及结束后约 20 秒内,指针和键盘命令会失败并提示
busy: the app is using the phone。等一会儿再试。 - 走蓝牙时画面慢。截图可能比实际画面慢约一秒,动画不连贯;能用 Wi-Fi 通道时尽量用。
- 不能直接打开或安装 App。CLI 不能直接打开 App,请让 Agent 通过主屏幕或搜索进入。
- 没有音量键和电源键。HOME 是唯一的硬件按键。
- 只能输入 ASCII,每个字符一次按键,不能访问剪贴板。
App 和 CLI 轮流使用
Section titled “App 和 CLI 轮流使用”App 正在执行的操作优先,可能会中断 CLI 连接。开始 CLI 任务前先停止 App 任务;CLI 提示板子忙时,等一会儿再试。切换后画面停止更新,就重新开启屏幕镜像,再截图确认。
CLI 的历史记录保存在电脑上,可以用 esp32agent history show latest 查看最近一次运行。意图文件(.esp32intent)可以导出,通过「文件」或 AirDrop 在电脑与 App 之间传递。
截图可能会发送到电脑 Agent 使用的模型服务。操作个人账号或含个人信息的页面前,请查看 Agent 的权限、模型服务的数据政策,以及 Manina AI 的隐私政策。
