CLI 后端

Documentation Index

Fetch the complete documentation index at: https://docs2.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",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          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），或者当 ID 需要插入多个标志时设置 sessionArgs（占位符 {sessionId}）。
• 如果 CLI 使用带有不同标志的 resume 子命令，请设置 resumeArgs（恢复时替代 args），并可选择设置 resumeOutput （用于非 JSON 恢复）。
• sessionMode：
  • always：始终发送会话 ID（如果没有已存储 ID，则使用新的 UUID）。
  • existing：仅在之前已存储会话 ID 时发送。
  • none：永不发送会话 ID。
• claude-cli 默认使用 liveSession: "claude-stdio"、output: "jsonl"、 和 input: "stdin"，因此后续轮次会在活动期间复用实时 Claude 进程。现在 warm stdio 是默认行为，包括省略传输字段的自定义配置。如果 Gateway 网关重启或空闲进程退出，OpenClaw 会从已存储的 Claude 会话 ID 恢复。恢复前会根据现有可读项目 transcript 验证已存储会话 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 仍会保持原始 transcript 重新播种有界，并且仅限于安全失效，例如缺失 CLI transcript、系统提示词/MCP 变更或会话过期重试；认证配置文件或凭据纪元变更绝不会重新播种原始 transcript 历史。

• 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 缺失或为空时，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 loopback 服务器会标记 Codex 的按服务器工具审批模式，这样 MCP 调用不会因本地审批提示而停滞
• google-gemini-cli：生成 Gemini 系统设置文件

• 生成一个 loopback HTTP MCP 服务器，向 CLI 进程暴露 Gateway 网关工具
• 使用每会话 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 runbook
• 本地模型