跳转到内容

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/ 目录。

这个例子里,Claude Code 在 iPhone 上打开 Chrome 无痕模式,进入 Google Maps 网页,搜索纽约 East Broadway 地铁站附近的咖啡店。它读取真实屏幕,逐步操作完成任务。

Claude Code 通过 CLI 操作真实 iPhone,在 Chrome 中打开 Google Maps,查找纽约 East Broadway 站附近的咖啡店。部分片段已加速或剪辑。

连接完成后,可以把同一个任务交给你的 Agent:

用 esp32agent 操作我的 iPhone,打开 Chrome 无痕模式,进入 Google Maps 网页,查找纽约 East Broadway 地铁站附近的咖啡店。每做一步都重新截图检查,看到地图和咖啡店结果后停止。

先完成准备板子,再跟着这段视频安装 CLI、连接你的 Agent。

Manina AI CLI 0.1.2 已发布,支持 macOS、Linux 和 Windows。板子需要固件 v0.2.2 或更新版本(Wi-Fi 通道需要 v0.2.3),可在安装页的 TestFlight 渠道安装;正式版 0.2.1 固件不含 CLI 连接。

终端窗口
curl -fsSL https://manina.ai/install.sh | sh
终端窗口
irm https://manina.ai/install.ps1 | iex
终端窗口
npm install -g esp32agent

npm 包需要 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 中。

按硬件购买指南选择支持的板子,并接好天线。从安装页的 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 devices
esp32agent pair

只有一块板子时,pair 会自己发现并完成配对,不需要先到电脑的系统蓝牙设置里配对。找到多块板子时,使用 devices 返回的标识指定设备:esp32agent pair --device <id>。

首次配对需要在板子上电后三分钟内运行 pair。超过窗口时,重新插拔板子,再试一次。

板子热点名(ESP32Agent-…)和密码可以在 ESP32 Agent App 里查看,或通过 USB 串口读取,见板子 Wi-Fi 密码哪里看。固件为 v0.2.3 时,也可以用 esp32agent net 查看。

然后在 iPhone 上操作:

  1. 打开设置 → 无线局域网,使用板子的热点名和密码连接。
  2. 打开控制中心 → 屏幕镜像 → ESP32 Agent。
  3. 开启设置 → 辅助功能 → 触控 → 辅助触控,保持指针可见、手机解锁并竖屏。

手机通过板子的 Wi-Fi 传输镜像,电脑通过蓝牙连接板子。板子重启后,需要让手机重新连接 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 info
esp32agent screenshot
esp32agent calibrate

截图命令会在电脑上保存 PNG,并返回 filePath。打开图片,确认是手机的当前画面。指针由 CLI 自己测量;缺少校准数据时,首次指针操作也会自动校准。

画面没有更新时,断开屏幕镜像后重新连接。配对失败时,检查天线并把电脑移近。

先在终端完成首次配对,或把上面的请求交给能使用本地终端的 Agent。MCP 提供手机操作工具,首次找板子和配对需要通过终端完成。

安装 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 mcp
esp32agent skill install

Skill 安装到 ~/.claude/skills/esp32agent/,提供手机操作流程与命令说明;MCP 提供实际工具。

把同一个 MCP 服务添加到 Codex:

终端窗口
codex mcp add esp32agent -- esp32agent mcp

安装插件,同样包含这个 MCP 服务器和 handsy 技能:

终端窗口
dsh plugin --profile web add dsh-esp32agent

重启 dsh web,再给它一个小任务。完整步骤见 DeepSeek Harness,插件源码见 integrations/dsh。

使用 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 的安装和验证步骤。

在 Agent 中试试:

用 esp32agent 先截取我的 iPhone 屏幕,打开设置,进入无线局域网。每做一步都重新截图检查结果。看到无线局域网页面后停止。

让 Agent 按看屏幕 → 执行一步 → 再看屏幕的节奏操作。第一次运行时在旁观察,走偏了就中断 Agent。更长的任务可以说明目标位置,以及怎样才算完成。

CLI 提供操作能力,电脑上的 Agent 提供推理和 AI 服务。手机 App 内的免费 AI 服务是另一种使用 Manina AI 的方式。

下面是单步操作示例。点按、滑动前先从最新截图选择坐标;坐标使用原始截图的像素。

终端窗口
esp32agent screenshot
esp32agent io tap 200,400
esp32agent io swipe 200,800,200,300
esp32agent io text 'hello'
esp32agent io keys enter
esp32agent 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。

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 连接。开始 CLI 任务前先停止 App 任务;CLI 提示板子忙时,等一会儿再试。切换后画面停止更新,就重新开启屏幕镜像,再截图确认。

CLI 的历史记录保存在电脑上,可以用 esp32agent history show latest 查看最近一次运行。意图文件(.esp32intent)可以导出,通过「文件」或 AirDrop 在电脑与 App 之间传递。

截图可能会发送到电脑 Agent 使用的模型服务。操作个人账号或含个人信息的页面前,请查看 Agent 的权限、模型服务的数据政策,以及 Manina AI 的隐私政策。

镜像、天线或指针问题见常见问题。仅操作自己拥有或明确获授权的设备和账号;使用范围见免责声明。