Codex 執行框架

內建的 codex 外掛讓 OpenClaw 透過 Codex app-server 執行嵌入式 OpenAI agent 回合，而不是使用內建的 OpenClaw harness。

當你希望由 Codex 擁有低階 agent 工作階段時，請使用 Codex harness：原生執行緒續接、原生工具延續、原生壓縮，以及 app-server 執行。OpenClaw 仍然擁有聊天通道、工作階段檔案、模型選擇、OpenClaw 動態工具、核准、媒體傳遞，以及可見的 transcript 鏡像。

一般設定會使用標準 OpenAI 模型參照，例如 openai/gpt-5.5。不要設定舊版 Codex GPT 參照。將 OpenAI agent 驗證順序放在 auth.order.openai 之下；較舊的舊版 Codex 驗證設定檔 ID 和舊版 Codex 驗證順序項目，都是由 openclaw doctor --fix 修復的舊版狀態。

沒有啟用 OpenClaw sandbox 時，OpenClaw 會在啟用 Codex 原生程式碼模式的情況下啟動 Codex app-server 執行緒，同時預設保持 code-mode-only 關閉。這會讓 Codex 原生工作區與程式碼能力保持可用，同時 OpenClaw 動態工具會繼續透過 app-server item/tool/call bridge。啟用中的 OpenClaw sandboxing 和受限工具政策會完全停用原生程式碼模式，除非你選擇加入實驗性的 sandbox exec-server 路徑。

這項 Codex 原生功能不同於 OpenClaw 程式碼模式，後者是針對一般 OpenClaw 執行的選用 QuickJS-WASI runtime，並使用不同的 exec 輸入形狀。

如需了解更廣泛的模型/提供者/runtime 分工，請先閱讀 Agent runtime。簡短來說：openai/gpt-5.5 是模型參照，codex 是 runtime，而 Telegram、Discord、Slack 或其他通道仍是通訊介面。

需求

• OpenClaw，且內建的 codex 外掛可用。
• 如果你的設定使用 plugins.allow，請包含 codex。
• Codex app-server 0.125.0 或更新版本。內建外掛預設會管理相容的 Codex app-server binary，因此 PATH 上的本機 codex 命令不會影響一般 harness 啟動。
• 可透過 openclaw models auth login --provider openai 使用 Codex 驗證、agent 的 Codex home 中的 app-server 帳戶，或明確的 Codex API 金鑰驗證設定檔。

如需驗證優先順序、環境隔離、自訂 app-server 命令、模型探索，以及所有設定欄位，請參閱 Codex harness 參考。

快速開始

多數想在 OpenClaw 中使用 Codex 的使用者會想走這條路徑：使用 ChatGPT/Codex 訂閱登入、啟用內建的 codex 外掛，並使用標準 openai/gpt-* 模型參照。

使用 Codex OAuth 登入：

openclaw models auth login --provider openai

啟用內建的 codex 外掛並選取 OpenAI agent 模型：

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.5",    },  },}

如果你的設定使用 plugins.allow，也請在那裡加入 codex：

{  plugins: {    allow: ["codex"],    entries: {      codex: {        enabled: true,      },    },  },}

變更外掛設定後，請重新啟動閘道。如果現有聊天已經有工作階段，請在測試 runtime 變更前使用 /new 或 /reset，讓下一個回合從目前設定解析 harness。

設定

快速開始設定是最低可行的 Codex harness 設定。請在 OpenClaw 設定中設定 Codex harness 選項，且命令列介面只用於 Codex 驗證：

對 Codex 後端的 OpenAI agent 回合使用 openai/gpt-* 模型參照。建議使用 auth.order.openai 來設定訂閱優先/API 金鑰備援的順序。現有舊版 Codex 驗證設定檔 ID 和舊版 Codex 驗證順序是只供 doctor 處理的舊版狀態；不要寫入新的舊版 Codex GPT 參照。

不要在 Codex 後端的 agent 上設定 compaction.model 或 compaction.provider。Codex 會透過其原生 app-server 執行緒狀態進行壓縮，因此 OpenClaw 會在 runtime 忽略這些本機 summarizer 覆寫，而當 agent 使用 Codex 時，openclaw doctor --fix 會移除它們。

Lossless 仍支援作為 Codex 回合周邊的組裝、擷取與維護 context engine。請透過 plugins.slots.contextEngine: "lossless-claw" 和 plugins.entries.lossless-claw.config.summaryModel 設定它，不要透過 agents.defaults.compaction.provider。當 Codex 是啟用中的 runtime 時，openclaw doctor --fix 會把舊的 compaction.provider: "lossless-claw" 形狀遷移到 Lossless context-engine slot，但原生 Codex 仍擁有壓縮。

原生 Codex app-server harness 支援需要 pre-prompt 組裝的 context engine。一般命令列介面後端，包括 codex-cli，不提供該 host 能力。

對 Codex 後端的 agent，/compact 會在綁定的執行緒上啟動原生 Codex app-server 壓縮。OpenClaw 不會等待完成、不會施加 OpenClaw timeout、不會重新啟動共用 app-server，也不會 fallback 到 context-engine 或公開 OpenAI summarizer。如果原生 Codex 執行緒綁定遺失或過期，命令會封閉失敗，讓操作者看到真正的 runtime 邊界，而不是靜默切換壓縮後端。

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

在該形狀中，這兩個設定檔對 openai/gpt-* agent 回合仍會透過 Codex 執行。API 金鑰只是驗證 fallback，不是要求切換到 OpenClaw 或普通 OpenAI Responses。

本頁其餘部分涵蓋使用者必須選擇的常見變體：部署形狀、封閉失敗路由、guardian 核准政策、原生 Codex 外掛，以及 Computer Use。如需完整選項清單、預設值、列舉、探索、環境隔離、timeout 和 app-server transport 欄位，請參閱 Codex harness 參考。

驗證 Codex runtime

在你預期使用 Codex 的聊天中使用 /status。Codex 後端的 OpenAI agent 回合會顯示：

Runtime: OpenAI Codex

接著檢查 Codex app-server 狀態：

/codex status/codex models

/codex status 會回報 app-server 連線能力、帳戶、速率限制、MCP 伺服器和 skills。/codex models 會列出該 harness 和帳戶的即時 Codex app-server catalog。如果 /status 的結果出乎預期，請參閱疑難排解。

路由與模型選擇

將提供者參照和 runtime 政策分開：

• 使用 openai/gpt-* 透過 Codex 執行 OpenAI agent 回合。
• 不要在設定中使用舊版 Codex GPT 參照。執行 openclaw doctor --fix 來修復舊版參照和過期的工作階段路由釘選。
• 對一般 OpenAI 自動模式而言，agentRuntime.id: "codex" 是選用的，但當部署應在 Codex 不可用時封閉失敗，這會很有用。
• agentRuntime.id: "openclaw" 會在有意這樣做時，將提供者或模型選用到 OpenClaw 嵌入式 runtime。
• /codex ... 會從聊天控制原生 Codex app-server 對話。
• ACP/acpx 是獨立的外部 harness 路徑。只有在使用者要求 ACP/acpx 或外部 harness adapter 時才使用。

常見命令路由：

agents.defaults.imageModel 遵循相同的前綴分流。一般 OpenAI 路徑使用 openai/gpt-*， 只有在影像理解應透過有界的 Codex 應用程式伺服器回合執行時，才使用 codex/gpt-*。不要使用 舊版 Codex GPT 參照；doctor 會將該舊版前綴重寫為 openai/gpt-*。

部署模式

基本 Codex 部署

當所有 OpenAI agent 回合預設都應使用 Codex 時，請使用快速入門設定。

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.5",    },  },}

混合 provider 部署

此形狀會保留 Claude 作為預設 agent，並新增一個具名 Codex agent：

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "anthropic/claude-opus-4-6",    },    list: [      {        id: "main",        default: true,        model: "anthropic/claude-opus-4-6",      },      {        id: "codex",        name: "Codex",        model: "openai/gpt-5.5",      },    ],  },}

使用此設定時，main agent 會使用其一般 provider 路徑，而 codex agent 會使用 Codex 應用程式伺服器。

失敗即關閉的 Codex 部署

對 OpenAI agent 回合而言，當 bundled 外掛可用時，openai/gpt-* 已經會解析為 Codex。 當你想要明文的失敗即關閉規則時，請加入明確的執行階段政策：

{  models: {    providers: {      openai: {        agentRuntime: {          id: "codex",        },      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.5",    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

在強制使用 Codex 時，如果 Codex 外掛已停用、應用程式伺服器版本太舊， 或應用程式伺服器無法啟動，OpenClaw 會提早失敗。

應用程式伺服器政策

預設情況下，外掛會以 stdio 傳輸在本機啟動 OpenClaw 管理的 Codex binary。 只有在你刻意要執行不同可執行檔時，才設定 appServer.command。 只有當應用程式伺服器已在其他地方執行時，才使用 WebSocket 傳輸：

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",          },        },      },    },  },}

本機 stdio 應用程式伺服器工作階段預設採用受信任的本機 operator 姿態： approvalPolicy: "never"、approvalsReviewer: "user"，以及 sandbox: "danger-full-access"。如果本機 Codex 需求不允許該隱含的 YOLO 姿態， OpenClaw 會改為選取允許的 guardian 權限。當 OpenClaw sandbox 對該工作階段啟用時， OpenClaw 會在該回合停用 Codex 原生 Code Mode、使用者 MCP 伺服器，以及應用程式支援的外掛執行， 而不是依賴 Codex 主機端 sandboxing。當一般 exec/process 工具可用時， shell 存取會透過 OpenClaw sandbox 支援的動態工具公開，例如 sandbox_exec 和 sandbox_process。

當你希望 Codex 原生 auto-review 先於 sandbox 逸出或額外權限時，請使用正規化的 OpenClaw exec 模式：

{  tools: {    exec: {      mode: "auto",    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

對於 Codex 應用程式伺服器工作階段，OpenClaw 會將 tools.exec.mode: "auto" 對應到 Codex Guardian 審查的核准，通常是在本機需求允許這些值時使用 approvalPolicy: "on-request"、approvalsReviewer: "auto_review"，以及 sandbox: "workspace-write"。在 tools.exec.mode: "auto" 中，OpenClaw 不會保留舊版不安全的 Codex approvalPolicy: "never" 或 sandbox: "danger-full-access" 覆寫；若要刻意採用不需核准的 Codex 姿態，請使用 tools.exec.mode: "full"。舊版 plugins.entries.codex.config.appServer.mode: "guardian" preset 仍可運作， 但 tools.exec.mode: "auto" 是正規化的 OpenClaw 介面。

如需與主機 exec 核准和 ACPX 權限的模式層級比較，請參閱 權限模式。

如需每個應用程式伺服器欄位、驗證順序、環境隔離、探索，以及逾時行為，請參閱 Codex harness 參考。

命令與診斷

bundled 外掛會在任何支援 OpenClaw 文字命令的 channel 上註冊 /codex 作為 slash command。

原生執行與控制需要 owner 或 operator.admin 閘道 client。這包括綁定或恢復執行緒、傳送或停止回合、 變更 model、fast-mode 或權限狀態、壓縮或審查，以及 分離綁定。其他授權寄件者保留唯讀狀態、help、 account、model、thread、MCP server、skill，以及 binding 檢查命令。

常見形式：

• /codex status 會檢查應用程式伺服器連線能力、models、account、rate limits、 MCP servers，以及 Skills。
• /codex models 會列出即時 Codex 應用程式伺服器 models。
• /codex threads [filter] 會列出最近的 Codex 應用程式伺服器執行緒。
• /codex resume <thread-id> 會將目前 OpenClaw 工作階段附加到 現有 Codex 執行緒。
• /codex compact 會要求 Codex 應用程式伺服器壓縮附加的執行緒。
• /codex review 會為附加的執行緒啟動 Codex 原生審查。
• /codex diagnostics [note] 會在傳送附加執行緒的 Codex feedback 前先詢問。
• /codex account 會顯示 account 與 rate-limit 狀態。
• /codex mcp 會列出 Codex 應用程式伺服器 MCP server 狀態。
• /codex skills 會列出 Codex 應用程式伺服器 Skills。

對於大多數支援回報，請在發生 bug 的對話中從 /diagnostics [note] 開始。 它會建立一份閘道診斷報告，並針對 Codex harness 工作階段，要求核准傳送相關的 Codex feedback bundle。 如需隱私模型與群組聊天行為，請參閱 診斷匯出。

只有在你特別想要針對目前附加執行緒上傳 Codex feedback，而不需要完整閘道 診斷 bundle 時，才使用 /codex diagnostics [note]。

在本機檢查 Codex 執行緒

檢查失敗 Codex 執行的最快方式，通常是直接開啟原生 Codex 執行緒：

codex resume <thread-id>

從完成的 /diagnostics 回覆、/codex binding，或 /codex threads [filter] 取得 thread id。

如需上傳機制與執行階段層級診斷邊界，請參閱 Codex harness 執行階段。

驗證會依此順序選取：

1. agent 的有序 OpenAI 驗證設定檔，最好位於 auth.order.openai 底下。執行 openclaw doctor --fix 以遷移較舊的 舊版 Codex 驗證設定檔 id 與舊版 Codex 驗證順序。
2. 該 agent 的 Codex home 中，應用程式伺服器既有的 account。
3. 僅限本機 stdio 應用程式伺服器啟動，在沒有應用程式伺服器 account 且仍需要 OpenAI 驗證時， 使用 CODEX_API_KEY，接著使用 OPENAI_API_KEY。

當 OpenClaw 看見 ChatGPT 訂閱樣式的 Codex 驗證設定檔時，會從 spawned Codex child process 中移除 CODEX_API_KEY 和 OPENAI_API_KEY。這會讓閘道層級 API keys 仍可用於 embeddings 或直接 OpenAI models， 但避免原生 Codex 應用程式伺服器回合意外透過 API 計費。 明確的 Codex API-key 設定檔與本機 stdio env-key 後援會使用 app-server login，而不是繼承的 child-process env。WebSocket 應用程式伺服器連線不會收到閘道 env API-key 後援； 請使用明確的驗證設定檔或遠端應用程式伺服器自己的 account。 設定原生 Codex 外掛時，OpenClaw 會先透過連線的應用程式伺服器安裝或重新整理這些 外掛，然後才將外掛擁有的 apps 暴露給 Codex 執行緒。app/list 仍是 app ids、 可存取性與 metadata 的事實來源，但 OpenClaw 擁有每個執行緒的啟用 決策：如果政策允許列出的可存取 app，OpenClaw 會傳送 thread/start.config.apps[appId].enabled = true，即使 app/list 目前 回報該 app 已停用。此路徑不會為未知 ids 發明 app 安裝； OpenClaw 只會透過 plugin/install 啟用 marketplace 外掛， 然後重新整理 inventory。

如果訂閱設定檔遇到 Codex 使用量限制，OpenClaw 會在 Codex 回報 reset time 時記錄它，並針對同一個 Codex 執行嘗試下一個有序驗證設定檔。 當 reset time 過後，該訂閱設定檔會再次符合資格， 不需要變更選取的 openai/gpt-* model 或 Codex 執行階段。

對於本機 stdio 應用程式伺服器啟動，OpenClaw 會將 CODEX_HOME 設為每個 agent 專屬目錄，因此 Codex config、auth/account 檔案、外掛 cache/data，以及原生 thread 狀態，預設不會讀寫 operator 的個人 ~/.codex。 OpenClaw 會保留一般 process HOME；Codex-run subprocesses 仍可找到 user-home config 與 tokens，而 Codex 也可能發現共用的 $HOME/.agents/skills 和 $HOME/.agents/plugins/marketplace.json entries。

如果部署需要額外環境隔離，請將那些變數加入 appServer.clearEnv：

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv 只會影響 spawned Codex 應用程式伺服器 child process。 OpenClaw 會在本機啟動正規化期間，從此清單移除 CODEX_HOME 和 HOME： CODEX_HOME 保持每個 agent 專屬，而 HOME 保持繼承，讓 subprocesses 可以使用一般 user-home 狀態。

Codex 動態工具預設為 searchable 載入。OpenClaw 不會公開 會重複 Codex 原生工作區操作的動態工具：read、write、 edit、apply_patch、exec、process 和 update_plan。大多數其餘的 OpenClaw 整合工具，例如訊息、媒體、排程、瀏覽器、節點、 閘道和 heartbeat_respond，都可透過 Codex 工具搜尋在 openclaw 命名空間下使用，讓初始模型上下文更小。啟用搜尋且未選取 受管理提供者時，網頁搜尋預設使用 Codex 託管的 web_search 工具。 原生託管搜尋與 OpenClaw 受管理的 web_search 動態工具互斥，因此受管理搜尋無法繞過 原生網域限制。當託管搜尋不可用、明確停用，或由選取的受管理提供者取代時， OpenClaw 會使用受管理工具。 OpenClaw 會保持停用 Codex 獨立的 web.run 擴充功能，因為 正式環境 app-server 流量會拒絕其使用者定義的 web 命名空間。 tools.web.search.enabled: false 會停用兩條路徑，停用工具的 僅 LLM 執行也一樣。Codex 會將 "cached" 視為偏好設定，並在不受限制的 app-server 回合中將其解析為即時外部存取。當設定原生 allowedDomains 時， 自動受管理後援會失敗關閉，因此允許清單無法被繞過。持久的有效搜尋政策變更會在下一個回合前輪替已繫結的 Codex 執行緒。暫時的逐回合限制會使用臨時的受限 執行緒，並保留現有繫結以便稍後恢復。 sessions_yield 和僅訊息工具來源的回覆會保持直接，因為 那些是回合控制合約。sessions_spawn 會保持可搜尋，因此 Codex 的 原生 spawn_agent 仍是主要的 Codex 子代理介面，而明確的 OpenClaw 或 ACP 委派仍可透過 openclaw 動態 工具命名空間使用。心跳偵測協作指示會告訴 Codex 在結束心跳偵測回合前搜尋 heartbeat_respond，前提是該工具尚未 載入。

只有在連線到無法搜尋延後動態工具的自訂 Codex app-server，或偵錯完整 工具承載資料時，才設定 codexDynamicToolsLoading: "direct"。

支援的頂層 Codex 外掛欄位：

支援的 appServer 欄位：

appServer.networkProxy 是明確設定，因為它會變更 Codex 沙盒 合約。啟用時，OpenClaw 也會在 Codex 執行緒設定中設定 features.network_proxy.enabled 和 default_permissions，讓產生的權限 設定檔可以啟動 Codex 受管理網路功能。預設情況下，OpenClaw 會從 設定檔本文產生抗碰撞的 openclaw-network-<fingerprint> 設定檔名稱； 只有在需要穩定的本機名稱時才使用 profileName。

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              unixSockets: {                "/tmp/proxy.sock": "allow",                "/tmp/blocked.sock": "none",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

如果一般 app-server 執行階段會是 danger-full-access，啟用 networkProxy 會對產生的權限設定檔使用工作區樣式的檔案系統存取權。 Codex 受管理網路強制執行是沙盒化網路，因此完整存取權設定檔無法保護 輸出流量。 網域項目使用 allow 或 deny；Unix socket 項目使用 Codex 的 allow 或 none 值。

OpenClaw 擁有的動態工具呼叫會獨立於 appServer.requestTimeoutMs 受到限制：Codex item/tool/call 請求預設使用 90 秒的 OpenClaw watchdog。正數的每次呼叫 timeoutMs 引數會延長 或縮短該特定工具預算。當工具呼叫未提供自己的逾時值時，image_generate 工具會使用 agents.defaults.imageGenerationModel.timeoutMs，否則會使用 120 秒的影像生成預設值。 媒體理解 image 工具會使用 tools.media.image.timeoutSeconds 或其 60 秒媒體預設值。對於影像 理解，該逾時會套用於請求本身，且不會 因先前的準備工作而縮短。動態工具預算 上限為 600000 ms。逾時時，OpenClaw 會在支援時中止工具訊號， 並向 Codex 傳回失敗的動態工具回應，讓該回合 可以繼續，而不是讓工作階段停留在 processing。 這個 watchdog 是外層動態 item/tool/call 預算；提供者特定的 請求逾時會在該呼叫內執行，並保留自己的逾時語意。

在 Codex 接受一個回合之後，以及 OpenClaw 回應回合範圍的 app-server 請求之後，harness 會期待 Codex 在目前回合中取得進展，並 最終以 turn/completed 完成原生回合。如果 app-server 在 appServer.turnCompletionIdleTimeoutMs 期間保持靜默，OpenClaw 會盡力 中斷 Codex 回合、記錄診斷逾時，並釋放 OpenClaw 工作階段通道，讓後續聊天訊息不會排在過期的 原生回合之後。同一回合的大多數非終止通知會解除這個短 watchdog，因為 Codex 已證明該回合仍在運作。工具交接會使用 較長的工具後閒置預算：在 OpenClaw 傳回 item/tool/call 回應之後、在 commandExecution 等原生工具項目完成之後、在原始 custom_tool_call_output 完成之後，以及在工具後原始助理 進展、原始推理完成或推理進展之後。若已設定，防護會使用 appServer.postToolRawAssistantCompletionIdleTimeoutMs，否則 預設為五分鐘。相同的工具後預算也會延長 Codex 發出下一個目前回合事件前，靜默合成視窗的進展 watchdog。 全域 app-server 通知，例如速率限制更新， 不會重設回合閒置進展。推理完成、commentary agentMessage 完成，以及工具前原始推理或助理進展，可能 接著自動產生最終回覆，因此它們會使用進展後回覆 防護，而不是立即釋放工作階段通道。只有 最終/非 commentary 已完成的 agentMessage 項目與工具前原始 助理完成，才會啟動助理輸出釋放：如果 Codex 接著保持靜默 且沒有 turn/completed，OpenClaw 會盡力中斷原生回合並 釋放工作階段通道。如果另一個回合監看贏得該釋放競爭， 只要沒有原生請求、項目或動態工具完成仍處於作用中，且 助理輸出釋放仍屬於最新完成項目，並且沒有 後續項目完成，OpenClaw 仍會接受已完成的最終助理項目。 這可以在已完成工具工作之後保留最終答案，而不重播該回合。 部分助理 delta、過期的較早回覆，以及空的較晚完成 都不符合資格。可安全重播的 stdio app-server 失敗， 包括沒有助理、工具、作用中項目或副作用證據的回合完成閒置逾時， 會在新的 app-server 嘗試中重試一次。不安全的 逾時仍會淘汰卡住的 app-server 用戶端並釋放 OpenClaw 工作階段通道。它們也會清除過期的原生執行緒綁定，而不是 自動重播。完成監看逾時會顯示 Codex 特定的逾時 文字：可安全重播的案例會表示回應可能不完整，而不安全案例 會告知使用者在重試前先驗證目前狀態。公開逾時診斷 包含結構化欄位，例如最後一個 app-server 通知方法、 原始助理回應項目 id/type/role、作用中請求/項目計數，以及已啟動的 監看狀態。當最後一個通知是原始助理回應項目時，它們 也會包含受限的助理文字預覽。它們不會包含原始提示或 工具內容。

環境覆寫仍可用於本機測試：

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

當 appServer.command 未設定時，OPENCLAW_CODEX_APP_SERVER_BIN 會略過受管理的二進位檔。

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 已移除。請改用 plugins.entries.codex.config.appServer.mode: "guardian"，或使用 OPENCLAW_CODEX_APP_SERVER_MODE=guardian 進行一次性本機測試。對於 可重複部署，建議使用設定，因為它會將外掛行為保留在 與其餘 Codex harness 設定相同的已審閱檔案中。

原生 Codex 外掛

原生 Codex 外掛支援會在與 OpenClaw harness 回合相同的 Codex 執行緒中，使用 Codex app-server 自己的 app 與外掛 能力。OpenClaw 不會將 Codex 外掛轉換為合成的 codex_plugin_* OpenClaw 動態工具。

codexPlugins 只會影響選取原生 Codex harness 的工作階段。它 不會影響內建 harness 執行、一般 OpenAI 提供者執行、ACP 對話 綁定，或其他 harness。

最小遷移設定：

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",              },            },          },        },      },    },  },}

當 OpenClaw 建立 Codex harness 工作階段或取代過期的 Codex 執行緒綁定時， 會計算執行緒 app 設定。它不會在每個回合都重新計算。 變更 codexPlugins 後，請使用 /new、/reset，或重新啟動閘道，讓 未來的 Codex harness 工作階段以更新後的 app 集合啟動。

如需遷移資格、app 清單、破壞性動作政策、 elicitations，以及原生外掛診斷，請參閱 原生 Codex 外掛。

OpenAI 端的 app 與外掛存取權由已登入的 Codex 帳戶控制， 而對 Business 與 Enterprise/Edu 工作區，則也由工作區 app 控制項控制。請參閱 透過你的 ChatGPT 方案使用 Codex 以了解 OpenAI 的帳戶與工作區控制概覽。

Computer Use

Computer Use 有自己的設定指南： Codex Computer Use。

簡短版：OpenClaw 不會內建桌面控制 app，也不會自行執行 桌面動作。它會準備 Codex app-server、驗證 computer-use MCP 伺服器可用，然後讓 Codex 在 Codex 模式回合期間擁有原生 MCP 工具呼叫。

執行階段邊界

Codex harness 只會變更低層級的嵌入式代理執行器。

• 支援 OpenClaw 動態工具。Codex 會要求 OpenClaw 執行這些 工具，因此 OpenClaw 仍留在執行路徑中。
• Codex 原生 shell、patch、MCP 與原生 app 工具由 Codex 擁有。 OpenClaw 可以透過支援的 relay 觀察或封鎖選定的原生事件，但它不會重寫原生工具引數。
• Codex 擁有原生壓縮。OpenClaw 會保留轉錄鏡像，用於頻道 歷史、搜尋、/new、/reset，以及未來的模型或 harness 切換，但 它不會以 OpenClaw 或 context-engine 摘要器取代 Codex 壓縮。
• 媒體生成、媒體理解、TTS、核准，以及 messaging-tool 輸出會繼續透過相符的 OpenClaw 提供者/模型設定。
• tool_result_persist 會套用於 OpenClaw 擁有的轉錄工具結果，而不是 Codex 原生工具結果記錄。

如需 hook 層、支援的 V1 表面、原生權限處理、佇列 導向、Codex 意見回饋上傳機制，以及壓縮詳細資訊，請參閱 Codex harness 執行階段。

疑難排解

Codex 未顯示為一般 /model 提供者： 對於 新設定，這是預期行為。請選取 openai/gpt-* 模型、啟用 plugins.entries.codex.enabled，並檢查 plugins.allow 是否排除 codex。

OpenClaw 使用內建 harness 而不是 Codex： 請確認模型參照是 官方 OpenAI 提供者上的 openai/gpt-*，且 Codex 外掛已 安裝並啟用。如果測試時需要嚴格證明，請設定提供者或 模型 agentRuntime.id: "codex"。強制使用 Codex 執行階段時，若失敗會直接失敗，而不是 退回到 OpenClaw。

OpenAI Codex 執行階段退回到 API 金鑰路徑： 收集一段已遮罩的 閘道摘錄，顯示模型、執行階段、選取的提供者，以及失敗。 請受影響的協作者在其 OpenClaw 主機上執行這個唯讀命令：

(  pattern='openai/gpt-5\.[45]|openai[-]codex|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|legacy OpenAI Codex prefix|resolveSelectedOpenAIRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'   if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then    grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true  else    journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \      | grep -E -i "$pattern" || true  fi) | sed -E \    -e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \    -e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \  | tail -200

有用的摘錄通常包含 openai/gpt-5.5 或 openai/gpt-5.4、 Runtime: OpenAI Codex、agentRuntime.id 或 harnessRuntime、 candidateProvider: "openai"，以及 401、Incorrect API key 或 No API key 結果。修正後的執行應顯示 OpenAI OAuth 路徑，而不是一般 OpenAI API 金鑰失敗。

舊版 Codex 模型參照設定仍存在： 執行 openclaw doctor --fix。 Doctor 會將舊版模型參照改寫為 openai/*、移除過期的工作階段與 整個代理執行階段 pin，並保留現有的 auth-profile 覆寫。

app-server 被拒絕： 請使用 Codex app-server 0.125.0 或更新版本。 相同版本的 prerelease 或帶有 build 後綴的版本，例如 0.125.0-alpha.2 或 0.125.0+custom 會被拒絕，因為 OpenClaw 會測試 穩定版 0.125.0 協定下限。

/codex status 無法連線： 檢查 bundled codex 外掛是否 已啟用、在設定 allowlist 時 plugins.allow 是否包含它，以及 任何自訂 appServer.command、url、authToken 或 headers 是否有效。

模型探索很慢： 降低 plugins.entries.codex.config.discovery.timeoutMs 或停用探索。請參閱 Codex harness 參考。

WebSocket 傳輸立即失敗： 檢查 appServer.url、authToken、 headers，並確認遠端 app-server 使用相同的 Codex app-server 協定版本。

原生 shell 或修補工具遭到封鎖並顯示 Native hook relay unavailable： Codex 執行緒仍在嘗試使用 OpenClaw 已不再註冊的原生鉤子中繼 ID。這是原生 Codex 鉤子傳輸問題，不是 ACP 後端、提供者、GitHub 或 shell 命令失敗。在受影響的聊天中使用 /new 或 /reset 啟動新工作階段，然後重試無害的命令。如果該命令成功一次，但下一次原生工具呼叫又失敗，請只將 /new 視為暫時性因應方式：重新啟動 Codex app-server 或 OpenClaw Gateway 後，將提示複製到新的工作階段，讓舊執行緒被捨棄並重新建立原生鉤子註冊。

**非 Codex 模型使用內建 harness：**這是預期行為，除非提供者或模型執行階段政策將它路由到另一個 harness。一般非 OpenAI 提供者參照在 auto 模式下會維持其正常提供者路徑。

**Computer Use 已安裝但工具未執行：**請從新的工作階段檢查 /codex computer-use status。如果工具回報 Native hook relay unavailable，請使用上方的原生鉤子中繼復原方式。請參閱 Codex Computer Use。

相關

• Codex harness 參考
• Codex harness 執行階段
• 原生 Codex 外掛
• Codex Computer Use
• 代理執行階段
• 模型提供者
• OpenAI 提供者
• OpenAI Codex 說明
• 代理 harness 外掛
• 外掛鉤子
• 診斷匯出
• 狀態
• 測試