当API提供商故障、限流或临时异常时，OpenClaw可以使用本地AI CLI作为纯文本降级后备，确保“总有响应”。配置核心在agents.defaults.cliBackends下，需设置command路径（如/opt/homebrew/bin/claude），并通过model ref引用（如claude-cli/claude-sonnet-4-6）。默认支持Claude Code CLI、Gemini CLI，无需额外Key即可快速体验：openclaw agent --message "hi" --model claude-cli/claude-sonnet-4-6。图片透传需设置imageArg，会话连续性需配置sessionArg和sessionMode。bundleMcp:true可让CLI接收网关工具，但非直接调用。

OpenClaw CLI Backends：本地AI CLI降级配置与故障排查

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

OpenClaw 工具不会直接注入，但设置了 bundleMcp: true 的 backend 可以通过回环 MCP 桥接收网关工具。
支持 JSONL 流式输出（如果 CLI 支持）。
支持会话，后续轮次保持连贯。
图片可透传（如果 CLI 接受图片路径）。

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

如果你需要完整的 ACP（Agent Communication Protocol）运行时（含会话控制、后台任务、线程/对话绑定、持久外部编码会话），请使用 ACP Agents。CLI backends 不是 ACP。

TIP

想要构建新的 backend 插件？请参考 CLI backend 插件。本页面向配置和操作已注册 backend 的用户。

新手快速入门

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

bash

openclaw agent --message "hi" --model claude-cli/claude-sonnet-4-6

如果你的 Gateway 运行在 launchd/systemd 下且 PATH 精简，只需添加命令路径：

json5

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

无需 Key，CLI 自身的认证就够了。

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

将本地 CLI 设为 API 降级

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

json5

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

注意：

如果使用 agents.defaults.models（白名单），必须包含 claude-cli/...。
如果主提供商失败（认证、限流、超时），OpenClaw 会接着尝试 CLI backend。

配置概览

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

agents.defaults.cliBackends

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

<provider>/<model>

完整配置示例

json5

{
  agents: {
    defaults: {
      cliBackends: {
        "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",
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

工作原理

选择 backend：根据提供商前缀（claude-cli/...）选择。
构建系统提示：使用与 OpenClaw 提示 + 工作空间上下文相同的方式生成。
执行 CLI：带上会话 id（如果支持），保持历史一致。内置 claude-cli backend 会为每个 OpenClaw 会话维持一个 Claude stdio 进程，后续轮次通过 stream-json stdin 发送。
解析输出：JSON 或纯文本，返回最终文本。
持久化会话 id：每个 backend 保存，后续使用复用同一 CLI 会话。

Claude CLI 特有的行为

内置 Anthropic 的 claude-cli backend 已恢复支持（Anthropic 明确允许 OpenClaw 式用法）。OpenClaw 将技能快照以两种方式传递给 Claude CLI：紧凑技能目录附加到系统提示中，以及通过 --plugin-dir 传递临时 Claude Code 插件。插件仅包含该 agent/会话的可用技能。
Claude CLI 有自己的非交互权限模式。OpenClaw 将其映射到已有的 exec 策略：当 exec 策略为 YOLO（tools.exec.security: "full" 且 tools.exec.ask: "off"）时，OpenClaw 添加 --permission-mode bypassPermissions。每个 agent 的 agents.list[].tools.exec 设置会覆盖全局 tools.exec。要强制不同模式，可在 agents.defaults.cliBackends.claude-cli.args 中设置显式参数如 --permission-mode default，并对应设置 resumeArgs。
OpenClaw 的 /think 级别会映射到 Claude Code 的 --effort 标志（非 off 级别）。minimal/low→low，adaptive/medium→medium，high/xhigh/max→对应值。其他 CLI backend 需由所属插件声明等效 argv mapper。

使用前需在主机上登录 Claude Code：

bash

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

仅当 claude 二进制不在 PATH 上时，才设置 agents.defaults.cliBackends.claude-cli.command。

会话管理

如果 CLI 支持会话，设置 sessionArg（例如 --session-id），或 sessionArgs（占位符 {sessionId}）当 ID 需要插入多个参数时。
如果 CLI 使用 resume 子命令配合不同参数，设置 resumeArgs（恢复时替换 args），可选 resumeOutput（用于非 JSON 恢复）。
sessionMode 选项：
- always：始终发送会话 id（如果没有存储，生成新 UUID）。
- existing：只有在之前存储了会话 id 时才发送。
- none：从不发送会话 id。
claude-cli 默认使用 liveSession: "claude-stdio"、output: "jsonl" 和 input: "stdin"，因此后续轮次在活动期间会复用实时 Claude 进程。现在默认使用 warm stdio，即使自定义配置省略了传输字段。如果 Gateway 重启或空闲进程退出，OpenClaw 会从存储的 Claude 会话 id 恢复。恢复前会验证存储的会话 id 是否对应一个可读的项目转录，避免幻影绑定。
Claude 实时会话有界限的 JSONL 输出保护。默认每个轮次最多 8 MiB 和 20,000 原始 JSONL 行。工具密集型轮次可通过 agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars 和 maxTurnLines 调高，OpenClaw 会限制到 64 MiB 和 100,000 行。
存储的 CLI 会话由提供商标识。隐式的每日会话重置不会切断它们，但 /reset 和显式 session.reset 策略会。
新的 CLI 会话默认只从 OpenClaw 的压缩摘要和压缩后尾部重新播种。要恢复在压缩前失效的短会话，backend 可以设置 reseedFromRawTranscriptWhenUncompacted: true。OpenClaw 仍会限制原始转录重新播种的范围，仅用于安全失效（如缺少 CLI 转录、系统提示/MCP 变更、会话过期重试）；认证配置文件或凭据 epoch 变更不会重新播种原始转录历史。

序列化：

serialize: true 使同一通道的运行有序。
大多数 CLI 在一个提供商通道上序列化。
当选择的认证身份变化（包括认证配置文件 id、静态 API key、静态 token 或 OAuth 账户身份变更）时，OpenClaw 会丢弃存储的 CLI 会话复用。OAuth access/refresh token 轮换不会切断存储的 CLI 会话。如果 CLI 不暴露稳定 OAuth 账户 id，OpenClaw 会让该 CLI 自行执行 resume 权限。

图片透传

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

json5

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

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

输入/输出格式

output: "json"（默认）：尝试解析 JSON 并提取文本 + 会话 id。
对于 Gemini CLI JSON 输出，OpenClaw 从 response 读取回复文本，从 stats 读取用量（当 usage 缺失或为空时）。
output: "jsonl"：解析 JSONL 流，提取最后一条 agent 消息和会话标识符（如果存在）。
output: "text"：将 stdout 作为最终响应。

输入模式：

input: "arg"（默认）：将提示作为最后一个 CLI 参数传入。
input: "stdin"：通过 stdin 发送提示。
如果提示很长且设置了 maxPromptArgChars，则使用 stdin。

插件拥有的默认值

内置 Anthropic 插件为 claude-cli 注册了默认值：

command: "claude"
args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]
output: "jsonl"
input: "stdin"
modelArg: "--model"
sessionMode: "always"

内置 Google 插件为 google-gemini-cli 注册了默认值：

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

前提条件：本地 Gemini CLI 必须已安装并可通过 gemini 在 PATH 上使用（brew install gemini-cli 或 npm install -g @google/gemini-cli）。

Gemini CLI JSON 说明：

回复文本从 JSON 的 response 字段读取。
当 usage 缺失或为空时，用量从 stats 回退。
stats.cached 会被归一化为 OpenClaw 的 cacheRead。
如果 stats.input 缺失，OpenClaw 从 stats.input_tokens - stats.cached 推导输入 token。

仅在需要时覆盖（常见：绝对路径 command）。

插件拥有的默认值

CLI backend 默认值现在是插件接口的一部分：

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

插件可以通过 api.registerTextTransforms 声明双向文本转换（例如替换特定短语），无需替换整个提供商标识或 CLI backend。

Bundle MCP Overlay

CLI backend 不会直接接收 OpenClaw 工具调用，但可以通过 bundleMcp: true 选择加入生成的 MCP 配置 overlay。

当前内置行为：

claude-cli：生成严格的 MCP 配置文件。
google-gemini-cli：生成 Gemini 系统设置文件。

当启用 bundle MCP 时，OpenClaw 会：

启动一个回环 HTTP MCP 服务器，向 CLI 进程暴露网关工具。
使用每会话 token（OPENCLAW_MCP_TOKEN）认证桥接。
将工具访问范围限定在当前会话、账户和通道上下文。
加载当前工作区已启用的 bundle-MCP 服务器。
与任何已有的 backend MCP 配置/设置合并。
使用所属扩展的 backend 集成模式重写启动配置。

如果没有启用的 MCP 服务器，OpenClaw 仍然在 backend 选择 bundle MCP 时注入严格配置，确保后台运行隔离。

会话范围的 bundle MCP 运行时会被缓存，在会话内复用，空闲 mcp.sessionIdleTtlMs 毫秒后回收（默认 10 分钟；设 0 禁用）。一次性嵌入式运行（如认证探针、slug 生成、活动记忆召回）在运行结束时清理，确保 stdio 子进程和 Streamable HTTP/SSE 流不会超时运行。

限制

无直接 OpenClaw 工具调用：CLI backend 协议中不会注入工具调用。仅在 bundleMcp: true 时才能看到网关工具。
流式输出因 backend 而异：有些 backend 流式输出 JSONL，其他则缓冲到退出。
结构化输出取决于 CLI 的 JSON 格式。

故障排查

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

常见问题

使用 Claude CLI 降级时，为什么 OpenClaw 提示“CLI not found”？

将 agents.defaults.cliBackends.claude-cli.command 设置为 claude 二进制文件的绝对路径，例如 /opt/homebrew/bin/claude。如果 Gateway 运行在 launchd/systemd 下，PATH 可能不含 Homebrew 路径。

降级时能使用 OpenClaw 的工具调用吗？

不能直接调用。CLI backend 默认不接收 OpenClaw 的工具调用。如果需要，可以设置 bundleMcp: true，OpenClaw 会启动一个回环 MCP HTTP 服务器，让 CLI 进程访问网关工具。该连接使用每会话 token 认证。

Gemini CLI 作为降级时，图片怎么配置？

设置 imageArg: "@" 和 imagePathScope: "workspace"。OpenClaw 会将图片路径以 @ 前缀传入。前提是 Gemini CLI 已安装并可通过 gemini 命令调用（brew install gemini-cli 或 npm install -g @google/gemini-cli）。

OpenClaw CLI Backends：本地AI CLI降级配置与故障排查 ​

新手快速入门 ​

将本地 CLI 设为 API 降级 ​

配置概览 ​

完整配置示例 ​

工作原理 ​

Claude CLI 特有的行为 ​

会话管理 ​

图片透传 ​

输入/输出格式 ​

插件拥有的默认值 ​

插件拥有的默认值 ​

Bundle MCP Overlay ​

限制 ​

故障排查 ​

常见问题 ​

使用 Claude CLI 降级时，为什么 OpenClaw 提示“CLI not found”？ ​

降级时能使用 OpenClaw 的工具调用吗？ ​

Gemini CLI 作为降级时，图片怎么配置？ ​

OpenClaw CLI Backends：本地AI CLI降级配置与故障排查

新手快速入门

将本地 CLI 设为 API 降级

配置概览

完整配置示例

工作原理

Claude CLI 特有的行为

会话管理

图片透传

输入/输出格式

插件拥有的默认值

插件拥有的默认值

Bundle MCP Overlay

限制

故障排查

常见问题

使用 Claude CLI 降级时，为什么 OpenClaw 提示“CLI not found”？

降级时能使用 OpenClaw 的工具调用吗？

Gemini CLI 作为降级时，图片怎么配置？