boheastill/phone-eye

Phone-Eye 📱👁️

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

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

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

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

| 你要提供 | 一次性还是每次? | 难度? |
|---|---|---|
| 一台开了 USB 调试的安卓手机 | 一次性,约 60 秒(连点"版本号"7 次→打开 USB 调试) | 简单,下面有分步指引 |
| 插一次 USB 线 | 一次性——之后工具把手机切成 Wi-Fi 模式,线可以永久收起来(恢复出厂才需要再来一次) | 零难度 |
| 一台装了 Python 3.10+ 和 git 的电脑(或者只用 Docker,见第 3 步) | — | — |
| 一个会看图的模型 | 一次配置——任选其一:• OpenAI 的 API key(或任何 OpenAI 兼容:GLM、DeepSeek、本地 llama.cpp/Ollama…)• 你已有的 MCP 视觉服务器 | 一个环境变量,大多数人手上就有 key |

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

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

| ✅ 稳定 | ⚠️ 能用但有保留 | ❌ 不可能(所有同类工具都一样) |
|---|---|---|
| 看屏幕(截图+读懂它) | 锁屏可以"读"但不能"操作" | 你自己没开 USB 调试的全新手机,任何工具都摸不到 |
| 点击 / 滑动 / 输入 | 输入只支持 ASCII(中文要走剪贴板方案——adb 的已知限制) | 新电脑密钥第一次弹出的"允许 USB 调试?"——那一下必须你自己点 |
| Wi-Fi adb 断线自动重连 | 部分厂商 ROM 限制锁屏下的输入(如 MIUI) | iOS——另一个宇宙 |
| 7×24 无人值守;计划外弹窗由你的 agent 读懂并处理 | 视觉质量取决于你带来的模型 | |
| 多手机(每台手机一个 phone-eye 进程,各设 ANDROID_SERIAL) | | |

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=                    # OpenAI / GLM / 任何兼容
(可选: PHONE_EYE_VISION_BASE_URL, PHONE_EYE_VISION_MODEL)
本地离线: ..._API_KEY=sk-noauth ..._BASE_URL=http://:8080/v1 ..._MODEL=

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=","phone-eye"] }

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

出问题了怎么办

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

工具一览

| 工具 | 干什么 |
|---|---|
| phone_look(question?) | 问视觉模型"屏幕现在什么样";融合 UI 树拿到精确文字/按钮坐标 |
| phone_tap(x, y) | 点击 |
| phone_swipe(x1, y1, x2, y2, ms?) | 滑动 |
| phone_type(text) | 输入 ASCII 文本 |
| phone_key(key) | 按硬件键——wake 唤醒睡着的手机(无人值守刚需),back/home/recents 导航 |
| phone_intent(action, uri?, component?) | 按 Android intent 直达任意页面(系统深页/应用页),无需坐标 |
| phone_screenshot() | 截图存盘,返回路径 |

示例

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

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

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

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

许可

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