摘要
在 OpenClaw 的二次开发中,官方推荐的 Channel 扩展模式往往伴随着较高的开发和部署成本。本文介绍了一种更直接的方案:通过逆向工程解析 Gateway 与 WebChat 之间的 WebSocket 通信协议,构建一个通用适配器。该适配器能将任何外部程序伪装成官方 WebChat 客户端,从而实现零后端修改接入,并天然支持会话历史同步。
缘起:为什么我们需要这层'胶水'?
在 OpenClaw 的生态中,如果你想让一个外部系统(比如 Python 脚本、IoT 设备或自定义网页)和 Agent 对话,官方的标准答案通常是:'去开发一个 Custom Channel 吧。'
但在实际工程中,开发 Channel 存在明显的痛点:
- 链路长:你需要理解 Gateway 的插件机制,编写服务端代码,重新部署 Gateway。
- 维护重:每个不同的端都要适配一遍,无法复用。
- 数据隔离:自定义 Channel 产生的对话数据,往往难以直接在官方提供的 Web 界面中无缝查看。
工程师的思维往往是追求效率的。既然官方自带的 WebChat 可以完美地和 Gateway 通信,且每个 OpenClaw 实例都默认支持,那为什么不直接复用这条通道呢?
只要我们能通过代码完美模拟 WebChat 的握手和通信协议,我们就拥有了一个'万能胶水'——无需修改服务端一行代码,就能把任何项目'粘'到 OpenClaw 上。
核心原理:协议逆向与伪装
本方案的核心不在于'对接接口',而在于'行为模拟'。
架构对比
- 传统 Channel 模式:需在 Gateway 侧开发插件,通过特定的 API 进行转换。
- 本方案(胶水模式):适配器运行在客户端侧,它在网络层面上完全伪装成了浏览器。Gateway 根本不知道对面是一个 Python 脚本还是 Chrome 浏览器,因此所有的鉴权、流式输出、历史记录保存机制都天然生效。
协议交互时序
通过抓包分析还原了 OpenClaw Gateway 的 WebSocket 握手协议,并将其封装在 SDK 中:
- 身份伪装 (Handshake):此时 Gateway 认为有一个"Web 用户"上线了。
- 消息透传 (Streaming):循环处理流式响应,历史记录自动存入数据库。
- 连接建立:读取 Token/AgentID,发送 WebSocket Connect 请求(Headers: Origin, Auth...),收到 101 Switching Protocols。
- 数据交互:发送 JSON 协议帧(Type: Chat),接收 WebSocket Frame Chunk,解析协议包提取 Content,yield 纯文本片段。
实战:三步实现'零侵入'接入
为了让这层'胶水'真正通用,我将其封装为 openclaw-webchat-adapter,屏蔽了底层复杂的协议帧处理。
安装与配置
这一步体现了'胶水'的特性:即插即用。
pip install openclaw-webchat-adapter
创建 .env 文件,填入你的 OpenClaw 服务地址。因为我们是模拟 WebChat,所以需要的配置和浏览器里看到的一模一样:
# .env 配置示例
OPENCLAW_GATEWAY_URL=ws://127.0.0.1:8080/socket # Gateway 的 WebSocket 地址
OPENCLAW_GATEWAY_TOKEN=eyJhbGciOiJIUz... # 你的用户 Token
=-abcde...

