--- 通过逆向 WebChat 协议打造 OpenClaw 的“万能胶水” ---

摘要

在 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) 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 安装与配置

这一步体现了"胶水"的特性：即插即用。

bash 复制代码

pip install openclaw-webchat-adapter

创建 .env 文件，填入你的 OpenClaw 服务地址。因为我们是模拟 WebChat，所以需要的配置和浏览器里看到的一模一样：

ini 复制代码

# .env 配置示例
OPENCLAW_GATEWAY_URL=ws://127.0.0.1:8080/socket  # Gateway 的 WebSocket 地址
OPENCLAW_GATEWAY_TOKEN=eyJhbGciOiJIUz...          # 你的用户 Token
OPENCLAW_SESSION_KEY=12345-abcde...          # 当前连接的会话id

3.2 极简代码示例

以下是一个最小化的实现。你可以把它看作是一个 Headless WebChat。

python 复制代码

"""
OpenClaw 通用适配器示例
目标：将终端 (Console) 变成 OpenClaw 的聊天窗口
"""
import sys
# 引入我们的"胶水"适配器
from openclaw_webchat_adapter.ws_adapter import OpenClawChatWsAdapter as adapter

def main() -> int:
    # 1. 一键连接：自动读取环境变量，完成复杂的握手协议
    print("正在连接 OpenClaw Gateway...")
    try:
        connect = adapter.create_connected_from_env()
        print("✅ 连接成功！(伪装 WebChat 模式)")
    except Exception as e:
        print(f"❌ 连接失败: {e}")
        return 1

    # 2. 交互循环
    try:
        while True:
            # 获取用户输入
            query = input("\n[我] > ").strip()
            
            if not query: continue
            if query.lower() in ("/exit", "/quit"): break

            print("[Agent] > ", end="")
            
            # 3. 流式透传：SDK 帮你处理了所有分包逻辑
            # 这里返回的 chunk 已经是清洗过的纯文本
            for chunk in connect.stream_chat(query):
                print(chunk, end="", flush=True)
            print("") # 换行
            
    except KeyboardInterrupt:
        print("\n再见！")
    finally:
        # 释放连接资源
        connect.stop()
    return 0

if __name__ == "__main__":
    sys.exit(main())

这里我成功的接入了自己的ai聊天平台项目中，并且还加入再了虾聊ai聊天社区中

去

4. 总结与思考

4.1 方案价值：通用性与一致性

无缝嵌入 ：因为接口极其简单（stream_chat），你可以把它嵌入到 Django/FastAPI 后端、Qt 桌面应用、甚至是树莓派的自动化脚本中。
历史漫游 ：这是一个巨大的隐形优势。因为 Gateway 认为你是 WebChat 用户，所以你在 CLI 里的所有聊天记录，打开浏览器登录 OpenClaw 官网时，全部都在。这对于调试 Agent Prompt 或回溯对话非常有用。

4.2 局限性

依赖稳定性：这本质上是一种 Protocol Reverse Engineering。如果 OpenClaw 官方大幅修改了 WebSocket 的通信 Payload 结构，适配器代码需要随之更新（虽然 WebChat 协议通常为了兼容性会保持稳定）。
并发模型 ：Python 的 WebSocket 依赖 threading 或 asyncio，在高并发场景下作为中间件转发时，需要注意连接池的管理。

5. 项目资源

Gitee : https://gitee.com/ha-big-brother/openclaw-webchat-adapter
GitHub : tangdeyx2333-beep/openclaw-webchat-adapter
协议细节: 详见仓库 README2 README3 文档

6. 维护

我会一直维护这个包，预计12号之前还还能实现支持获取会话聊天消息的接口