QCLAW 浏览器联通指南：原理、架构与配置详解
本文档旨在帮助用户深入理解QCLAW如何通过OpenClaw Browser Relay控制浏览器，彻底解决常见的500 Internal Server Error问题，并提供标准的配置流程。
一共进行了45次对话，消耗了token：6,199,223，跑通该流程！！！
🧠 核心原理：QCLAW 如何控制浏览器？
QCLAW 并非直接“黑入”浏览器，而是通过一套标准的客户端 - 中继 - 网关架构，利用 Chrome DevTools Protocol (CDP) 的思想来实现对浏览器的安全控制。
1. 交互架构图
2. 详细交互流程
当您在 QCLAW 中触发一个需要浏览器操作的任务（如“知乎发帖”）时，背后发生了以下精密的交互：
- 指令发起：
- QCLAW 桌面端（或 Web 端）生成一个任务指令，包含具体的动作（如
click,type,navigate）。 - 系统生成当前的SessionKey（格式：
agent:main:session-xxxxx），这是本次对话的唯一身份标识。
- QCLAW 桌面端（或 Web 端）生成一个任务指令，包含具体的动作（如
- 网关路由 (Gateway - Port 28789)：
- 指令首先发送到Gateway。
- Gateway 验证Gateway Token和SessionKey的有效性。
- 关键点：如果 SessionKey 格式错误（如旧版的
agent:main:main），Gateway 会直接拒绝并返回500 Unknown sessionKey。
- 中继桥接 (Relay - Port 28792)：
- Gateway 将合法的浏览器控制指令转发给本地的Relay 服务（端口 28792）。
- Relay 服务是一个轻量级的 Node.js 进程，它充当“翻译官”，将 QCLAW 的内部指令转换为浏览器扩展能听懂的格式。
- 扩展执行 (Browser Extension)：
- OpenClaw Browser Relay扩展监听 28792 端口，收到指令后，利用 Chrome 扩展 API (
chrome.tabs,debugger等) 注入到当前激活的 Tab 中。 - 扩展在页面上下文中执行 DOM 操作（填写表单、点击按钮），并将结果（截图、HTML 内容、执行状态）回传给 Relay。
- OpenClaw Browser Relay扩展监听 28792 端口，收到指令后，利用 Chrome 扩展 API (
- 结果反馈：
- 执行结果沿原路返回：扩展 -> Relay -> Gateway -> QCLAW 界面，最终呈现给用户。
⚠️ 核心警告：版本兼容性是成败关键
根据调试记录，90% 的连接失败（尤其是 500 错误）源于扩展版本不匹配。
- ❌** 错误根源**：Chrome 商店版的扩展通常更新滞后，硬编码了旧的SessionKey格式（
agent:main:main）。 - ✅** 现状**：新版 QCLAW 使用动态SessionKey（
agent:main:session-时间戳 - 随机码）。 - 后果：旧扩展发出的“暗号”服务端听不懂，直接报错
Unknown sessionKey，导致整个链路中断。
结论：必须使用 QCLAW 安装包内自带的扩展程序，严禁从 Chrome 商店下载。
📡 端口架构详解：28789 vs 28792
理解这两个端口的分工，是正确配置的前提：
| 端口号 | 名称 | 角色 | 作用描述 | 配置建议 |
|---|---|---|---|---|
| 28789 | Gateway Port | 大脑 | 核心业务中枢。负责身份验证、会话管理 (Session Key)、工具调用逻辑及大模型交互。 | 不要在扩展中直接配置此端口。它是后端服务，由中继层间接访问。 |
| 28792 | Relay Port | 桥梁 | 浏览器专用接口。计算公式：Gateway 端口 + 3。专门供浏览器扩展连接，处理跨域、CDP 协议转换及 Session 同步。 | 必须在扩展设置中填写此端口。扩展通过它与 Gateway 通信。 |
*� 记忆法则：浏览器扩展只认28792（中继），剩下的交给中继去和28789（网关）沟通。
🛠️ 标准安装与配置步骤
第一步：清理旧环境
- 打开 Chrome 浏览器，访问
chrome://extensions/。 - 开启右上角的“开发者模式” (Developer Mode)。
- 移除任何从 Chrome 商店安装的 “OpenClaw Browser Relay” 或类似扩展。
第二步：加载自带扩展
- 点击“加载已解压的扩展程序” (Load unpacked)。
- 定位到 QCLAW 应用内部的扩展目录。
- macOS 典型路径：
/Applications/QClaw.app/Contents/Resources/openclaw/node_modules/openclaw/assets/chrome-extension- _查找技巧_：如果不确定路径，可在终端运行：find/Applications/QClaw.app-name"manifest.json"|grepchrome- 选中文件夹并确认加载。
第三步：获取并配置 Token
- 获取 Gateway Token：
- 在终端运行以下命令提取 Token：
cat~/.qclaw/openclaw.json|python3-c"import json,sys; d=json.load(sys.stdin); print(d.get('gateway',{}).get('auth',{}).get('token'))"- 或者直接在 QCLAW 桌面端的设置界面查看。 - _示例 Token_：`***********************************************`- 填写扩展设置：
- 点击扩展图标进入设置页。
- Port: 填入
28792。 - Gateway Token: 填入上一步获取的 Token。
- 点击Save。
第四步：验证状态
- 成功标志：页面底部显示绿色提示：
Relay reachable and authenticated at http://127.0.0.1:28792/
(这意味着 Token 验证通过，且中继服务正常)
- 失败排查：
- 若显示红色：检查 QCLAW 桌面端是否启动；确认端口未被占用；检查防火墙。
✅ 验证与测试
配置完成后，进行功能性验证：
- 刷新页面：刷新聊天窗口或重新激活扩展。
- 执行测试指令：
- 简单测试：“帮我算一下 123 * 456”（验证工具调用）。
- 浏览器测试：“打开百度并搜索 QCLAW”（验证浏览器控制）。
- 预期结果：
- 不再出现
500 Internal Server Error。 - 浏览器自动打开新标签页并执行搜索操作。
- 不再出现
📝 常见问题总结 (FAQ)
Q: 为什么 Token 还需要推导 (HMAC)？
A: 在底层通信中，扩展连接 28792 端口时，会使用HMAC-SHA256算法基于 Gateway Token 和端口号推导出一个临时的Relay Token(openclaw-extension-relay-v1:{port})。您只需在界面填入原始的 Gateway Token，扩展内部会自动完成推导，无需手动计算。
Q: 每次重启 QCLAW 都需要重新配置吗？
A: 不需要。只要 QCLAW 没有重装或重置配置，Token 和端口通常保持不变。唯一的变量是SessionKey，但新版扩展会自动从 Gateway 获取最新的 SessionKey，无需人工干预。
Q: 找不到自带的扩展文件夹怎么办？
A: 请确保安装的是官方最新版 QCLAW。如果路径结构发生变化，请使用终端搜索manifest.json文件定位。
结语：遵循“使用自带扩展 + 连接 28792 端口 + 正确 Token”这一黄金法则，即可确保持续、稳定地享受 QCLAW 带来的自动化浏览器体验。