openClaw源码解析额-第四章 网关系统
OpenClaw Gateway 是整个平台的中央控制平面，它是所有消息通道、AI 模型、Agent 会话和工具调用的交汇点。
4.1 网关架构总览
┌──────────────────┐
│ Control UI │
│ (Lit Web 组件) │
└────────┬─────────┘
│ HTTP/WS
▼
┌─────────────┐ ws ┌──────────────────┐ HTTP ┌─────────────┐
│ Channel │◄───────►│ │◄──────────►│ Native App │
│ Plugins │ │ Express Server │ │ (macOS) │
│ (Telegram, │ │ (Gateway Core) │ └─────────────┘
│ WhatsApp, │ │ │
│ Discord..) │ └────────┬─────────┘
└─────────────┘ │
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Agent A │ │ Agent B │ │ Agent C │
│ (Anthropic) │ │ (OpenAI) │ │ (Gemini) │
└─────────────┘ └─────────────┘ └─────────────┘4.2 Express HTTP 服务器
Gateway 基于 Express 5.x 构建，提供 RESTful API 和 WebSocket 服务。
4.2.1 核心路由
HTTP Routes:
├── GET /healthz # 存活检查 (Kubernetes liveness)
├── GET /readyz # 就绪检查 (Kubernetes readiness)
├── POST /v1/chat/completions # OpenAI 兼容的 Chat Completions
├── POST /v1/responses # OpenAI 兼容的 Responses
├── POST /tools/invoke # 直接工具调用
├── GET /__openclaw__/canvas/* # Canvas/A2UI 宿主
├── WS /ws # WebSocket 双向通信
└── ... # 更多内部 API4.2.2 Health Check 端点
typescript
// 存活检查 - 最轻量，仅确认进程存活
GET /healthz → 200 OK { "status": "ok" }
// 就绪检查 - 确认服务可用
GET /readyz → 200 OK {
"status": "ok",
"checks": {
"database": "connected",
"agents": "3 loaded",
"channels": "2 active"
}
}这两个端点是容器编排（Kubernetes、Fly.io）的关键接口：
healthz: 由 liveness probe 使用，失败 → 重启容器readyz: 由 readiness probe 使用，失败 → 停止路由流量
4.2.3 OpenAI 兼容端点
Gateway 提供与 OpenAI API 兼容的端点，允许标准工具和 SDK 直接接入：
bash
# POST /v1/chat/completions
curl -X POST http://localhost:18789/v1/chat/completions \
-H "Authorization: Bearer <gateway-token>" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-5",
"messages": [{"role": "user", "content": "Hello"}]
}'
# 响应格式与 OpenAI API 一致
{
"id": "chatcmpl-...",
"object": "chat.completion",
"choices": [...],
"usage": { ... }
}4.3 WebSocket 实时通信
WebSocket /ws 端点提供实时双向通信，是 Control UI 和节点通信的骨干：
4.3.1 通信架构
Client (Control UI / Node) ──WebSocket──► Gateway /ws
│
├──► 通道消息转发
├──► Agent 会话流式输出
├──► 审批请求/响应
├──► 状态更新推送
└──► 实时日志4.3.2 Gateway Protocol (src/gateway/protocol/)
网关协议定义了严格的消息类型契约，使用 Zod/TypeBox 进行 schema 定义：
typescript
// 协议类型分类
protocol/
├── channels.ts # 通道消息类型
├── agents.ts # Agent 控制消息
├── devices.ts # 设备配对和管理
├── sessions.ts # 会话管理
├── cron.ts # 定时任务
├── exec-approvals.ts # 命令审批
├── plugins.ts # 插件管理
├── secrets.ts # 凭据管理
├── push.ts # 推送通知
├── snapshots.ts # 状态快照
├── artifacts.ts # 产物传输
└── schema/ # JSON Schema 定义4.3.3 协议设计原则
- 类型安全：所有消息由 Zod/TypeBox schema 在编译时和运行时双重校验
- 向下兼容：协议变更优先采用加法式修改（新增字段、新增消息类型）
- 不兼容变更需版本化：破坏性修改必须有版本号变更和客户端同步更新
- Schema 即文档：JSON Schema 自动生成，保证协议文档与实际实现一致
4.4 Control UI
Control UI 是一个基于 Lit Web Components 的 Web 管理界面，运行在 Gateway 端口上：
http://localhost:18789/4.4.1 功能模块
- Dashboard：系统概览、Agent 状态、通道状态
- Agent 管理：创建/配置/删除 Agent
- 通道管理：管理各消息平台的连接
- 会话监控：实时查看和管理 Agent 会话
- 审批队列：查看和审批 Agent 的命令执行请求
- 日志查看：实时系统日志
- 配置编辑：在线编辑配置文件
4.4.2 A2UI / Canvas
Control UI 还包含 Canvas 宿主，允许 Agent 渲染交互式 HTML/JS 界面：
/__openclaw__/canvas/{session-id}Agent 可以通过 Canvas 向用户展示富交互内容，比如：
- 数据可视化图表
- 文件预览
- 表单交互
- 代码编辑器
4.5 Bonjour/mDNS 服务发现
Gateway 使用 @homebridge/ciao 库在局域网内广播服务：
_http._tcp OpenClaw Gateway port:18789这让同一局域网内的原生应用（macOS、iOS）可以自动发现并连接到网关。
4.5.1 安全注意
- 本地回路使用明文
ws://连接 - 私有网络
ws://需要设置OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 - Tailscale/公网使用
wss://或隧道
4.6 Gateway 生命周期管理
4.6.1 启动流程
openclaw gateway
│
├── 1. 加载并验证配置
│ ├── openclaw.yaml / openclaw.json
│ ├── schema 校验
│ └── 默认值填充
│
├── 2. 初始化 Express 服务
│ ├── 中间件注册 (CORS, body-parser, 认证)
│ ├── API 路由注册
│ └── 静态文件服务 (Control UI)
│
├── 3. 启动 WebSocket 服务
│ ├── 升级 HTTP 连接
│ └── 注册消息处理器
│
├── 4. 生成/验证 Gateway Token
│ ├── 首次启动生成随机 token
│ └── 持久化到凭据目录
│
├── 5. 加载通道插件
│ ├── 读取 manifest
│ ├── 初始化通道连接
│ └── 启动消息监听
│
├── 6. 初始化 Agent 运行时
│ ├── 加载 Agent 配置
│ ├── 启动会话管理器
│ └── 连接 AI 模型提供商
│
├── 7. 启动后台任务
│ ├── Cron 调度器
│ ├── 通道健康检查
│ └── Bonjour 广播
│
└── 8. 打开 Control UI (可选)4.6.2 运行模式
Gateway 支持多种运行模式：
| 模式 | 命令 | 特点 |
|---|---|---|
| 前台 | openclaw gateway |
直接在前台运行，stdout 输出日志 |
| 后台 | openclaw gateway --daemon |
后台运行（macOS LaunchAgent 管理） |
| 托管 | openclaw gateway restart --deep |
macOS 安装的托管模式 |
| 容器 | docker-compose up |
Docker 容器运行 |
4.6.3 健康监控
Gateway 持续监控所有通道的健康状态：
健康检查周期：
├── Telegram → 检查 Bot API 连通性
├── Discord → 检查 Gateway 连接
├── Slack → 检查 RTM/Socket Mode 连接
├── WhatsApp → 检查 WebSocket 会话
├── Matrix → 检查 homeserver 同步
└── ... → 各通道自有检查逻辑当通道异常时：
- 自动尝试重连（指数退避）
- 更新 Gateway 协议状态
- 通知 Control UI
- 记录日志
4.7 Web Push 通知
Gateway 支持 Web Push 通知，使用 web-push 库实现：
Agent 有重要更新 → Gateway → Web Push → 浏览器通知下章预告：Agent 运行时 ------ AI 模型接入、工具执行、子代理 ACP、会话管理。