Control UI（浏览器）

Control UI 是一个由 Gateway 提供的小型 Vite + Lit 单页应用：

  • 默认地址：http://<host>:18789/
  • 可选前缀：设置 gateway.controlUi.basePath（例如 /openclaw）

它通过同一端口直接与 Gateway WebSocket 通信。

快速打开（本地）

如果 Gateway 在同一台电脑上运行，打开：

如果页面加载失败，先启动 Gateway：openclaw gateway。

认证信息在 WebSocket 握手时通过以下方式提供：

  • connect.params.auth.token
  • connect.params.auth.password

控制面板的设置面板可以保存 token；密码不会持久化。引导向导默认会生成一个 Gateway token，首次连接时把它粘贴到这里。

设备配对（首次连接）

当你从新浏览器或设备连接到 Control UI 时，Gateway 需要一次性配对批准 —— 即使你在同一个 Tailnet 上并且设置了 gateway.auth.allowTailscale: true。这是一项安全措施，用于防止未经授权的访问。

你会看到： “disconnected (1008): pairing required”

批准设备的方法：

# 列出待处理的请求
openclaw devices list

# 通过请求 ID 批准
openclaw devices approve <requestId>

批准后，设备会被记住，不需要重新批准，除非你用 openclaw devices revoke --device <id> --role <role> 撤销它。查看 Devices CLI 了解 token 轮换和撤销。

注意：

  • 本地连接（127.0.0.1）会自动批准。
  • 远程连接（局域网、Tailnet 等）需要明确批准。
  • 每个浏览器配置文件会生成唯一的设备 ID，所以切换浏览器或清除浏览器数据会需要重新配对。

功能列表（当前版本）

  • 通过 Gateway WS 与模型聊天（chat.history、chat.send、chat.abort、chat.inject）
  • 在聊天中流式显示工具调用和实时工具输出卡片（Agent 事件）
  • Channels：WhatsApp/Telegram/Discord/Slack + Plugin channels（Mattermost 等）状态 + 二维码登录 + 每个 Channel 的配置（channels.status、web.login.*、config.patch）
  • 实例：在线列表 + 刷新（system-presence）
  • Sessions：列表 + 每个 Session 的 thinking/verbose 覆盖设置（sessions.list、sessions.patch）
  • Cron 任务：列表/添加/运行/启用/禁用 + 运行历史（cron.*）
  • Skills：状态、启用/禁用、安装、API 密钥更新（skills.*）
  • 节点：列表 + 能力（node.list）
  • 执行批准：编辑 Gateway 或节点白名单 + exec host=gateway/node 的询问策略（exec.approvals.*）
  • 配置：查看/编辑 ~/.openclaw/openclaw.json（config.get、config.set）
  • 配置：应用 + 带验证的重启（config.apply）并唤醒最后活跃的 Session
  • 配置写入包含 base-hash 保护，防止并发编辑冲突
  • 配置 schema + 表单渲染（config.schema，包括 Plugin + Channel schemas）；原始 JSON 编辑器仍然可用
  • 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（status、health、models.list）
  • 日志：实时查看 Gateway 文件日志，支持过滤/导出（logs.tail）
  • 更新：运行包/git 更新 + 重启（update.run）并提供重启报告

聊天行为

  • chat.send 是非阻塞的：它会立即确认并返回 { runId, status: "started" }，响应通过 chat 事件流式传输。
  • 使用相同的 idempotencyKey 重新发送时，运行中会返回 { status: "in_flight" }，完成后返回 { status: "ok" }。
  • chat.inject 会向 Session 记录中追加一条助手备注，并广播一个 chat 事件用于 UI 更新（不会运行 Agent，不会发送到 Channel）。
  • 停止：
    • 点击 Stop（调用 chat.abort）
    • 输入 /stop（或 stop|esc|abort|wait|exit|interrupt）来带外中止
    • chat.abort 支持 { sessionKey }（不需要 runId）来中止该 Session 的所有活跃运行

Tailnet 访问（推荐）

集成 Tailscale Serve（首选）

让 Gateway 保持在本地回环地址，让 Tailscale Serve 用 HTTPS 代理它：

openclaw gateway --tailscale serve

打开：

  • https://<magicdns>/（或你配置的 gateway.controlUi.basePath）

默认情况下，当 gateway.auth.allowTailscale 为 true 时，Serve 请求可以通过 Tailscale 身份头（tailscale-user-login）进行认证。OpenClaw 会通过 tailscale whois 解析 x-forwarded-for 地址来验证身份，并将其与头信息匹配，只有当请求带着 Tailscale 的 x-forwarded-* 头访问本地回环地址时才接受这些请求。如果你想对 Serve 流量也要求 token/密码，可以设置 gateway.auth.allowTailscale: false（或强制 gateway.auth.mode: "password"）。

绑定到 Tailnet + token

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

然后打开：

  • http://<tailscale-ip>:18789/（或你配置的 gateway.controlUi.basePath）

把 token 粘贴到 UI 设置中（作为 connect.params.auth.token 发送）。

不安全的 HTTP

如果你通过纯 HTTP 打开控制面板（http://<lan-ip> 或 http://<tailscale-ip>），浏览器会运行在非安全上下文中并阻止 WebCrypto。默认情况下，OpenClaw 会阻止没有设备身份的 Control UI 连接。

推荐的解决方法： 使用 HTTPS（Tailscale Serve）或在本地打开 UI：

  • https://<magicdns>/（Serve）
  • http://127.0.0.1:18789/（在 Gateway 主机上）

降级示例（通过 HTTP 仅使用 token）：

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

这会禁用 Control UI 的设备身份 + 配对（即使在 HTTPS 上）。只在你信任网络时使用。

查看 Tailscale 了解 HTTPS 设置指南。

构建 UI

Gateway 从 dist/control-ui 提供静态文件。用以下命令构建它们：

pnpm ui:build # 首次运行时自动安装 UI 依赖

可选的绝对路径（当你想要固定的资源 URL 时）：

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

本地开发（独立的开发服务器）：

pnpm ui:dev # 首次运行时自动安装 UI 依赖

然后将 UI 指向你的 Gateway WS URL（例如 ws://127.0.0.1:18789）。

调试/测试：开发服务器 + 远程 Gateway

Control UI 是静态文件；WebSocket 目标是可配置的，可以与 HTTP 源不同。当你想在本地使用 Vite 开发服务器但 Gateway 运行在其他地方时，这很方便。

  1. 启动 UI 开发服务器：pnpm ui:dev
  2. 打开类似这样的 URL：
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

可选的一次性认证（如果需要）：

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789&token=<gateway-token>

注意：

  • gatewayUrl 在加载后会存储在 localStorage 中并从 URL 中移除。
  • token 存储在 localStorage 中；password 只保存在内存中。
  • 当 Gateway 在 TLS 后面时（Tailscale Serve、HTTPS 代理等），使用 wss://。

远程访问设置详情：Remote access。