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 RegistryAgent 层智能体层接收 Gateway 转发的消息后执行推理链路意图识别 → 技能匹配 → 知识检索 → LLM 调用 → 响应生成Agent Runtime、Skills、MCP 工具Channel 层通道层对接外部 IM 平台的适配层完成协议转换、身份认证、消息格式统一Channel Adapter / RuntimeChannel这种分层带来的设计优势在于新增一个通道只需实现 Channel 接口替换或升级 Agent 推理引擎无需改动 GatewayGateway 本身可独立扩缩容以应对流量峰值。OpenClaw 上游支持 20 即时通讯通道国产 IM钉钉、飞书、企业微信、QQ、微信等在生态扩展中同样遵循这一适配器模式。二、Gateway 核心设计Gateway 层HTTP WebSocket · 单端口 · RPC 握手Agent 层Skills · MCP · LLM 推理 · 流式响应Channel 层Telegram · Discord · Slack · 钉钉/飞书…IM 入站Control UIOpenClaw Gateway 三层架构概念流程图非产品截图2.1 单端口双协议复用传统架构中 WebSocket 服务与 HTTP REST 服务通常分端口监听既增加部署复杂度又引入跨端口通信开销。OpenClaw Gateway 采用单端口双协议复用方案在同一 HTTP Server 上承载静态 Control UI、REST API 与 WebSocket 升级网络策略只需开放一个端口。以 OpenOctaGo 兼容实现协议对齐 OpenClaw为例Gateway 在连接建立阶段通过协议检测自动区分连接类型TCP 连接建立 │ ├─ 检测到 HTTP Upgrade 请求头GET / 或 GET /ws │ └─ 升级为 WebSocket 长连接 │ └─ 检测到普通 HTTP 请求 └─ 按 REST API 路由分发/api/*、/hooks/*、/openocta/open/v1/*路由路径协议功能典型场景/或/wsWebSocket实时双向通信Control UI 长连接、事件推送、RPC 调用/api/*HTTPRESTful 管理接口配置查询、技能上传、健康检查/hooks/{wake,agent,alert}HTTP POST外部 WebhookIM 平台回调、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/PongWebSocket 连接由服务端定期发送 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.sendGateway Handler ↓ 会话解析、历史加载、转写预处理 Agent RuntimeEino Engine / Node Agent ↓ 多轮生成Tool Calls → Tool Results → LLM 响应 Gateway Broadcastchat / agent 事件 ↓ WebSocket 推送到 Control UI 与已连接节点 deliverAssistantToIM若 delivertrue ↓ 通过 ChannelManager 写回 IM 平台Agent 层的关键设计点包括会话与记忆隔离每个sessionKey如agent:main:channel:feishu:oc_xxx独立维护上下文IM 入站与 Web UI 入站可共享或隔离。流式响应RunStream将模型输出切片为StreamEventGateway 实时广播chat事件用户无需等待完整回复。工具闭环Agent 可通过InvokeMethod回调 Gateway 方法如sessions.*、send实现 Agent ↔ Gateway 双向协作。Agent 层保持与 Gateway 的松耦合替换推理引擎Node → Go Eino不影响通道适配与 UI 协议这正是分层架构的价值所在。四、Channel 层多通道消息流转全链路4.1 消息生命周期以飞书群聊场景为例从用户发送消息到智能体回复的完整链路如下用户在飞书群 机器人帮我查一下今天的天气 ↓ ① 飞书 WebSocket 长连接推送事件 RuntimeChannelfeishu接收原始消息 ↓ ② 解析飞书特有消息格式 ↓ ③ 白名单过滤、 检测转换为 InboundMessage InboundSinkhooksAgentSink ↓ ④ 生成 HooksAgentParams内部触发 chat.send Agent Engine 技能调度 ↓ ⑤ 加载 weather skill / 调用天气 API ↓ ⑥ 组装 Prompt调用 LLM 生成自然语言回复 Gateway 响应路由 ↓ ⑦ deliverAssistantToIM 写回 ChannelManager RuntimeChannelfeishu ↓ ⑧ 转换为飞书 Markdown 卡片调用 API 发送 用户收到回复北京今天晴气温 25-32°C4.2 Channel 三层抽象组件职责ChannelPlugin元信息ID、名称、文档路径用于 UI 展示与 Gateway 方法注册OutboundAdapter单条出站发送供send/chat.send调用RuntimeChannel长连接入站、生命周期管理、流式回复通道入站模式出站能力飞书FeishuWebSocket 长连接Markdown 卡片、图片钉钉DingTalkStream SDK 长连接Markdown 文本、sessionWebhook企业微信WeWorkWebSocket / 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维度OpenClawHermes AgentOpenOcta定位Node 自托管个人助手Python CLI 智能体国产个人桌面级智能体运行时Node.js 22PythonGo 单二进制安装方式npm install -g onboard 向导pip / 源码双击安装包约 30 秒Gateway 协议原生定义者无内置 Gateway兼容 OpenClaw WS RPC默认端口18789可配置—18900国产 IM社区扩展社区扩展内置钉钉/飞书/企微/QQ/微信生产依赖Node.jsPython无 Node/PythonStar 规模38 万21 万新兴项目七、OpenClaw 在 Node 生态部署上的客观特点优势生态成熟度最高38 万 Star、20 通道、ClawHub 技能市场、活跃社区与详尽文档。协议开放Gateway WebSocket RPC 成为事实标准Control UI、移动端节点、第三方工具均可对接。扩展性强TypeScript 插件体系、MCP 集成、多 Agent 协同与本地工具自动发现。客观成本运行时依赖生产环境需 Node.js 22.19推荐 Node 24npm install -g与 onboard 向导对非开发者有一定学习曲线。资源占用Node 运行时 依赖树通常占用数百 MB 磁盘与较高内存基线。国产化适配国产 IM 与国产大模型集成多依赖社区插件或自行配置。对于熟悉 Node/TypeScript 的开发者OpenClaw 仍是功能最完整、社区最活跃的选择对于希望「装完即用」的桌面用户则需要关注部署链路的简化空间——这正是国产开源智能体赛道的差异化切入点。从工程实践看Gateway 层的稳定性直接决定多通道 Agent 的生产可用性心跳超时配置、Webhook 签名验证、通道限流策略、会话隔离粒度每一项都需在架构设计阶段预留扩展点。八、OpenOctaGo 单二进制路径上的 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 安装包约 30MB30 秒内完成部署无需 CLI onboard 向导。本地优先会话、记忆、Knowledge Vault 数据留在本机支持内网离线运行。国产 IM 原生集成钉钉、飞书、企业微信、QQ、微信开箱配置远程驱动桌面 Agent。统一端口 18900HTTP REST 与 WebSocket 单端口复用desktop 与 server 模式均可切换。L4 进化与四层记忆Knowledge Vault 随使用积累偏好形成个人级数字员工能力。OpenOcta 与 OpenClaw、Hermes Agent 的关键差异不在 Gateway 协议本身而在运行时形态Go 单二进制消除了 Node/Python 部署链国产 IM 原生集成降低了通道调试成本Knowledge Vault 则将记忆能力从插件生态转化为开箱即用的本地能力。Gateway starting addr127.0.0.1:18900 modedesktop version1.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 助手系统。建议读者在本地启动 OpenOctahttp://localhost:18900对照本文架构图观察 Control UI 中的通道状态、心跳延迟与会话计数将抽象架构与真实运行态一一对应。OpenOcta 八爪鱼智能体官方网站https://openocta.com开源仓库可下载源码、提交 PR、查看完整文档https://github.com/openocta/openocta