代理程式執行環境

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.

• 嵌入式 harness 會在 OpenClaw 已準備好的代理程式迴圈內執行。目前這包含內建的 pi 執行階段，以及已註冊的 Plugin harness，例如 codex。
• CLI 後端 會執行本機 CLI 程序，同時保持模型參照的標準形式。例如，anthropic/claude-opus-4-7 搭配 agentRuntime.id: "claude-cli" 表示「選取 Anthropic 模型，透過 Claude CLI 執行。」claude-cli 不是嵌入式 harness id，且不得傳給 AgentHarness 選取流程。

​

三個名為 Codex 的項目

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

1. 如果使用者要求 Codex 綁定/控制/執行緒/恢復/導引/停止，在內建的 codex Plugin 已啟用時，使用原生 /codex 命令介面。
2. 如果使用者要求 Codex 作為嵌入式執行階段，使用 openai/<model> 搭配 agentRuntime.id: "codex"。
3. 如果使用者要求 一般 OpenClaw 執行器上的 Codex OAuth/訂閱驗證，使用 openai-codex/<model>，並將執行階段保留為 PI。
4. 如果使用者明確提到 ACP、acpx 或 Codex ACP 配接器，使用 ACP 搭配 runtime: "acp" 和 agentId: "codex"。
5. 如果要求是針對 Claude Code、Gemini CLI、OpenCode、Cursor、Droid，或其他外部 harness，使用 ACP/acpx，而不是原生子代理程式執行階段。

​

執行階段擁有權

• 如果 OpenClaw 擁有該介面，OpenClaw 可以提供一般 Plugin hook 行為。
• 如果原生執行階段擁有該介面，OpenClaw 需要執行階段事件或原生 hook。
• 如果原生執行階段擁有標準執行緒狀態，OpenClaw 應該鏡像並投射 context，而不是改寫不受支援的內部狀態。

​

執行階段選取

1. 工作階段記錄的執行階段優先。設定變更不會將現有逐字稿熱切換到不同的原生執行緒系統。
2. OPENCLAW_AGENT_RUNTIME=<id> 會強制新工作階段或重設後工作階段使用該執行階段。
3. agents.defaults.agentRuntime.id 或 agents.list[].agentRuntime.id 可以設定 auto、pi、已註冊的嵌入式 harness id（例如 codex），或受支援的 CLI 後端別名（例如 claude-cli）。
4. 在 auto 模式中，已註冊的 Plugin 執行階段可以宣告支援的提供者/模型配對。
5. 如果在 auto 模式中沒有執行階段宣告某個回合，且已設定 fallback: "pi"（預設值），OpenClaw 會使用 PI 作為相容性備援。設定 fallback: "none" 可改為讓未匹配的 auto 模式選取失敗。

{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-7",
      agentRuntime: { id: "claude-cli" },
    },
  },
}

​

相容性契約

​

狀態標籤

• 像 openai/gpt-5.5 這樣的模型參照會告訴你所選的提供者/模型。
• 像 codex 這樣的執行階段 ID 會告訴你是哪個迴圈正在執行這一輪。
• 像 Telegram 或 Discord 這樣的頻道標籤會告訴你對話發生在哪裡。

​

相關

• Codex 執行框架
• OpenAI
• 代理執行框架 Plugin
• 代理迴圈
• 模型
• 狀態