CLI 后端(备用运行时)

当 API 提供商宕机、受速率限制或临时故障时,OpenClaw 可以运行本地 AI CLI 作为纯文本备用方案。这是有意设计得保守的:

工具已禁用(无工具调用)。
文本输入 → 文本输出(可靠)。
支持会话(因此后续轮次保持连贯)。
可以传递图像(如果 CLI 接受图像路径)。

这被设计为安全网而非主要路径。当你希望获得"始终可用"的文本响应而不依赖外部 API 时使用它。

新手友好快速入门

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

bash

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

Codex CLI 也可以开箱即用:

bash

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

如果你的网关在 launchd/systemd 下运行且 PATH 最小化,只需添加命令路径:

json5

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

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

用作备用方案

将 CLI 后端添加到备用列表中,使其仅在主模型失败时运行:

json5

{
  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/...。
如果主提供商失败(认证、速率限制、超时),OpenClaw 将尝试下一个 CLI 后端。

配置概览

所有 CLI 后端位于:

agents.defaults.cliBackends

每个条目由一个提供商 id 作为键(例如 claude-cli、my-cli)。提供商 id 成为模型引用的左侧部分:

<provider>/<model>

配置示例

json5

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

工作原理

根据提供商前缀选择后端(claude-cli/...)。
使用相同的 OpenClaw 提示词 + 工作区上下文构建系统提示词。
执行 CLI 并带上会话 id(如果支持),以保持历史一致性。
解析输出(JSON 或纯文本)并返回最终文本。
为每个后端持久化会话 id,以便后续交互复用同一 CLI 会话。

会话

如果 CLI 支持会话,设置 sessionArg(例如 --session-id) 或 sessionArgs(占位符 {sessionId}),当 ID 需要插入到多个标志中时。
如果 CLI 使用带有不同标志的恢复子命令,设置 resumeArgs(恢复时替换 args) 和可选的 resumeOutput(用于非 JSON 恢复)。
sessionMode:
- always:始终发送会话 id(如果没有存储则使用新 UUID)。
- existing:仅在之前存储过会话 id 时发送。
- none:从不发送会话 id。

图像(透传)

如果你的 CLI 接受图像路径,设置 imageArg:

json5

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

OpenClaw 将把 base64 图像写入临时文件。如果设置了 imageArg,这些路径将作为 CLI 参数传递。如果缺少 imageArg,OpenClaw 会将文件路径附加到提示词中(路径注入),这对于能从纯路径自动加载本地文件的 CLI 已足够(Claude Code CLI 行为)。

输入/输出

output: "json"(默认)尝试解析 JSON 并提取文本 + 会话 id。
output: "jsonl" 解析 JSONL 流(Codex CLI --json)并提取最后的代理消息以及 thread_id(如果存在)。
output: "text" 将 stdout 视为最终响应。

输入模式:

input: "arg"(默认)将提示词作为最后一个 CLI 参数传递。
input: "stdin" 通过 stdin 发送提示词。
如果提示词很长且设置了 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 后端从不接收工具调用)。某些 CLI 可能仍运行其自己的代理工具。
无流式传输(CLI 输出被收集后返回)。
结构化输出取决于 CLI 的 JSON 格式。
Codex CLI 会话通过文本输出恢复(无 JSONL),这比初始 --json 运行结构化程度低。OpenClaw 会话仍正常工作。

故障排除

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

CLI 后端(备用运行时) ​

新手友好快速入门 ​

用作备用方案 ​

配置概览 ​

配置示例 ​

工作原理 ​

会话 ​

图像(透传) ​

输入/输出 ​

默认值(内置) ​

限制 ​

故障排除 ​

CLI 后端(备用运行时)

新手友好快速入门

用作备用方案

配置概览

配置示例

工作原理

会话

图像(透传)

输入/输出

默认值(内置)

限制

故障排除