CLI 后端

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

适合初学者的快速开始

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

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

​

将其用作回退

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

• 如果你使用 agents.defaults.models（允许列表），也必须把你的 CLI 后端模型包含进去。
• 如果主要提供商失败（鉴权、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。

​

配置概览

agents.defaults.cliBackends

<provider>/<model>

​

配置示例

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​

工作方式

1. 根据提供商前缀（codex-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 支持会话，请设置 sessionArg（例如 --session-id）或 sessionArgs（占位符 {sessionId}），当 ID 需要插入多个标志时使用。
• 如果 CLI 使用带不同标志的恢复子命令，请设置 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 会根据现有可读项目 transcript 验证，因此幽灵绑定会以 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 策略仍然会截断。

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

​

来自 claude-cli 会话的回退前导内容

• 前导内容优先使用最新的 /compact 摘要或 compact_boundary 标记，然后在字符预算内追加边界之后最近的轮次。边界之前的轮次会被丢弃，因为摘要已经代表了它们。
• 工具块会合并为紧凑的 (tool call: name) 和 (tool result: …) 提示，以如实控制提示词预算。如果摘要溢出，会标记为 (truncated)。
• 同提供商的 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 流（例如 Codex CLI --json），并提取最终智能体消息以及存在的会话标识符。
• output: "text" 会将 stdout 视为最终响应。

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

​

默认值（插件拥有）

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

• 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" },
  ],
});

​

捆绑 MCP 覆盖层

• claude-cli：生成严格 MCP 配置文件
• codex-cli：对 mcp_servers 使用内联配置覆盖；生成的 OpenClaw 回环服务器会标记 Codex 的按服务器工具审批模式， 因此 MCP 调用不会因本地审批提示而停滞
• google-gemini-cli：生成 Gemini 系统设置文件

• 启动一个向 CLI 进程暴露 Gateway 网关工具的回环 HTTP MCP 服务器
• 使用按会话 token（OPENCLAW_MCP_TOKEN）验证桥接
• 将工具访问限定到当前会话、账号和渠道上下文
• 为当前工作区加载已启用的捆绑 MCP 服务器
• 将它们与任何现有的后端 MCP 配置/设置形状合并
• 使用所属插件提供的、由后端负责的集成模式重写启动配置

​

限制

• 没有直接的 OpenClaw 工具调用。 OpenClaw 不会把工具调用注入 CLI 后端协议。只有当后端选择启用 bundleMcp: true 时，后端才会看到 Gateway 网关工具。
• 流式传输由后端决定。 某些后端会流式传输 JSONL；其他后端会缓冲到退出。
• 结构化输出取决于 CLI 的 JSON 格式。
• Codex CLI 会话通过文本输出恢复（没有 JSONL），这比初始的 --json 运行结构化程度更低。OpenClaw 会话仍可正常工作。

​

故障排除

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

​

相关

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