CLI 后端

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

​

快速开始

openclaw agent --agent main --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: {
      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",
          // Dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style config-override flag instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed invalidated sessions from
          // bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

工作方式

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

​

Claude CLI 细节

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

​

会话

• 如果 CLI 支持会话，请设置 sessionArg（例如 --session-id），或者在 id 需要落入多个标志时设置 sessionArgs（占位符 {sessionId}）。
• 如果 CLI 使用带有不同标志的 resume 子命令，请设置 resumeArgs（恢复时替代 args），并可选择为非 JSON 恢复设置 resumeOutput。
• sessionMode：
  • always：始终发送会话 id（如果未存储则使用新的 UUID）。
  • existing：只有之前存储过会话 id 时才发送。
  • none：从不发送会话 id。
• claude-cli 默认使用 liveSession: "claude-stdio"、output: "jsonl" 和 input: "stdin"，因此在实时 Claude 进程仍活跃时，后续轮次会复用该进程，包括省略传输字段的自定义配置。如果 Gateway 网关重启或空闲进程退出，OpenClaw 会从存储的 Claude 会话 id 恢复。恢复前会根据可读的项目 transcript 验证已存储的会话 id；缺少 transcript 会清除绑定（记录为 reason=transcript-missing），而不是在 --resume 下静默启动新会话。
• 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 的压缩摘要加上压缩后尾部重新播种。要恢复压缩前失效的短会话，后端可以用 reseedFromRawTranscriptWhenUncompacted: true 选择启用。原始 transcript 重新播种保持有界，并且仅限于安全失效场景，例如缺少 CLI transcript、孤立的工具使用尾部、消息策略/系统提示词/cwd/MCP 变更，或会话过期重试；凭证配置文件或凭证 epoch 变更绝不会重新播种原始 transcript 历史。

​

来自 claude-cli 会话的回退前导上下文

• 前导上下文优先使用最新的 /compact 摘要或 compact_boundary 标记，然后在字符预算内追加最近的边界后轮次。边界前轮次会被丢弃，因为摘要已经表示了它们。
• 工具块会被合并成紧凑的 (tool call: name) 和 (tool result: …) 提示，以保持提示词预算真实；过大的摘要会被截断并标记为 (truncated)。
• 同提供商 claude-cli 到 claude-cli 的回退依赖 Claude 自己的 --resume，并跳过前导上下文。
• 该种子复用现有的 Claude 会话文件路径验证，因此无法读取任意路径。

​

图片

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

​

输入和输出

• output: "text"（默认）将 stdout 视为最终响应。
• output: "json" 会尝试解析 JSON，并提取文本和会话 id。
• output: "jsonl" 会解析 JSONL 流，并在存在时提取最终智能体消息和会话标识符。
• 对于 Gemini CLI JSON 输出，当 usage 缺失或为空时，OpenClaw 会从 response 读取回复文本，并从 stats 读取用量。内置 Gemini CLI 默认使用 stream-json；旧的 --output-format json 覆盖仍会使用 JSON 解析器。

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

​

插件拥有的默认值

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

• 默认 stream-json 解析器会读取助手 message 事件、工具事件、最终 result 用量以及致命 Gemini 错误事件。
• 如果你将 Gemini 参数覆盖为 --output-format json，OpenClaw 会把该后端规范化回 output: "json"，并从 JSON response 字段读取回复文本。
• 当 usage 缺失或为空时，用量会回退到 stats；stats.cached 会规范化为 OpenClaw cacheRead，并且如果缺少 stats.input，输入 token 会从 stats.input_tokens - stats.cached 推导。

​

文本转换覆盖层

api.registerTextTransforms({
  input: [{ from: /red basket/g, to: "blue basket" }],
  output: [{ from: /blue basket/g, to: "red basket" }],
});

​

原生压缩所有权

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

​

内置 MCP 覆盖层

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

• 启动一个 local loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程，并使用每会话 token（OPENCLAW_MCP_TOKEN）进行认证；
• 将工具访问范围限定到当前会话、账号和渠道上下文；
• 加载当前工作区启用的内置 MCP 服务器，并将其与任何现有后端 MCP 配置/设置形状合并；
• 使用所属插件提供的后端自有集成模式重写启动配置。

​

重新播种历史上限

​

限制

• 无直接 OpenClaw 工具调用：OpenClaw 不会将工具调用注入 CLI 后端协议。只有当后端选择启用 bundleMcp: true 时，后端才会看到 Gateway 网关工具。
• 流式传输因后端而异：一些后端会流式传输 JSONL，另一些会缓冲到退出时。
• 结构化输出取决于 CLI 自身的 JSON 格式。

​

故障排查

​

相关内容

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