跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

本參考說明隨附 codex Plugin 的詳細設定。若要設定與做路由決策，請從 Codex harness 開始。

​
Plugin 設定介面

所有 Codex harness 設定都位於 plugins.entries.codex.config 之下。 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
          appServer: {
            mode: "guardian",
          },
        },
      },
    },
  },
}
支援的頂層欄位：
欄位預設值含義
discovery已啟用Codex app-server model/list 的模型探索設定。
appServer受管理的 stdio app-server傳輸、指令、驗證、核准、沙箱與逾時設定。
codexDynamicToolsLoading"searchable"使用 "direct" 將 OpenClaw 動態工具直接放入初始 Codex 工具脈絡中。
codexDynamicToolsExclude[]要從 Codex app-server 回合中略過的其他 OpenClaw 動態工具名稱。
codexPlugins已停用對已遷移、以原始碼安裝的精選 Plugin 提供原生 Codex Plugin/應用程式支援。請參閱原生 Codex Plugin。
computerUse已停用Codex Computer Use 設定。請參閱 Codex Computer Use。

​
App-server 傳輸

預設情況下，OpenClaw 會啟動隨附 Plugin 所提供的受管理 Codex 二進位檔： 
codex app-server --listen stdio://
這會讓 app-server 版本繫結到隨附的 codex Plugin，而不是本機剛好另外安裝的任何 Codex CLI。只有在你明確想執行不同可執行檔時，才設定 appServer.command。 對於已在執行的 app-server，請使用 WebSocket 傳輸： 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}
支援的 appServer 欄位：
欄位預設值含義
transport"stdio""stdio" 會產生 Codex；"websocket" 會連線到 url。
command受管理的 Codex 二進位檔stdio 傳輸使用的可執行檔。保留未設定即可使用受管理的二進位檔。
args["app-server", "--listen", "stdio://"]stdio 傳輸使用的引數。
url未設定WebSocket app-server URL。
authToken未設定WebSocket 傳輸使用的 Bearer 權杖。
headers{}額外的 WebSocket 標頭。
clearEnv[]OpenClaw 建立其繼承環境後，從產生的 stdio app-server 程序移除的額外環境變數名稱。
requestTimeoutMs60000app-server 控制平面呼叫的逾時。
turnCompletionIdleTimeoutMs60000在回合範圍的 app-server 請求之後，OpenClaw 等待 turn/completed 時使用的安靜視窗。
mode除非本機 Codex 要求不允許 YOLO，否則為 "yolo"YOLO 或經 guardian 審查執行的預設集。
approvalPolicy"never" 或允許的 guardian 核准政策傳送到執行緒開始、繼續和回合的原生 Codex 核准政策。
sandbox"danger-full-access" 或允許的 guardian 沙箱傳送到執行緒開始和繼續的原生 Codex 沙箱模式。
approvalsReviewer"user" 或允許的 guardian 審查者使用 "auto_review" 可在允許時讓 Codex 審查原生核准提示。
defaultWorkspaceDir目前程序目錄省略 --cwd 時，/codex bind 使用的工作區。
serviceTier未設定選用的 Codex app-server 服務層級。"priority" 會啟用快速模式路由，"flex" 會要求 flex 處理，而 null 會清除覆寫。舊版 "fast" 會被接受為 "priority"。
Plugin 會封鎖較舊或未版本化的 app-server 交握。Codex app-server 必須回報穩定版本 0.125.0 或更新版本。

​
核准與沙箱模式

本機 stdio app-server 工作階段預設為 YOLO 模式： approvalPolicy: "never"、approvalsReviewer: "user"，以及 sandbox: "danger-full-access"。這個受信任的本機操作者姿態，讓無人看管的 OpenClaw 回合與 Heartbeat 能夠持續推進，而不會出現沒有人能回答的原生核准提示。 如果 Codex 的本機系統要求檔不允許隱含的 YOLO 核准、審查者或沙箱值，OpenClaw 會改將隱含預設值視為 guardian，並選擇允許的 guardian 權限。同一個要求檔中符合主機名稱的 [[remote_sandbox_config]] 項目，會用於沙箱預設值決策。 設定 appServer.mode: "guardian" 以使用 Codex guardian 審查的核准： 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}
當這些值被允許時，guardian 預設集會展開為 approvalPolicy: "on-request"、approvalsReviewer: "auto_review"，以及 sandbox: "workspace-write"。個別政策欄位會覆寫 mode。較舊的 guardian_subagent 審查者值仍會作為相容別名接受，但新設定應使用 auto_review。

​
驗證與環境隔離

驗證會依下列順序選擇：
  1. 代理程式的明確 OpenClaw Codex 驗證設定檔。
  2. app-server 在該代理程式 Codex home 中的既有帳戶。
  3. 僅限本機 stdio app-server 啟動：沒有 app-server 帳戶且仍需要 OpenAI 驗證時，先使用 CODEX_API_KEY，再使用 OPENAI_API_KEY。
當 OpenClaw 看到 ChatGPT 訂閱樣式的 Codex 驗證設定檔時，會從產生的 Codex 子程序移除 CODEX_API_KEY 和 OPENAI_API_KEY。這會讓 Gateway 層級的 API 金鑰仍可用於嵌入或直接 OpenAI 模型，而不會讓原生 Codex app-server 回合意外透過 API 計費。 明確的 Codex API 金鑰設定檔和本機 stdio 環境金鑰後援會使用 app-server 登入，而不是繼承的子程序環境。WebSocket app-server 連線不會接收 Gateway 環境 API 金鑰後援；請使用明確的驗證設定檔，或遠端 app-server 自己的帳戶。 stdio app-server 啟動預設會繼承 OpenClaw 的程序環境，但 OpenClaw 擁有 Codex app-server 帳戶橋接，並將 CODEX_HOME 和 HOME 都設為該代理程式 OpenClaw 狀態底下的每代理程式目錄。Codex 自身的 Skill 載入器會讀取 $CODEX_HOME/skills 和 $HOME/.agents/skills，因此本機 app-server 啟動時這兩個值都會被隔離。這會讓 Codex 原生 Skills、Plugin、設定、帳戶與執行緒狀態限縮到 OpenClaw 代理程式，而不會從操作者的個人 Codex CLI home 外洩進來。 OpenClaw Plugin 和 OpenClaw Skill 快照仍會透過 OpenClaw 自己的 Plugin 登錄檔與 Skill 載入器流動。個人 Codex CLI 資產不會。如果你有實用的 Codex CLI Skills 或 Plugin 應成為 OpenClaw 代理程式的一部分，請明確清點它們： 
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes
如果部署需要額外的環境隔離，請將那些變數加入 appServer.clearEnv： 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}
appServer.clearEnv 只會影響產生的 Codex app-server 子程序。 在本機啟動時，CODEX_HOME 和 HOME 仍保留給 OpenClaw 的每代理程式 Codex 隔離使用。

​
動態工具

Codex 動態工具預設為 searchable 載入。OpenClaw 不會公開與 Codex 原生工作區操作重複的動態工具：
  • read
  • write
  • edit
  • apply_patch
  • exec
  • process
  • update_plan
其餘 OpenClaw 整合工具，例如訊息傳遞、工作階段、媒體、cron、 瀏覽器、節點、gateway、heartbeat_respond 和 web_search，可透過 Codex 工具搜尋在 openclaw 命名空間下使用。這能讓初始模型上下文更小。 sessions_yield 和僅限訊息工具來源的回覆會維持直接提供，因為這些是回合控制合約。 只有在連接至無法搜尋延遲動態工具的自訂 Codex app-server，或除錯完整工具酬載時，才設定 codexDynamicToolsLoading: "direct"。

​
逾時

OpenClaw 擁有的動態工具呼叫會獨立於 appServer.requestTimeoutMs 設定界限。每個 Codex item/tool/call 請求會依下列順序使用第一個可用逾時：
  • 正值的每次呼叫 timeoutMs 引數。
  • 對於 image_generate，使用 agents.defaults.imageGenerationModel.timeoutMs。
  • 對於媒體理解 image 工具，使用 tools.media.image.timeoutSeconds 轉換為毫秒，或 60 秒的媒體預設值。
  • 30 秒的動態工具預設值。
動態工具預算上限為 600000 毫秒。逾時時，OpenClaw 會在支援處中止工具訊號，並向 Codex 回傳失敗的動態工具回應，讓該回合能繼續，而不是讓工作階段停留在 processing。 OpenClaw 回應 Codex 回合範圍的 app-server 請求後，harness 也預期 Codex 以 turn/completed 完成原生回合。如果 app-server 在該回應後超過 appServer.turnCompletionIdleTimeoutMs 仍無動靜，OpenClaw 會盡力中斷 Codex 回合，記錄診斷逾時，並釋放 OpenClaw 工作階段通道，讓後續聊天訊息不會排在過期的原生回合後方。 同一回合的任何非終止通知，包括 rawResponseItem/completed，都會解除這個短監看器，因為 Codex 已證明該回合仍然存活。較長的終止監看器會繼續保護真正卡住的回合。逾時診斷包含最後一個 app-server 通知方法；對於原始助理回應項目，則包含項目類型、角色、ID，以及有界限的助理文字預覽。

​
模型探索

預設情況下，Codex Plugin 會向 app-server 要求可用模型。模型可用性由 Codex app-server 擁有，因此當 OpenClaw 升級內建的 @openai/codex 版本，或部署將 appServer.command 指向不同的 Codex 二進位檔時，清單可能會變更。可用性也可能依帳戶範圍而異。請在執行中的 gateway 上使用 /codex models，查看該 harness 和帳戶的即時目錄。 如果探索失敗或逾時，OpenClaw 會使用下列項目的內建備援目錄：
  • GPT-5.5
  • GPT-5.4 mini
  • GPT-5.2
目前內建 harness 為 @openai/codex 0.130.0。對該內建 app-server 執行的 model/list 探測回傳：
模型 ID預設隱藏輸入模態推理強度
gpt-5.5是否文字、圖片low, medium, high, xhigh
gpt-5.4否否文字、圖片low, medium, high, xhigh
gpt-5.4-mini否否文字、圖片low, medium, high, xhigh
gpt-5.3-codex否否文字、圖片low, medium, high, xhigh
gpt-5.3-codex-spark否否文字low, medium, high, xhigh
gpt-5.2否否文字、圖片low, medium, high, xhigh
隱藏模型可由 app-server 目錄針對內部或特殊流程回傳，但它們不是一般模型選擇器選項。 在 plugins.entries.codex.config.discovery 下調整探索： 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}
若想讓啟動時避免探測 Codex，並且只使用備援目錄，請停用探索： 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}

​
工作區啟動檔案

Codex 會透過原生專案文件探索自行處理 AGENTS.md。OpenClaw 不會寫入合成的 Codex 專案文件檔案，也不依賴 Codex 的 persona 檔案備援檔名，因為 Codex 備援只會在 AGENTS.md 缺少時套用。 為了維持 OpenClaw 工作區一致性，Codex harness 會解析其他啟動檔案，包括存在時的 SOUL.md、TOOLS.md、IDENTITY.md、USER.md、 HEARTBEAT.md、BOOTSTRAP.md 和 MEMORY.md，並透過 thread/start 和 thread/resume 上的 Codex 開發者指示轉送它們。 這能讓工作區 persona 和設定檔上下文在原生 Codex 行為塑形通道上可見，而不需重複 AGENTS.md。

​
環境覆寫

環境覆寫仍可用於本機測試：
  • 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 進行一次性本機測試。對於可重複的部署，建議使用設定，因為它會將 Plugin 行為保留在與其餘 Codex harness 設定相同的已審閱檔案中。

​
相關