CLI 后端（回退运行时）

OpenClaw 可以把本地 AI CLI 当作纯文本回退来用——当 API 提供商挂了、限流了或临时抽风时，这个备用方案就派上用场了。设计上故意保守：

• 工具被禁用（不执行工具调用）。
• 文本进→文本出（稳定可靠）。
• 支持会话（后续对话仍然连贯）。
• 如果 CLI 支持图片路径，也可以传图。

这是一个安全网，不是主力。当你希望不依赖外部 API 也能”总是能得到回复”时，就用它。

新手快速上手

Claude Code CLI 不需要任何配置就能用（OpenClaw 内置了默认设置）：

openclaw agent --message "hi" --model claude-cli/opus-4.6

Codex CLI 也开箱即用：

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

如果 Gateway 跑在 launchd/systemd 下且 PATH 很精简，只需加上命令路径：

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

搞定。不需要密钥，不需要额外的认证配置——CLI 本身就够了。

作为回退使用

把 CLI 后端加到回退列表里，只有主模型失败时才会启用：

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

说明：

• 如果你用了 agents.defaults.models（白名单），必须包含 claude-cli/...。
• 主提供商失败（认证、限流、超时）时，OpenClaw 会接着尝试 CLI 后端。

配置概览

所有 CLI 后端位于：

agents.defaults.cliBackends

每个条目以提供商 id 为键（如 claude-cli、my-cli）。 提供商 id 是模型引用的左半部分：

<provider>/<model>

配置示例

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

工作原理

1. 选择后端：根据提供商前缀（claude-cli/...）匹配。
2. 构建系统提示：使用与 OpenClaw 相同的提示词 + 工作区上下文。
3. 执行 CLI：带会话 id（如果支持），保持历史一致。
4. 解析输出（JSON 或纯文本），返回最终文本。
5. 持久化会话 id：每个后端独立存储，后续对话复用同一 CLI 会话。

会话

• 如果 CLI 支持会话，设置 sessionArg（如 --session-id），或者用 sessionArgs（占位符 {sessionId}）将 ID 插入多个参数。
• 如果 CLI 用恢复子命令且参数不同，设置 resumeArgs（恢复时替换 args），可选 resumeOutput（非 JSON 恢复时用）。
• sessionMode：
  • always：始终发送会话 id（没有存储时生成新 UUID）。
  • existing：仅在之前存储过会话 id 时发送。
  • none：永不发送会话 id。

图片（透传）

如果 CLI 接受图片路径，设置 imageArg：

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

OpenClaw 会将 base64 图片写入临时文件。设置了 imageArg 时，路径通过 CLI 参数传递。没设置 imageArg 时，OpenClaw 将文件路径附加到提示内容中（路径注入方式），对于那些能自动从纯路径加载本地文件的 CLI（如 Claude Code CLI）来说够用了。

输入/输出

• output: "json"（默认）尝试解析 JSON 并提取文本 + 会话 id。
• output: "jsonl" 解析 JSONL 流（Codex CLI --json），提取最后一条 agent 消息以及 thread_id（如果有）。
• output: "text" 将 stdout 视为最终响应。

输入模式：

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

默认配置（内置）

OpenClaw 内置了 claude-cli 的默认值：

• command: "claude"
• args: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions"]
• resumeArgs: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]
• modelArg: "--model"
• systemPromptArg: "--append-system-prompt"
• sessionArg: "--session-id"
• systemPromptWhen: "first"
• sessionMode: "always"

还内置了 codex-cli 的默认值：

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

只在需要时覆盖（常见：用绝对路径的 command）。

限制

• 没有 OpenClaw 工具（CLI 后端不会收到工具调用）。部分 CLI 可能会运行自己的 agent 工具。
• 不支持流式输出（CLI 输出收集完毕后一次性返回）。
• 结构化输出取决于 CLI 的 JSON 格式。
• Codex CLI 会话恢复时使用纯文本输出（不是 JSONL），结构化程度不如首次 --json 运行。OpenClaw 的会话功能不受影响。

故障排除

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