OpenClaw Bridge 协议：历史回顾与架构演进

 

 状态说明：已弃用 (Deprecated)

Bridge 协议（TCP/JSONL）已在当前 OpenClaw 版本中移除。

• bridge.* 配置项已失效。
• TCP 监听器（默认端口 18790）不再启动。
• 新节点客户端请统一使用 Gateway WebSocket 协议。

本文档保留作为历史参考，旨在记录 OpenClaw 架构演进的设计思路与经验教训。

1. 历史背景：为什么曾经需要 Bridge？

在 OpenClaw 的早期架构中，Bridge 协议是基于 TCP + JSONL (JSON Lines) 的节点通信标准。它在特定历史阶段解决了三个核心痛点：

1. 安全边界隔离：通过小型 allowlist 暴露有限接口，而非完整网关 API。
2. 显式准入控制：引入“配对+令牌”机制，确保只有受信任的节点能接入。
3. 控制平面分离：将高频数据平面（TCP Bridge）与管理控制平面（WebSocket）物理隔离。

随着架构成熟，这些需求已被更统一的 Gateway WebSocket 协议 完美覆盖，双协议栈反而成为了维护负担。

2. 协议回顾：设计与机制

传输层特性

• 协议：Raw TCP，每行一个 JSON 对象 (JSONL)。
• 端口：18790 (历史默认值)。
• 加密：可选 TLS (bridge.tls.enabled)。
• 发现：依赖 Bonjour/mDNS TXT 记录 (bridgeTls=1, bridgeTlsSha256)。

安全警示：mDNS TXT 记录未经签名验证。客户端绝不可将广播的 TLS 指纹视为权威信任锚，必须通过带外验证或用户确认。

握手与配对流程

Bridge 设计了严格的“先配对，后通信”流程：

消息帧类型体系

典型事件：执行生命周期

节点通过 exec.finished 或 exec.denied 上报本地命令执行结果：

{
  "type": "exec.finished",
  "payload": {
    "sessionKey": "agent-session-123",
    "runId": "exec-456",
    "command": "ls -la",
    "exitCode": 0,
    "success": true,
    "output": "总用量 32\ndrwxr-xr-x ..."
  }
}

---

3. 演进动因：为什么从 Bridge 走向 Gateway？

从 TCP Bridge 到 Unified WebSocket 的演进，是架构简化的必然选择。

核心驱动力

1. 统一即正义：消除双协议栈带来的逻辑分裂和安全策略不一致。
2. 云原生友好：WebSocket 基于 HTTP，天然适配 Kubernetes Ingress、Cloudflare Tunnel 等现代基础设施。
3. 开发体验：开发者无需编写自定义 TCP 解析器，直接使用标准 WS 库即可。

4. 迁移指南：从 Bridge 到 Gateway

对于节点客户端开发者

1. 连接层变更

// 旧：TCP Bridge
const net = require('net');
const socket = net.createConnection(18790, host);
socket.on('data', (data) => handleLine(data.toString()));

// 新：Gateway WebSocket
const WebSocket = require('ws');
const ws = new WebSocket(`wss://${host}:18789/gateway`, {
  headers: { Authorization: `Bearer ${TOKEN}` } // 认证移至 Header
});
ws.on('message', (data) => handleMessage(JSON.parse(data)));

2. 认证逻辑变更

• Bridge: 在第一条 JSON 消息 (hello) 中携带 Token。
• Gateway: 在 WebSocket 握手阶段的 HTTP Header 中携带 Authorization。

3. 消息兼容性

• 大部分 req/res/event 结构保持兼容。
• 注意 invoke 调用可能需要适配新的参数格式（参考最新 API 文档）。

对于网关运维者

1. 清理配置：从 openclaw.json 中移除所有 bridge.* 字段。
2. 调整防火墙：关闭 TCP 18790 端口，仅开放 WebSocket 18789 端口。
3. 升级客户端：强制所有连接节点升级至支持 Gateway 协议的版本。

5. 设计启示：原则比技术更持久

Bridge 协议虽然已退场，但其蕴含的设计原则被 Gateway 协议完整继承并发扬光大：

值得保留的遗产

• 最小权限 (Least Privilege)：从 allowlist 演变为更细粒度的工具策略。
• 显式信任 (Explicit Trust)：配对流程演变为更 robust 的设备认证机制。
• 事件驱动 (Event-Driven)：松耦合的异步通信模式依然是核心架构。
• 可调试性：JSONL 的清晰性在 WebSocket JSON 消息中得以延续。

演进带来的思考

• 不要过早优化：早期的双协议栈是为了隔离风险，但当统一协议足够强大时，简化才是王道。
• 拥抱标准：自定义 TCP 协议虽然灵活，但失去了 HTTP 生态的巨大红利（代理、监控、调试）。
• 网络现实：在 NAT 和防火墙遍布的今天，"看起来像 HTTP" 往往比 "高性能 TCP" 更重要。

结语

Bridge 协议是 OpenClaw 成长路上的重要里程碑。它证明了安全边界和显式授权在 AI 网关架构中的核心价值。

虽然具体的实现技术从 TCP/JSONL 演进到了 WebSocket/JSON，但核心设计哲学从未改变：

在便利性与安全性之间寻找平衡，在灵活性与标准化之间选择务实。

对于历史研究者，Bridge 文档是一份珍贵的档案；对于现行开发者，请记住：忘掉 TCP 端口，拥抱 WebSocket，让连接更简单，让安全更内建。