phone-harness：让Codex等AI Agent直接操控真实手机的开源工具

现在我们电脑上的 Codex、Claude Code 这类 AI agent，帮忙写代码、改文件都挺顺手了，但手机上的事它们一直插不上手，想让它帮忙在手机上点个什么都做不到。原因也不复杂，iPhone 这边的系统管得严，不让随便碰，Android 那边虽然有 adb，但太原始，大多数项目做到一半就停了。 前阵子我在 GitHub 上翻到 phone-harness 这个项目，发现它把这条路走通了。手机上什么都不用装，不用越狱，不用 Xcode，就能把电脑上的 agent 和真手机连起来，看屏幕、点按、打字都行。手机上那些重复又耗时间的操作，丢给它去跑就行，我们自己去忙别的。 今天我们来聊聊这个开源项目。 phone-harness 是什么 一句话说完：它是一个开源工具，让我们电脑上的 AI agent 直接操作一台真实手机。 作者在仓库里写的介绍也是这个意思，let your agent control your phone。 iPhone 和 Android 都支持，但两边走的路子不一样。 iPhone 用的是 macOS 自带的 iPhone 镜像功能，手机屏幕会显示成 Mac 上的一个窗口，phone-harness 截这个窗口的画面，用苹果自家的 Vision 框架做文字识别，再把点按和打字通过系统级事件发进手机里。 Android 走的是 adb，靠截屏加系统的无障碍树来读屏幕，靠 input 命令模拟手指，插数据线和走 WiFi 都可以。 它能在手机上干什么 这块内容比较多，我挑几个重要的点，一个一个说。 看得懂屏幕上有什么 agent 想操作手机，头一件事是得看得见屏幕。iPhone 这边，phone-harness 的 ocr() 会把屏幕上所有可见文字读出来，每个词都自带坐标，拿到坐标直接就能点。想点屏幕上的“设置”两个字，不用自己去算位置，一句 tap_text("设置") 就完事。 装好以后实际跑一下 ocr()，返回来的东西大概长这样：屏幕上每个词一条记录，词的内容、识别的置信度、坐标全在里面，agent 拿到这个就知道该点哪了。 Android 那边更省心，文字是系统无障碍树直接报出来的，不存在识别出错的问题，连没有文字的图标按钮，也能靠系统给的描述信息找到。 实在碰上纯图标、什么文字都没有的按钮，也有办法，screenshot() 截一张图，让有视觉能力的模型看一眼，再用 tap_image_point() 按图里的像素位置点下去，坐标换算工具自己会做，不用我们操心。 点按、打字、滑动，基本操作都全 open_app 打开应用，tap 点坐标，type_text 打字，scroll 滚动列表，swipe 左右翻页，home 回桌面，长按也有。写法和普通的 Python 脚本没什么区别，agent 拿到这些之后，就能自己把一连串操作组合起来。 官方主页放了一个演示，任务是跟 agent 说一句“帮我叫一辆 Waymo 去 Delah Coffee”，剩下的选地点、走流程，都是它在真机上自己点的。演示视频在项目 README 里也能找到，看一遍就明白它大概能做到什么程度。 我自己装好以后先试了个简单的，跟 agent 说“打开笔记，新建一条笔记，内容写 Hello World”，它就自己点开备忘录、找到新建按钮、把字打了进去，全程我没碰手机。中间每走一步它都会先读一遍屏幕，确认上一步生效了再往下走，不是闷头一通乱点，另外每个步骤都有记录。 翻列表、收信息，它能自己跑完 除了一步一步的点按，它还能自己把一个长列表从头翻到尾。比如让它把某个应用里的列表翻完，把每一项的标题整理出来，它会一边滚动一边去重，翻到底了自己停下来，最后把整理好的结果给我们。中间过程不用人盯着，我们去干别的就行。 用得越多，它越顺手 还有一个设计我觉得挺有意思，agent 在任务里摸出来的经验，比如某个应用里哪个按钮长什么样、怎么判断一步操作成没成功，可以存进仓库里的一个文件（agent-workspace 目录下的 agent_helpers.py）。 下次再碰到类似的活儿，它直接拿上次的经验用，不用从头再摸一遍，等于说它在我们自己的手机上是越用越顺手的。 iPhone 和 Android 用同一套写法 不管连的是哪种手机，上面这些函数的写法和含义完全一样，用的时候不用管底下走的是哪套方案。默认操作哪台手机，一句 phone-harness config set platform ios 或 android 就设好了。想两台都接着用也行，两套连接互不干扰，iPhone 走镜像窗口，Android 走 adb。 在后台操作，不影响你正常用电脑 这一点我觉得做得挺好，iPhone 镜像方案里，截图是按窗口抓的，点按和打字是直接投递给应用的事件，所以 agent 操作手机的时候，镜像窗口不用一直摆在最前面，我们该干嘛干嘛，不受影响。 唯一的例外是滚动，macOS 的滚动事件必须落在指针下面的窗口上，所以滚动的那一瞬间镜像窗口会跳到前面一下，滚完马上还回去。 能做的和不能做的，都写明白了 这开源项目，它的边界画得很清楚，它不会替手机输锁屏密码，手机锁着就停下来等我们解锁。给 agent 的使用守则里写明了一条：凡是发消息、买东西、删东西、改设置这类对外或者不好撤回的动作，必须先问过用户再动手。连接手机这件事也永远由用户自己做，工具连不上手机就把缺哪一步报出来，不会自己在那儿瞎重试。 我们试试让它打开淘宝，买包纸巾，看看它会不会不询问直接用我的小额免密直接付款。 做不到的事也没藏着掖着：文字识别只认字不认图标，多点触控不支持，相机和 Face ID 相关的流程走不了，有 DRM 保护的视频截出来是黑屏。 上手教程 装的过程我们自己基本不用动手，agent 会装。 作者在项目 README 里准备了一段现成的安装提示词，就是下面这段，原样复制，发给我们平时在用的编程 agent 就行，Claude Code、Codex 这类支持技能的都可以： Set up phone-harness for me. Clone https://github.com/ShawnPana/phone-harness into ~/.phone-harness, read `install.md` first, install it so `phone-harness` is a command on my PATH, and register it as an agent skill named phone-harness using `phone-harness skill` as the body. Then read `onboarding.md` and walk me through it. 不用担心是英文的，直接发就行。agent 收到之后会自己把仓库克隆到 ~/.phone-harness，读 install.md，把 phone-harness 命令装好，再注册成自己的技能，最后带着我们过一遍必须亲手做的部分。 需要亲手的就两件事： 1. iPhone 用户要先把 iPhone 镜像和手机配好对，然后在系统设置的隐私与安全性里，给终端开两个权限：辅助功能和屏幕录制。 2. Android 用户要先装一下 adb，手机上打开开发者选项和 USB 调试，插上数据线点允许。不想插线的话，Android 11 以上可以用无线调试配对一次，以后它自己就能找到手机。 都弄完跑一句 phone-harness --doctor，它会按顺序把整条链路检查一遍，哪一步缺了会直接说出来，照着补就行。 装好以后我们说一句话，它就会去读手机屏幕了，比如让它打开备忘录新建一条笔记，能看着它自己一步一步点完。环境要求不高，一台 Mac，Python 3.10 以上。 什么时候值得用它 能在电脑和网页上办的事，就别麻烦手机，它适合的是那些真的需要手机才能办的事。 • 只在手机端存在的应用和功能，不少服务只有 App 里有，网页版根本没有； • 那些和手机号、短信验证码绑定的操作，登录验证这类事在电脑上没法弄； • 做移动端开发、测试的朋友，需要真机测试，直接安排Codex操作真机做测试就行； • 一些重复性的活儿，比如每天打开某个 App 看一眼数据、截个图存下来，这种机械事交给它也合适。 我自己的感觉是，以前 agent 能操作浏览器，能操作终端，一到手机就没办法了，这个工具正好把这块补上了。 我的看法 这个项目用到的技术其实没什么新的，iPhone 镜像是苹果自己做的功能，Vision 是系统自带的识别框架，adb 是安卓官方工具，全是现成的东西。但它把这几样拼到一起，拼出来一个不用越狱、不用在手机上装任何东西的方案，这个思路我觉得是真的巧。靠系统自带能力撑起来的方案，天生就比那些靠注入、靠破解的稳，手机上也不用担心被搞出毛病。 我自己从装好到看着它完成第一个任务，中间真正动手的只有配对手机和开权限，剩下的都是 agent 自己跑的。 要说门槛也有，得有台 Mac 才能玩，iPhone 那边更是离不开 macOS 的镜像功能，这是苹果定的规矩，没什么办法。另外项目还年轻，开源到现在一个月左右，坑肯定有，用着用着碰上问题很正常。 如果工作里时不时就会遇到“这事只能在手机上弄”的情况，可以先收藏起来。 开源地址 https://github.com/ShawnPana/phone-harness