Plugin guides
Codex 電腦操作
Computer Use 是用於本機桌面控制的 Codex 原生 MCP 外掛。OpenClaw
不會內建桌面應用程式、不會自行執行桌面操作，也不會繞過
Codex 權限。隨附的 codex 外掛只會準備 Codex app-server：
啟用 Codex 外掛支援、尋找或安裝已設定的 Computer Use
外掛、檢查 computer-use MCP 伺服器是否可用，然後在 Codex 模式的回合中
讓 Codex 負責原生 MCP 工具呼叫。
當 OpenClaw 已使用原生 Codex 執行框架時，請使用本頁。若要瞭解 執行階段本身的設定，請參閱 Codex 執行框架。
這與 OpenClaw 內建的節點支援電腦工具不同。當相同的代理契約需要控制已配對的 Mac，無論代理是在閘道或其他節點上執行時，請使用內建工具。當 Codex app-server 應負責本機 MCP 安裝、權限與原生工具呼叫時，請使用 Codex Computer Use。
OpenClaw.app 與 Peekaboo
OpenClaw.app 的 Peekaboo 整合與 Codex Computer Use 分開運作。
macOS 應用程式可託管 PeekabooBridge 通訊端，讓 peekaboo 命令列介面重複使用
應用程式的本機「輔助使用」與「螢幕錄製」授權，以供 Peekaboo 自己的
自動化工具使用。該橋接器不會安裝或代理 Codex Computer Use，而
Codex Computer Use 也不會透過 PeekabooBridge 通訊端進行呼叫。
當您希望 OpenClaw.app 成為具權限感知能力的 Peekaboo 命令列介面自動化
主機時，請使用 Peekaboo 橋接器。當
Codex 模式的 OpenClaw 代理應在回合開始前使用 Codex 原生的 computer-use MCP 外掛
時，請使用本頁。
iOS 應用程式
iOS 應用程式與 Codex Computer Use 分開運作。它不會安裝或代理
Codex computer-use MCP 伺服器，也不是桌面控制後端。
相反地，iOS 應用程式會作為 OpenClaw 節點連線，並透過
canvas.*、camera.*、screen.*、
location.* 與 talk.* 等節點命令公開行動裝置功能。
當您希望代理透過閘道驅動 iPhone 節點時，請使用 iOS。 當 Codex 模式代理應透過 Codex 原生 Computer Use 外掛控制 本機 macOS 桌面時，請使用本頁。
直接使用 cua-driver MCP
Codex Computer Use 並非公開桌面控制功能的唯一方式。如果您希望
由 OpenClaw 管理的執行階段直接呼叫 TryCua 的驅動程式，請透過 OpenClaw 的 MCP 登錄檔使用上游
cua-driver mcp 伺服器，而非
Codex 專用的市集流程。
安裝 cua-driver 後，可以要求它提供 OpenClaw 命令：
cua-driver mcp-config --client openclaw或直接註冊 stdio 伺服器：
openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'此路徑會保持上游 MCP 工具介面不變，包括驅動程式 結構描述與結構化 MCP 回應。當您希望 CUA 驅動程式 可作為一般 OpenClaw MCP 伺服器使用時，請採用此方式。當 Codex app-server 應在 Codex 模式回合內負責外掛安裝、MCP 重新載入 與原生工具呼叫時，請使用本頁的 Codex Computer Use 設定。
CUA 的驅動程式僅適用於 macOS，且仍需要其應用程式提示授予的
本機 macOS 權限，例如「輔助使用」與「螢幕錄製」。OpenClaw 不會
安裝 cua-driver、授予這些權限，或繞過上游
驅動程式的安全模型。
快速設定
當 Codex 模式回合必須在對話串開始前使用 Computer Use 時，請設定 plugins.entries.codex.config.computerUse。
autoInstall: true 會選擇啟用 Computer Use，並讓 OpenClaw 在回合前安裝或重新啟用它：
{ plugins: { entries: { codex: { enabled: true, config: { computerUse: { autoInstall: true, }, }, }, }, }, agents: { defaults: { model: "openai/gpt-5.6-sol", }, },}使用此設定時，OpenClaw 會在每個 Codex 模式
回合前檢查 Codex app-server。如果缺少 Computer Use，但 Codex app-server 已發現
可安裝的市集，OpenClaw 會要求 Codex app-server 安裝或
重新啟用該外掛，並重新載入 MCP 伺服器。在 macOS 上，若未註冊相符的
市集且存在標準桌面應用程式套件，OpenClaw
也會嘗試從
/Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled 註冊隨附的 Codex 市集，
並保留
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled
作為舊版獨立安裝的備援。如果設定後仍無法讓
MCP 伺服器可用，回合會在對話串開始前失敗。
變更 Computer Use 設定後，如果現有 Codex 對話串已開始，
請先在受影響的聊天中使用 /new 或 /reset，再進行測試。
在 macOS 上，Computer Use 的受管理啟動會優先使用
/Applications/ChatGPT.app/Contents/Resources/codex 的桌面應用程式二進位檔，
然後針對舊版獨立安裝
退回使用 /Applications/Codex.app/Contents/Resources/codex。
這也適用於會啟動自身用戶端的一次性 Computer Use 狀態與
安裝命令。這能讓桌面控制維持在
擁有本機 macOS 權限的應用程式套件下。如果未安裝桌面應用程式，
OpenClaw 會退回使用安裝於外掛旁的受管理 Codex 二進位檔。
使用預設隔離代理主目錄的一般受管理 Codex 回合會優先使用
該固定版本套件，避免較舊的桌面應用程式遮蔽目前的模型
支援。使用者範圍的主目錄仍會優先使用桌面應用程式，因為它們可以載入原生
Computer Use 狀態。有效 Codex 設定已啟用
Computer Use 的隔離代理主目錄也會繼續優先使用桌面應用程式。明確的
appServer.command 設定或 OPENCLAW_CODEX_APP_SERVER_BIN 仍會覆寫
此受管理選擇。
OpenClaw 會在單一執行中的閘道內，將原生 Codex 設定讀取與 Computer Use 安裝 依序執行。獨立的 Codex 處理程序或另一個閘道不在 此互斥範圍內。在閘道外變更原生 Codex 外掛設定後， 請重新啟動閘道並開始新的聊天，再依賴新的 選擇結果。
命令
可從任何提供 codex 外掛命令介面的聊天介面使用
/codex computer-use 命令。這些是 OpenClaw 聊天／執行階段
命令，而不是 openclaw codex ... 命令列介面子命令：
/codex computer-use status/codex computer-use install/codex computer-use install --source <marketplace-source>/codex computer-use install --marketplace-path <path>/codex computer-use install --marketplace <name>status 是預設操作且為唯讀：它不會新增市集
來源、安裝外掛，或啟用 Codex 外掛支援。如果沒有任何設定選擇啟用
Computer Use，即使執行過一次性安裝
命令，status 仍可能回報停用。
install 會啟用 Codex app-server 外掛支援、選擇性新增
已設定的市集來源、透過 Codex app-server 安裝或重新啟用已設定的外掛、
重新載入 MCP 伺服器，並驗證 MCP
伺服器是否公開工具。由於安裝會變更受信任的主機資源，
只有擁有者或 operator.admin 閘道用戶端可以執行 install。其他
已授權的傳送者仍可繼續使用唯讀的 status 命令，
包括搭配覆寫選項使用。
較舊版本接受一次性的 --plugin、--server 與 --mcp-server
身分覆寫。請改為持續設定 computerUse.pluginName 與
computerUse.mcpServerName。使用舊版身分旗標時，
命令會指出需要持續儲存的確切設定，並在移轉指引中重複列出
所要求的操作及任何受支援的市集旗標。
市集選項
OpenClaw 使用 Codex 本身公開的相同 app-server API。
市集欄位會選擇 Codex 應從何處尋找 computer-use。
| 欄位 | 適用情況 | 安裝支援 |
|---|---|---|
| 無市集欄位 | 您希望 Codex app-server 使用它已知的市集。 | 是，當 app-server 傳回本機市集時。 |
marketplaceSource |
您有可由 app-server 新增的 Codex 市集來源。 | 是，適用於明確執行的 /codex computer-use install。 |
marketplacePath |
您已知道主機上的本機市集檔案路徑。 | 是，適用於明確安裝與回合開始時的自動安裝。 |
marketplaceName |
您希望依名稱選取已註冊的市集。 | 僅當所選市集具有本機路徑時支援。 |
全新的 Codex 主目錄可能需要一點時間來初始化其官方
市集。安裝期間，OpenClaw 會輪詢 plugin/list，最長持續
marketplaceDiscoveryTimeoutMs 毫秒（預設為 60 秒）。
如果多個已知市集包含 Computer Use，OpenClaw 會依序優先選擇
openai-bundled、openai-curated，最後是 local。未知且有歧義的
相符項目會採取封閉式失敗，並要求您設定 marketplaceName 或
marketplacePath。
隨附的 macOS 市集
目前的 ChatGPT 桌面版會在此處隨附 Computer Use；舊版獨立
Codex 桌面版則在 Codex.app 下使用相同的配置：
/Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use/Applications/Codex.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use當 computerUse.autoInstall 為 true，且未註冊任何包含
computer-use 的市集時，OpenClaw 會嘗試新增第一個存在的標準
隨附市集根目錄：
/Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled/Applications/Codex.app/Contents/Resources/plugins/openai-bundled您也可以從殼層使用 Codex 明確註冊：
codex plugin marketplace add /Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled如果您使用非標準的 Codex 應用程式路徑，請執行一次 /codex computer-use install --source <marketplace-root>，或將 computerUse.marketplacePath 設為
本機市集檔案路徑。只有在您持有
市集 JSON 檔案路徑時才使用 --marketplace-path，不要傳入隨附市集根目錄。
共用外掛快取
預設的 pluginCacheMode: "independent" 會讓每個 Codex 主目錄及其
外掛快取不受管理。設定 pluginCacheMode: "shared"，可在 app-server 啟動前將隨附的
Computer Use 外掛複製到使用中 Codex 主目錄可探索的外掛快取。
共用模式會保留較舊的快取版本，因為
執行中的 Codex 用戶端仍可能參照其帶版本號的外掛目錄；若
替換複製失敗，也會保留使用中的快取。明確設定
marketplaceName 或 marketplacePath 會停用此
調整流程，避免 OpenClaw 覆寫該選擇。
遠端目錄限制
Codex app-server 可以列出並讀取僅限遠端的目錄項目，但目前
不支援遠端 plugin/install。這表示 marketplaceName
可以選取僅限遠端的市集進行狀態檢查，但安裝與
重新啟用仍需透過 marketplaceSource 或
marketplacePath 使用本機市集。
如果狀態指出該外掛可在遠端 Codex 市集中取得，但 不支援遠端安裝，請使用本機來源或路徑執行安裝：
/codex computer-use install --source <marketplace-source>/codex computer-use install --marketplace-path <path>設定參考
| 欄位 | 預設值 | 說明 |
|---|---|---|
enabled |
推斷 | 要求使用電腦操作。設定其他任何電腦操作欄位時，預設為 true。 |
autoInstall |
false | 每次對話輪次開始時，從已探索到的市集安裝或重新啟用。 |
marketplaceDiscoveryTimeoutMs |
60000 | 安裝等待 Codex app-server 探索市集的時間。 |
liveTestTimeoutMs |
60000 | 暫時就緒執行緒及其清理請求的逾時時間。 |
toolCallTimeoutMs |
60000 | 電腦操作 list_apps 就緒工具呼叫的逾時時間。 |
healthCheckEnabled |
false | 當所屬的 app-server 用戶端處於作用中時，定期執行就緒探測。 |
healthCheckIntervalMinutes |
60 | 探測頻率；可接受的值為 30、60、120 或 240 分鐘。 |
pluginCacheMode |
independent |
使用 shared 從隨附的桌面外掛重新整理 Codex 主目錄快取。 |
strictReadiness |
false | 即時探測失敗時停止啟動，而非發出警告後繼續。 |
autoRepair |
false | 終止範圍內已失效的電腦操作 MCP 子程序，並重試失敗的探測一次。 |
marketplaceSource |
未設定 | 傳遞給 Codex app-server marketplace/add 的來源字串。 |
marketplacePath |
未設定 | 包含該外掛的本機 Codex 市集檔案路徑。 |
marketplaceName |
未設定 | 要選取的已註冊 Codex 市集名稱。 |
pluginName |
computer-use |
Codex 市集外掛名稱。 |
mcpServerName |
computer-use |
已安裝外掛公開的 MCP 伺服器名稱。 |
對話輪次開始時的自動安裝會刻意拒絕已設定的 marketplaceSource
值。新增來源是明確的設定操作，因此請先執行一次
/codex computer-use install --source <marketplace-source>，之後再讓
autoInstall 從已探索到的本機市集處理重新啟用。對話輪次開始時的自動安裝
可以使用已設定的 marketplacePath，因為它已是主機上的本機路徑。
每個欄位也接受環境變數覆寫；當對應的設定鍵未設定時會檢查該環境變數：
| 欄位 | 環境變數 |
|---|---|
enabled |
OPENCLAW_CODEX_COMPUTER_USE |
autoInstall |
OPENCLAW_CODEX_COMPUTER_USE_AUTO_INSTALL |
marketplaceDiscoveryTimeoutMs |
OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_DISCOVERY_TIMEOUT_MS |
liveTestTimeoutMs |
OPENCLAW_CODEX_COMPUTER_USE_LIVE_TEST_TIMEOUT_MS |
toolCallTimeoutMs |
OPENCLAW_CODEX_COMPUTER_USE_TOOL_CALL_TIMEOUT_MS |
healthCheckEnabled |
OPENCLAW_CODEX_COMPUTER_USE_HEALTH_CHECK_ENABLED |
healthCheckIntervalMinutes |
OPENCLAW_CODEX_COMPUTER_USE_HEALTH_CHECK_INTERVAL_MINUTES |
pluginCacheMode |
OPENCLAW_CODEX_COMPUTER_USE_PLUGIN_CACHE_MODE |
strictReadiness |
OPENCLAW_CODEX_COMPUTER_USE_STRICT_READINESS |
autoRepair |
OPENCLAW_CODEX_COMPUTER_USE_AUTO_REPAIR |
marketplaceSource |
OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_SOURCE |
marketplacePath |
OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_PATH |
marketplaceName |
OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_NAME |
pluginName |
OPENCLAW_CODEX_COMPUTER_USE_PLUGIN_NAME |
mcpServerName |
OPENCLAW_CODEX_COMPUTER_USE_MCP_SERVER_NAME |
OpenClaw 會檢查什麼
OpenClaw 會在內部回報穩定的設定原因，並為聊天格式化 面向使用者的狀態：
| 原因 | 說明 | 下一步 |
|---|---|---|
disabled |
computerUse.enabled 解析為 false。 |
設定 enabled 或其他電腦操作欄位。 |
marketplace_missing |
沒有可用的相符市集。 | 設定來源、路徑或市集名稱。 |
plugin_not_installed |
市集存在，但未安裝外掛。 | 執行安裝或啟用 autoInstall。 |
plugin_disabled |
外掛已安裝，但在 Codex 設定中停用。 | 執行安裝以重新啟用。 |
remote_install_unsupported |
選取的市集僅限遠端。 | 使用 marketplaceSource 或 marketplacePath。 |
mcp_missing |
外掛已啟用，但 MCP 伺服器無法使用。 | 檢查 Codex 電腦操作與作業系統權限。 |
ready |
外掛與 MCP 工具皆可使用。 | 開始 Codex 模式的對話輪次。 |
check_failed |
狀態檢查期間 Codex app-server 請求失敗。 | 檢查 app-server 連線與日誌。 |
auto_install_blocked |
對話輪次開始時的設定需要新增來源。 | 先執行明確安裝。 |
聊天輸出包含外掛狀態、MCP 伺服器狀態、市集、可用時的工具， 以及設定失敗步驟的特定訊息。
macOS 權限
電腦操作僅適用於 macOS。Codex 所擁有的 MCP 伺服器在檢查或控制應用程式前， 可能需要本機作業系統權限。如果 OpenClaw 表示電腦操作已安裝，但 MCP 伺服器無法使用，請先確認 Codex 端的電腦操作設定：
- Codex app-server 正在應進行桌面控制的同一台主機上執行。
- 電腦操作外掛已在 Codex 設定中啟用。
computer-useMCP 伺服器出現在 Codex app-server MCP 狀態中。- macOS 已授予桌面控制應用程式所需的權限。
- 目前的主機工作階段可以存取受控制的桌面。
當 computerUse.enabled 為 true 時，OpenClaw 會刻意採取失敗即關閉策略。
若缺少設定所要求的原生桌面工具，Codex 模式的對話輪次不應在未提示的情況下繼續。
疑難排解
狀態顯示尚未安裝。 執行 /codex computer-use install。如果未探索到
市集，請傳入 --source 或 --marketplace-path。
狀態顯示已安裝但已停用。 再次執行 /codex computer-use install。
Codex app-server 安裝會將外掛設定寫回啟用狀態。
狀態顯示不支援遠端安裝。 使用本機市集來源或路徑。僅限遠端的目錄項目 可供檢查，但無法透過目前的 app-server API 安裝。
狀態顯示 MCP 伺服器無法使用。 重新執行一次安裝，使 MCP 伺服器重新載入。如果仍無法使用，請修正 Codex 電腦操作應用程式、 Codex app-server MCP 狀態或 macOS 權限。
狀態或探測在 computer-use.list_apps 上逾時。 外掛與 MCP
伺服器皆已存在，但本機電腦操作橋接器沒有回應。結束或重新啟動 Codex
電腦操作，並視需要重新啟動 Codex Desktop，然後在新的 OpenClaw
工作階段中重試。如果主機先前透過較舊的受管理 Codex app-server 執行
電腦操作，請從桌面應用程式隨附的市集重新整理已安裝的外掛（獨立 Codex
桌面安裝請使用 Codex.app 路徑）：
/codex computer-use install --source /Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled電腦操作工具顯示 Native hook relay unavailable。 Codex 原生工具掛鉤
無法透過本機橋接器或閘道後援連線至作用中的 OpenClaw 中繼。請使用 /new
或 /reset 啟動新的 OpenClaw 工作階段。如果它成功一次，但後續工具呼叫
又再次失敗，/new 只會清除目前這次嘗試；請重新啟動 Codex app-server
或 OpenClaw 閘道，使舊執行緒與掛鉤註冊被移除，然後在新的工作階段中重試。
對話輪次開始時的自動安裝拒絕某個來源。 這是刻意設計。請先使用明確的
/codex computer-use install --source <marketplace-source> 新增來源，
之後對話輪次開始時的自動安裝即可使用已探索到的本機市集。
