CLI 後端

Documentation Index

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

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

• OpenClaw 工具不會被直接注入，但使用 bundleMcp: true 的後端可以透過 loopback 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",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

運作方式

1. 根據提供者前綴（codex-cli/...）選取後端。
2. 使用相同的 OpenClaw 提示 + 工作區內容建構系統提示。
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 支援工作階段，請設定 sessionArg（例如 --session-id），或在 ID 需要插入多個旗標時設定 sessionArgs（placeholder {sessionId}）。
• 如果 CLI 使用具有不同旗標的resume 子命令，請設定 resumeArgs（恢復時取代 args），並可選擇設定 resumeOutput （用於非 JSON resume）。
• sessionMode：
  • always：一律傳送工作階段 ID（若未儲存則使用新的 UUID）。
  • existing：只有在先前已儲存時才傳送工作階段 ID。
  • none：永不傳送工作階段 ID。
• claude-cli 預設為 liveSession: "claude-stdio"、output: "jsonl"， 以及 input: "stdin"，因此在其作用中時，後續回合會重用即時 Claude 程序。暖 stdio 現在是預設值，也包含省略傳輸欄位的自訂設定。如果 Gateway 重新啟動或閒置程序結束，OpenClaw 會從已儲存的 Claude 工作階段 ID 恢復。儲存的工作階段 ID 會在 resume 前對照現有可讀的專案 transcript 驗證，因此幽靈綁定會以 reason=transcript-missing 清除，而不是在 --resume 下悄悄啟動新的 Claude CLI 工作階段。
• Claude 即時工作階段會保留有界的 JSONL 輸出防護。預設每回合最多允許 8 MiB 和 20,000 行原始 JSONL。大量使用工具的 Claude 回合可以用 agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars 和 maxTurnLines 在每個後端提高上限；OpenClaw 會將這些設定限制在 64 MiB 和 100,000 行。
• 儲存的 CLI 工作階段是由提供者擁有的連續性。隱含的每日工作階段重設不會切斷它們；/reset 和明確的 session.reset 政策仍會切斷。
• 新的 CLI 工作階段通常只會從 OpenClaw 的 Compaction 摘要加上 Compaction 後尾端重新植入。若要復原在 Compaction 前失效的短工作階段，後端可以透過 reseedFromRawTranscriptWhenUncompacted: true 選擇加入。OpenClaw 仍會讓原始 transcript 重新植入保持有界，並將其限制於安全的失效情況，例如缺少 CLI transcript、系統提示/MCP 變更，或工作階段過期重試；驗證設定檔或憑證 epoch 變更永遠不會重新植入原始 transcript 歷史。

• serialize: true 會讓同一 lane 的執行保持有序。
• 大多數 CLI 會在一個提供者 lane 上序列化。
• 當選取的驗證身分改變時，OpenClaw 會放棄重用儲存的 CLI 工作階段，包含變更的驗證設定檔 ID、靜態 API 金鑰、靜態 token，或 CLI 有公開時的 OAuth 帳號身分。OAuth 存取與重新整理 token 輪替不會切斷儲存的 CLI 工作階段。如果 CLI 未公開穩定的 OAuth 帳號 ID，OpenClaw 會讓該 CLI 強制執行 resume 權限。

​

來自 claude-cli 工作階段的後備前言

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

​

圖片（傳遞）

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

​

輸入 / 輸出

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

• input: "arg"（預設）會將提示作為最後一個 CLI 引數傳遞。
• input: "stdin" 會透過 stdin 傳送提示。
• 如果提示非常長且已設定 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 會成為模型參照中的 provider 前綴。
• 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 覆蓋層

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

• 啟動 loopback HTTP MCP 伺服器，向 CLI 程序公開 gateway 工具
• 使用每個 session 的 token（OPENCLAW_MCP_TOKEN）驗證橋接
• 將工具存取範圍限定在目前的 session、帳戶和頻道情境
• 載入目前 workspace 已啟用的 bundle-MCP 伺服器
• 將它們與任何既有的後端 MCP 設定/設定形狀合併
• 使用擁有該後端的 extension 所擁有的整合模式，重寫啟動設定

​

限制

• 沒有直接的 OpenClaw 工具呼叫。 OpenClaw 不會將工具呼叫注入 CLI 後端協定。後端只有在選擇啟用 bundleMcp: true 時，才會看到 gateway 工具。
• 串流是後端特定的。 有些後端會串流 JSONL；其他則會緩衝直到結束。
• 結構化輸出取決於 CLI 的 JSON 格式。
• Codex CLI session會透過文字輸出續接（沒有 JSONL），其結構性不如初始的 --json 執行。OpenClaw session 仍會正常運作。

​

疑難排解

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

​

相關

• Gateway runbook
• 本機模型