Skip to content

README.zh-CN.md

Latest commit

 

History

History
313 lines (221 loc) · 12.6 KB

README.zh-CN.md

File metadata and controls

313 lines (221 loc) · 12.6 KB

语言切换：English | 简体中文 | 日本語

OpenGUI banner

Bootstrap with Claude or Codex Multi-role operator system Tasks up to 12 hours Recommended model profiles Manual setup docs

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

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

Demo

OpenGUI 移动端 GUI Agent Demo

OpenGUI 会读取真实 Android App 界面，规划下一步操作，执行移动端动作，并返回结构化结果。

Quick Start

最快的试用方式，是让 Claude Code 或 Codex 帮你完成启动。

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 客户端：

cd server
./start.sh
cd client
./start.sh

后端和 Android 客户端都跑起来后，发送第一个任务：

cd server
pnpm opengui -- devices --json
pnpm opengui -- do "观察当前手机屏幕，简要描述你看到了什么，然后结束" --json

手动安装指南：docs/get-started.md。

近期更新

  • [2026.5.16] 新增 Codex / Claude Code 远程控制，提供本地 REST API、pnpm opengui -- ... CLI，以及 open-gui-remote-control Skill，可从编码 Agent 下发 Android App 任务。
  • [2026.5.9] 新增 Discord IM 入口，支持前缀命令、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 交给模型，直接用自然语言描述目标，让它处理安装、构建、安装 APK 和本地排障。
  • 让 Codex 控制 Android App：OpenGUI 启动后，把 skills/open-gui-remote-control/SKILL.md 交给 Codex 或 Claude Code，用本地 CLI 列设备、下发任务并查询 execution 状态。
  • 把手机当成远程 worker 使用：通过飞书、Telegram、Discord 或 REST API 下发任务，让设备保持待命，并从后端拿回结构化结果。
  • 加入 Discord 社区

亮点

  • 适合长时任务：OpenGUI 面向长时移动工作流，任务可以持续运行数小时，并在过程中继续推进、复核和恢复。
  • 先规划，再执行，最后总结：在真正操作 App 前，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 开始。

推荐流程很简单：

  1. 把 skill 交给 Claude 或 Codex
  2. 直接用自然语言描述目标
  3. 让模型处理后端 bootstrap、APK 构建、安装和本地排障

模型只应该在这些事情上打断你：

  • 连接手机或启动模拟器
  • 允许 USB 调试
  • 开启 AccessibilityService
  • 授予悬浮窗或电池权限
  • 提供 API Key 或机器人密钥

后端和 Android client 跑起来后，可以继续使用 skills/open-gui-remote-control/SKILL.md，让 Codex 或 Claude Code 通过本地 CLI 控制手机：

cd server
pnpm opengui -- devices --json
pnpm opengui -- do "观察当前手机屏幕，简要描述你看到了什么，然后结束" --json
pnpm opengui -- status <executionId> --json

推荐配置：

高配版

如果你优先要效果，可以把规划、监督、复核和视觉分析都放到最新的 Claude Opus 模型族上。

这条路径最省心，整体质量也最高，同时成本最高。

省钱混用版

如果你优先控制成本，建议把 Planner、Supervisor 这类文本角色放到 千问 3.6 Plus，把 VLM 这一侧放到 豆包 Pro。

在很多任务里，这种混用方式还能保持整体系统结构，同时把模型成本大致降到全量 Opus 方案的 1/10 到 1/15，实际比例会受到任务时长、截图数量和 token 结构影响。

推荐说法：

直接运行

读一下 ./skills/open-gui-bootstrap/SKILL.md，然后帮我把 OpenGUI 跑起来，只在必须时告诉我手机上要做什么。

全部使用 Claude Opus

读一下 ./skills/open-gui-bootstrap/SKILL.md，然后用最新的 Claude Opus 模型族来配置 OpenGUI，把规划、监督、复核和视觉分析都放进去。

用千问 + 豆包省钱

读一下 ./skills/open-gui-bootstrap/SKILL.md，然后帮我把 OpenGUI 配成：Planner 和 Supervisor 用千问 3.6 Plus，VLM 执行侧用豆包 Pro。

使用我自己的 API

读一下 ./skills/open-gui-bootstrap/SKILL.md，然后用我现有的模型 API 把 OpenGUI 跑起来。

2. 手动安装

直接使用仓库里的脚本：

cd server
./start.sh
cd client
./start.sh

参考文档：

3. 可选的 Discord 远程控制

Discord 可以作为可选 IM 入口启用。Discord Bot 接收 !opengui devices 或 !opengui do ... 这类命令，后端再把任务下发给待命 Android 手机，并把进度回传到 同一个 Discord 频道。

这不是本地运行的必选项。DISCORD_BOT_TOKEN 为空时，后端会正常启动并跳过 Discord。

完整配置说明见：docs/DISCORD.zh-CN.md。

系统结构

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
Loading

运行时核心部件

  • 后端 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

文档

社区 / 支持

最有价值的项目反馈包括：

  • 提交 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。