Android Use

让 Codex 通过 ADB 和 UI Automator 操作 Android 手机。首版支持设备诊断与选择、READY 验收、应用查找与启动、控件树、截图、点击、滑动、Unicode 输入、Home/返回/多任务、已知步骤批处理、停止和重连。

手机屏幕面板首版约每秒刷新一次截图，不是视频流。画面与控制都通过本机 ADB；不需要 root 或 Apple 开发团队。需要 Android SDK Platform Tools、Python 3.10+，以及手机已开启 USB 调试并授权电脑。初次连接由固定版本 uiautomator2 推送测试执行 jar。

安装

sh scripts/install.sh

安装使用独立 Python 环境，注册本地 marketplace、插件及同名 MCP。重连聊天后说「配置 Android Use，连接我的手机直到 ready=true，再打开屏幕」。本地路径如果移动，需要从新位置重跑安装脚本。多个设备时明确选择一个 serial。

依赖版本固定在 requirements.lock，UI 构建依赖固定在 ui/package-lock.json。正常使用不用重新编译 UI；开发时执行 npm ci --prefix ui，再 npm run build --prefix ui。

停止与重连

「停止 Android Use」禁用本插件并停止当前进程拥有的 UI Automator，保留配置；不会杀掉共享 ADB 服务、卸载 App 或撤销授权。「重新连接 Android Use」复用设备配置启动并重新验证 READY。拔线、关闭 USB 调试或撤销授权也会断开；恢复后重新 READY。

本机数据位于 ~/.local/share/android-use：设备选择、连接开关、暂停状态、观察截图。代码不包含设备标识，不发送使用统计。密码、解锁和认证由用户亲自在手机完成；认证接管期间暂停预览及手机工具。

验证与限制

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python server/android_use.py --tool aua_doctor
npm run check --prefix ui
npm run build --prefix ui

单元测试和 MCP 协议测试不证明真机可用；实际需要连接设备后取得 ready=true，并在真机验证应用启动、中文输入、截图、Home/多任务、停止与重连。安全窗口可能不允许截图，自绘界面可能没有完整控件树，部分厂商还需要开启额外 USB 调试安全设置。多任务卡片数量不代表实际运行进程数量。

工具前缀为 aua_。CLI 入口共享同一配置与操作锁，适合诊断；CLI 退出关闭自己启动的服务，持续操作应使用长驻 MCP。

参考：Android ADB、UI Automator、uiautomator2。

许可

本项目采用 MIT License，Copyright (c) 2026 ebwood。第三方依赖遵循各自的许可证。