适用于 macOS（Apple 芯片 / Intel）、WorkBuddy 5.5.3 及以上版本，包含国际版 WorkBuddy AI。通过 OpenGUI GitHub 仓库和 GitHub Release 安装本地 MCP、Skill、任务 Hooks 及依赖，不需要先在官方连接器市场上架，也不需要部署 server/ 或编译 Android 客户端。
当前公开运行时为 0.4.1 公测预发布版，国内版和国际版共用同一个安装包。中英文切换、自动跟随 WorkBuddy 语言和模拟器下拉框改进尚未合入公开源码或安装包。
完整流程：运行 GitHub 安装脚本 → 重启 WorkBuddy 一次 → 用户授权 Skill 和 MCP → 原生工具验证 → 登录并开始手机任务。
| 目标 | 使用方式 |
|---|---|
| 国际版 WorkBuddy AI，安装 GitHub 已发布运行时 | 使用本文的 --app "/Applications/WorkBuddy AI.app" --download-source official 命令。 |
| 国内版 WorkBuddy，安装 GitHub 已发布运行时 | 将 --app 改为 "/Applications/WorkBuddy.app"；可按网络情况选择 cn 或 official 下载源。 |
| 安装当前源码，包括本地未发布改动 | 在源码目录构建并打包，再用 --archive 安装本地产物，见下方“当前源码安装”。 |
两版同时安装时，明确指定 --app，以免自动发现选中另一版。应用不在 /Applications 时，改成其实际绝对路径。配置目录从所选应用的产品信息读取；国际版当前为 ~/.workbuddy-ai。
本文所说“从 GitHub 安装”是下载并执行仓库提供的完整安装器。上传单个 SKILL.md 或手动添加一段 MCP JSON，不能替代任务 Hooks 和本地依赖的安装。
打开国际版 WorkBuddy，新建聊天，粘贴：
请从官方仓库 https://github.com/Core-Mate/OpenGUI 安装 OpenGUI 到本机国际版 WorkBuddy AI。
我的国际版应用位于 /Applications/WorkBuddy AI.app。
先读取仓库 workbuddy-plugin/docs/install-from-github.zh-CN.md，并检查公开安装脚本的参数。
使用仓库 workbuddy-plugin/install.sh，明确指定 --app "/Applications/WorkBuddy AI.app" 和 --download-source official。
先执行 --check；通过后执行完整安装，保留安装结果、日志和授权指南路径。
已有运行中的 OpenGUI 任务导致升级受阻时，报告原因并保留原配置，不强制结束进程。
安装完成后提醒我结束其他任务，用 Command-Q 完全退出并重新打开国际版。
Skill 授权、MCP Trust/启用和可能出现的 Hooks 审阅由我本人完成。
我确认完成后，只调用一次 opengui_list_devices 验证连接，报告成功与设备数量。
安装和连接验证期间，不截图、不打开投屏、不创建控制会话、不操作手机。
WorkBuddy 的正常终端权限提示仍适用。如果它无法读取 GitHub 或执行安装命令，使用下面的终端方式。无需把整个 OpenGUI 源码复制进聊天，也无需让它从零重新实现插件。
可选：先执行环境检查。入口会下载并校验文件、保留本次检查记录，不写 MCP、Skill 或 Hooks 配置：
cd "$HOME" && curl -fsSL https://raw.githubusercontent.com/Core-Mate/OpenGUI/main/workbuddy-plugin/install.sh | bash -s -- --check --app "/Applications/WorkBuddy AI.app" --download-source official然后执行完整安装：
cd "$HOME" && curl -fsSL https://raw.githubusercontent.com/Core-Mate/OpenGUI/main/workbuddy-plugin/install.sh | bash -s -- --app "/Applications/WorkBuddy AI.app" --download-source official也可以下载 install.sh，保存到电脑后执行：
bash /实际下载路径/install.sh --app "/Applications/WorkBuddy AI.app" --download-source official安装器会校验后续脚本、运行包和视频资源，准备私有 Node 与插件依赖，备份并增量合并所选 WorkBuddy 的 MCP、Skill、Hooks 配置。现有其他插件保留。运行包版本由 GitHub 安装器指定，安装 GitHub Release 的构建产物，不会自动包含本机未提交的改动。
Node/npm 的 official 源分别为 nodejs.org 和 registry.npmjs.org；视频和 OpenGUI 运行包另从 GitHub 获取。网络问题可以选择下载源或视频镜像，校验失败时应排查文件来源，不跳过校验。
- 确认安装输出包含
CONFIG_WRITTEN；GitHub 脚本入口还会打印INSTALLATION_RESULT和AUTHORIZATION_GUIDE。本次回执中的status=configuration_written只证明配置已写入。 - 结束其他 WorkBuddy 任务，按 ⌘Q 完全退出，再打开国际版 WorkBuddy AI。关闭窗口不能代替退出。
- 打开 Experts · Skills · Connectors → Connectors → Custom connectors，找到
opengui，亲自点击 Trust，确认开关开启、服务连接成功。 - 在 Skills 中找到 OpenGUI /
opengui，按提示完成授权并启用。若提示审阅 Hooks，使用/hooks检查当前 OpenGUI 对应项。
安装器不会替用户完成首次信任。WorkBuddy 可能有独立的工具授权提示，也由用户检查。界面已加载但连接失败时，先看实际错误与本次日志；打开指南失败可以直接打开 AUTHORIZATION_GUIDE 对应文件。
授权后新建聊天，发送：
仅验证 OpenGUI MCP 连接：调用一次 opengui_list_devices，用中文报告调用是否成功、发现几台设备。
不截图、不打开工作台或投屏、不创建控制会话、不操作手机。
看到原生 opengui_list_devices 成功返回，才算通过 WorkBuddy 工具调用验证。设备数量为 0 也可以证明连接成功；安装回执、开关启用、单独进程返回工具目录，都不能代替这次原生调用。
开始实际任务时：
- Android 手机开启 USB 调试，连接电脑，在手机上允许调试授权；也可使用支持的本地模拟器。
- 在 WorkBuddy 输入
/opengui，按工作台提示登录 OpenGUI 账号。当前账号服务仍需中国大陆手机号；WorkBuddy 的 Google/GitHub 登录与其独立。 - 输入真实任务，检查目标和设备，点击“开始执行”。例如：“打开手机设置，再返回桌面，确认回到桌面后结束。”
连接验证不等于真机任务验收；首次画面、操作、停止、接管和报告分别以实际执行结果为准。
这条路线适合开发者验证当前提交或本地改动，要求有兼容 Node/npm；macOS 构建包含原生辅助程序，还需要 Xcode Command Line Tools。普通用户使用上方已发布版本安装即可。
从 GitHub 获取一个独立源码目录，或使用现有工作区；已有目录中先检查本地改动，再决定更新方式：
git clone https://github.com/Core-Mate/OpenGUI.git
cd OpenGUI/workbuddy-plugin
npm ci
npm run pack:release打包成功后，由当前源码的 package.json 读取版本，再安装对应归档：
plugin_version=$(node -p 'JSON.parse(require("node:fs").readFileSync("package.json", "utf8")).version')
bash scripts/install-macos.command \
--app "/Applications/WorkBuddy AI.app" \
--download-source official \
--archive "$PWD/dist/opengui-mcp-$plugin_version.tgz"归档与相邻 .sha256 保持在同一目录。源码安装后也要完成上面的重启、原生授权及只读工具调用验证。WorkBuddy 聊天同样可以在该源码工作区执行这组命令；需要安装当前源码时，明确要求 --archive，否则安装器仍会下载已发布运行时。