CLI 后端
OpenClaw CLI 本身是一个轻量客户端，实际的计算和执行由后端（Backend）完成。本文档介绍 CLI 的后端架构和通信机制。
架构概览
text
┌──────────────────────────────────────────────┐
│ CLI 客户端 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 命令解析 │ │ TUI 渲染 │ │ 输入处理 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ┌────┴──────────────┴──────────────┴────┐ │
│ │ RPC Transport Layer │ │
│ └───────────────────┬──────────────────┘ │
└──────────────────────┼──────────────────────┘
│
┌────────┴────────┐
│ │
┌────────┴───┐ ┌───────┴────────┐
│ Gateway │ │ Embedded │
│ Backend │ │ Backend │
│ (远程RPC) │ │ (本地进程内) │
└────────────┘ └────────────────┘后端类型
Gateway Backend（网关后端）
CLI 通过 WebSocket 或 HTTP 连接到远程（或本地）的 Gateway 进程。
text
CLI ──WebSocket──▶ Gateway Daemon ──▶ LLM Provider- ✅ 共享 Gateway 的所有 Channel 和配置
- ✅ 多客户端可共享同一 Gateway
- ✅ 会话持久化
- ❌ 需要 Gateway 进程在运行
默认后端
当检测到 Gateway 正在运行时，CLI 默认使用 Gateway Backend。
Embedded Backend（嵌入式后端）
CLI 内嵌一个精简的运行时，无需 Gateway 进程即可直接与 LLM 提供商通信。
text
CLI ──HTTP──▶ LLM Provider (直连)- ✅ 无需启动 Gateway
- ✅ 适合快速单次调用
- ❌ 不支持多客户端共享
- ❌ 功能受限（无 WebSocket 事件、无设备配对等）
RPC 通信
CLI 与 Gateway Backend 之间通过 RPC（远程过程调用）通信。
通信流程
text
1. CLI 启动
├─ 检测 Gateway 是否在运行
├─ 发现 Gateway (Bonjour / 手动配置)
└─ 建立 WebSocket 连接并认证
2. 命令执行
├─ CLI 序列化命令为 RPC 请求
├─ 发送到 Gateway
├─ Gateway 处理并返回结果
└─ CLI 渲染结果
3. 交互会话
├─ CLI 维持 WebSocket 连接
├─ 实时接收流式响应
├─ 处理工具审批交互
└─ 断线自动重连RPC 消息格式
json
{
"jsonrpc": "2.0",
"method": "chat.send",
"params": {
"sessionId": "sess_abc",
"message": "Hello",
"model": "gpt-4o"
},
"id": "rpc_001"
}响应：
json
{
"jsonrpc": "2.0",
"result": {
"sessionId": "sess_abc",
"response": "Hello! How can I help you?"
},
"id": "rpc_001"
}后端选择
自动选择
CLI 按以下逻辑自动选择后端：
text
Gateway 正在运行？
├─ 是 → 使用 Gateway Backend
└─ 否 → 配置了 API Key？
├─ 是 → 使用 Embedded Backend
└─ 否 → 提示用户启动 Gateway 或配置 API Key手动指定
bash
# 强制使用 Gateway Backend
openclaw chat --backend gateway
# 强制使用 Embedded Backend
openclaw chat --backend embedded
# 指定 Gateway 地址
openclaw chat --backend gateway --gateway-url ws://192.168.1.10:18789配置默认后端
bash
openclaw config set cli.defaultBackend gateway后端能力对比
| 功能 | Gateway | Embedded |
|---|---|---|
| 多模型路由 | ✅ | ❌（单模型） |
| 流式响应 | ✅ | ✅ |
| 工具执行 | ✅ | ✅（受限） |
| 会话持久化 | ✅ | ❌ |
| 设备配对 | ✅ | ❌ |
| 多客户端共享 | ✅ | ❌ |
| 离线使用（本地模型） | ✅ | ✅ |
| 零依赖启动 | ❌ | ✅ |
连接诊断
bash
# 检查后端连接状态
openclaw status --backend
# 测试 Gateway 连接
openclaw doctor --check gateway-connection
# 查看当前使用的后端
openclaw config get cli.activeBackend输出示例：
text
Backend Status:
Type: gateway
URL: ws://127.0.0.1:18789/ws
Status: connected
Latency: 2ms
Gateway: v0.5.0
Channels: 3 available延迟优化
对于本地 Gateway，RPC 延迟通常在 1~5ms。如果延迟异常高，检查是否有防火墙或代理中间件干扰。