面向 Android 的移动端 GUI Agent 框架。

OpenGUI 让 AI Agent 能够看懂、理解并操作真实 Android 设备上的 App 界面。

## Demo Demo 视频即将补充。第一版 Demo 会展示 OpenGUI 在真实 Android 设备上操作真实 App，包括屏幕理解、点击、输入和返回结构化结果。 ## Quick Start 最快的试用方式，是让 Claude Code 或 Codex 帮你完成启动。 ```text Read ./skills/open-gui-bootstrap/SKILL.md and help me run OpenGUI. Only ask me for phone-side actions. ``` 你需要准备： - 一台 Android 手机或模拟器 - 已开启 USB 调试 - 已开启 AccessibilityService - 用于真实任务执行的模型 API Key OpenGUI 会使用仓库内脚本启动后端，并安装 Android 客户端： ```bash cd server ./start.sh ``` ```bash cd client ./start.sh ``` 后端和 Android 客户端都跑起来后，发送第一个任务： ```bash cd server pnpm opengui -- devices --json pnpm opengui -- do "观察当前手机屏幕，简要描述你看到了什么，然后结束" --json ``` 手动安装指南：[`docs/get-started.md`](./docs/get-started.md)。 ## 近期更新 - `[2026.5.16]` 新增 [Codex / Claude Code 远程控制](./docs/codex-remote-control.zh-CN.md)，提供本地 REST API、`pnpm opengui -- ...` CLI，以及 [`open-gui-remote-control`](./skills/open-gui-remote-control/SKILL.md) Skill，可从编码 Agent 下发 Android App 任务。 - `[2026.5.9]` 新增 [Discord IM 入口](./docs/DISCORD.zh-CN.md)，支持前缀命令、Slash 命令、安全白名单和 guild-scoped 命令注册，可从 Discord 频道远程下发 Android 任务。 - `[2026.5.7]` 本地启动流程增强，Docker 方式启动后端时会避开常见的 PostgreSQL 和 Redis 端口冲突。 - `[2026.5.1]` 后端上手流程补齐 `.env.example`、启动检查提示和 graph agent 的 VLM 环境变量配置。 ## 你可以用 OpenGUI 做什么 OpenGUI 让 AI 操作真实的 Android 手机。同一个仓库里，你可以直接做四类事情： - **操作主流 Android App**：让 AI 在真实手机上执行 X、Reddit、Hacker News、Telegram、微信、微博、小红书等移动任务。 - **运行现成工作流**：仓库已经包含可直接启动的后端、Android 客户端、待命派发链路，以及部分预置任务能力。 - **让 Claude 或 Codex 帮你跑起来**：把 [`skills/open-gui-bootstrap/SKILL.md`](./skills/open-gui-bootstrap/SKILL.md) 交给模型，直接用自然语言描述目标，让它处理安装、构建、安装 APK 和本地排障。 - **让 Codex 控制 Android App**：OpenGUI 启动后，把 [`skills/open-gui-remote-control/SKILL.md`](./skills/open-gui-remote-control/SKILL.md) 交给 Codex 或 Claude Code，用本地 CLI 列设备、下发任务并查询 execution 状态。 - **把手机当成远程 worker 使用**：通过飞书、Telegram、Discord 或 REST API 下发任务，让设备保持待命，并从后端拿回结构化结果。 - [加入 Discord 社区](https://discord.gg/pqHHw7XgJ3) ## 亮点 - **适合长时任务**：OpenGUI 面向长时移动工作流，任务可以持续运行数小时，并在过程中继续推进、复核和恢复。 - **任务能持续跑下去**：`Plan Supervisor` 维护任务列表和继续执行状态，`Executor Graph` 围绕当前设备状态运行截图、视觉分析、动作执行和 call-user 循环，`Summarizer` 在任务结束时输出结构化结果。 - **手机可以保持待命**：待命派发链路让设备可以通过飞书、Telegram、Discord 或 REST 入口接收远程任务。 - **模型可以按角色分工**：模型路由把规划侧和 VLM 执行侧拆开，便于按角色选择 provider。 - **整套系统围绕真实移动工作流组织**：graph、设备执行链路和模型分工已经在源码里落地。 ## 为什么 OpenGUI 不一样 OpenGUI 采用的是一套分层清晰的移动 operator system。当前源码里可以直接看到这些关键部分： - `server/apps/backend/src/modules/graph-agent/graph/mobile-agent.graph.ts` 主图 - `server/apps/backend/src/modules/graph-agent/graph/executor.graph.ts` 设备执行子图 - `server/apps/backend/src/common/ws/standby.gateway.ts` 待命设备派发 - `client/core_network/.../StandbySocketManager.kt` 设备待命连接 - `client/core_accessibility/.../GestureService.kt` Android 侧动作执行 | 维度 | 典型手机 Agent Demo | OpenGUI | |---|---|---| | **执行模型** | 短时交互循环 | 主图 + executor 子图 | | **任务状态** | 常常停留在本地会话里 | 任务状态由后端 graph 持有 | | **设备链路** | 常见是电脑侧驱动手机 | Android 客户端自带待命与执行连接 | | **模型使用** | 一个主模型承担大部分工作 | 规划和 VLM 执行可以拆给不同 provider | | **远程运行** | 往往是附加能力 | 飞书、Telegram、Discord、REST API、待命派发已经在后端里 | ## 典型使用场景 - 打开 X 并采集某个主题的近期内容 - 在真实手机上阅读并总结 Reddit 或 Hacker News 帖子 - 从飞书、Telegram、Discord 或 REST API 远程触发手机任务 - 在 Android 设备上执行重复性的移动工作流 - 运行需要状态管理、复核和恢复机制的长时移动工作流 ## 当前限制 - 需要 Android 真机或模拟器。 - 需要开启 USB 调试和 AccessibilityService 权限。 - 执行质量会受到模型能力、App UI、网络状态和任务长度影响。 - 目前还不是 OS 级常驻助手；任务需要手动触发，或通过已配置的派发入口触发。 - 系统设计支持长时任务，但可靠性仍需要更多真实场景测试。 - 还需要补充更多可直接运行的任务示例和 benchmark。 ## Roadmap - 补充短 Demo 视频和更多真实 App 示例。 - 优化一键本地启动流程。 - 增加更多可直接运行的 phone-use 任务模板。 - 提升执行恢复和失败反馈能力。 - 增加 Android GUI Agent 可靠性 benchmark 任务。 - 完善模型配置和省钱混用方案文档。 ## 怎么使用 OpenGUI ### 1. 用 Claude 或 Codex 帮你跑起来优先从 [`skills/open-gui-bootstrap/SKILL.md`](./skills/open-gui-bootstrap/SKILL.md) 开始。推荐流程很简单： 1. 把 skill 交给 Claude 或 Codex 2. 直接用自然语言描述目标 3. 让模型处理后端 bootstrap、APK 构建、安装和本地排障模型只应该在这些事情上打断你： - 连接手机或启动模拟器 - 允许 USB 调试 - 开启 AccessibilityService - 授予悬浮窗或电池权限 - 提供 API Key 或机器人密钥后端和 Android client 跑起来后，可以继续使用 [`skills/open-gui-remote-control/SKILL.md`](./skills/open-gui-remote-control/SKILL.md)，让 Codex 或 Claude Code 通过本地 CLI 控制手机： ```bash cd server pnpm opengui -- devices --json pnpm opengui -- do "观察当前手机屏幕，简要描述你看到了什么，然后结束" --json pnpm opengui -- status --json ``` 推荐配置： #### 高配版如果你优先要效果，可以把规划、监督、复核和视觉分析都放到最新的 Claude Opus 模型族上。这条路径最省心，整体质量也最高，同时成本最高。 #### 省钱混用版如果你优先控制成本，建议把 **Planner**、**Supervisor** 这类文本角色放到 **千问 3.6 Plus**，把 **VLM** 这一侧放到 **豆包 Pro**。在很多任务里，这种混用方式还能保持整体系统结构，同时把模型成本大致降到全量 Opus 方案的 **1/10 到 1/15**，实际比例会受到任务时长、截图数量和 token 结构影响。推荐说法： #### 直接运行 ```text 读一下 ./skills/open-gui-bootstrap/SKILL.md，然后帮我把 OpenGUI 跑起来，只在必须时告诉我手机上要做什么。 ``` #### 全部使用 Claude Opus ```text 读一下 ./skills/open-gui-bootstrap/SKILL.md，然后用最新的 Claude Opus 模型族来配置 OpenGUI，把规划、监督、复核和视觉分析都放进去。 ``` #### 用千问 + 豆包省钱 ```text 读一下 ./skills/open-gui-bootstrap/SKILL.md，然后帮我把 OpenGUI 配成：Planner 和 Supervisor 用千问 3.6 Plus，VLM 执行侧用豆包 Pro。 ``` #### 使用我自己的 API ```text 读一下 ./skills/open-gui-bootstrap/SKILL.md，然后用我现有的模型 API 把 OpenGUI 跑起来。 ``` ### 2. 手动安装直接使用仓库里的脚本： ```bash cd server ./start.sh ``` ```bash cd client ./start.sh ``` 参考文档： - [docs/get-started.md](./docs/get-started.md) - [server/start.sh](./server/start.sh) - [client/start.sh](./client/start.sh) - [server/apps/backend/README.md](./server/apps/backend/README.md) - [docs/DISCORD.zh-CN.md](./docs/DISCORD.zh-CN.md) - [client/README.md](./client/README.md) ### 3. 可选的 Discord 远程控制 Discord 可以作为可选 IM 入口启用。Discord Bot 接收 `!opengui devices` 或 `!opengui do ...` 这类命令，后端再把任务下发给待命 Android 手机，并把进度回传到同一个 Discord 频道。这不是本地运行的必选项。`DISCORD_BOT_TOKEN` 为空时，后端会正常启动并跳过 Discord。完整配置说明见：[docs/DISCORD.zh-CN.md](./docs/DISCORD.zh-CN.md)。 ## 系统结构 ```mermaid flowchart LR U["用户或 IM 指令"] --> BS["Bootstrap Skill / API / IM 入口"] BS --> SP["Plan Supervisor"] SP --> EX["Executor Graph"] EX --> AC["Android 客户端"] AC --> GX["AccessibilityService + 截图 + 动作"] EX --> RV["执行复核与重试"] RV --> SP SP --> SM["Summarizer"] SM --> SR["结构化结果"] RD["Feishu / Telegram / Discord / REST API"] --> ST["Standby Gateway"] ST --> AC SP --> MR["Model Routing"] MR --> MA["Claude / GPT / Gemini / Kimi / MiniMax / compatible"] EX --> MR ``` ### 运行时核心部件 - **后端 graph**：`server/apps/backend/src/modules/graph-agent/graph/` - **任务 API**：`server/apps/backend/src/modules/task/task.controller.ts` - **待命派发**：`server/apps/backend/src/common/ws/standby.gateway.ts` - **IM 入口派发**：`server/apps/backend/src/modules/im-channel/` - **设备待命连接**：`client/core_network/src/main/java/com/coremate/opengui/network/websocket/StandbySocketManager.kt` - **Android 执行链路**：`client/core_accessibility/src/main/java/com/coremate/opengui/accessibility/GestureService.kt` ## 文档 - [skills/open-gui-bootstrap/SKILL.md](./skills/open-gui-bootstrap/SKILL.md) - [docs/get-started.md](./docs/get-started.md) - [server/apps/backend/README.md](./server/apps/backend/README.md) - [docs/DISCORD.zh-CN.md](./docs/DISCORD.zh-CN.md) - [client/README.md](./client/README.md) - [CONTRIBUTING.md](./CONTRIBUTING.md) - [SECURITY.md](./SECURITY.md) - [CLAUDE.md](./CLAUDE.md) ## 社区 / 支持最有价值的项目反馈包括： - 提交 bug 和 feature request - 分享真实使用场景和部署反馈 - 贡献文档、集成和修复 ## 许可证 OpenGUI 采用 Business Source License 1.1 (BUSL-1.1)，源码可见。你可以复制、修改、分发源码，并用于非生产用途。生产使用、商业使用、托管服务、集成到商业产品中，都需要 Core-Mate 的单独商业授权。当前版本： - Change Date: 2030-04-29 - Change License: Apache License, Version 2.0 这代表源码公开 / source-available，但在 Change Date 前不是 OSI 批准的许可证。详见 [LICENSE](./LICENSE)。