設定 OpenClaw CLI 後備機制：API 故障時自動切換

當你正埋頭寫程式，API 服務卻突然掛掉或因為達到 Rate Limit 而把你擋在門外，這種挫折感我們都懂。這時候，如果有一個能直接在本地運行的備援方案，就能讓你的開發流程不被打斷。

OpenClaw 可以將 本地 AI CLI 作為 純文字備援 運行。當 API 提供商斷線、限流或暫時出現異常時，這就是你的安全網。這個功能的設計理念偏向保守：

工具已停用（不支援 tool calls）。
純文字進 → 純文字出（穩定可靠）。
支援會話（確保後續對話保持連貫）。
支援圖片透傳（如果 CLI 接受圖片路徑）。

這被設計為一個安全網，而非主要路徑。當你想要「保證有效」的文字回應，且不想依賴外部 API 時，就可以使用它。

初學者快速上手

你可以不需要任何設定就直接使用 Claude Code CLI（內建的 Anthropic 外掛已經註冊了預設的後端）：

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

Codex CLI 也能開箱即用（透過內建的 OpenAI 外掛）：

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 本身之外，不需要任何 Key 或額外的認證設定。

如果你在 Gateway 主機上使用內建的 CLI 後端作為主要訊息提供者，當你的設定在 model ref 或 agents.defaults.cliBackends 中明確引用該後端時，OpenClaw 現在會自動載入所屬的內建外掛。

將其作為備援方案

將 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-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

運作原理

選擇後端：根據 provider 前綴（claude-cli/...）來決定。
建立 System Prompt：使用與 OpenClaw 相同的 prompt + workspace context。
執行 CLI：帶上 session id（如果支援），讓對話歷史保持一致。
解析輸出（JSON 或純文字）並回傳最終文字。
持久化 Session ID：每個後端都會儲存，因此後續對話會重複使用同一個 CLI 會話。

會話 (Sessions)

如果 CLI 支援會話，請設定 sessionArg（例如 --session-id）；如果 ID 需要插入到多個 flag 中，請使用 sessionArgs（佔位符為 {sessionId}）。
如果 CLI 使用帶有不同 flag 的 resume 子指令，請設定 resumeArgs（恢復會話時會取代 args），並可選擇性設定 resumeOutput（用於非 JSON 格式的恢復輸出）。
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）並提取最後一條代理訊息，如果存在 thread_id 也會一併提取。
output: "text" 將標準輸出 (stdout) 視為最終回應。

輸入模式：

input: "arg"（預設）將 prompt 作為最後一個 CLI 參數傳遞。
input: "stdin" 透過標準輸入發送 prompt。
如果 prompt 非常長且設定了 maxPromptArgChars，則會改用 stdin。

預設值 (外掛持有)

內建的 Anthropic 外掛為 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"

內建的 OpenAI 外掛也為 codex-cli 註冊了預設值：

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

內建的 Google 外掛也為 google-gemini-cli 註冊了預設值：

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

僅在需要時進行覆寫（常見情況：設定 command 的絕對路徑）。

外掛持有的預設值

CLI 後端預設值現在是外掛介面的一部分：

外掛透過 api.registerCliBackend(...) 註冊它們。
後端 id 成為 model ref 中的 provider 前綴。
agents.defaults.cliBackends.<id> 中的使用者設定仍然會覆寫外掛預設值。
後端特定的設定清理透過選用的 normalizeConfig hook 仍由外掛持有。

限制

不支援 OpenClaw 工具（CLI 後端永遠不會收到 tool calls）。不過某些 CLI 可能仍會運行它們自己的代理工具。
不支援串流 (Streaming)（CLI 輸出會被收集後才回傳）。
結構化輸出 取決於 CLI 的 JSON 格式。
Codex CLI 會話 透過文字輸出（非 JSONL）恢復，這比初始的 --json 運行結構化程度較低。OpenClaw 會話仍可正常運作。

疑難排解

找不到 CLI：將 command 設定為完整路徑。
模型名稱錯誤：使用 modelAliases 來對應 provider/model → CLI 模型。
會話無法連貫：確保設定了 sessionArg 且 sessionMode 不是 none（Codex CLI 目前無法以 JSON 輸出恢復會話）。
圖片被忽略：設定 imageArg（並確認 CLI 支援檔案路徑）。

想要更自動化的設定體驗嗎？試試我們的 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。