古法编程

Appearance

本页介绍 OpenClaw Gateway 内置的浏览器管理界面（Control UI）。默认地址 http://localhost:18789/，通过 WebSocket 与 Gateway 直接通信。覆盖设备配对流程（首次连接需批准）、13 种语言支持、聊天行为（流式工具调用/中止/chat.inject）、Tailscale Serve HTTPS 集成、不安全 HTTP 处理，以及所有可用功能模块（Dreams、Exec 批准、定时任务、配置表单 + SecretRef 保护等）。

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
  • 当 gateway.auth.allowTailscale: true 时的 Tailscale Serve 身份头
  • 当 gateway.auth.mode: "trusted-proxy" 时的可信代理身份头

控制台设置面板为当前浏览器标签会话和所选网关 URL 保存 token；密码不会持久化。引导程序通常在第一次连接时生成共享密钥 token，密码认证在 gateway.auth.mode 为 "password" 时也可用。

设备配对（首次连接） ​

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

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

批准设备的方法：

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

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

若浏览器以更改的认证详情（角色/范围/公钥）重试配对，之前的待处理请求会被取代，新的 requestId 会被创建。批准前重新运行 openclaw devices list。

批准后，设备会被记住，除非通过 openclaw devices revoke --device <id> --role <role> 撤销，否则不需要重新配对。详见 Devices CLI，了解 token 轮换和撤销。

注意：

  • 本地回环连接（127.0.0.1 / localhost）自动批准。
  • Tailnet 和局域网浏览器连接仍需明确批准，即使来自同一台机器。
  • 每个浏览器配置文件生成唯一设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。

语言支持 ​

Control UI 可以在首次加载时根据浏览器语言自动本地化。之后，在 Overview → Gateway Access → Language 中切换（语言选择器在网关访问卡片内，而非在外观设置下）。

  • 支持的语言：en、zh-CN、zh-TW、pt-BR、de、es、ja-JP、ko、fr、tr、uk、id、pl
  • 非英语翻译在浏览器中延迟加载。
  • 所选语言保存在浏览器存储中，下次访问时复用。
  • 缺失的翻译键回退到英语。

当前功能 ​

  • 通过 Gateway WS 与模型聊天（chat.history、chat.send、chat.abort、chat.inject）
  • 在聊天中流式显示工具调用 + 实时工具输出卡片（代理事件）
  • 频道：内置 + 捆绑/外部插件频道状态、QR 登录和每频道配置（channels.status、web.login.*、config.patch）
  • 实例：存在列表 + 刷新（system-presence）
  • 会话：列表 + 每会话模型/思考/快速/详细/推理覆盖（sessions.list、sessions.patch）
  • Dreams：做梦状态、启用/禁用切换和梦日记阅读器（doctor.memory.status、doctor.memory.dreamDiary、config.patch）
  • 定时任务：列表/添加/编辑/运行/启用/禁用 + 运行历史（cron.*）
  • 技能：状态、启用/禁用、安装、API Key 更新（skills.*）
  • 节点：列表 + 能力（node.list）
  • Exec 批准：编辑网关或节点白名单 + exec host=gateway/node 的询问策略（exec.approvals.*）
  • 配置：查看/编辑 ~/.openclaw/openclaw.json（config.get、config.set）
  • 配置：带验证的应用 + 重启，并唤醒最后活跃的会话
  • 配置写入包含基础哈希保护，防止并发编辑冲突
  • 配置写入（config.set/config.apply/config.patch）在写入前预检提交配置载荷中的活跃 SecretRef 解析；未解析的活跃提交引用在写入前被拒绝
  • 配置 schema + 表单渲染（含字段 title/description、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点的文档元数据，以及可用时的插件 + 频道 schema）；只有在快照安全往返时才提供原始 JSON 编辑器
  • 如果快照无法安全往返，Control UI 强制使用表单模式并禁用原始模式
  • 结构化 SecretRef 对象值在表单文本输入中以只读方式呈现，防止意外的对象到字符串损坏
  • 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（status、health、models.list）
  • 日志：带过滤/导出的网关文件日志实时尾部追踪（logs.tail）
  • 更新：运行包/git 更新 + 重启（update.run），带重启报告

定时任务面板说明：

  • 对于隔离任务，投递默认为通告摘要。若只需内部运行，可切换为无投递。
  • 选择通告时显示频道/目标字段。
  • Webhook 模式使用 delivery.mode = "webhook" 加设置为有效 HTTP(S) Webhook URL 的 delivery.to。
  • 对于主会话任务，Webhook 和无投递模式均可用。
  • 高级编辑控件包括运行后删除、清除代理覆盖、cron 精确/交错选项、代理模型/思考覆盖和尽力投递开关。
  • 表单验证内联显示字段级错误；无效值禁用保存按钮。
  • 设置 cron.webhookToken 发送专用 bearer token，若省略则发送时不带认证头。
  • 弃用回退：存储了 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.history 还会从可见 assistant 文本中剥离仅供显示的内联指令标签（如 [[reply_to_*]] 和 [[audio_as_voice]]）、纯文本工具调用 XML 载荷（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 以及截断的工具调用块），以及泄漏的 ASCII/全角模型控制 token，并省略整个可见文本仅为精确静默令牌 NO_REPLY / no_reply 的 assistant 条目。
  • chat.inject 直接向会话转录追加助手注释，并为 UI 广播 chat 事件（无代理运行，无频道投递）。
  • 聊天头部的模型和思考选择器通过 sessions.patch 立即修补活跃会话；它们是持久的会话覆盖，而非单次发送选项。
  • 停止方式：
    • 点击停止（调用 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://<magicdns>/（或你配置的 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 流量也需要明确共享密钥凭据，设置 gateway.auth.allowTailscale: false（然后使用 gateway.auth.mode: "token" 或 "password"）。无 token 的 Serve 认证假定网关主机是可信的；若主机上可能运行不可信的本地代码，需要 token/密码认证。

绑定到 tailnet + token ​

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

然后打开：

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

将匹配的共享密钥粘贴到 UI 设置中（作为 connect.params.auth.token 或 connect.params.auth.password 发送）。

不安全 HTTP ​

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

已记录的例外：

  • 带 gateway.controlUi.allowInsecureAuth=true 的仅 localhost 不安全 HTTP 兼容性
  • 通过 gateway.auth.mode: "trusted-proxy" 的成功操作员 Control UI 认证
  • 紧急情况 gateway.controlUi.dangerouslyDisableDeviceAuth=true

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

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

不安全认证切换行为：

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

allowInsecureAuth 仅是本地兼容性切换：允许本地 Control UI 会话在非安全 HTTP 上下文中无设备身份继续；不绕过配对检查；不放宽远程（非本地）设备身份要求。

紧急情况专用：

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

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

可信代理说明：成功的可信代理认证可以无需设备身份接入操作员 Control UI 会话，但这不适用于节点角色的 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://<gateway-host>:18789

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

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

注意：

  • gatewayUrl 加载后存储在 localStorage 中，并从 URL 中移除。
  • token 应尽可能通过 URL 片段（#token=...）传递。片段不会发送到服务器，避免请求日志和 Referer 泄漏。旧版 ?token= 查询参数仍作为回退一次性导入以保持兼容性，但立即引导后会被清除。
  • password 仅保存在内存中。
  • 设置 gatewayUrl 时，UI 不会回退到配置或环境凭据，需显式提供 token（或 password）。缺少显式凭据是错误。
  • Gateway 在 TLS 后面时（Tailscale Serve、HTTPS 代理等）使用 wss://。
  • gatewayUrl 仅在顶级窗口（非嵌入）中被接受，防止点击劫持。
  • 非回环 Control UI 部署必须明确设置 gateway.controlUi.allowedOrigins（完整来源），包括远程开发设置。
  • 不要将 gateway.controlUi.allowedOrigins: ["*"] 用于严格控制的本地测试以外的场景。它意味着允许任何浏览器来源，而不是"匹配我使用的任何主机"。

示例：

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

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

相关链接 ​

常见问题 ​

Q: 为什么每次换浏览器都要重新配对？

A: Control UI 使用设备身份验证来防止未授权访问。每个浏览器配置文件生成唯一设备 ID——切换浏览器、使用无痕模式或清除浏览器存储都会产生新的设备 ID，需要重新配对。本地回环连接（127.0.0.1）是例外，自动批准，无需配对。

Q: 语言选择器在哪里？

A: 在 Overview → Gateway Access → Language，注意是在"网关访问"卡片内，不是"外观"设置下。首次加载时自动根据浏览器语言设置，之后可手动切换。目前支持 13 种语言：中文简繁、英语、葡萄牙语、德语、西班牙语、日语、韩语、法语、土耳其语、乌克兰语、印度尼西亚语、波兰语。

Q: 配置表单里的 SecretRef 字段为什么是只读的？

A: 这是设计安全保护。SecretRef 字段（用于引用外部密钥系统的配置）在表单中以只读方式渲染，防止意外将结构化对象值覆盖为普通字符串，导致密钥引用损坏。如需修改，使用原始 JSON 编辑器（仅在快照能安全往返时可用）。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策