CLI 後端

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.

• OpenClaw 工具不會直接注入，但具有 bundleMcp: true 的後端可以透過迴送 MCP 橋接接收 gateway 工具。
• 適用於支援的 CLI 的 JSONL 串流。
• 支援工作階段（因此後續回合會保持連貫）。
• 如果 CLI 接受圖片路徑，可以傳遞圖片。

​

適合初學者的快速開始

openclaw agent --message "hi" --model codex-cli/gpt-5.5

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}

​

作為備援使用

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["codex-cli/gpt-5.5"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.5": {},
      },
    },
  },
}

• 如果你使用 agents.defaults.models（允許清單），也必須在其中包含你的 CLI 後端模型。
• 如果主要供應商失敗（驗證、速率限制、逾時），OpenClaw 會 接著嘗試 CLI 後端。

​

設定概觀

agents.defaults.cliBackends

<provider>/<model>

​

設定範例

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​

運作方式

1. 根據供應商前綴（codex-cli/...）選取後端。
2. 使用相同的 OpenClaw prompt + 工作區脈絡建構系統 prompt。
3. 使用工作階段 ID（如果支援）執行 CLI，讓歷史保持一致。 內建的 claude-cli 後端會為每個 OpenClaw 工作階段保留一個 Claude stdio 程序，並透過 stream-json stdin 傳送後續回合。
4. 剖析輸出（JSON 或純文字）並回傳最終文字。
5. 依後端持久保存工作階段 ID，因此後續回合會重用相同的 CLI 工作階段。

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

工作階段

• 如果 CLI 支援工作階段，請在 ID 需要插入 多個旗標時設定 sessionArg（例如 --session-id）或 sessionArgs（placeholder {sessionId}）。
• 如果 CLI 使用具有不同旗標的 resume 子命令，請設定 resumeArgs（恢復時取代 args），並視需要設定 resumeOutput （用於非 JSON 恢復）。
• sessionMode：
  • always：一律傳送工作階段 ID（若未儲存則使用新的 UUID）。
  • existing：只有在先前已儲存工作階段 ID 時才傳送。
  • none：永不傳送工作階段 ID。
• claude-cli 預設為 liveSession: "claude-stdio"、output: "jsonl"， 以及 input: "stdin"，因此後續回合會在即時 Claude 程序仍作用中時重用它。 Warm stdio 現在是預設值，也包含省略 transport 欄位的自訂設定。 如果 Gateway 重新啟動或閒置程序 結束，OpenClaw 會從儲存的 Claude 工作階段 ID 恢復。儲存的工作階段 ID 會在恢復前對照現有可讀的專案 transcript 驗證，因此 phantom 綁定會以 reason=transcript-missing 清除，而不是在 --resume 底下靜默啟動新的 Claude CLI 工作階段。
• 儲存的 CLI 工作階段是供應商擁有的連續性。隱含的每日工作階段 重設不會切斷它們；/reset 和明確的 session.reset 政策仍會 這麼做。

• serialize: true 會保持同一 lane 的執行有序。
• 大多數 CLI 會在單一供應商 lane 上序列化。
• 當選取的驗證身分改變時，OpenClaw 會放棄重用已儲存的 CLI 工作階段， 包括變更的驗證設定檔 ID、靜態 API key、靜態 token，或 CLI 有公開時的 OAuth 帳戶身分。OAuth 存取與 refresh token 輪替不會切斷已儲存的 CLI 工作階段。如果 CLI 未公開 穩定的 OAuth 帳戶 ID，OpenClaw 會讓該 CLI 強制執行恢復權限。

​

來自 claude-cli 工作階段的備援前奏

• 前奏會偏好最新的 /compact 摘要或 compact_boundary 標記，然後在字元 預算內附加最近的邊界後回合。邊界前回合會被丟棄，因為摘要已經代表 它們。
• Tool 區塊會合併為精簡的 (tool call: name) 和 (tool result: …) 提示，以誠實維持 prompt 預算。如果摘要 溢出，會標示為 (truncated)。
• 同供應商的 claude-cli 到 claude-cli 備援會依賴 Claude 自己的 --resume 並略過前奏。
• 該種子會重用現有的 Claude 工作階段檔案路徑驗證，因此 無法讀取任意路徑。

​

圖片（傳遞）

imageArg: "--image",
imageMode: "repeat"

​

輸入 / 輸出

• output: "json"（預設）會嘗試剖析 JSON 並擷取文字 + 工作階段 ID。
• 對於 Gemini CLI JSON 輸出，OpenClaw 會從 response 讀取回覆文字，並在 usage 缺少或為空時 從 stats 讀取用量。
• output: "jsonl" 會剖析 JSONL 串流（例如 Codex CLI --json）並擷取最終 agent 訊息以及存在時的工作階段 識別碼。
• output: "text" 會將 stdout 視為最終回應。

• input: "arg"（預設）會將 prompt 作為最後一個 CLI 引數傳遞。
• input: "stdin" 會透過 stdin 傳送 prompt。
• 如果 prompt 很長且設定了 maxPromptArgChars，會使用 stdin。

​

預設值（Plugin 擁有）

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

• command: "gemini"
• args: ["--output-format", "json", "--prompt", "{prompt}"]
• resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• 回覆文字會從 JSON response 欄位讀取。
• 當 usage 不存在或為空時，用量會退回使用 stats。
• stats.cached 會正規化為 OpenClaw cacheRead。
• 如果缺少 stats.input，OpenClaw 會從 stats.input_tokens - stats.cached 推導輸入 token。

​

Plugin 擁有的預設值

• Plugin 使用 api.registerCliBackend(...) 註冊它們。
• 後端 id 會成為模型參照中的供應商前綴。
• agents.defaults.cliBackends.<id> 中的使用者設定仍會覆寫 Plugin 預設值。
• 後端專屬的設定清理會透過選用的 normalizeConfig hook 保持由 Plugin 擁有。

api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});

​

Bundle MCP overlays

• claude-cli：產生嚴格的 MCP 設定檔
• codex-cli：針對 mcp_servers 的 inline 設定覆寫；產生的 OpenClaw loopback 伺服器會標記 Codex 的每伺服器工具核准模式， 因此 MCP 呼叫不會因本機核准提示而停滯
• google-gemini-cli：產生 Gemini 系統設定檔

• 產生一個 loopback HTTP MCP 伺服器，將 gateway 工具暴露給 CLI 程序
• 使用每個工作階段的權杖（OPENCLAW_MCP_TOKEN）驗證橋接
• 將工具存取範圍限制在目前工作階段、帳戶和通道情境
• 載入目前工作區啟用的 bundle-MCP 伺服器
• 將它們與任何現有後端 MCP 設定/設定形狀合併
• 使用擁有 extension 的後端自有整合模式改寫啟動設定

​

限制

• 沒有直接 OpenClaw 工具呼叫。 OpenClaw 不會將工具呼叫注入 CLI 後端協定。後端只有在選擇加入 bundleMcp: true 時才會看到 gateway 工具。
• 串流因後端而異。 有些後端會串流 JSONL；其他則會緩衝到結束。
• 結構化輸出取決於 CLI 的 JSON 格式。
• Codex CLI 工作階段會透過文字輸出恢復（沒有 JSONL），這比初始 --json 執行更不具結構。OpenClaw 工作階段仍會正常運作。

​

疑難排解

• 找不到 CLI：將 command 設為完整路徑。
• 模型名稱錯誤：使用 modelAliases 將 provider/model 對應到 CLI 模型。
• 沒有工作階段連續性：請確認已設定 sessionArg，且 sessionMode 不是 none（Codex CLI 目前無法使用 JSON 輸出恢復）。
• 圖片遭忽略：設定 imageArg（並確認 CLI 支援檔案路徑）。

​

相關

• Gateway runbook
• 本機模型