CLI 後端（備援執行環境）

OpenClaw 可以將本地 AI CLI 作為純文字備援，在 API 提供者離線、被限速或暫時異常時使用。這個機制刻意保守：

工具功能停用（不發起 tool call）。
文字進、文字出（穩定可靠）。
支援 session（後續對話保持連貫）。
可傳入圖片（如果 CLI 支援圖片路徑）。

這是設計為安全網，而非主要路徑。當你需要「隨時都能用」的文字回應而不依賴外部 API 時使用。

新手快速入門

不需要任何設定就能使用 Claude Code CLI（OpenClaw 內建預設值）：

openclaw agent --message "hi" --model claude-cli/opus-4.6

Codex CLI 也能直接使用：

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

如果你的 Gateway 是透過 launchd/systemd 運行，PATH 可能很精簡，只需加上指令路徑即可：

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

就這樣。不需要額外的金鑰或驗證設定，只要 CLI 本身能用就好。

作為備援使用

把 CLI 後端加到你的備援清單，這樣只有在主要模型失敗時才會啟用：

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

注意：

如果你用了 agents.defaults.models（白名單），必須包含 claude-cli/...。
當主要提供者失敗（驗證、限速、逾時），OpenClaw 會接著嘗試 CLI 後端。

設定概覽

所有 CLI 後端都在這個路徑下：

agents.defaults.cliBackends

每筆設定以 provider id 為鍵（例如 claude-cli、my-cli）。 provider id 就是 model ref 的左半部：

<provider>/<model>

設定範例

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

運作原理

根據 provider 前綴（claude-cli/...）選擇後端。
用相同的 OpenClaw prompt + workspace 上下文組建系統提示。
執行 CLI，附帶 session id（如果支援），讓對話紀錄保持一致。
解析輸出（JSON 或純文字），回傳最終文字。
持久化 session id，後續對話會重複使用同一個 CLI session。

Sessions

如果 CLI 支援 sessions，設定 sessionArg（例如 --session-id），或 sessionArgs（使用佔位符 {sessionId}），用於需要在多個 flag 中插入 ID 的情況。
如果 CLI 使用resume 子指令且需要不同的 flag，設定 resumeArgs（resume 時取代 args），以及可選的 resumeOutput （非 JSON 的 resume 輸出格式）。
sessionMode：
- always：永遠傳送 session id（沒有儲存過的話用新的 UUID）。
- existing：只有之前存過 session id 才傳送。
- none：永遠不傳送 session id。

圖片（透傳）

如果你的 CLI 支援圖片路徑，設定 imageArg：

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

OpenClaw 會將 base64 圖片寫入暫存檔。有設定 imageArg 時，路徑會作為 CLI 參數傳入。沒有 imageArg 時，OpenClaw 會把檔案路徑附加到 prompt 中（路徑注入），對於會自動從路徑載入本地檔案的 CLI（如 Claude Code CLI）已經足夠。

輸入/輸出

output: "json"（預設）嘗試解析 JSON 並擷取文字和 session id。
output: "jsonl" 解析 JSONL 串流（Codex CLI --json），擷取最後一筆 agent 訊息及 thread_id（如果有的話）。
output: "text" 將 stdout 視為最終回應。

輸入模式：

input: "arg"（預設）將 prompt 作為最後一個 CLI 參數。
input: "stdin" 透過 stdin 傳送 prompt。
如果 prompt 太長且有設定 maxPromptArgChars，會改用 stdin。

預設值（內建）

OpenClaw 為 claude-cli 提供內建預設值：

command: "claude"
args: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions"]
resumeArgs: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]
modelArg: "--model"
systemPromptArg: "--append-system-prompt"
sessionArg: "--session-id"
systemPromptWhen: "first"
sessionMode: "always"

OpenClaw 也為 codex-cli 提供內建預設值：

command: "codex"
args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]
resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]
output: "jsonl"
resumeOutput: "text"
modelArg: "--model"
imageArg: "--image"
sessionMode: "existing"

只有需要時才覆寫（常見的是指定 command 的絕對路徑）。

限制

不支援 OpenClaw 工具（CLI 後端不會收到 tool call）。部分 CLI 可能會執行自己的 agent 工具。
不支援串流（CLI 輸出是收集完再回傳）。
結構化輸出取決於 CLI 的 JSON 格式。
Codex CLI sessions resume 時使用文字輸出（沒有 JSONL），結構性不如初始的 --json 執行。OpenClaw session 功能本身不受影響。

疑難排解

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