OpenClaw 中文

深色模式

广告 · 本站推荐广告

Control UI（浏览器控制界面） ​

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

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

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

快速打开（本地） ​

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

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

如果页面加载失败，请先启动 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"

批准设备：

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

# 按请求 ID 批准
openclaw devices approve <request-id>

一旦批准，该设备会被记住，除非你使用 openclaw devices revoke --device <id> --role <role> 撤销。详见 设备 CLI 了解 token 轮换和撤销。

注意事项：

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

语言支持 ​

Control UI 可以在首次加载时根据浏览器语言环境自动本地化，你也可以稍后在 Access 卡片的语言选择器中覆盖。

  • 支持的语言：en、zh-CN、zh-TW、pt-BR、de、es
  • 非英语翻译在浏览器中延迟加载。
  • 选定的语言保存在浏览器存储中，后续访问时复用。
  • 缺失的翻译键回退到英语。

功能概览（当前） ​

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

定时任务面板说明 ​

  • 对于隔离任务，投递默认为 announce summary。如果只需要内部运行，可以切换为 none。
  • 选择 announce 时会显示频道/目标字段。
  • Webhook 模式使用 delivery.mode = "webhook"，delivery.to 设置为有效的 HTTP(S) webhook URL。
  • 对于 main-session 任务，webhook 和 none 投递模式可用。
  • 高级编辑控件包括：运行后删除、清除 agent 覆盖、cron 精确/交错选项、agent 模型/思考覆盖，以及 best-effort 投递开关。
  • 表单验证为内联字段级错误；无效值会禁用保存按钮直到修复。
  • 设置 cron.webhookToken 以发送专用 bearer token；如果省略则 webhook 不带认证头发送。
  • 已弃用回退：存储的旧版任务（notify: true）在迁移前仍可使用 cron.webhook。

聊天行为 ​

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

Tailnet 访问（推荐） ​

集成 Tailscale Serve（首选） ​

保持 Gateway 在回环地址上，让 Tailscale Serve 以 HTTPS 代理：

bash
openclaw gateway --tailscale serve

打开：

  • https://<你的机器名>.<tailnet名>.ts.net（或你配置的 gateway.controlUi.basePath）

默认情况下，当 gateway.auth.allowTailscale 为 true 时，Control UI/WebSocket Serve 请求可通过 Tailscale 身份头（tailscale-user-login）进行认证。OpenClaw 通过使用 tailscale whois 解析 x-forwarded-for 地址并与头部匹配来验证身份，且仅在请求通过回环地址并带有 Tailscale 的 x-forwarded-** 头时接受。

如果你想即使对 Serve 流量也要求 token/密码，可设置 gateway.auth.allowTailscale: false（或强制 gateway.auth.mode: "password"）。无 token 的 Serve 认证假设 gateway 主机是受信任的。如果该主机上可能运行不受信任的本地代码，请要求 token/密码认证。

绑定到 tailnet + token ​

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

然后打开：

  • http://<你的机器名>:18789/（或你配置的 gateway.controlUi.basePath）

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

不安全的 HTTP 访问 ​

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

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

  • https://<机器名>.ts.net（Serve）
  • http://127.0.0.1:18789/（在 gateway 主机上）

不安全认证开关行为：

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

allowInsecureAuth 不会绕过 Control UI 设备身份或配对检查。

仅限紧急情况（break-glass）：

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

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

参阅 Tailscale 了解 HTTPS 设置指南。

构建 UI ​

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

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

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

bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

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

bash
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：
text
http://localhost:5173/?gatewayUrl=ws://<远程主机>:18789

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

text
http://localhost:5173/?gatewayUrl=wss://<主机>:18789&token=<你的token>

注意事项：

  • gatewayUrl 在加载后存储到 localStorage 中，并从 URL 中移除。
  • token 存储在 localStorage 中；password 仅保留在内存中。
  • 设置 gatewayUrl 后，UI 不会回退到配置或环境凭据。请显式提供 token（或 password）。缺少显式凭据会报错。
  • 当 Gateway 在 TLS 后面时使用 wss://（Tailscale Serve、HTTPS 代理等）。
  • gatewayUrl 仅在顶层窗口中接受（不在嵌入式中），以防止点击劫持。
  • 非回环 Control UI 部署必须显式设置 gateway.controlUi.allowedOrigins（完整 origin）。这包括远程开发设置。
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true 启用 Host 头 origin 回退模式，但这是一个危险的安全模式。

配置示例：

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

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

基于MIT协议开源 | 内容翻译自 官方文档，同步更新

Copyright © 2026 OpenClaw 中文社区