CLI Backends（降级运行时）

OpenClaw 可以将本地 AI CLI 作为纯文本降级后备，在 API 提供商故障、限流或临时异常时使用。这是有意保守的设计：

• 工具已禁用（无工具调用）
• 文本输入 → 文本输出（稳定可靠）
• 支持会话（后续轮次保持连贯）
• 可透传图片（如果 CLI 接受图片路径）

这是一个安全网，而非主路径。当你希望"总是能工作"的文本响应而不依赖外部 API 时，可以使用它。

新手快速入门

你可以在无需任何配置的情况下使用 Claude Code CLI（内置 Anthropic 插件会注册默认 backend）：

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",
        },
      },
    },
  },
}

就这些。无需 Key，CLI 本身的认证就够了。

如果你将内置 CLI backend 用作 Gateway 主机上的主要消息提供商，当你的配置在模型引用或 agents.defaults.cliBackends 下显式引用该 backend 时，OpenClaw 会自动加载其所属的内置插件。

作为降级使用

将 CLI backend 加入降级列表，仅在主模型失败时运行：

{
  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（allowlist），必须包含 claude-cli/...。
• 如果主提供商失败（认证、限流、超时），OpenClaw 会接着尝试 CLI backend。

配置概览

所有 CLI backend 都在以下位置配置：

agents.defaults.cliBackends

每个条目以提供商 id 为键（例如 claude-cli、my-cli）。 提供商 id 成为你的模型引用的左侧部分：

<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,
        },
      },
    },
  },
}

工作原理

1. 选择 backend：根据提供商前缀（claude-cli/...）选择。
2. 构建系统提示：使用与 OpenClaw 提示 + 工作空间上下文相同的方式。
3. 执行 CLI：带上会话 id（如果支持），保持历史一致。
4. 解析输出：JSON 或纯文本，返回最终文本。
5. 持久化会话 id：每个 backend 保存，后续使用复用同一 CLI 会话。

会话管理

• 如果 CLI 支持会话，设置 sessionArg（例如 --session-id），或设置 sessionArgs（占位符 {sessionId}）当 ID 需要插入多个参数时。
• 如果 CLI 使用resume 子命令配合不同参数，设置 resumeArgs（恢复时替换 args），可选 resumeOutput（用于非 JSON 恢复）。
• sessionMode：
  • always：始终发送会话 id（如果没有存储，则生成新 UUID）。
  • existing：只有在之前存储了会话 id 时才发送。
  • none：从不发送会话 id。

图片（透传）

如果你的 CLI 接受图片路径，设置 imageArg：

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

OpenClaw 会将 base64 图片写入临时文件。如果设置了 imageArg，这些路径会作为 CLI 参数传入。如果没有 imageArg，OpenClaw 会将文件路径追加到提示中（路径注入），这对于能从普通路径自动加载本地文件的 CLI 已经足够（Claude Code CLI 的行为）。

输入/输出格式

• output: "json"（默认）：尝试解析 JSON 并提取文本 + 会话 id。
• output: "jsonl"：解析 JSONL 流（Codex CLI --json），提取最后一条 agent 消息和 thread_id（如果存在）。
• output: "text"：将 stdout 作为最终响应。

输入模式：

• input: "arg"（默认）：将提示作为最后一个 CLI 参数传入。
• input: "stdin"：通过 stdin 发送提示。
• 如果提示很长且设置了 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 backend 默认值现在是插件接口的一部分：

• 插件通过 api.registerCliBackend(...) 注册。
• backend id 成为模型引用中的提供商前缀。
• agents.defaults.cliBackends.<id> 中的用户配置仍然可以覆盖插件默认值。
• Backend 特定的配置清理通过可选的 normalizeConfig 钩子保持在插件负责范围内。

限制

• 无 OpenClaw 工具（CLI backend 永远不会收到工具调用）。一些 CLI 可能仍然运行自己的 agent 工具。
• 无流式输出（CLI 输出收集后再返回）。
• 结构化输出取决于 CLI 的 JSON 格式。
• Codex CLI 会话通过文本输出（非 JSONL）恢复，结构不如初始 --json 运行。OpenClaw 会话仍正常工作。

故障排查

• 找不到 CLI：将 command 设置为完整路径。
• 模型名称错误：使用 modelAliases 将 provider/model 映射到 CLI 模型名。
• 无会话连续性：确保设置了 sessionArg 且 sessionMode 不是 none（Codex CLI 目前无法用 JSON 输出恢复）。
• 图片被忽略：设置 imageArg（并验证 CLI 支持文件路径）。