CLI backends（降级 Runtime）

OpenClaw 可以运行本地 AI CLI 作为纯文本降级方案,当 API Provider 宕机、限流或临时异常时使用。这个设计刻意保守:

• 禁用工具调用（不会调用 tool）。
• 文本输入 → 文本输出（可靠）。
• 支持 Session（后续对话保持连贯）。
• 可以传递图片（如果 CLI 接受图片路径）。

这是作为安全网而非主要路径设计的。当你想要”永远可用”的文本响应,而不依赖外部 API 时使用它。

新手快速开始

你可以无需任何配置就使用 Claude Code CLI（OpenClaw 内置了默认配置）:

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

Codex CLI 也开箱即用:

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

如果你的 Gateway 运行在 launchd/systemd 下,PATH 环境变量很少,只需添加命令路径:

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

就这样。除了 CLI 本身,不需要密钥,不需要额外的认证配置。

作为降级方案使用

把 CLI backend 添加到降级列表,这样只有在主模型失败时才会运行:

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

注意:

• 如果你使用 agents.defaults.models（白名单）,必须包含 claude-cli/...。
• 如果主 Provider 失败（认证、限流、超时）,OpenClaw 会尝试下一个 CLI backend。

配置概览

所有 CLI backend 都在这个位置:

agents.defaults.cliBackends

每个条目用 provider id 作为键（例如 claude-cli、my-cli）。 provider 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-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,
        },
      },
    },
  },
}

工作原理

1. 选择 backend 基于 provider 前缀（claude-cli/...）。
2. 构建 system prompt 使用相同的 OpenClaw prompt + Workspace 上下文。
3. 执行 CLI 带上 session id（如果支持）,这样历史记录保持一致。
4. 解析输出（JSON 或纯文本）并返回最终文本。
5. 持久化 session id 按 backend 存储,后续对话复用同一个 CLI session。

Session

• 如果 CLI 支持 Session,设置 sessionArg（例如 --session-id）或 sessionArgs（占位符 {sessionId}）,当 ID 需要插入到多个标志时使用。
• 如果 CLI 使用恢复子命令且标志不同,设置 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）并提取最后一条 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", "--dangerously-skip-permissions"]
• resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--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 backend 永远不会收到工具调用）。某些 CLI 可能仍会运行自己的 agent 工具。
• 没有流式输出（CLI 输出被收集后返回）。
• 结构化输出取决于 CLI 的 JSON 格式。
• Codex CLI Session 通过文本输出恢复（没有 JSONL）,比初始 --json 运行的结构化程度低。OpenClaw Session 仍正常工作。

故障排除

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