Gateway 仪表盘¶

Gateway 仪表盘是默认在 / 路径提供的基于浏览器的 Control UI（可通过 gateway.controlUi.basePath 覆盖）。

快速打开（本地 Gateway）：

• http://127.0.0.1:18789/（或 http://localhost:18789/）
• 当 gateway.tls.enabled: true 时，使用 https://127.0.0.1:18789/，WebSocket 端点使用 wss://127.0.0.1:18789。

关键参考：

• Control UI：用法和 UI 能力。
• Tailscale：Serve/Funnel 自动化。
• Web surfaces：绑定模式和安全说明。

认证在 WebSocket 握手时通过配置的 gateway 认证路径强制执行：

• connect.params.auth.token 或 connect.params.auth.password 中配置的共享密钥；gateway.auth.mode 决定使用哪个配置值
• 当 gateway.auth.allowTailscale: true 时，使用 Tailscale Serve 身份头
• 当 gateway.auth.mode: "trusted-proxy" 时，使用受信任代理身份头

参见 Gateway 配置 中的 gateway.auth。

快速路径（推荐）¶

• 完成初始配置后，CLI 会自动打开仪表盘并输出一个干净链接。
• 随时重新打开或修复浏览器：openclaw dashboard。它会复制/打开一个一次性配对链接，授予该特定签名浏览器管理员访问权限，包括从先前受限凭据中恢复，而不会授予全面的远程自动批准权限。
• 如果剪贴板复制和浏览器打开均失败，openclaw dashboard 会给出一个安全的手动 token 提示，或告知你运行 openclaw dashboard --json 并打开其短期的 browserUrl；它绝不会在交互式日志中打印共享 token 值。
• 如果 UI 提示输入共享密钥认证，请将配置的 token 粘贴到登录屏幕的 Gateway secret 中，或在 设置 → Gateway 中输入密码。

认证基础（本地与远程）¶

• localhost：打开 http://127.0.0.1:18789/。
• Gateway TLS：当 gateway.tls.enabled: true 时，仪表盘/状态链接使用 https://，Control UI WebSocket 链接使用 wss://。
• 共享密钥 token 来源：gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。成功进行 token 模式连接后，手动输入的内容保存在当前标签页和所选 Gateway URL 的 sessionStorage 中，而非 localStorage。
• 主机授权浏览器交接：openclaw dashboard 签发一个短期、一次性的引导凭证，而不是将共享 Gateway token 放入浏览器启动 URL。该引导凭证绑定到该浏览器的签名设备身份，并交换为持久的管理员凭据。其他浏览器配置文件无法兑换同一交接或继承由此产生的访问权限。
• 缺少配置的运行时 token：如果启动时提示生成了运行时 token，则该 token 是临时的，无法恢复。Loopback 仍然需要认证。运行 openclaw doctor --generate-gateway-token，重启 Gateway，然后在交互式终端中运行 openclaw gateway auth-token --show，并将输出粘贴到 Control UI 设置中。
• 如果 gateway.auth.token 由 SecretRef 管理，交互式仪表盘交接仍然有效，因为它仅携带短期的浏览器引导凭证；外部共享 token 不会出现在终端输出、剪贴板历史或浏览器启动参数中。
• 共享密钥密码：使用配置的 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。仪表盘不会在重新加载后持久保存密码。
• 携带身份的模式：当 gateway.auth.allowTailscale: true 时，Tailscale Serve 通过身份头满足 Control UI/WebSocket 认证；非 loopback 的身份感知反向代理满足 gateway.auth.mode: "trusted-proxy"。两者都不需要为 WebSocket 粘贴共享密钥。
• 非 localhost：使用 Tailscale Serve、非 loopback 共享密钥绑定、带 gateway.auth.mode: "trusted-proxy" 的非 loopback 身份感知反向代理，或 SSH 隧道。HTTP API 仍然使用共享密钥认证，除非你故意运行私有入口 gateway.auth.mode: "none" 或受信任代理 HTTP 认证。参见 Web surfaces。

自动浏览器交接¶

身份感知的 HTTPS 主机可以为直接仪表盘链接提供自动登录，同时保留 Gateway 现有的 token 和设备认证。当初始连接因缺少认证而失败时，Control UI 会向 GET /.well-known/openclaw/browser-bootstrap（如果配置了 Control UI 基础路径，则在其下）发起一次同源请求。会首先尝试现有凭据。显式凭据、远程 Gateway 选择、配对失败和被拒绝的凭据不会触发此恢复。

该端点属于部署的已认证代理或交接服务。OpenClaw 不会暴露未认证的凭据签发者。该服务必须在使用主机的 openclaw dashboard --json 交接之前独立验证浏览器的身份和授权。仅返回其一次性浏览器凭据：

{ "bootstrapToken": "<single-use-browser-bootstrap>", "bootstrapProfile": "owner" }

使用 Content-Type: application/json 和 Cache-Control: no-store，拒绝跨源请求，并且绝不返回共享 Gateway token。UI 拒绝重定向、大于 8 KiB 的响应，以及超过 4096 个可打印 ASCII 字符的 token。请求有 45 秒的期限，如果连接更改或页面停止，则会被取消。成功恢复会保留当前仪表盘路由。如果未配置端点或主机拒绝该请求，则现有的登录说明仍然可用。

在 Telegram 中打开¶

Telegram 机器人可以使用 /dashboard 将仪表盘作为 Telegram Mini App 打开。

要求：

• gateway.tailscale.mode: "serve" 或 "funnel"，以便 Telegram 获得 HTTPS Mini App URL。
• Telegram 发送者必须是机器人所有者：commands.ownerAllowFrom 中的数字 Telegram 用户 ID，或所选账户生效的 channels.telegram.allowFrom。
• 在与机器人的 DM 中运行 /dashboard。群组中的调用只会提示你在 DM 中打开该命令，并且不包含按钮。
• Docker 安装：Serve/Funnel 模式要求网关在 tailscaled 旁边绑定 loopback，而使用已发布端口的 bridge 网络无法满足这一点。使用 network_mode: host 运行网关容器，并将主机 tailscaled socket（/var/run/tailscale）以及 tailscale CLI 挂载到容器中。

Mini App 会执行一次有界的一次性仪表盘交接，并使用短期 bootstrap token 重定向到 Control UI。它不会在 URL 中暴露共享网关令牌，也不会获得为 Gateway 主机直接签发的交接保留的管理员授权。

v1 的非目标：

• 不支持 Telegram Web iframe。
• Tailscale Serve/Funnel 是唯一支持的已发布 URL 路径。

如果看到 “unauthorized” / 1008¶

• 确认网关可访问：本地运行 openclaw status；远程则使用 SSH 隧道 ssh -N -L 18789:127.0.0.1:18789 user@gateway-host，然后打开 http://127.0.0.1:18789/。
• 对于 AUTH_TOKEN_MISMATCH，当网关返回重试提示时，客户端可以使用缓存的设备令牌进行一次可信重试；该重试会复用令牌中缓存的已批准 scopes（显式 deviceToken/scopes 调用方保留其请求的 scope 集合）。如果该重试后认证仍然失败，请手动解决令牌漂移。
• 对于 AUTH_SCOPE_MISMATCH，设备令牌已被识别，但不包含请求的 scopes；请重新配对或批准新的 scope 集合，而不是轮换共享网关令牌。
• 对于 Proxy authentication required 或 AUTH_IDENTITY_HEADER_REQUIRED，打开已配置的代理/SSO 仪表盘 URL 并在那里登录。请 Gateway 管理员检查 WebSocket 升级时的身份头转发和账户访问。Gateway 令牌无法覆盖可信代理模式；参见 可信代理故障排查。
• 在该重试路径之外，Control UI 会优先使用待处理的 bootstrap token，以便新的由主机签发的交接可以创建或升级浏览器凭据。如果没有待处理的 bootstrap，则显式共享令牌/密码优先于已存储的设备令牌。
• 在异步 Tailscale Serve 路径上，针对相同 {scope, ip} 的失败尝试会在失败认证限流器记录之前被串行化，因此第二个并发的错误重试可能已经显示 retry later。
• 有关令牌漂移修复步骤，参见 令牌漂移恢复清单。
• 对于共享密钥认证，请从网关主机获取或提供已配置的密钥：
• Token：在 Gateway 主机的交互式终端中运行 openclaw gateway auth-token --show
• 密码：解析已配置的 gateway.auth.password 或 OPENCLAW_GATEWAY_PASSWORD
• 由 SecretRef 管理的令牌：运行 openclaw gateway auth-token --show；如果解析失败，请修复外部密钥提供程序并重新运行
• 由于未配置共享密钥而生成的运行时令牌：运行 openclaw doctor --generate-gateway-token，重启 Gateway，然后使用已配置的令牌
• 在仪表盘设置中，将令牌或密码粘贴到 网关密钥，然后连接。
• UI 语言选择器位于 设置 → 外观 → 语言。

相关¶

• Control UI
• WebChat
• openclaw dashboard — 从 CLI 安全打开 Control UI