远程Web版如何连上本机GatewayClawPanel WebSocket代理与Origin安全策略完整解析【免费下载链接】clawpanel OpenClaw Hermes Agent 多引擎 AI 管理面板 — 内置 AI 助手工具调用 图片识别 多模态一键安装 | Tauri v2 跨平台桌面应用 | 11 种语言项目地址: https://gitcode.com/qingchencloud/clawpanelClawPanel 是一个面向 OpenClaw Hermes Agent 的多引擎 AI 管理面板支持桌面端与纯 WebHeadless部署。把面板部署到远程服务器后新手最常踩的坑就是浏览器能打开面板却连不上本机的 Gateway。这篇文章带你深入理解 ClawPanel Web 版的 WebSocket 代理原理与 Origin 安全策略并给出 3 步连通本机的完整路径。一、为什么浏览器不能直连 GatewayOpenClaw 从 2026.8.1 版本开始会对 Control UI 的来源Origin做严格校验。直连模式下会发生什么你通过http://服务器IP:1420或公网域名访问 Web 面板浏览器发起 WebSocket 握手时会把这个远程地址作为Origin请求头发给 GatewayGateway 发现 Origin 不在本机白名单里直接在 connect 阶段拒绝返回CONTROL_UI_ORIGIN_NOT_ALLOWED。如果你直连 Gateway 端口默认 18789除了 Origin 校验外还得自己处理认证 Token、配对等一堆协议细节。所以正确姿势是所有连接都走 ClawPanel Web 服务由它在同一台机器上代理到本机 Gateway。二、架构总览一个本机可信出口ClawPanel 的 Web 版由独立 Node.js 服务serve.js提供无需 Tauri/Rust/GUI启动后它同时干两件事对外提供面板静态页面与 API监听 WebSocketupgrade事件把/ws开头的连接同机转发到127.0.0.1的 Gateway 端口。转发是纯 TCP 管道双向pipeGateway 只认得到来自本机的连接Origin 问题从根源上消失。仪表盘的 Gateway 卡片上显示的本机端口如 18789就是代理的转发目标。Web 服务启动时会读取~/.openclaw/openclaw.json里的gateway.port未配置时回退到默认值 18789见 scripts/serve.js。三、连通本机 Gateway 的 3 个关键步骤步骤 1启动 Web 服务并进入面板在面板所在机器上执行npm run serve # 默认监听 0.0.0.0:1420 npm run serve -- --port 8080 # 自定义端口然后用任意设备的浏览器访问http://服务器地址:1420。如果面板配置了访问密码需要先登录——这一步会种下clawpanel_session会话 Cookie后面 WebSocket 鉴权靠它。步骤 2WebSocket 握手前先验面板 Session注意一个容易忽略的细节WebSocket 的 upgrade 请求不会经过普通 HTTP API 中间件必须单独校验。serve.js在 upgrade 回调里显式调用会话鉴权函数未通过直接回 401 并断开连接鉴权实现_isWebSocketAuthorized内部检查clawpanel_sessionCookie 对应的 Session 是否有效、未过期未设面板密码时默认放行设了密码则匿名连接一律拒绝。这意味着能建立 WebSocket 的客户端必然是已经登录过面板的客户端Gateway 因此获得了一层来自面板的访问保护。步骤 3规范化请求头以本机身份转发验证通过后代理把原始握手请求改写再转发核心逻辑在 scripts/gateway-ws-proxy.js做了三件事处理说明覆写Host强制改为127.0.0.1:Gateway端口与真实转发目标一致覆写Origin强制改为http://localhost本机可信来源丢弃浏览器带来的远程 Origin清洗头值把所有请求头里的换行符替换为空格防止头部注入让请求走样这个 Origin 常量定义在同文件的GATEWAY_LOOPBACK_ORIGIN第 10 行相关行为由单元测试锁定tests/gateway-websocket-proxy.test.js。 一句话总结代理把你是谁换成我是本机所以 Gateway 的 Origin 白名单不再要求你录入每一个远程访问地址。四、Origin 安全策略的两个细节为什么换 Origin不算偷天换日安全性没有降低因为信任链转移到了面板侧Gateway 只信任来自 127.0.0.1 的连接而能到达这个本地代理连接的只有通过面板 Session 认证的浏览器攻击者即使知道 Gateway 端口直接连127.0.0.1也无法绕过那正是 Gateway 自己的 Origin/配对校验要挡住的来源。头部清洗防注入cleanHeaderValue会把头值中的\r、\n统一替换为空格。这是防御经典 HTTP 头部注入的基础手段——否则攻击者可能借伪造的换行插入额外头让上游 Gateway 看到的请求与代理转发的请求不一致。该行为同样有测试覆盖tests/gateway-websocket-proxy.test.js。五、前端 ws-client 的容错与自愈面板前端的 WebSocket 客户端 src/lib/ws-client.js 还内置了一整套握手容错即使代理链路之外比如桌面端直连场景出现握手失败也会自动分流处理收到connect.challenge后回复连接帧完成质询-响应式握手PAIRING_REQUIRED/CONTROL_UI_ORIGIN_NOT_ALLOWED→ 自动修复配对 写 origins并重连尝试 1 次AUTH_TOKEN_*/AUTH_PASSWORD_*类错误 → 刷新凭据后重试最多 2 次AUTH_RATE_LIMITED→ 按服务端给的retryAfterMs等待后自动重连设备签名类错误DEVICE_IDENTITY_REQUIRED等→ 重新配对。这套自愈逻辑让连不上 Gateway从需要手工修配置的故障变成了大多数情况下自动恢复的体验。六、快速排查清单 ✅遇到Web 版连不上 Gateway时按顺序检查面板登录了吗未登录时 WebSocket 会在 upgrade 阶段被 401 拒绝Gateway 在跑吗打开仪表盘确认 Gateway 状态为运行中必要时点重启 Gateway端口对吗Web 服务读取的是~/.openclaw/openclaw.json的gateway.port手动改过配置后需重启npm run serve才生效走的是 /ws 吗代理只处理/ws前缀的 upgrade 请求其他路径会被直接断开浏览器控制台查看[ws]前缀的日志握手失败的errCode/detailCode会明确告诉你卡在哪个环节。七、核心源码索引 想进一步阅读原理重点看这几处WebSocket 代理头策略scripts/gateway-ws-proxy.jsWeb 服务与 upgrade 处理scripts/serve.jsSession 鉴权scripts/dev-api.js前端 WebSocket 客户端与错误分流src/lib/ws-client.js代理行为单元测试tests/gateway-websocket-proxy.test.jsWeb 版部署相关文档docs/linux-deploy.md、docs/docker-deploy.md理解了这套面板 Session 认证 本机回环转发 Origin 规范化的组合你就掌握了 ClawPanel 远程 Web 版连上本机 Gateway 的全部关键——既不牺牲 Gateway 的 Origin 安全策略又让远程用户零配置可用。【免费下载链接】clawpanel OpenClaw Hermes Agent 多引擎 AI 管理面板 — 内置 AI 助手工具调用 图片识别 多模态一键安装 | Tauri v2 跨平台桌面应用 | 11 种语言项目地址: https://gitcode.com/qingchencloud/clawpanel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考