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