boheastill/phone-eye

Phone-Eye 📱👁️

English | 简体中文

让你的 AI 助手真正"看见"并"操作"一台真实的安卓手机。

phone_look("屏幕上是什么?登录按钮在哪?")
  → "登录按钮在 (540, 1830)——绿色 Sign in …"
phone_tap(540, 1830)
phone_look("下一页加载出来了吗?")

适配任何 MCP 客户端——Claude Code、Codex、Cursor、dsh 等。

---

你需要准备什么(大白话)

就这些。手机上不用装任何 App。不需要 root。不需要额外起服务器。

能做什么 / 不能做什么(诚实表)

60 秒规则:每台安卓需要人类的一次性时刻——开调试+授权一次。之后,手机就属于你的 agent 了,Wi-Fi 也行,电脑重启也不怕。

安装(3 步)

1. 打开 USB 调试(每台手机一次)

设置 → 关于手机 → 连点**"版本号" 7 次**(解锁开发者选项)→ 开发者选项 → 打开 USB 调试。 (卡住了?到 Discussions 报你的手机型号,我们带你走。MIUI/HyperOS 可能还要求先登录小米账号。)

2. 装 adb(如果还没有),插一次 USB,然后转无线

# macOS: brew install android-platform-tools · Ubuntu/Debian: sudo apt install adb
# Windows: scoop install adb(或下载 Android platform-tools)
adb devices          # 手机出现了?在手机弹窗上点"允许"——勾选"一律允许"
adb shell ip route   # ← 趁还插着线,记下手机的 Wi-Fi IP(如 192.168.1.23)
adb tcpip 5555       # 切到 Wi-Fi 模式(adb 会重启,USB 条目消失——正常)
adb connect 192.168.1.23:5555   # 用上面的 IP;然后拔线,永久无线

ip route 没输出?其他找手机 IP 的办法

设置 → WLAN → 你的网络 → 详情里有 IP;或 adb shell ip addr show wlan0 | grep inet。

3. 启动 phone-eye

git clone https://github.com/boheastill/phone-eye && cd phone-eye
pip install -r requirements.txt

# 眼睛——三选一:
export PHONE_EYE_VISION_API_KEY=<key>                    # OpenAI / GLM / 任何兼容
#   (可选: PHONE_EYE_VISION_BASE_URL, PHONE_EYE_VISION_MODEL)
#   本地离线: ..._API_KEY=sk-noauth ..._BASE_URL=http://<主机>:8080/v1 ..._MODEL=<你的 qwen-vl>

python server.py       # stdio MCP 服务器——接进你的客户端:

接入客户端——挑你的:

# Claude Code(最简单):
claude mcp add phone-eye -- python /path/to/phone-eye/server.py

// 任何 MCP 客户端(通用 stdio 形状):
{ "mcpServers": { "phone-eye": { "command": "python", "args": ["/path/to/phone-eye/server.py"] } } }

Docker(可选——宿主机不需要 Python)

仓库自带 Dockerfile(Python 3.12 + adb):

podman build -t phone-eye .        # 或: docker build -t phone-eye .
# 冒烟:stdout 打出 JSON-RPC initialize 回复即说明能跑:
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n' \
  | podman run --rm -i phone-eye

用 --network host 让 adb 能摸到 Wi-Fi 手机和视觉端点:

"phone-eye": { "command": "podman", "args": ["run","--rm","-i","--network","host",
  "-e","ANDROID_SERIAL=192.168.1.23:5555","-e","PHONE_EYE_VISION_API_KEY=<key>","phone-eye"] }

推荐视觉模型(任何能看图的对话模型都行):gpt-4o-mini(默认)、GLM glm-4.6v-flash(便宜)、或本地 Qwen-VL(经 llama.cpp)——截图一个字节都不出你的局域网。

出问题了怎么办

• "No Android device reachable" → 工具已经自动重连过一次了;再跑 adb connect <ip>:5555,或重新插线。
• "No vision server reachable" → 你没设 key;错误信息里有两条具体修法。
• 手机重启了 → 大多数 ROM 上 Wi-Fi adb 能活;不行就再 adb connect 一次。
• 还卡着?**开个 Discussion——我们会回,并且陪你把环境调通。**报 bug 和"我的 X 型号能用"的留言同样欢迎。

工具一览

示例

• 移动 Web QA 循环——agent 在真机上验收自己的活
• 走过 OEM 设置向导——弹什么都能视觉应对
• 表单回归检查
• 无人值守哨兵——你的 agent 值夜班:唤醒→解锁→直达→查看→存证

想了解原理、想改代码?工作原理白皮书。要以常驻 HTTP 服务跑?docs/fleet.md。

为什么叫"看"?这不就是 adb 吗?

只读 UI 树的工具看不见游戏画面、图片、无障碍树里没有的东西;只靠视觉的工具坐标会飘。phone_look 融合两者:模型回答"这是什么",UI 树给出"具体在哪"。我们 dogfood 的第一天,它发现自己屏幕上挂着一个 USB 调试授权弹窗,读出按钮坐标,自己点了"允许"——故事在这里。

许可

MIT。已在 Redmi K40 Gaming / Android 13 上验证——欢迎 PR 补充你的机型。