命令列介面後端

• OpenClaw 工具不會直接注入，但具備 bundleMcp: true 的後端可以透過 loopback MCP 橋接接收閘道工具。
• 支援 JSONL 串流，適用於支援該功能的命令列介面。
• 支援工作階段，因此後續回合能保持一致。
• 如果命令列介面接受圖片路徑，圖片會直接傳遞。

​

快速開始

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

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

​

作為備援使用

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

​

設定

{
  agents: {
    defaults: {
      cliBackends: {
        "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",
          // Dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style config-override flag instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed invalidated sessions from
          // bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

運作方式

1. 依提供者前綴選擇後端（claude-cli/...）。
2. 使用相同的 OpenClaw 提示詞與工作區內容建立系統提示詞。
3. 使用工作階段 ID（若支援）執行命令列介面，讓歷史保持一致。內建的 claude-cli 後端會為每個 OpenClaw 工作階段保持一個 Claude stdio 程序存活，並透過 stream-json stdin 傳送後續回合。
4. 剖析輸出（JSON 或純文字）並回傳最終文字。
5. 依後端持久保存工作階段 ID，讓後續回合重用相同的命令列介面工作階段。

​

Claude 命令列介面細節

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

​

工作階段

• 如果命令列介面支援工作階段，請設定 sessionArg（例如 --session-id），或在 ID 需要落在多個旗標中時設定 sessionArgs（預留位置 {sessionId}）。
• 如果命令列介面使用帶有不同旗標的續接子命令，請設定 resumeArgs（續接時取代 args），並可選擇性為非 JSON 續接設定 resumeOutput。
• sessionMode：
  • always：一律傳送工作階段 ID（若未儲存則使用新的 UUID）。
  • existing：只有先前已儲存工作階段 ID 時才傳送。
  • none：絕不傳送工作階段 ID。
• claude-cli 預設為 liveSession: "claude-stdio"、output: "jsonl" 與 input: "stdin"，因此在自訂設定省略傳輸欄位時，後續回合仍會在即時 Claude 程序作用中時重用該程序。如果閘道重新啟動或閒置程序結束，OpenClaw 會從已儲存的 Claude 工作階段 ID 續接。儲存的工作階段 ID 會先驗證是否對應可讀的專案逐字稿再續接；缺少逐字稿時會清除綁定（記錄為 reason=transcript-missing），而不是在 --resume 下靜默啟動全新工作階段。
• Claude 即時工作階段會保留有界 JSONL 輸出防護：預設每回合 8 MiB 與 20,000 行原始 JSONL。可透過 agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars 與 maxTurnLines 依後端提高限制；OpenClaw 會將這些設定限制在 64 MiB 與 100,000 行。
• 儲存的命令列介面工作階段是由提供者擁有的連續性。隱含的每日工作階段重設不會切斷它們；/reset 與明確的 session.reset 政策仍會切斷。
• 新的命令列介面工作階段通常只會從 OpenClaw 的壓縮摘要加上壓縮後尾段重新播種。若要復原壓縮前失效的短工作階段，後端可透過 reseedFromRawTranscriptWhenUncompacted: true 選擇加入。原始逐字稿重新播種會維持有界，且限制於安全失效情境，例如缺少命令列介面逐字稿、孤立的工具使用尾段、訊息政策/系統提示詞/cwd/MCP 變更，或工作階段過期重試；驗證設定檔或憑證世代變更絕不會重新播種原始逐字稿歷史。

​

來自 claude-cli 工作階段的備援前導內容

• 前導內容偏好最新的 /compact 摘要或 compact_boundary 標記，然後在字元預算內附加邊界後最近的回合。邊界前回合會被丟棄，因為摘要已代表它們。
• 工具區塊會合併為精簡的 (tool call: name) 與 (tool result: …) 提示，以誠實維持提示詞預算；過大的摘要會被截斷並標示為 (truncated)。
• 同提供者的 claude-cli 到 claude-cli 備援會依賴 Claude 自身的 --resume，並跳過前導內容。
• 種子會重用現有的 Claude 工作階段檔案路徑驗證，因此無法讀取任意路徑。

​

圖片

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

​

輸入與輸出

• output: "text"（預設）會將 stdout 視為最終回應。
• output: "json" 會嘗試剖析 JSON，並擷取文字加上工作階段 ID。
• output: "jsonl" 會剖析 JSONL 串流，並在存在時擷取最終代理訊息與工作階段識別碼。
• 對於 Gemini 命令列介面 JSON 輸出，當 usage 缺少或為空時，OpenClaw 會從 response 讀取回覆文字，並從 stats 讀取用量。內建 Gemini 命令列介面預設使用 stream-json；舊的 --output-format json 覆寫仍使用 JSON 剖析器。

• input: "arg"（預設）會將提示詞作為最後一個命令列介面引數傳遞。
• input: "stdin" 會透過 stdin 傳送提示詞。
• 如果提示詞非常長且已設定 maxPromptArgChars，則會改用 stdin。

​

外掛擁有的預設值

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

• 預設的 stream-json 剖析器會讀取助理 message 事件、工具事件、最終 result 用量，以及致命 Gemini 錯誤事件。
• 如果你將 Gemini 參數覆寫為 --output-format json，OpenClaw 會將該後端正規化回 output: "json"，並從 JSON response 欄位讀取回覆文字。
• 當 usage 不存在或為空時，用量會退回使用 stats；stats.cached 會正規化為 OpenClaw cacheRead，而如果缺少 stats.input，輸入權杖會從 stats.input_tokens - stats.cached 推導而來。

​

文字轉換覆蓋層

api.registerTextTransforms({
  input: [{ from: /red basket/g, to: "blue basket" }],
  output: [{ from: /blue basket/g, to: "red basket" }],
});

​

原生壓縮所有權

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

Bundle MCP 覆蓋層

• claude-cli：產生嚴格的 MCP 設定檔。
• google-gemini-cli：產生 Gemini 系統設定檔。

• 生成一個 loopback HTTP MCP 伺服器，將閘道工具公開給命令列介面程序，並使用每個工作階段專屬權杖（OPENCLAW_MCP_TOKEN）進行驗證；
• 將工具存取範圍限定於目前工作階段、帳戶和頻道脈絡；
• 載入目前工作區啟用的 bundle-MCP 伺服器，並將它們與任何現有後端 MCP 設定/設定形狀合併；
• 使用擁有外掛的後端所擁有整合模式重寫啟動設定。

​

重新植入歷史上限

​

限制

• 無直接 OpenClaw 工具呼叫：OpenClaw 不會將工具呼叫注入命令列介面後端協定。後端只有在選擇加入 bundleMcp: true 時，才會看到閘道工具。
• 串流是後端特定的：有些後端會串流 JSONL，其他後端則會緩衝到結束才輸出。
• 結構化輸出取決於命令列介面自身的 JSON 格式。

​

疑難排解

​

相關

• 閘道 runbook
• 本機模型