OpenClaw 架构入门：Gateway 与多通道消息流转原理

过去一年，「个人 AI 助手」从概念验证走向日常工具。开发者希望助手能读本地文件、执行终端命令、在钉钉或飞书里随时响应；运维同学则想把告警分析、日志检索交给常驻 Agent，而不是每次打开网页复制粘贴。与 SaaS 聊天机器人不同，自托管部署意味着 Gateway 跑在你自己的机器或 VPS 上，会话与工具权限留在本地，通道密钥由你掌控。

在国产开源智能体赛道，OpenClaw 凭借 38 万+ GitHub Star 成为高频搜索词；Hermes Agent 则以 Python CLI 形态覆盖另一批偏好命令行的用户。两者与本文后半段介绍的 OpenOcta 共同构成了当前个人级智能体生态的主要选择。要理解这些项目的共性，需要先读懂 OpenClaw 的 Gateway 架构——它是整个系统的「神经中枢」，承载着协议适配、消息路由、会话管理与多通道协调。

本文从架构层面客观拆解 OpenClaw 的 Gateway 层、Agent 层与 Channel 层设计，说明单端口复用、WebSocket RPC 握手、心跳保活与多通道适配的完整链路。文末会总结 OpenClaw 在 Node 生态部署上的客观特点，并介绍国产开源智能体 OpenOcta 在 Go 单二进制路径上的差异化实现。

一、系统架构分层

OpenClaw 采用经典的三层架构，各层职责清晰、接口解耦，便于独立演进和水平扩展。官方文档（docs.openclaw.ai）与上游仓库 README 均以此为核心叙事。

层级	职责	典型组件
Gateway 层（接入层）	系统唯一流量入口，管理长短连接；协议适配（WebSocket / HTTP）、消息路由、会话管理、连接健康监测	HTTP Server、WebSocket Hub、Handler Registry
Agent 层（智能体层）	接收 Gateway 转发的消息后执行推理链路：意图识别 → 技能匹配 → 知识检索 → LLM 调用 → 响应生成	Agent Runtime、Skills、MCP 工具
Channel 层（通道层）	对接外部 IM 平台的适配层，完成协议转换、身份认证、消息格式统一	Channel Adapter / RuntimeChannel

这种分层带来的设计优势在于：新增一个通道只需实现 Channel 接口；替换或升级 Agent 推理引擎无需改动 Gateway；Gateway 本身可独立扩缩容以应对流量峰值。OpenClaw 上游支持 20+ 即时通讯通道；国产 IM（钉钉、飞书、企业微信、QQ、微信等）在生态扩展中同样遵循这一适配器模式。

二、Gateway 核心设计

Gateway 层HTTP + WebSocket · 单端口 · RPC 握手Agent 层Skills · MCP · LLM 推理 · 流式响应Channel 层Telegram · Discord · Slack · 钉钉/飞书…IM 入站Control UI

OpenClaw Gateway 三层架构（概念流程图，非产品截图）

2.1 单端口双协议复用

传统架构中 WebSocket 服务与 HTTP REST 服务通常分端口监听，既增加部署复杂度，又引入跨端口通信开销。OpenClaw Gateway 采用单端口双协议复用方案：在同一 HTTP Server 上承载静态 Control UI、REST API 与 WebSocket 升级，网络策略只需开放一个端口。

以 OpenOcta（Go 兼容实现，协议对齐 OpenClaw）为例，Gateway 在连接建立阶段通过协议检测自动区分连接类型：

TCP 连接建立
 │
 ├─ 检测到 HTTP Upgrade 请求头（GET / 或 GET /ws）
 │   └─ 升级为 WebSocket 长连接
 │
 └─ 检测到普通 HTTP 请求
     └─ 按 REST API 路由分发（/api/*、/hooks/*、/openocta/open/v1/*）

路由路径	协议	功能	典型场景
/ 或 /ws	WebSocket	实时双向通信	Control UI 长连接、事件推送、RPC 调用
/api/*	HTTP	RESTful 管理接口	配置查询、技能上传、健康检查
/hooks/{wake,agent,alert}	HTTP POST	外部 Webhook	IM 平台回调、CI/CD 事件、监控告警
/openocta/open/v1/*	HTTP	开放平台 API	第三方系统集成、自定义客户端

OpenOcta 默认监听 18900 端口，将 UI、API、WebSocket 收敛到单一入口，大幅降低运维复杂度。

2.2 WebSocket RPC 握手协议

WebSocket 连接建立后，客户端与 Gateway 需完成一次轻量级 RPC 握手，用于版本协商、会话创建与能力声明。OpenClaw 协议采用 req / res / event 三帧模型，当前协议版本为 3。

Step 1 - 客户端发送 connect 请求（首帧必须是 connect）:
→ { "type": "req", "id": "...", "method": "connect", "params": { "role": "operator", ... } }

Step 2 - 服务端回复 hello-ok:
← {
  "type": "res", "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 3,
    "features": { "methods": [...], "events": [...] },
    "policy": { "tickIntervalMs": 5000, "maxPayload": 1048576 }
  }
}

握手完成后，客户端通过 request(method, params) 发送 RPC 调用，服务端经 Handler Registry 分发到具体方法。核心方法包括 health、channels.status、chat.send、agent、send 等，与 OpenClaw 上游 server-methods-list.ts 对齐。

Control UI 侧的典型调用模式如下：客户端发送 req 帧，Promise 等待 res 响应，同一 WebSocket 连接上还可订阅 event 帧接收 chat、agent、tick 等实时事件。这种设计将 HTTP 管理接口与 WebSocket 实时通道统一在 Gateway 控制平面下，Agent 执行、通道状态、会话事件均可通过同一连接订阅。

2.3 心跳保活与连接健康管理

Gateway 使用多层心跳机制维护长连接健康状态：

• 传输层 Ping/Pong： WebSocket 连接由服务端定期发送 Ping 帧，客户端须在超时窗口内回复 Pong。
• 协议层 tick / heartbeat 事件： hello-ok 的 Policy.TickIntervalMs 声明为 5000 毫秒，Control UI 仪表盘据此展示连接延迟、在线时长与通道概览。
• Agent 主动心跳： 上游 OpenClaw 支持配置 AgentHeartbeatConfig，使 Agent 在空闲时主动发起推理循环。

完整心跳决策链可概括为：传输层保活 → 协议层 tick 广播 → Agent 层主动唤醒，三层各司其职，避免将「连接存活」与「业务活跃」混为一谈。

三、Agent 层：推理执行平面

Gateway 收到 chat.send 或 /hooks/agent 请求后，将消息转交 Agent Runtime 执行。OpenClaw 上游基于 Node.js 运行时，支持多轮工具调用、Skills 匹配与 MCP 协议扩展；OpenOcta 则以 CloudWeGo Eino DeepAgent 为执行引擎，但消息流转语义与上游保持一致。

chat.send（Gateway Handler）
  ↓ 会话解析、历史加载、转写预处理
Agent Runtime（Eino Engine / Node Agent）
  ↓ 多轮生成：Tool Calls → Tool Results → LLM 响应
Gateway Broadcast（chat / agent 事件）
  ↓ WebSocket 推送到 Control UI 与已连接节点
deliverAssistantToIM（若 deliver=true）
  ↓ 通过 ChannelManager 写回 IM 平台

Agent 层的关键设计点包括：

• 会话与记忆隔离： 每个 sessionKey（如 agent:main:channel:feishu:oc_xxx）独立维护上下文，IM 入站与 Web UI 入站可共享或隔离。
• 流式响应： RunStream 将模型输出切片为 StreamEvent，Gateway 实时广播 chat 事件，用户无需等待完整回复。
• 工具闭环： Agent 可通过 InvokeMethod 回调 Gateway 方法（如 sessions.*、send），实现 Agent ↔ Gateway 双向协作。

Agent 层保持与 Gateway 的松耦合：替换推理引擎（Node → Go Eino）不影响通道适配与 UI 协议，这正是分层架构的价值所在。

四、Channel 层：多通道消息流转全链路

4.1 消息生命周期

以飞书群聊场景为例，从用户发送消息到智能体回复的完整链路如下：

用户在飞书群 @机器人："帮我查一下今天的天气"
  ↓ ① 飞书 WebSocket 长连接推送事件
RuntimeChannel（feishu）接收原始消息
  ↓ ② 解析飞书特有消息格式
  ↓ ③ 白名单过滤、@ 检测，转换为 InboundMessage
InboundSink（hooksAgentSink）
  ↓ ④ 生成 HooksAgentParams，内部触发 chat.send
Agent Engine 技能调度
  ↓ ⑤ 加载 weather skill / 调用天气 API
  ↓ ⑥ 组装 Prompt，调用 LLM 生成自然语言回复
Gateway 响应路由
  ↓ ⑦ deliverAssistantToIM 写回 ChannelManager
RuntimeChannel（feishu）
  ↓ ⑧ 转换为飞书 Markdown 卡片，调用 API 发送
用户收到回复："北京今天晴，气温 25-32°C"

4.2 Channel 三层抽象

组件	职责
ChannelPlugin	元信息（ID、名称、文档路径），用于 UI 展示与 Gateway 方法注册
OutboundAdapter	单条出站发送，供 send / chat.send 调用
RuntimeChannel	长连接入站、生命周期管理、流式回复

通道	入站模式	出站能力
飞书（Feishu）	WebSocket 长连接	Markdown 卡片、图片
钉钉（DingTalk）	Stream SDK 长连接	Markdown 文本、sessionWebhook
企业微信（WeWork）	WebSocket / Webhook	文本消息
QQ	平台 SDK	文本/富文本
微信（Weixin）	平台回调	文本消息

4.3 三种路由模式

路由模式	触发条件	工作原理	适用场景
直连模式	payload 含明确 target 或 sessionKey	消息直接进入指定 Agent 队列	用户私聊、指定 Agent 任务
技能匹配模式	消息内容命中已注册 Skill 的 trigger	语义/关键词匹配后路由到对应技能	「查天气」→ weather skill
广播模式	无 target 且无技能匹配	广播给在线 Agent，取首个有效响应	通用问答、容错回退

新增通道只需实现 RuntimeChannel 接口的 Start、Stop、Send 方法，并通过 InboundSink.Deliver 桥接到 Gateway，即可无缝接入现有消息流转体系。ChannelManager 统一管理所有 RuntimeChannel 的生命周期，配置热重载时先 StopAll 再重建，避免僵尸连接——OpenOcta 文档（docs/channels-overview.md）对此有完整说明。

五、本地 Agent 自动发现与 Control UI 仪表盘

5.1 本地 Agent 自动发现（OpenClaw 原生能力）

OpenClaw Gateway 还具备本地 Agent 自动发现能力：启动时扫描本机运行环境，检测常见智能体工具进程并自动注册到管理面板，包括 Claude Code、Cline、Codex、Aider、Goose 等。自动发现通过进程检测或 Unix Socket 扫描建立通信链路，大幅简化多工具协同的配置成本。对于不在自动发现列表中的自定义 Agent，也支持手动注册。OpenOcta 在兼容层中保留了相关 Gateway 方法与 Control UI 入口，便于桌面用户统一管理本地工具节点。

5.2 Control UI 与运行仪表盘

Gateway 的 Web 管理界面（Control UI）是运行状况的「驾驶舱」。运维人员可在一屏内掌握：各通道与客户端连接的心跳延迟、活跃会话数、系统运行时长、消息收发速率与错误计数。仪表盘数据与 tickIntervalMs（默认 5 秒）对齐刷新，确保第一时间感知连接异常。消息聚合界面将来自不同渠道的对话统一呈现，每条消息标注 channel_type 来源，用户无需在多个 IM 客户端间切换即可完成跨平台回复与会话管理。

六、架构对比：OpenClaw、Hermes Agent 与 OpenOcta

维度	OpenClaw	Hermes Agent	OpenOcta
定位	Node 自托管个人助手	Python CLI 智能体	国产个人桌面级智能体
运行时	Node.js 22+	Python	Go 单二进制
安装方式	npm install -g + onboard 向导	pip / 源码	双击安装包（约 30 秒）
Gateway 协议	原生定义者	无内置 Gateway	兼容 OpenClaw WS RPC
默认端口	18789（可配置）	—	18900
国产 IM	社区扩展	社区扩展	内置钉钉/飞书/企微/QQ/微信
生产依赖	Node.js	Python	无 Node/Python
Star 规模	38 万+	21 万+	新兴项目

七、OpenClaw 在 Node 生态部署上的客观特点

优势：

• 生态成熟度最高： 38 万+ Star、20+ 通道、ClawHub 技能市场、活跃社区与详尽文档。
• 协议开放： Gateway WebSocket RPC 成为事实标准，Control UI、移动端节点、第三方工具均可对接。
• 扩展性强： TypeScript 插件体系、MCP 集成、多 Agent 协同与本地工具自动发现。

客观成本：

• 运行时依赖： 生产环境需 Node.js 22.19+（推荐 Node 24），npm install -g 与 onboard 向导对非开发者有一定学习曲线。
• 资源占用： Node 运行时 + 依赖树通常占用数百 MB 磁盘与较高内存基线。
• 国产化适配： 国产 IM 与国产大模型集成多依赖社区插件或自行配置。

对于熟悉 Node/TypeScript 的开发者，OpenClaw 仍是功能最完整、社区最活跃的选择；对于希望「装完即用」的桌面用户，则需要关注部署链路的简化空间——这正是国产开源智能体赛道的差异化切入点。从工程实践看，Gateway 层的稳定性直接决定多通道 Agent 的生产可用性：心跳超时配置、Webhook 签名验证、通道限流策略、会话隔离粒度，每一项都需在架构设计阶段预留扩展点。

八、OpenOcta：Go 单二进制路径上的 Gateway 实践

OpenOcta 消息对话界面（工具调用示例）— localhost:18900 实测截图

OpenClaw 所确立的 Gateway 架构——单端口双协议复用、WebSocket RPC 握手、心跳保活、Channel Adapter 模式、分级路由策略——在 OpenOcta 中得到了完整的 Go 原生实现。OpenOcta 明确借鉴 OpenClaw 的 Gateway 协议与 Control UI 交互模型，但 Gateway、Agent、Channel 三层均为自研 Go 代码，编译为单一可执行文件，Web UI 通过 go:embed 嵌入，部署零 Node/Python 依赖。

• 双击安装： macOS / Windows / Linux 安装包约 30MB，30 秒内完成部署，无需 CLI onboard 向导。
• 本地优先： 会话、记忆、Knowledge Vault 数据留在本机，支持内网离线运行。
• 国产 IM 原生集成： 钉钉、飞书、企业微信、QQ、微信开箱配置，远程驱动桌面 Agent。
• 统一端口 18900： HTTP REST 与 WebSocket 单端口复用，desktop 与 server 模式均可切换。
• L4 进化与四层记忆： Knowledge Vault 随使用积累偏好，形成个人级数字员工能力。

OpenOcta 与 OpenClaw、Hermes Agent 的关键差异不在 Gateway 协议本身，而在运行时形态：Go 单二进制消除了 Node/Python 部署链，国产 IM 原生集成降低了通道调试成本，Knowledge Vault 则将记忆能力从插件生态转化为开箱即用的本地能力。

Gateway starting addr=127.0.0.1:18900 mode=desktop version=1.0.5
Web UI available at http://127.0.0.1:18900

若你正评估国产开源智能体方案，希望在不牺牲 Gateway 协议体验的前提下降低 Node 部署成本，OpenOcta 提供了一条可验证的替代路径：协议兼容、源码开放（Apache-2.0）、支持提交 PR 与二次开发。其 Knowledge Vault 与 L4 自主进化能力，则进一步将 Gateway 架构从「消息路由」延伸为「个人数字员工」的完整运行时。

结语

消息网关在多智能体平台中居于核心地位——它不仅是连接客户端与服务端的桥梁，更是异构协议、多通道、多 Agent 之间的协调者。OpenClaw 以 Node 生态定义了 Gateway 的产品形态与协议标准；Hermes Agent 在 Python 赛道提供了另一条 Agent 推理路径；OpenOcta 则以 Go 单二进制将同一套 Gateway 理念落地到个人桌面级场景。理解 Gateway 的分层设计、RPC 握手与多通道流转原理，无论选择哪条技术路线，都能帮助你构建更可靠、可扩展的个人 AI 助手系统。建议读者在本地启动 OpenOcta（http://localhost:18900）对照本文架构图，观察 Control UI 中的通道状态、心跳延迟与会话计数，将抽象架构与真实运行态一一对应。

OpenOcta 八爪鱼智能体官方网站：https://openocta.com

开源仓库（可下载源码、提交 PR、查看完整文档）：https://github.com/openocta/openocta