CLI 后端

• OpenClaw 工具不会被直接注入，但带有 bundleMcp: true 的后端 可以通过回环 MCP 桥接接收网关工具。
• 对支持的 CLI 使用 JSONL 流式输出。
• 支持会话（因此后续轮次能保持连贯）。
• 如果 CLI 接受图片路径，可以透传图片。

​

适合初学者的快速开始

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

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

​

作为回退使用

{
  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（允许列表），也必须把你的 CLI 后端模型包含进去。
• 如果主提供方失败（认证、限流、超时），OpenClaw 会接着尝试 CLI 后端。

​

配置概览

agents.defaults.cliBackends

<provider>/<model>

​

配置示例

{
  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",
          // 对于带有专用 prompt-file 标志的 CLI：
          // systemPromptFileArg: "--system-file",
          // 类似 Codex 的 CLI 也可以改为指向一个 prompt 文件：
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // 仅在该后端可能在压缩前，从有界的原始 OpenClaw 转录历史中重新种子化
          // 安全失效的会话时启用
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

工作原理

1. 根据 provider 前缀选择后端（claude-cli/...）。
2. 使用相同的 OpenClaw 提示词 + 工作区上下文构建系统提示。
3. 以会话 id 执行 CLI（如果支持），以保持历史一致。 捆绑的 claude-cli 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活， 并通过 stream-json stdin 发送后续轮次。
4. 解析输出（JSON 或纯文本）并返回最终文本。
5. 按后端持久化会话 id，因此后续调用会复用同一个 CLI 会话。

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

​

会话

• 如果 CLI 支持会话，请在需要将 ID 插入多个标志时设置 sessionArg（例如 --session-id）或 sessionArgs（占位符 {sessionId}）。
• 如果 CLI 使用带有不同标志的 resume 子命令，请设置 resumeArgs（在恢复时替换 args），并可选设置 resumeOutput （用于非 JSON 恢复）。
• sessionMode：
  • always：始终发送会话 id（若未存储则使用新的 UUID）。
  • existing：仅在之前存储过会话 id 时发送。
  • none：从不发送会话 id。
• claude-cli 默认 liveSession: "claude-stdio"、output: "jsonl"， 以及 input: "stdin"，因此后续轮次会在活动期间复用同一个 Claude 进程。 现在默认使用热 stdio，包括那些省略传输字段的自定义配置。如果网关重启或空闲进程 退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。已存储的会话 id 在恢复前会与现有可读的项目转录进行验证，因此幽灵绑定会以 reason=transcript-missing 被清除，而不是在 --resume 下悄悄启动一个新的 Claude CLI 会话。
• Claude 活动会话保留有界的 JSONL 输出保护。默认允许每轮最多 8 MiB 和 20,000 行原始 JSONL。工具较多的 Claude 轮次可以按后端提升这些限制，使用 agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars 和 maxTurnLines; OpenClaw 将这些设置上限夹紧到 64 MiB 和 100,000 行。
• 存储的 CLI 会话属于提供方所有的连续性。隐式的每日会话 重置不会切断它们；/reset 和显式的 session.reset 策略仍然会 这样做。
• 新的 CLI 会话通常只会从 OpenClaw 的压缩摘要 加上压缩后的尾部重新种子化。要恢复在压缩前就失效的短会话，后端可以通过 reseedFromRawTranscriptWhenUncompacted: true 选择启用。OpenClaw 仍会对原始 转录重新种子化进行有界控制，并将其限制为安全失效场景，例如缺失 CLI 转录、系统提示/MCP 变更，或会话过期重试；认证配置文件或凭据周期更改 永远不会重新种子化原始转录历史。

• serialize: true 会保持同一通道上的运行顺序。
• 大多数 CLI 会在单个 provider 通道上序列化。
• 当所选认证身份发生变化时，OpenClaw 会放弃已存储的 CLI 会话复用，包括更改了认证配置文件 id、静态 API key、静态 token，或 CLI 暴露的 OAuth 账户身份。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 不暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。

​

claude-cli 会话中的回退前导

• 前导会优先使用最新的 /compact 摘要或 compact_boundary 标记，然后附加边界之后最近的轮次，直至达到字符预算。边界之前的轮次会被丢弃，因为摘要已经代表了它们了。
• 工具块会被合并为简洁的 (tool call: name) 和 (tool result: …) 提示，以保持提示预算真实可控。如果摘要超出长度，会标记为 (truncated)。
• 同 provider 的 claude-cli 到 claude-cli 回退依赖 Claude 自己的 --resume，并跳过前导。
• 该种子会复用现有的 Claude 会话文件路径验证，因此无法读取任意路径。

​

图片（透传）

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

​

输入 / 输出

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

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

​

默认值（插件所有）

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

• 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"]

• 回复文本从 JSON 的 response 字段中读取。
• 当 usage 缺失或为空时，使用 stats 作为回退。
• stats.cached 会被规范化为 OpenClaw 的 cacheRead。
• 如果 stats.input 缺失，OpenClaw 会通过 stats.input_tokens - stats.cached 推导输入 token。

​

插件所有的默认值

• 插件通过 api.registerCliBackend(...) 注册它们。
• 后端的 id 会成为模型引用中的提供方前缀。
• agents.defaults.cliBackends.<id> 中的用户配置仍然会覆盖插件默认值。
• 后端特定的配置清理仍通过可选的 normalizeConfig 钩子由插件所有。

api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});

​

原生压缩所有权

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

Bundle MCP 覆盖层

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

• 启动一个回环 HTTP MCP 服务器，为 CLI 进程暴露网关工具
• 使用按会话令牌（OPENCLAW_MCP_TOKEN）对桥接进行身份验证
• 将工具访问范围限定到当前会话、账号和通道上下文
• 为当前工作区加载已启用的 bundle-MCP 服务器
• 将它们与任何现有的后端 MCP 配置/设置形状合并
• 使用所属扩展中的后端所有集成模式重写启动配置

​

重设历史上限

• 该上限只约束重设提示中的先前历史块。实时会话 输出限制会在 reliability.outputLimits 下单独调优 （参见 Sessions）。

​

限制

• 不直接调用 OpenClaw 工具。 OpenClaw 不会向 CLI 后端协议注入工具调用。只有在后端选择接入 bundleMcp: true 时，后端才会看到网关工具。
• 流式传输由后端决定。 有些后端流式输出 JSONL；另一些则会缓冲直到退出。
• 结构化输出 取决于 CLI 的 JSON 格式。

​

故障排除

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

​

相关

• 网关运行手册
• 本地模型