Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

Install open-computer-use Codex plugin

Leo823fa517f5a6
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
new file mode 100644
index 0000000..f8a091e
--- /dev/null
+++ b/.agents/plugins/marketplace.json
@@ -0,0 +1,20 @@
+{
+ "name": "open-computer-use-local",
+ "interface": {
+ "displayName": "Open Computer Use Local"
+ },
+ "plugins": [
+ {
+ "name": "open-computer-use",
+ "source": {
+ "source": "local",
+ "path": "./plugins/open-computer-use"
+ },
+ "policy": {
+ "installation": "AVAILABLE",
+ "authentication": "ON_INSTALL"
+ },
+ "category": "Productivity"
+ }
+ ]
+}
diff --git a/README.md b/README.md
index dd0168b..64e23ee 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,15 @@ open dist/OpenCodexComputerUse.app
.build/debug/OpenCodexComputerUse mcp
```
+安装到本机 Codex 插件系统:
+
+```bash
+./scripts/install-codex-plugin.sh
+```
+
+这会把当前仓库注册成一个 repo-local marketplace,并启用插件 `open-computer-use`。脚本会在缺少打包产物时自动构建 `dist/OpenCodexComputerUse.app`,写入 `~/.codex/config.toml`,并移除旧的直连 `mcp_servers."open-codex-computer-use"` 配置,避免同一组 tools 被重复注册。安装后重启 Codex 即可看到插件入口。
+它还会把插件包和已构建的 app 同步到 `~/.codex/plugins/cache/open-computer-use-local/open-computer-use/<version>/`,这样 Codex 实际加载的是本机插件缓存,而不是直接从源码仓库路径启动。
+
本地验证:
```bash
@@ -77,6 +86,10 @@ swift test
端到端 smoke runner,会真实拉起 fixture 和 MCP server,对 9 个 tools 做回归。
- `scripts/build-open-codex-app.sh`
生成最小可运行的 `.app` bundle,便于真实授权与本地 UI 验证。
+- `plugins/open-computer-use`
+ repo-local Codex plugin 包装层,包含 plugin manifest、MCP 启动脚本和展示资源。
+- `scripts/install-codex-plugin.sh`
+ 把当前仓库注册到本机 Codex 的本地 marketplace,安装插件缓存包,并启用 `open-computer-use` 插件。
## 当前取舍
diff --git a/docs/histories/2026-04/20260417-1532-install-open-computer-use-plugin.md b/docs/histories/2026-04/20260417-1532-install-open-computer-use-plugin.md
new file mode 100644
index 0000000..5afa2ce
--- /dev/null
+++ b/docs/histories/2026-04/20260417-1532-install-open-computer-use-plugin.md
@@ -0,0 +1,38 @@
+## [2026-04-17 15:32] | Task: 安装 open-computer-use Codex 插件
+
+### 🤖 Execution Context
+* **Agent ID**: `codex`
+* **Base Model**: `gpt-5.4`
+* **Runtime**: `Codex CLI on macOS`
+
+### 📥 User Query
+> 把我们的 open-codex-computer-use 安装到 codex app 的 plugin 里,plugin 名叫 open-computer-use。
+
+### 🛠 Changes Overview
+**Scope:** `plugins/open-computer-use`, `scripts/`, `README.md`, `.agents/plugins/`
+
+**Key Actions:**
+- **[Plugin Packaging]**: 在仓库内新增 repo-local Codex marketplace 和 `open-computer-use` 插件 manifest、MCP wrapper 与展示资源。
+- **[Local Install Flow]**: 新增 `scripts/install-codex-plugin.sh`,用于构建 app、注册本仓库为本机 Codex marketplace、把插件缓存包安装到 `~/.codex/plugins/cache/...`,并启用插件。
+- **[Docs Sync]**: 在 README 补充插件安装入口和行为说明,避免插件接入方式只存在聊天上下文里。
+
+### 🧠 Design Intent (Why)
+把插件定义版本化落在仓库里,比只手工改 `~/.codex/config.toml` 更可追溯,也更符合这个仓库“Agent-first、知识落盘”的约束。安装脚本顺手清理旧的直连 MCP 配置,是为了避免同一套 computer-use tools 被重复注册。
+
+### 🔁 Follow-up Fix (2026-04-17 15:38)
+- 补齐真实安装缺口:Codex Desktop 实际从 `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/` 加载插件,单纯写 `config.toml` 不会让插件出现在 UI 里。
+- 更新 launcher,使其同时支持:
+ - 从源码仓库里的 `dist/OpenCodexComputerUse.app` 直接运行
+ - 从 Codex 插件缓存目录里的 `OpenCodexComputerUse.app` 运行
+- README 同步改成当前真实行为,避免“重启后就会出现”的说明继续误导后续安装。
+
+### 📁 Files Modified
+- `.agents/plugins/marketplace.json`
+- `plugins/open-computer-use/.codex-plugin/plugin.json`
+- `plugins/open-computer-use/.mcp.json`
+- `plugins/open-computer-use/assets/open-computer-use.svg`
+- `plugins/open-computer-use/assets/open-computer-use-small.svg`
+- `plugins/open-computer-use/scripts/launch-open-computer-use.sh`
+- `scripts/install-codex-plugin.sh`
+- `README.md`
+- `docs/histories/2026-04/20260417-1532-install-open-computer-use-plugin.md`
diff --git a/plugins/open-computer-use/.codex-plugin/plugin.json b/plugins/open-computer-use/.codex-plugin/plugin.json
new file mode 100644
index 0000000..9ec966d
--- /dev/null
+++ b/plugins/open-computer-use/.codex-plugin/plugin.json
@@ -0,0 +1,44 @@
+{
+ "name": "open-computer-use",
+ "version": "0.1.0",
+ "description": "Open-source macOS Computer Use MCP server packaged as a Codex plugin.",
+ "author": {
+ "name": "Leo",
+ "url": "https://github.com/iFurySt"
+ },
+ "homepage": "https://github.com/iFurySt/open-codex-computer-use",
+ "repository": "https://github.com/iFurySt/open-codex-computer-use",
+ "license": "MIT",
+ "keywords": [
+ "computer-use",
+ "macos",
+ "automation",
+ "mcp",
+ "codex"
+ ],
+ "mcpServers": "./.mcp.json",
+ "interface": {
+ "displayName": "Open Computer Use",
+ "shortDescription": "Control macOS apps from Codex with the open local server",
+ "longDescription": "Open Computer Use packages this repository's open-source macOS automation server as a Codex plugin. It exposes the same nine desktop-control MCP tools through the locally built OpenCodexComputerUse app bundle.",
+ "developerName": "Leo",
+ "category": "Productivity",
+ "capabilities": [
+ "Interactive",
+ "Read",
+ "Write"
+ ],
+ "websiteURL": "https://github.com/iFurySt/open-codex-computer-use",
+ "privacyPolicyURL": "https://github.com/iFurySt/open-codex-computer-use/blob/main/SECURITY.md",
+ "termsOfServiceURL": "https://github.com/iFurySt/open-codex-computer-use/blob/main/LICENSE",
+ "defaultPrompt": [
+ "Inspect the current UI state of this Mac app without stealing focus when possible",
+ "Click through a local macOS workflow and summarize what changed",
+ "Drive the fixture app and verify the nine computer-use tools still behave correctly"
+ ],
+ "brandColor": "#0E7490",
+ "composerIcon": "./assets/open-computer-use-small.svg",
+ "logo": "./assets/open-computer-use.svg",
+ "screenshots": []
+ }
+}
diff --git a/plugins/open-computer-use/.mcp.json b/plugins/open-computer-use/.mcp.json
new file mode 100644
index 0000000..3700cdb
--- /dev/null
+++ b/plugins/open-computer-use/.mcp.json
@@ -0,0 +1,8 @@
+{
+ "mcpServers": {
+ "open-computer-use": {
+ "command": "./scripts/launch-open-computer-use.sh",
+ "cwd": "."
+ }
+ }
+}
diff --git a/plugins/open-computer-use/assets/open-computer-use-small.svg b/plugins/open-computer-use/assets/open-computer-use-small.svg
new file mode 100644
index 0000000..9bb63fd
--- /dev/null
+++ b/plugins/open-computer-use/assets/open-computer-use-small.svg
@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Open Computer Use">
+ <defs>
+ <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+ <stop offset="0%" stop-color="#0F172A"/>
+ <stop offset="100%" stop-color="#155E75"/>
+ </linearGradient>
+ <linearGradient id="cursor" x1="0%" y1="0%" x2="100%" y2="100%">
+ <stop offset="0%" stop-color="#99F6E4"/>
+ <stop offset="100%" stop-color="#22D3EE"/>
+ </linearGradient>
+ </defs>
+ <rect x="5" y="5" width="54" height="54" rx="13" fill="url(#bg)"/>
+ <rect x="14" y="16" width="36" height="18" rx="5" fill="#E2E8F0" fill-opacity="0.14" stroke="#67E8F9" stroke-opacity="0.55" stroke-width="2"/>
+ <path d="M27 46V20l18 14-10 3-4 10z" fill="url(#cursor)" stroke="#CFFAFE" stroke-width="2.5" stroke-linejoin="round"/>
+</svg>
diff --git a/plugins/open-computer-use/assets/open-computer-use.svg b/plugins/open-computer-use/assets/open-computer-use.svg
new file mode 100644
index 0000000..40a47df
--- /dev/null
+++ b/plugins/open-computer-use/assets/open-computer-use.svg
@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="Open Computer Use">
+ <defs>
+ <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+ <stop offset="0%" stop-color="#0F172A"/>
+ <stop offset="100%" stop-color="#155E75"/>
+ </linearGradient>
+ <linearGradient id="cursor" x1="0%" y1="0%" x2="100%" y2="100%">
+ <stop offset="0%" stop-color="#99F6E4"/>
+ <stop offset="100%" stop-color="#22D3EE"/>
+ </linearGradient>
+ </defs>
+ <rect x="20" y="20" width="216" height="216" rx="52" fill="url(#bg)"/>
+ <rect x="52" y="64" width="152" height="96" rx="18" fill="#E2E8F0" fill-opacity="0.14" stroke="#67E8F9" stroke-opacity="0.55" stroke-width="6"/>
+ <path d="M128 108h54" stroke="#67E8F9" stroke-width="10" stroke-linecap="round"/>
+ <path d="M74 108h30" stroke="#99F6E4" stroke-width="10" stroke-linecap="round"/>
+ <path d="M92 182V94l74 56-40 10-18 42z" fill="url(#cursor)" stroke="#CFFAFE" stroke-width="8" stroke-linejoin="round"/>
+</svg>
diff --git a/plugins/open-computer-use/scripts/launch-open-computer-use.sh b/plugins/open-computer-use/scripts/launch-open-computer-use.sh
new file mode 100755
index 0000000..a806ad9
--- /dev/null
+++ b/plugins/open-computer-use/scripts/launch-open-computer-use.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+plugin_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+bundled_app_binary="${plugin_root}/OpenCodexComputerUse.app/Contents/MacOS/OpenCodexComputerUse"
+repo_root="$(cd "${plugin_root}/../.." && pwd)"
+repo_app_binary="${repo_root}/dist/OpenCodexComputerUse.app/Contents/MacOS/OpenCodexComputerUse"
+
+if [[ -x "${bundled_app_binary}" ]]; then
+ cd "${plugin_root}"
+ exec "${bundled_app_binary}" mcp
+fi
+
+if [[ -x "${repo_app_binary}" ]]; then
+ cd "${repo_root}"
+ exec "${repo_app_binary}" mcp
+fi
+
+echo "open-computer-use could not find a runnable app bundle." >&2
+echo "Checked:" >&2
+echo " - ${bundled_app_binary}" >&2
+echo " - ${repo_app_binary}" >&2
+echo "Run ./scripts/install-codex-plugin.sh to populate the Codex plugin cache." >&2
+exit 1
diff --git a/scripts/install-codex-plugin.sh b/scripts/install-codex-plugin.sh
new file mode 100755
index 0000000..69b9b72
--- /dev/null
+++ b/scripts/install-codex-plugin.sh
@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+codex_home="${CODEX_HOME:-${HOME}/.codex}"
+config_path="${codex_home}/config.toml"
+marketplace_name="open-computer-use-local"
+plugin_name="open-computer-use"
+plugin_source_root="${repo_root}/plugins/${plugin_name}"
+plugin_manifest="${plugin_source_root}/.codex-plugin/plugin.json"
+configuration="debug"
+rebuild="false"
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --rebuild)
+ rebuild="true"
+ shift
+ ;;
+ --configuration)
+ configuration="${2:-}"
+ if [[ -z "${configuration}" ]]; then
+ echo "--configuration requires a value" >&2
+ exit 1
+ fi
+ shift 2
+ ;;
+ *)
+ echo "Unknown argument: $1" >&2
+ echo "Usage: $0 [--rebuild] [--configuration debug|release]" >&2
+ exit 1
+ ;;
+ esac
+done
+
+app_binary="${repo_root}/dist/OpenCodexComputerUse.app/Contents/MacOS/OpenCodexComputerUse"
+
+if [[ "${rebuild}" == "true" || ! -x "${app_binary}" ]]; then
+ "${repo_root}/scripts/build-open-codex-app.sh" "${configuration}"
+fi
+
+if [[ ! -f "${repo_root}/.agents/plugins/marketplace.json" ]]; then
+ echo "Missing ${repo_root}/.agents/plugins/marketplace.json" >&2
+ exit 1
+fi
+
+if [[ ! -f "${plugin_manifest}" ]]; then
+ echo "Missing ${plugin_manifest}" >&2
+ exit 1
+fi
+
+if [[ ! -x "${app_binary}" ]]; then
+ echo "Missing runnable app binary at ${app_binary}" >&2
+ exit 1
+fi
+
+plugin_version="$(
+ python3 - "${plugin_manifest}" <<'PY'
+import json
+import sys
+
+with open(sys.argv[1], "r", encoding="utf-8") as fh:
+ manifest = json.load(fh)
+
+print(manifest["version"])
+PY
+)"
+
+if [[ -z "${plugin_version}" ]]; then
+ echo "Failed to read plugin version from ${plugin_manifest}" >&2
+ exit 1
+fi
+
+plugin_cache_root="${codex_home}/plugins/cache/${marketplace_name}/${plugin_name}"
+plugin_install_root="${plugin_cache_root}/${plugin_version}"
+
+mkdir -p "${codex_home}" "${plugin_cache_root}"
+rm -rf "${plugin_install_root}"
+mkdir -p "${plugin_install_root}"
+
+rsync -a "${plugin_source_root}/" "${plugin_install_root}/"
+rsync -a "${repo_root}/dist/OpenCodexComputerUse.app" "${plugin_install_root}/"
+
+python3 - "${config_path}" "${repo_root}" "${marketplace_name}" "${plugin_name}" <<'PY'
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def section_pattern(header: str) -> re.Pattern[str]:
+ return re.compile(rf'(?ms)^\[{re.escape(header)}\]\n.*?(?=^\[|\Z)')
+
+
+def remove_section(text: str, header: str) -> str:
+ return section_pattern(header).sub("", text)
+
+
+def upsert_section(text: str, header: str, body: str) -> str:
+ section = f'[{header}]\n{body.rstrip()}\n'
+ pattern = section_pattern(header)
+ if pattern.search(text):
+ return pattern.sub(section, text, count=1)
+
+ if text and not text.endswith("\n"):
+ text += "\n"
+ if text and not text.endswith("\n\n"):
+ text += "\n"
+ return text + section
+
+
+config_path = Path(sys.argv[1])
+repo_root = Path(sys.argv[2]).resolve()
+marketplace_name = sys.argv[3]
+plugin_name = sys.argv[4]
+
+text = config_path.read_text() if config_path.exists() else ""
+
+for header in (
+ 'mcp_servers."open-codex-computer-use"',
+ 'mcp_servers."open-computer-use"',
+):
+ text = remove_section(text, header)
+
+text = upsert_section(
+ text,
+ f"marketplaces.{marketplace_name}",
+ f'source_type = "local"\nsource = {json.dumps(str(repo_root))}',
+)
+text = upsert_section(
+ text,
+ f'plugins."{plugin_name}@{marketplace_name}"',
+ "enabled = true",
+)
+
+text = re.sub(r"\n{3,}", "\n\n", text).rstrip() + "\n"
+config_path.write_text(text)
+PY
+
+echo "Installed ${plugin_name}@${marketplace_name}"
+echo "Marketplace source: ${repo_root}"
+echo "Plugin cache: ${plugin_install_root}"
+echo "Updated Codex config: ${config_path}"
+echo "Restart Codex to load the plugin marketplace."