控制 UI

控制 UI（浏览器）

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

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

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

快速打开（本地）

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

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

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

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

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

设备配对（首次连接）

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

你会看到什么： "disconnected (1008): pairing required"

批准设备：

# 列出待处理请求
openclaw devices list

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

一旦批准，设备会被记住，除非 你使用 openclaw devices revoke --device <id> --role <role> 撤销它，否则不需要重新批准。参见 设备 CLI 了解令牌轮换和撤销。

注意：

• 本地连接（127.0.0.1）自动批准。
• 远程连接（LAN、Tailnet 等）需要显式批准。
• 每个浏览器配置文件生成唯一的设备 ID，因此切换浏览器或 清除浏览器数据将需要重新配对。

它可以做什么（今天）

• 通过网关 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 host=gateway/node（exec.approvals.*）
• 配置：查看/编辑 ~/.openclaw/openclaw.json（config.get、config.set）
• 配置：应用 + 重启并验证（config.apply）并唤醒最后一个活动会话
• 配置写入包括 base-hash 保护以防止破坏并发编辑
• 配置模式 + 表单渲染（config.schema，包括插件 + 频道模式）；原始 JSON 编辑器仍然可用
• 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（status、health、models.list）
• 日志：实时跟踪网关文件日志，带有过滤/导出（logs.tail）
• 更新：运行包/git 更新 + 重启（update.run）并带有重启报告

Cron 作业面板说明：

• 对于隔离作业，交付默认为宣布摘要。如果你想要仅内部运行，可以切换到无。
• 选择宣布时会出现频道/目标字段。
• Webhook 模式使用 delivery.mode = "webhook"，delivery.to 设置为有效的 HTTP(S) webhook URL。
• 对于主会话作业，webhook 和无交付模式可用。
• 高级编辑控制包括运行后删除、清除代理覆盖、cron 精确/交错选项、 代理模型/思考覆盖和尽力而为交付切换。
• 表单验证是内联的，带有字段级错误；无效值会禁用保存按钮直到修复。
• 设置 cron.webhookToken 以发送专用的 bearer 令牌，如果省略，webhook 发送时不带认证头部。
• 弃用的回退：存储的旧版作业带有 notify: true 仍然可以使用 cron.webhook 直到迁移。

聊天行为

• chat.send 是非阻塞的：它立即确认 { runId, status: "started" }，响应通过 chat 事件流式传输。
• 使用相同的 idempotencyKey 重新发送在运行时返回 { status: "in_flight" }，完成后返回 { status: "ok" }。
• chat.history 响应为 UI 安全进行大小限制。当转录条目太大时，网关可能会截断长文本字段，省略重的元数据块，并用占位符替换过大的消息（[chat.history omitted: message too large]）。
• chat.inject 将助手注释附加到会话转录并广播 chat 事件以进行仅 UI 更新（无代理运行，无频道交付）。
• 停止：
  • 点击停止（调用 chat.abort）
  • 输入 /stop（或独立的终止短语如 stop、stop action、stop run、stop openclaw、please stop）以带外终止
  • chat.abort 支持 { sessionKey }（无 runId）以终止该会话的所有活动运行
• 终止部分保留：
  • 当运行被终止时，部分助手文本仍然可以在 UI 中显示
  • 当存在缓冲输出时，网关将终止的部分助手文本持久化到转录历史中
  • 持久化条目包括终止元数据，以便转录消费者可以区分终止部分和正常完成输出

Tailnet 访问（推荐）

集成 Tailscale Serve（首选）

保持网关在回环上，让 Tailscale Serve 用 HTTPS 代理它：

openclaw gateway --tailscale serve

打开：

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

默认情况下，当 gateway.auth.allowTailscale 为 true 时，控制 UI/WebSocket Serve 请求可以通过 Tailscale 身份头部 （tailscale-user-login）进行认证。OpenClaw 通过 tailscale whois 解析 x-forwarded-for 地址并匹配头部来验证身份，并且仅当请求 使用 Tailscale 的 x-forwarded-* 头部击中回环时才接受这些。设置 gateway.auth.allowTailscale: false（或强制 gateway.auth.mode: "password"） 如果你想要即使对于 Serve 流量也需要令牌/密码。 无令牌 Serve 认证假设网关主机是可信的。如果不受信任的本地 代码可能在该主机上运行，需要令牌/密码认证。

绑定到 tailnet + 令牌

openclaw 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。默认情况下， OpenClaw 阻止没有设备身份的控制 UI 连接。

推荐修复： 使用 HTTPS（Tailscale Serve）或在本地打开 UI：

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

不安全认证切换行为：

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

allowInsecureAuth 不绕过控制 UI 设备身份或配对检查。

紧急突破：

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

dangerouslyDisableDeviceAuth 禁用控制 UI 设备身份检查，是一个 严重的安全降级。紧急使用后快速恢复。

参见 Tailscale 了解 HTTPS 设置指导。

构建 UI

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

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

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

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

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

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

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

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

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

1. 启动 UI dev 服务器：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 仅保留在内存中。
• 设置 gatewayUrl 时，UI 不会回退到配置或环境凭据。 显式提供 token（或 password）。缺少显式凭据是一个错误。
• 当网关在 TLS 后面时（Tailscale Serve、HTTPS 代理等），使用 wss://。
• gatewayUrl 仅在顶级窗口中接受（不嵌入）以防止点击劫持。
• 非回环控制 UI 部署必须显式设置 gateway.controlUi.allowedOrigins （完整来源）。这包括远程 dev 设置。
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true 启用 Host-header 来源回退模式，但它是一个危险的安全模式。

示例：

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

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