This guide installs the published OpenGUI 0.4.1 WorkBuddy connector on macOS. It uses the official public-testing release; no source checkout, system Node installation, full backend deployment, or DSH installation is needed.
Important
Restart WorkBuddy once after installation. Finish other tasks, fully quit with ⌘Q, then reopen WorkBuddy before authorizing the Skill and connector. Closing its window is not enough.
For copyable WorkBuddy chat prompts and the full Chinese flow, see install from GitHub. China and international WorkBuddy use the same OpenGUI 0.4.1 package and version.
The complete download, authorization and first-task instructions are in the root README (中文). Open macOS Terminal and select the target application explicitly.
China edition — WorkBuddy.app:
cd "$HOME" && curl -fsSL https://raw.githubusercontent.com/Core-Mate/OpenGUI/main/workbuddy-plugin/install.sh | bash -s -- --app "/Applications/WorkBuddy.app" --download-source cnInternational edition — WorkBuddy AI.app:
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 officialInstall separately if you use both editions. Replace the application path if it has been moved or renamed. Alternatively, download install.sh and run bash /actual/path/install.sh with the same --app and --download-source arguments. Restart the selected WorkBuddy once afterward, then authorize OpenGUI and verify the connection.
The repository entry and its pinned installer/authorization guide are published together. They install the refreshed public-testing 0.4.1 runtime. This release uses new versioned assets and adjacent SHA-256 sidecars; earlier releases remain unchanged. The manual installation guide remains available as an alternative.
The entry downloads the installer and a self-contained authorization guide, verifies their SHA-256 pins, and runs installation without a Terminal confirmation or Finder step. After successful configuration it opens the guide in the default browser and prints AUTHORIZATION_GUIDE and INSTALLATION_RESULT paths. WorkBuddy can display that same HTML if browser opening is unavailable. Browser failure does not mean installation failed; do not reinstall just to reopen the instructions.
The user completes both Skill and connector authorization, then starts or opens a WorkBuddy chat to request connection verification. The assistant checks this attempt's receipt and makes a native read-only MCP call. Do not approve trust on the user's behalf or bypass WorkBuddy's normal security review.
Node.js and npm dependencies default to npmmirror: https://npmmirror.com/mirrors/node and https://registry.npmmirror.com. If a Node mirror request fails or npm installation fails, the installer retries the official source. Node archives retain the pinned SHA-256 checks; a checksum mismatch stops installation. Registry selection is passed to the private npm process and does not change global npm settings.
Choose official Node.js and npm sources for one installation:
bash /actual/path/install.sh --download-source officialFor the streamed entry, use curl -fsSL https://raw.githubusercontent.com/Core-Mate/OpenGUI/main/workbuddy-plugin/install.sh | bash -s -- --download-source official. --download-source cn selects the default explicitly. OPENGUI_DOWNLOAD_SOURCE=cn|official also sets the default; command-line arguments take priority.
The roughly 13 MB video component is a scrcpy release archive hosted on GitHub. It is separate from Node.js and npm; changing the npm registry does not accelerate it. GitHub bootstrap files and OpenGUI release packages also retain their official URLs.
If you have a video archive mirror, pass --video-mirror https://your-mirror.example/scrcpy/v4.1 or set OPENGUI_VIDEO_MIRROR to that directory. It must contain the original release filenames, such as scrcpy-macos-aarch64-v4.1.tar.gz. The mirror attempt is limited to 60 seconds; failed requests, size mismatches and checksum mismatches fall back to the official archive. Original sizes and SHA-256 pins are always verified before extraction. Cancellation stops installation instead of starting a fallback download. Video mirrors require a package built with this feature; older packages report VIDEO_MIRROR_UNSUPPORTED rather than ignoring the option. Cached resources are reused regardless of the selected source.
Installation downloads a private Node runtime and the published OpenGUI package, adds the opengui MCP server and Skill, and registers seven lifecycle Hooks: UserPromptSubmit, PreToolUse, Stop, SubagentStop, FinalStop, SessionEnd, and StopFailure. These local commands bind tasks and handle stopping and cleanup; review them in /hooks when prompted. Affected settings are backed up and unrelated plugins are retained.
No phone is required during installation. Later Android use requires USB debugging authorization. The official CoreMate account service handles SMS sign-in and automatic registration, currently requiring a mainland-China phone number. Execution follows the current WorkBuddy conversation model. Task screenshots go through WorkBuddy’s model/tool loop; local preview video is not sent frame by frame.
- macOS on Apple Silicon or Intel, with WorkBuddy 5.5.3 or newer installed.
- Network access to GitHub and runtime downloads.
- WorkBuddy may stay open during installation, but must be fully quit and reopened once afterward. If an active old OpenGUI service blocks an upgrade, finish its tasks, close its viewers, disable the old MCP and wait for it to exit before retrying.
The script entry stores each attempt's log, receipt and guide in ~/.workbuddy/opengui/installations/install.*. Only status=configuration_written establishes that configuration was written; host loading remains unverified. --check performs the core preflight, with bootstrap downloads and its own receipt, but does not install or open authorization instructions. The core installer's direct --check remains read-only.
Automatic discovery recognizes com.workbuddy.workbuddy, com.workbuddy.workbuddy-ai, and legacy com.tencent.workbuddy.* bundles. WorkBuddy (including legacy bundles) takes priority over WorkBuddy AI. If multiple bundles remain at the preferred priority, choose one with --app /absolute/path/WorkBuddy.app. Use --app to select WorkBuddy AI explicitly even when WorkBuddy is installed. The installer reads the selected application's product metadata to resolve its configuration directory and prints the selected application and directory during preflight.
Custom MCP installation does not require a marketplace listing. Select WorkBuddy AI.app with --app and use --download-source official, as shown above. The OpenGUI 0.4.1 installer supports --app.
The installer reads the selected application’s product metadata. Current international builds use ~/.workbuddy-ai for MCP, Skill and Hook configuration; China builds use their own configuration root, normally ~/.workbuddy. OpenGUI keeps shared private runtime/account/device state under ~/.workbuddy/opengui, with separate installation receipts for each configuration root. Do not operate the same phone through both hosts concurrently.
OpenGUI’s SMS account is separate from WorkBuddy’s Google/GitHub account. OpenGUI currently requires a mainland-China phone number. Chinese/English switching and following WorkBuddy’s display language are being tested and are not yet included in the public source or 0.4.1 package.
In international WorkBuddy AI, authorize and enable OpenGUI under Experts · Skills · Connectors → Skills. Then open Connectors → Custom connectors, find opengui, click Trust, and enable it. The user completes both authorizations. An update may trigger another Trust prompt when the runtime path changes. The official MCP guide also covers custom servers.
See install from GitHub for chat installation, read-only verification and installing an explicitly selected local archive.
The existing OpenGUI installation guide retains the ZIP download and manual launcher. Use it when the user explicitly prefers a manual installation. Its embedded archive is built ahead of time; do not generate another guide during installation. The manual launcher's receipt is in its installation-result.* directory.
Installation has three distinct results:
- Configuration written: this attempt's returned
INSTALLATION_RESULTfile (or the manual launcher'sinstallation-result.*/result.txt) reportsstatus=configuration_written, and itsinstall.logcontains the corresponding successful configuration result.status=running, a failed receipt, or an older receipt does not establish completion. - Host loaded: OpenGUI appears in MCP management and its trust/enablement is complete. Skill authorization and MCP trust are separate. Hook changes may require review in
/hooks. - Read-only tool call: a native
opengui_list_devicescall succeeds. WorkBuddy may expose it asmcp__opengui__opengui_list_devices. An empty device list can still confirm that the plugin is loaded; connecting a phone is a later step.
The connection-check request starts verification; it is not proof that the host loaded the plugin. The installer itself records hostLoaded=unverified. A phone-control task is not needed for installation verification.
If Skill or connector authorization remains incomplete, reopen the authorization guide:
- 国内版：在“专家·技能·连接器 → 技能”中授权 OpenGUI；再到“连接器 → 自定义连接器”，为
opengui完成信任并开启开关。 - International edition: authorize OpenGUI under Experts · Skills · Connectors → Skills, then click Trust for
openguiunder Connectors → Custom connectors and enable it.
注意：技能 和 连接器，都需要授权哦！
查看原始授权动图与说明。已经启用、状态为绿色的连接器保持不变。
The published 0.4.1 installer can write configuration while newer WorkBuddy versions are running, but that does not establish live reload. A local WorkBuddy 5.7.6 comparison found that neither external in-place writing nor atomic replacement updated the custom MCP list. Saving the same configuration through WorkBuddy's built-in MCP editor updated the list without restarting. See the local verification record.
The standard installation flow requires one restart: finish other tasks, fully quit WorkBuddy with Command-Q, reopen it, then continue Skill authorization and MCP trust. If OpenGUI is still missing after that, open Experts · Skills · Connectors → Connectors → Custom connectors → Add MCP and check for the opengui entry in the expected configuration file. If it is absent, inspect the installer receipt and configuration path. The built-in editor's Save action is a verified manual refresh option; it is not the default onboarding step. If configuration is already loaded but a connection fails, inspect the actual error before restarting again.
If the row appears with a first-use trust prompt, the remaining step is the native Trust action. disabled: false in mcp.json does not grant trust. If a current conversation still lacks the tools after the server connects, a new conversation may refresh its tool list. The receipt and actual native tool-call result distinguish configuration, discovery, and connection failures.
After receipt and native tool-call verification, Android setup and task examples are:
Android 手机开启 USB 调试、连接电脑并允许调试授权，也可使用工作台中的本地 Android 模拟器。在 WorkBuddy 输入 /opengui，打开右侧任务首页并登录 OpenGUI，填写目标、确认设备，点击“开始执行”。执行模型跟随当前 WorkBuddy 对话。
试一试：用小红书发帖
试一试：Vibe Testing
These links open task drafts without sending them. Edit the placeholders before submitting. Device and model confirmation still apply.
WorkBuddy state directory must be private, owned by this user, and not a symlink refers to OpenGUI's state directory, normally ~/.workbuddy/opengui. The published installer checks ownership and redirected paths before setting this directory to mode 0700. It does not change permissions on the WorkBuddy root directory. This error is separate from a host permission refusal; its actual cause should be checked before retrying installation.
This error occurs when npm cannot read the Terminal process's current directory. npm --prefix does not change that working directory. The current installer runs npm from its own verified private package directory, including when the launch directory is inaccessible or has been deleted. Download the current script and retry; for an older installer, first run cd "$HOME" in Terminal.