OpenClaw Dashboard / Control UI 前端实现框架与原理本文基于openclaw仓库源码与官方文档对Gateway DashboardControl UI的前端实现做一次整体梳理方便在 MW4Agent 中对标实现类似的 Web 控制台。1. 整体架构概览定位Dashboard 即 Gateway 的Control UI是一个浏览器单页应用用于查看和控制聊天会话、通道状态、定时任务、技能、节点、日志等作为 Gateway 的“管理后台”暴露各种管理级 RPC。运行位置由 Gateway HTTP 服务器直接提供静态资源默认地址http://host:18789/可通过gateway.controlUi.basePath改为子路径例如/openclaw静态文件路径为dist/control-ui。技术栈构建ViteUILitWeb Components而不是 React/Vue与 Gateway 的通信浏览器端WebSocket直接连 Gateway 的 WS 端口典型部署形态本机开发openclaw gateway 浏览器直接访问127.0.0.1:18789远程/内网通过 Tailscale Serve/Tailnet 或 SSH 隧道暴露 Control UI公网推荐配合 HTTPS 严格 authtoken/password 设备配对2. CLI 到 Dashboard 的链路openclaw dashboard入口在src/commands/dashboard.tsCLI 负责读取配置与 Gateway 监听信息readConfigFileSnapshot()解析当前OpenClawConfigresolveGatewayPort(cfg)获取 Gateway 监听端口默认 18789cfg.gateway.bind/cfg.gateway.customBindHost/cfg.gateway.controlUi.basePath解析 Dashboard 访问 URL// src/commands/dashboard.ts节选constlinksresolveControlUiLinks({port,bind:bindlan?loopback:bind,customBindHost,basePath,});处理网关认证 tokengateway.auth.token可以配置为明文、环境变量或 SecretRef外部密钥管理解析逻辑抽象在// src/commands/dashboard.ts节选constresolvedawaitresolveConfiguredSecretInputWithFallback({config:cfg,env,value:cfg.gateway?.auth?.token,path:gateway.auth.token,readFallback:()readGatewayTokenEnv(env),});URL 中是否带 token 的决策如果 token 直接来自配置或环境变量非 SecretRefCLI 可以在 URL 的fragment中添加一次性 token// src/commands/dashboard.ts节选constincludeTokenInUrltoken.length0!resolvedToken.tokenSecretRefConfigured;constdashboardUrlincludeTokenInUrl?${links.httpUrl}#token${encodeURIComponent(token)}:links.httpUrl;若 token 由 SecretRef 管理则不注入 URL只打印无 token 的 Dashboard 地址避免在终端、剪贴板或浏览器启动参数中泄露外部密钥。额外 UX自动复制链接到剪贴板copyToClipboard(dashboardUrl)尝试自动打开浏览器openUrl(dashboardUrl)使用detectBrowserOpenSupport检查平台支持在无法自动打开时打印 SSH 隧道提示formatControlUiSshHint(...)小结openclaw dashboard本身不包含前端逻辑而是负责“拼好 URL 安全地处理 token 打开浏览器/打印提示”前端 SPA 全在dist/control-ui里由 Gateway 提供。3. Dashboard 前端框架Vite Lit SPA3.1 构建与产物在docs/web/control-ui.md中官方说明Gateway 从dist/control-ui提供静态文件The Gateway serves static files from dist/control-ui. Build them with: bash pnpm ui:build # auto-installs UI deps on first run- 开发模式通过 Vite dev server bash pnpm ui:dev # auto-installs UI deps on first run可选的绝对 basePath构建时注入OPENCLAW_CONTROL_UI_BASE_PATH/openclaw/pnpmui:build因此Dashboard 是一个典型的Vite SPA使用 Vite 的 dev server默认 5173 端口进行开发编译后的静态资源HTML/JS/CSS/静态资源放入dist/control-ui由 Gateway HTTP 服务托管。UI 组件使用Lit构建每个模块聊天、会话、通道、Cron、配置等对应一个或多个 Lit Web Components通过自定义元素 Shadow DOM 组合出完整控制台。3.2 Browser → Gateway WebSocket 通道Dashboard 本身不通过 REST API而是直接通过 WebSocket 与 Gateway 通信WebSocket 地址与 HTTP 同端口基于 Gateway 配置 / 控制台设置推导所有前端动作发送消息、查看状态、修改配置等都封装为RPC 事件发送给 Gateway如chat.send/chat.history/config.get/config.set/skills.*/cron.*等Gateway 回发事件流前端根据事件类型和 payload 更新 UI 状态。这部分逻辑对应于src/web/*下的一系列 TypeScript 模块更偏内部协议层而非 UI 组件本身src/web/inbound.*处理 WebSocket 入站事件src/web/outbound.ts将前端操作转为发送给 Gateway 的消息格式src/web/session.ts/src/web/auth-store.ts负责连接生命周期管理与认证处理src/web/auto-reply/**为 Web 自动回复场景复用同一套事件/会话抽象。从架构角度看Dashboard UI Vite Lit 组件层src/web/** WebSocket 协议与会话管理层两者通过浏览器端 JS 共享同一运行环境。4. 认证与安全模型前端视角4.1 WebSocket 握手认证在docs/web/control-ui.md中认证是通过 WebSocket 握手参数完成的控制 UI 在建立连接时发送connect.params.auth.token或connect.params.auth.passwordGateway 会在握手时校验token/password 是否匹配gateway.auth.*配置设备是否已完成配对Device pairing 系统是否允许 Tailscale 身份作为认证来源gateway.auth.allowTailscale。前端这边的核心原则不在 URL query 中传 token避免日志泄漏、Referer 泄漏首次打开可从 URL fragment / 页面设置中注入 token然后token存在于sessionStorage当前标签页 当前 Gateway URLpassword仅保存在内存不落盘部分网关 URL 配置gatewayUrl可以保存在 localStorage 中以方便 dev server 远程 Gateway 开发模式。4.2 URL 参数与本地存储策略docs/web/control-ui.md对 dev server remote Gateway 场景有示例http://localhost:5173/?gatewayUrlws://gateway-host:18789 http://localhost:5173/?gatewayUrlwss://gateway-host:18789#tokengateway-token行为总结gatewayUrlWS 地址从 URL query 读取读取后写入 localStorage随后从 URL 移除允许指定远程 Gateway 主机配合 Tailscale / SSH 转发。token认证 token从 URL fragment#token...读取存入 sessionStorage仅对当前浏览器标签页 当前gatewayUrl生效随后从 URL 中剥离以减少泄漏面。password不落盘只驻留在内存状态机中由用户在 UI 中手动输入。Dashboard 的前端状态管理大致遵循初始化阶段解析 URL → gatewayUrl token根据 URL / 存储的 gatewayUrl 决定连接目标若无显式凭证则报错提示用户补充认证信息。运行时UI 内的“设置面板”允许用户修改gatewayUrl、token、语言、主题等改动会反映到本地存储与当前 WebSocket 连接。5. 功能模块与 WebSocket 协议映射Control UI 在文档中列举了当前支持的主要模块它们都通过统一的 Gateway WS RPC 协议实现聊天Chat调用chat.send/chat.history/chat.inject/chat.abortUI 显示消息列表、实时流式输出、工具卡片/事件流。通道ChannelsWhatsApp / Telegram / Discord / Slack 等渠道的状态、登录 QR、配置表单使用channels.status/web.login.*/config.patch等 RPC。会话Sessionssessions.list/sessions.patch支持 per-session 的思考/verbose 开关定时任务Croncron.*一整套 RPC列表、创建、编辑、运行、启停、历史查看等技能Skillsskills.*查看/启用/禁用/安装/更新 Skill配置Configconfig.get/config.set/config.apply/config.schema等支持 JSON 表单渲染 原始 JSON 编辑写入时使用 base-hash 防止覆盖并发修改节点、日志、更新等模块node.list、logs.tail、update.run、status、health、models.list等。从前端实现角度Lit 组件只负责渲染与事件触发RPC 发送 / 事件流订阅统一封装在某个“GatewayClient / Session” 抽象里对应src/web/session.ts/src/web/outbound.ts等UI 和 WebSocket 层松耦合替换 Gateway 后端时只要 RPC 协议保持兼容Control UI 可以复用。6. 调试与远程开发模式Dashboard 支持使用 Vite dev server 连接远程 Gateway便于在本机上开发前端将 Gateway 部署在本地 Docker / 远程服务器 / Tailscale 节点上。典型流程见docs/web/control-ui.md本地起 UI dev serverpnpmui:dev用gatewayUrl指向远程 Gatewayhttp://localhost:5173/?gatewayUrlws://gateway-host:18789如需带 token一次性通过 URL fragment 传入http://localhost:5173/?gatewayUrlwss://gateway-host:18789#tokengateway-tokenControl UI 会将gatewayUrl存入 localStorage将token存入 sessionStorage当前标签页并从 URL 移除建立到 Gateway 的 WebSocket 连接并在失败时展示详细错误与重连提示。安全注意远程 Gateway 部署时必须配置gateway.controlUi.allowedOrigins以白名单方式允许 dev server 源如http://localhost:5173否则 Gateway 拒绝启动可以通过gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback暂时放宽 Host header 检查但这是“救火模式”应尽快恢复安全配置。7. 设计启示前后端边界清晰所有管理能力都通过统一的 WebSocket RPC 暴露前端只是 Vite Lit SPA专注 UI 和状态管理。认证与 token 处理安全token 使用 URL fragment sessionStorage一次性导入后即从 URL 剥离密钥管理支持 SecretRef / 环境变量CLI 明确避免在非必要场景下打印或拼接敏感值。绑定模式与 Origin 安全通过bindcontrolUi.basePathallowedOrigins管理 Control UI 暴露面Tailscale Serve / Tailnet 与 JWT/token/password 结合形成多层防护。模块化的 WebSocket 协议所有功能面板都基于一套统一的事件/命令总线chat.*、config.*、skills.*等为未来扩展新模块如 Memory 可视化、LLM 监控提供良好基础。