01 OpenClaw Gateway 架构——服务型 Agent

原文：Gateway Architecture

核心差异：CLI vs Gateway

如果 Claude Code 是”你打开终端，和 AI 聊天”，那 OpenClaw 就是”AI 作为一个后台服务 7×24 运行，接受来自任何渠道的消息”。

这个差异决定了一切架构选择。

Gateway 是什么

Gateway 是一个长驻的 WebSocket 服务器（默认 127.0.0.1:18789），它是整个系统的中枢：

                    ┌── WhatsApp（via Baileys）
                    ├── Telegram（via grammY）
         消息渠道 ──├── Slack
                    ├── Discord
                    └── Signal / iMessage / WebChat

         控制面 ──── macOS App / CLI / Web UI / 自动化脚本
              │
              └───→ Gateway（WebSocket Server）
                      │
                      ├── Agent Runtime（pi-agent-core）
                      ├── Session Store
                      ├── Memory Store
                      └── Tool Executor

一台主机只有一个 Gateway。它独占 WhatsApp 会话（Baileys 的限制），管理所有渠道连接。

类比：Gateway 就像是一个 消息代理（Message Broker）——类似 RabbitMQ 或 Kafka，它同时维护和多个消息平台的长连接，收到消息后路由到正确的 Agent 处理。

WebSocket 协议

Gateway 使用纯 JSON 文本帧通信：

首帧必须是 connect（握手）
请求：{type: "req", id, method, params} → 响应：{type: "res", id, ok, payload|error}
事件：{type: "event", event, payload}

类比 HTTP 的 REST API，但 WebSocket 提供双向推送能力。

安全：设备配对

所有客户端连接时提供设备身份
新设备需要配对审批
本地连接（loopback）可自动审批
远程连接（SSH/Tailscale）必须显式审批
签名载荷绑定平台和设备类型

Nodes（远程节点）

macOS、Linux 或其他设备可以作为 Node 连接到 Gateway：

声明 role: node
暴露设备能力（camera、screen、location 等）
Agent 可以通过 nodes.run 工具远程调用这些能力

这是 OpenClaw 独有的概念：Agent 不只有读写文件和执行命令的能力，还可以操控连接的物理设备。

与 Claude Code 的架构对比

	Claude Code	OpenClaw
进程模型	短生命周期 CLI 进程	长驻 Gateway 服务
通信	stdin/stdout	WebSocket（双向）
客户端	终端 / IDE	多平台（Web、CLI、桌面 App）
远程访问	SSH + 端口转发 / Web	Tailscale / SSH tunnel
设备能力	无	Node 系统（调用远程设备能力）
多渠道	无（单一终端）	WhatsApp/Telegram/Slack 等
状态持久	文件系统（~/.claude/）	文件系统（~/.openclaw/）

知识检测

概念理解题

为什么 OpenClaw 选择 WebSocket 而不是 HTTP REST API 作为通信协议？这个选择和它的”服务型 Agent”定位有什么关系？
“一台主机只有一个 Gateway”——这个约束来自哪里？如果你想在一台机器上运行两个不同的 AI 助手怎么办？（提示：Multi-Agent Routing）
Node 系统让 Agent 可以调用物理设备能力。这从安全角度有什么风险？OpenClaw 如何通过设备配对来缓解？

迁移思考题

Claude Code 是无状态的（每次 claude 命令是独立进程），OpenClaw 是有状态的（Gateway 长驻）。这两种模型各自的优缺点是什么？（从运维、可靠性、资源消耗角度思考）
如果要把 Claude Code 改造成像 OpenClaw 一样支持 WhatsApp 消息，最小的架构改动是什么？

参见

02-OpenClaw-Agent-Loop — Gateway 内部的 Agent 运行机制
01-AI-Agent-架构原理（Claude Code 版） — 对比 CLI 架构
SlipBox 相关：Agent、OpenClaw、Session

参考答案

1. 为什么选 WebSocket

HTTP REST 是请求-响应模式——客户端发请求，等服务器回，然后连接结束。但 Agent 处理可能耗时 10-600 秒，期间需要推送中间状态（工具调用进度、流式文本）。WebSocket 是双向持久连接——服务器可以随时推送事件，客户端可以随时发送新消息。对于”服务型 Agent”来说，WebSocket 是必然选择，因为 Agent 的工作是异步的、流式的、长时间的。

2. 单 Gateway 约束

主要来自 WhatsApp Baileys 库（每台设备只能有一个 WhatsApp Web 会话）。如果要运行两个不同的 AI 助手，使用 Multi-Agent Routing——一个 Gateway 内运行多个 Agent，根据消息内容路由到不同 Agent。这比运行两个 Gateway 更高效（共享连接、共享资源）。

3. Node 系统的安全风险

风险：Agent 可以远程调用设备摄像头、读取屏幕、获取位置——这些都是高敏感操作。缓解措施：(1) 设备配对需要审批（新设备首次连接时需要已信任设备确认）(2) 远程连接必须显式审批（不像本地 loopback 可以自动审批）(3) 签名载荷绑定设备类型，防止身份伪造。但本质上，一旦配对成功，Agent 就有了完整的设备访问权限——这是一个需要用户充分理解的信任决策。

4. 无状态 vs 有状态的利弊

无状态（Claude Code CLI）：优点——简单（无需运维）、可靠（崩溃不影响下次使用）、资源友好（用完即释放）。缺点——无法接收推送消息、不能做后台任务、每次启动有冷启动成本。
有状态（OpenClaw Gateway）：优点——实时推送、后台任务、多渠道连接、会话持久化。缺点——需要运维（进程挂了需要重启）、占用常驻资源、状态不一致风险（崩溃后恢复）。

5. 让 Claude Code 支持 WhatsApp

最小改动：写一个中间层服务，(1) 用 Baileys 维护 WhatsApp 连接 (2) 收到消息时调用 claude --bare -p "<message>" --continue --session-id <peer_session> (3) 把输出转发回 WhatsApp。本质上是把 Claude Code 当作无状态函数调用。缺点是每次调用都是冷启动，没有流式输出。OpenClaw 的架构优势在于 Gateway 是长驻的，模型调用是热的。