CLI 后端

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

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

• OpenClaw 工具不会被直接注入，但带有 bundleMcp: true 的后端 可以通过回环 MCP 桥接接收网关工具。
• 对支持的 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",
          // 对于带有专用 prompt-file 标志的 CLI：
          // systemPromptFileArg: "--system-file",
          // 类似 Codex 的 CLI 也可以改为指向一个 prompt 文件：
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​

工作原理

1. 根据 provider 前缀选择后端（codex-cli/...）。
2. 使用相同的 OpenClaw 提示词 + 工作区上下文构建系统提示。
3. 执行 CLI，带上会话 id（如果支持），以便历史记录保持一致。 捆绑的 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

​

会话

• If the CLI supports sessions, set sessionArg (e.g. --session-id) or sessionArgs (placeholder {sessionId}) when the ID needs to be inserted into multiple flags.
• If the CLI uses a resume subcommand with different flags, set resumeArgs (replaces args when resuming) and optionally resumeOutput (for non-JSON resumes).
• sessionMode:
  • always: always send a session id (new UUID if none stored).
  • existing: only send a session id if one was stored before.
  • none: never send a session id.
• claude-cli defaults to liveSession: "claude-stdio", output: "jsonl", and input: "stdin" so follow-up turns reuse the live Claude process while it is active. Warm stdio is the default now, including for custom configs that omit transport fields. If the Gateway restarts or the idle process exits, OpenClaw resumes from the stored Claude session id. Stored session ids are verified against an existing readable project transcript before resume, so phantom bindings are cleared with reason=transcript-missing instead of silently starting a fresh Claude CLI session under --resume.
• Claude live sessions keep bounded JSONL output guards. Defaults allow up to 8 MiB and 20,000 raw JSONL lines per turn. Tool-heavy Claude turns can raise them per backend with agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars and maxTurnLines; OpenClaw clamps those settings to 64 MiB and 100,000 lines.
• Stored CLI sessions are provider-owned continuity. The implicit daily session reset does not cut them; /reset and explicit session.reset policies still do.

• 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 流（例如 Codex CLI --json），并在存在时提取最终的 agent 消息以及会话标识符。
• 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" },
  ],
});

​

Bundle MCP 覆盖层

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

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

​

限制

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

​

故障排除

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

​

相关

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