OpenClaw CLI 后端：构建“永远在线”的本地 AI 安全网

在 AI 应用的生产环境中，API 服务中断、速率限制（Rate Limit）或网络波动是不可避免的痛点。OpenClaw 的 CLI 后端（CLI Backend） 机制提供了一种优雅的解决方案：将本地安装的 AI 命令行工具（如 Claude Code CLI, Codex CLI）作为云 API 的“备胎”。

当云端路径失效时，系统自动无缝切换至本地 CLI，确保你的 AI 助手始终可用。

💡 核心设计原则

• 保守可靠：仅处理文本输入/输出，禁用工具调用（Tool Use），确保执行安全。
• 会话感知：支持传递 Session ID，保持对话上下文的连贯性。
• 图像穿透：支持通过临时文件传递图像（取决于 CLI 能力）。
• 安全网定位：专为 Fallback（故障转移） 设计，而非替代高性能云 API。

1. 快速开始：零配置体验

OpenClaw 已内置 Claude Code CLI 和 Codex CLI 的默认配置。只要本地安装了相应工具，即可直接使用。

立即试用

# 直接使用本地 Claude Code CLI
openclaw agent --message "你好" --model claude-cli/opus-4.6

# 直接使用本地 Codex CLI
openclaw agent --message "你好" --model codex-cli/gpt-5.4

修复 PATH 问题

若网关以守护进程（systemd/launchd）运行导致找不到命令，只需指定绝对路径：

// ~/.openclaw/config.json
{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude" // 指定绝对路径
        }
      }
    }
  }
}

无需 API Key，无需额外认证，即刻生效。

2. 核心机制：自动故障转移 (Failover)

CLI 后端最强大的用法是作为主模型的自动备胎。

工作流程

1. 主请求失败：云 API 返回 429 (限流), 503 (服务不可用), 或超时。
2. 自动触发：OpenClaw 检测到失败，立即尝试 fallbacks 列表中的下一个模型。
3. 无缝响应：用户收到来自本地 CLI 的回复，几乎无感知。

配置示例

{
  agents: {
    defaults: {
      model: {
        // 首选云端 Opus
        primary: "anthropic/claude-opus-4-6",
        // 备选：本地 CLI (按顺序尝试)
        fallbacks: [
          "claude-cli/opus-4.6", 
          "claude-cli/opus-4.5",
          "codex-cli/gpt-5.4" 
        ],
        // 可选：仅在特定错误码触发 fallback
        fallbackTriggers: ["rate_limit", "quota_exceeded", "timeout"]
      }
    }
  }
}

3. 深度配置：自定义 CLI 后端

所有配置位于 agents.defaults.cliBackends。键名（如 my-cli）将作为模型引用的前缀：<provider>/<model>。

完整配置参数详解

高级配置示例：自定义 LLaMA CLI

{
  agents: {
    defaults: {
      cliBackends: {
        "local-llama": {
          command: "/usr/local/bin/llama-cli",
          args: ["--interactive", "--color", "never"],
          input: "stdin",              // 通过 stdin 传递长提示
          output: "text",              // 纯文本输出
          modelArg: "-m",
          modelAliases: {
            "llama3-8b": "models/llama-3-8b.Q4_K_M.gguf"
          },
          sessionMode: "none"          // 假设该 CLI 不支持会话
        }
      }
    }
  }
}

4. 内置默认配置参考

OpenClaw 为流行 CLI 预设了最佳实践配置，可直接复用或作为模板。

Claude Code 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",
  sessionMode: "always",
  systemPromptWhen: "first"
}

Codex CLI

{
  command: "codex",
  args: ["exec", "--json", "--color", "never", "--sandbox", "read-only"],
  resumeArgs: ["exec", "resume", "{sessionId}", "--color", "never", "--sandbox", "read-only"],
  output: "jsonl",       // 流式 JSONL
  resumeOutput: "text",  // 恢复模式可能不同
  modelArg: "--model",
  imageArg: "--image",
  sessionMode: "existing"
}

5. 典型高可用场景

场景 A：家庭网络不稳定

策略：优先云 API，网络波动时自动降级为本地 CLI。

{
  model: {
    primary: "openai/gpt-4o",
    fallbacks: ["claude-cli/haiku-3.5"], // 本地快速响应
    fallbackStrategy: "sequential"
  }
}

场景 B：API 配额耗尽保护

策略：日常使用低成本云模型，配额满时切换本地免费模型。

{
  model: {
    primary: "anthropic/claude-3-haiku",
    fallbacks: ["local-llama/llama3-8b"],
    fallbackTriggers: ["quota_exceeded", "insufficient_quota"]
  }
}

场景 C：本地优先 + 云增强

策略：默认本地运行保护隐私，复杂任务手动或自动切换云端。
(注：此场景通常需手动切换模型，或通过 Agent 路由逻辑实现)

{
  model: {
    primary: "local-llama/llama3-70b",
    fallbacks: ["anthropic/claude-opus-4.6"] // 本地出错或超时才上云
  }
}

6. 故障排查指南

7. 限制与安全须知

已知限制

1. 无工具调用 (No Tool Use)：CLI 后端不会接收 OpenClaw 的工具定义（如文件读写、搜索）。它只能进行纯文本对话。
2. 非流式响应：必须等待 CLI 完整执行完毕后才能返回结果，用户体验可能有延迟。
3. 依赖 CLI 格式：严重依赖 CLI 输出的 JSON 结构稳定性。
4. Codex 恢复限制：部分 CLI 在恢复会话时可能无法输出标准 JSONL。

安全建议

• 权限隔离：CLI 以网关进程的用户身份运行，注意文件系统权限。
• 临时文件清理：图像传输会生成临时文件，确保系统有定期清理机制。
• 日志脱敏：CLI 的输出可能包含敏感信息，建议在日志配置中开启脱敏。

结语

OpenClaw 的 CLI 后端机制体现了 "可靠性优先" 的工程哲学。它不追求取代强大的云 API，而是致力于在云端失效时，提供一道坚实的本地防线。

• 对于家庭用户：它是网络波动时的定心丸。
• 对于开发者：它是测试和本地调试的利器。
• 对于企业：它是保障业务连续性的最后一道保险。

配置建议：从极简的默认配置开始，验证本地 CLI 可用性，然后将其加入 fallbacks 列表。记住：API 可能会宕机，但本地的命令行永远忠诚。