6.13 CLI后端

CLI Backends 允许 OpenClaw 使用本地 AI 命令行工具作为纯文本后备方案，当 API 提供商失败时提供安全网。本文档介绍如何配置和使用 CLI 后端。

什么是 CLI Backends

CLI Backends 是本地 AI CLI 的集成方式，作为纯文本后备选项：

• 用途：当 API 提供商失败时的后备方案
• 限制：仅支持文本，不支持工具调用
• 会话：支持会话延续
• 图片：可传递图片路径

快速开始（无需配置）

直接使用内置的 CLI 后端：

使用 Claude CLI

openclaw agent --message "你好" --model claude-cli/opus-4.5

使用 Codex CLI

openclaw agent --message "你好" --model codex-cli/gpt-5.2-codex

配置 CLI Backends

配置结构

在 agents.defaults.cliBackends 中配置，键为提供商 ID：

{
  "agents": {
    "defaults": {
      "cliBackends": {
        "claude-cli": {
          "command": "claude",
          "args": ["chat"],
          "output": "text",
          "input": "arg"
        }
      }
    }
  }
}

配置字段说明

字段	类型	说明
command	string	CLI 命令路径
args	array	基本参数
output	string	输出格式："json"/"jsonl"/"text"
input	string	输入方式："arg"/"stdin"
modelArg	string	模型参数名
modelAliases	object	模型名称映射
sessionArg	string	会话 ID 参数
sessionMode	string	"always"/"existing"/"none"
systemPromptArg	string	系统提示词参数
imageArg	string	图片参数
imageMode	string	图片处理模式
serialize	boolean	是否序列化执行

后备配置

将 CLI Backend 配置为后备方案：

{
  "agents": {
    "defaults": {
      "models": [
        "anthropic:claude-3-5-sonnet",
        "claude-cli/opus-4.5"
      ],
      "fallbacks": [
        {
          "model": "claude-cli/opus-4.5",
          "on": ["auth", "rate_limit", "timeout"]
        }
      ]
    }
  }
}

工作原理

1. 路由：根据提供商前缀路由请求
2. 构建提示词：使用 OpenClaw 和工作区上下文构建系统提示词
3. 执行 CLI：使用会话 ID（如启用）执行命令
4. 解析输出：解析 JSON/JSONL/文本输出并返回文本
5. 持久化会话：按后端持久化会话 ID

会话管理

会话参数注入

使用 sessionArg 或 sessionArgs 注入 {sessionId}：

{
  "sessionArg": "--session-id",
  "sessionMode": "always"
}

会话模式

• always：总是创建或恢复会话（Claude CLI 默认）
• existing：仅恢复已知会话（Codex CLI 默认）
• none：不使用会话

恢复会话

{
  "resumeArgs": ["resume"],
  "resumeOutput": "text"
}

图片处理

使用 imageArg

将 base64 图片转为临时文件并作为 CLI 参数：

{
  "imageArg": "--image",
  "imageMode": "file"
}

无 imageArg

将图片路径注入提示词（Claude Code CLI 自动加载）：

# 图片路径会被添加到提示词中
# Claude Code CLI 会自动识别并加载

I/O 模式

JSONL 输出

解析 JSONL 流（Codex 使用）：

{
  "output": "jsonl"
}

提取最后的代理消息和 thread_id。

标准输入

当提示词过长时使用标准输入：

{
  "input": "stdin",
  "maxPromptArgChars": 10000
}

内置默认配置

Claude CLI

{
  "claude-cli": {
    "command": "claude",
    "sessionArg": "--session-id",
    "systemPromptArg": "--append-system-prompt",
    "sessionMode": "always",
    "output": "text",
    "input": "arg"
  }
}

Codex CLI

{
  "codex-cli": {
    "command": "codex",
    "output": "jsonl",
    "sessionMode": "existing",
    "resumeOutput": "text"
  }
}

限制

• 无工具调用：CLI Backend 永远不会接收工具调用
• 无流式输出：不支持流式响应
• 结构化输出：依赖 CLI 的 JSON 格式
• Codex 恢复限制：恢复时使用文本输出，结构化程度不如初始 JSON 运行

故障排查

CLI 未找到

解决方案：使用绝对路径的 command：

{
  "command": "/usr/local/bin/claude"
}

模型名称错误

解决方案：通过 modelAliases 映射：

{
  "modelAliases": {
    "opus-4.5": "claude-opus-4-5"
  }
}

无会话延续

解决方案：验证 sessionArg 和 sessionMode：

{
  "sessionArg": "--session-id",
  "sessionMode": "always"
}

图片被忽略

解决方案：设置 imageArg 并确认 CLI 接受文件路径：

{
  "imageArg": "--image",
  "imageMode": "file"
}

完整示例

配置自定义 CLI Backend：

{
  "agents": {
    "defaults": {
      "models": [
        "anthropic:claude-3-5-sonnet",
        "my-cli/custom-model"
      ],
      "cliBackends": {
        "my-cli": {
          "command": "/usr/local/bin/my-ai-cli",
          "args": ["chat"],
          "output": "json",
          "input": "arg",
          "modelArg": "--model",
          "modelAliases": {
            "custom-model": "my-model-v1"
          },
          "sessionArg": "--session",
          "sessionMode": "always",
          "systemPromptArg": "--system",
          "imageArg": "--image",
          "imageMode": "file",
          "maxPromptArgChars": 5000
        }
      },
      "fallbacks": [
        {
          "model": "my-cli/custom-model",
          "on": ["auth", "rate_limit", "timeout"]
        }
      ]
    }
  }
}