文档
Web（网关）
控制 UI（浏览器）

控制 UI（浏览器）

适用范围

在以下情况使用此页面：

  • 你想从浏览器操作网关
  • 你想要无需 SSH 隧道的 Tailnet 访问

控制 UI 是由网关提供的小型 Vite + Lit 单页应用：

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

它直接与同一端口上的网关 WebSocket 对话。

快速打开（本地）

如果网关在同一台计算机上运行，打开：

  • http://127.0.0.1:18789/（或 http://localhost:18789/）

如果页面无法加载，请先启动网关：clawdbot gateway。

认证在 WebSocket 握手期间通过以下方式提供：

  • connect.params.auth.token
  • connect.params.auth.password 仪表板设置面板允许你存储令牌；密码不会持久化。 入门向导默认生成网关令牌，因此在首次连接时将其粘贴到此处。

它可以做什么（今天）

  • 通过网关 WS 与模型聊天（chat.history、chat.send、chat.abort、chat.inject）
  • 在聊天中流式传输工具调用 + 实时工具输出卡（智能体事件）
  • 渠道：WhatsApp/Telegram/Discord/Slack + 插件渠道（Mattermost 等）状态 + QR 登录 + 每渠道配置（channels.status、web.login.*、config.patch）
  • 实例：在线列表 + 刷新（system-presence）
  • 会话：列表 + 每会话思考/详细覆盖（sessions.list、sessions.patch）
  • Cron 作业：列表/添加/运行/启用/禁用 + 运行历史（cron.*）
  • 技能：状态、启用/禁用、安装、API 密钥更新（skills.*）
  • 节点：列表 + 能力（node.list）
  • Exec 审批：编辑网关或节点允许列表 + exec host=gateway/node 的询问策略（exec.approvals.*）
  • 配置：查看/编辑 ~/.clawdbot/clawdbot.json（config.get、config.set）
  • 配置：应用 + 带验证的重启（config.apply）并唤醒最后一个活动会话
  • 配置写入包含基础哈希保护，以防止破坏并发编辑
  • 配置架构 + 表单呈现（config.schema，包括插件 + 渠道架构）；原始 JSON 编辑器仍然可用
  • 调试：status/health/models 快照 + 事件日志 + 手动 RPC 调用（status、health、models.list）
  • 日志：网关文件日志的实时尾随，带过滤器/导出（logs.tail）
  • 更新：运行包/git 更新 + 重启（update.run）并附带重启报告

聊天行为

  • chat.send 是非阻塞：它立即确认 { runId, status: "started" }，响应通过 chat 事件流式传输。
  • 使用相同的 idempotencyKey 重新发送在运行时返回 { status: "in_flight" }，完成后返回 { status: "ok" }。
  • chat.inject 将助手注释直接附加到会话记录，并为仅 UI 更新广播 chat 事件（无智能体运行，无渠道传递）。
  • 停止：
    • 点击 停止（调用 chat.abort）
    • 输入 /stop（或 stop|esc|abort|wait|exit|interrupt）以中止
    • chat.abort 支持 { sessionKey }（无 runId）以中止该会话的所有活动运行

Tailnet 访问（推荐）

集成的 Tailscale Serve（首选）

保持网关回环并让 Tailscale Serve 使用 HTTPS 代理它：

clawdbot gateway --tailscale serve

打开：

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

默认情况下，当 gateway.auth.allowTailscale 为 true 时，Serve 请求可以通过 Tailscale 身份标头（tailscale-user-login）进行认证。Clawdbot 通过使用 tailscale whois 解析 x-forwarded-for 地址并与标头匹配来验证身份，并且仅当请求使用 Tailscale 的 x-forwarded-* 标头命中回环时才接受这些请求。如果你希望即使对于 Serve 流量也需要令牌/密码，请设置 gateway.auth.allowTailscale: false（或强制 gateway.auth.mode: "password"）。

绑定到 tailnet + 令牌 

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

然后打开：

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

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

不安全的 HTTP

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

建议的修复方法： 使用 HTTPS（Tailscale Serve）或在本地打开 UI：

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

降级示例（仅通过 HTTP 的令牌）：

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

这将禁用控制 UI 的设备身份 + 配对（即使在 HTTPS 上也是如此）。仅当你信任网络时才使用它。

有关 HTTPS 设置指导，请参阅 Tailscale。

构建 UI

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

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

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

CLAWDBOT_CONTROL_UI_BASE_PATH=/clawdbot/ pnpm ui:build

对于本地开发（单独的开发服务器）：

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

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

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

控制 UI 是静态文件；WebSocket 目标是可配置的，可以与 HTTP 源不同。当你希望在本地使用 Vite 开发服务器但网关在其他地方运行时，这非常方便。

  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 仅保留在内存中。
  • 当网关位于 TLS 后面（Tailscale Serve、HTTPS 代理等）时，使用 wss://。

远程访问设置详细信息：远程访问。

WebChat（网关 WebSocket UI）仪表板（控制 UI）