OpenGUI

OpenGUI 快速入门

「让 AI 真的会用你的手机」——OpenGUI（Core-Mate/OpenGUI）是一个 Android 手机 GUI Agent 框架：AI 读真实 App 界面、规划下一步、执行点击滑动等操作、返回结构化结果。可以装进 DeepSeek Harness 当插件用，也能让 Claude Code / Codex / OpenCode 一条引导命令把整套后端 + Android 客户端搭起来。2026-09-24 核验：GitHub 1,804★ / 114 fork，Trendshift Kotlin 仓库日榜 #25，最近 push 2026-09-17，TypeScript/Kotlin。

这是什么？适合谁？

OpenGUI 解决的是 phone-use AI 的工程化问题：不是靠模拟点击坐标的黑盒脚本，而是「视觉理解 → 任务规划 → 动作执行 → 复查 → 恢复」的完整 Agent 栈，通过 Android AccessibilityService API 截图与操作，配合 ADB（adb reverse 隧道），不需要 root、不改系统。

适合人群：

• 想做 Android App 自动化操作/回归测试的开发者：替代脆弱的 UI 脚本
• 研究 phone-use / GUI Agent 的工程师：完整开源参考实现
• 想让 AI 帮忙处理手机上重复操作（X、Telegram、微信、小红书等主流 App）的进阶用户

不适合谁：普通手机用户（需要完整后端部署或装 DeepSeek Harness/WorkBuddy，有门槛）；iOS 用户（仅支持 Android）。

准备工作

• 设备：Android 11（API 30）或更新版本的真机或模拟器；开启 USB 调试并授权
• 宿主环境（三选一）：
  1. DeepSeek Harness（DSH）插件路线：Node.js 22.19+ 或 24+
  2. WorkBuddy 连接器路线：macOS 公测版 0.3.1（MCP + Skill + Hooks）
  3. 完整后端路线：clone 仓库，用 pnpm 跑后端 + 构建/安装 Android 客户端 + adb 配置
• 模型：推荐 Claude Opus / Qwen / 豆包，或自带 API key（BYO API）
• 时间预算：DSH 插件路线约 10-20 分钟（一条 prompt 自动装）；完整后端路线 1-2 小时（含环境配置）
• 费用：开源免费；视觉模型调用费用取决于你选的模型（DSH 内置模型或自己的 API key）
• 前置知识：会用 adb、了解 Android USB 调试授权；完整后端路线需要 Node.js/pnpm 工具链

快速上手

第一步：选路线（以最短的 DSH 插件路线为例）

在 Codex（或兼容的 agent CLI）里粘贴这条 prompt：

Install and run the OpenGUI installer Skill from https://github.com/Core-Mate/OpenGUI/tree/main/deepseek-harness-plugin/skills/opengui-coremate-install for my DSH web profile. Install the latest stable release. Proceed autonomously, and only pause when I need to authorize or select a phone, add or select a DSH workspace, or provide fallback visual-model credentials.

每次安装都会解析最新稳定版插件，也可显式指定版本回滚。需要 Node.js 22.19+ / 24+，会自动装兼容的 DSH 版本。

第二步：连接并授权手机

安装完成后：添加/选择 DSH workspace → 用 USB 连接已开 USB 调试授权的 Android 手机 → 在 DSH 里选中它。注意：各厂商的权限名称与菜单位置不同，先照官方 docs/android-permissions.md 走完 Android 权限设置。

第三步：发出第一个任务

在 DSH 里对 OpenGUI 说：

@OpenGUI Open Settings and report the Android version

预期产出：OpenGUI 读取当前屏幕 → 规划点击路径 → 打开设置 → 读出版本号并以结构化结果返回。看到正确版本号即链路打通。

第四步：进阶——完整后端与 CLI

完整后端路线由 Claude Code / Codex / OpenCode 引导：agent 读 skill 文档、启动本地后端、构建/安装 Android 客户端、跑 adb 设置、检查手机可见性。之后可用 CLI：

pnpm opengui -- devices --json
pnpm opengui -- do "Observe the current Android screen and summarize what you see" --json

常见踩坑

1. 症状：后端连不上手机。 根因：USB 调试未授权、或 adb reverse 隧道没建立。解法：重插 USB 并在手机上确认授权弹窗；官方有专门的后端连接排障文档（2026-05-12 更新）。
2. 症状：操作无反应或界面读不懂。 根因：Android 厂商定制导致 AccessibilityService 权限入口不同。解法：按 docs/android-permissions.md 逐项核对厂商差异，别按通用教程猜。
3. 症状：任务中途失败不恢复。 根因：视觉模型太弱（规划/复查环节掉链子）。解法：换推荐的模型档位（Claude Opus / Qwen / 豆包）或配置自己的强模型 API。
4. 症状：本地 Redis/PostgreSQL 冲突导致后端起不来。 根因：完整后端依赖与机器上已有服务端口冲突。解法：官方排障指南覆盖此场景，改端口或停冲突服务。
5. 症状：WorkBuddy 装完不工作。 根因：0.3.1 是 macOS 公测预发布版，且 WorkBuddy 5.5.6 以下不支持在线安装流。解法：升级 WorkBuddy，或改用旧版的 Command-Q fallback（preflight 会提示）。
6. 症状：12 小时长任务中断。 根因：锁屏/省电模式杀后台。解法：保持亮屏充电、关掉厂商的激进省电；OpenGUI 的多角色操作员系统设计支持最长 12 小时任务，但系统层省电不在其控制范围。

权限、安全与成本边界

• 安全机制：只用 AccessibilityService（截图+操作）与 ADB（adb reverse）；不 root、不改 Android 系统；WorkBuddy 路线默认开只读 scrcpy 观察窗口
• 授权边界：操作的是你已授权的设备与 App；长任务（最长 12 小时）建议在测试机上跑
• 成本：框架免费；视觉/规划模型的 token 费用自担（BYO API 或宿主内置模型）
• 平台：仅 Android 11+；iOS 无支持

小技巧

1. 首次跑通后先用 --json 模式发「观察当前屏幕并总结」类任务，确认视觉理解质量再上复杂操作。
2. 把常用任务写成 OpenClaw/Claude Code 的 skill，配合 open-gui-remote-control Skill 从编码 agent 远程派发手机任务。
3. 有 Discord 的话可以搭官方 Discord 远程派单（支持前缀命令、斜杠命令、白名单）。
4. 回归测试场景固定机型/系统版本，权限差异是最大变量。
5. 多角色操作员系统适合把「观察/操作/复查」拆给不同模型档位，省钱且更稳。

进阶学习方向

• phone-use Agent 栈：研究 OpenGUI 的「屏幕理解 → 任务规划 → 动作执行 → 复查 → 恢复」五段式架构，对比坐标脚本方案的本质差异。
• DeepSeek Harness 插件体系：OpenGUI 的 DSH 插件（版本解析 + 显式回滚）是插件分发的干净范例。
• Claude Code 远程控制：docs/codex-remote-control.md + 本地 REST API + CLI，把手机任务嵌进编码工作流。
• 组合链路：OpenGUI（手机操作）→ Codex/Claude Code（任务编排）→ Discord（远程派单），官方文档覆盖了这条完整链路。

参考链接

• 官方仓库
• 快速开始文档
• Android 权限设置指南
• Codex/Claude Code 远程控制文档
• Trendshift 日榜