跳转至

仪表盘

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

快速打开(本地 Gateway):

关键参考:

认证在 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。

Warning

Control UI 是管理面(聊天、配置、exec 审批)。请勿将其公开暴露。UI 在加载后会将凭据从 URL 中移除。成功建立 token 模式连接后,它会将共享密钥保存在当前浏览器标签页和 Gateway 来源的 sessionStorage 中;密码仅保留在内存中。建议优先使用 localhost、Tailscale Serve 或 SSH 隧道。

  • 完成初始引导后,CLI 会自动打开仪表盘并打印一个简洁链接。
  • 随时重新打开或修复浏览器:运行 openclaw dashboard。它会复制/打开一个单次使用的配对链接,该链接授予该特定已签名浏览器管理员访问权限,包括从先前受限凭据中恢复,但不会授予全面的远程自动批准权限。
  • 如果剪贴板和浏览器投递均失败,openclaw dashboard 要么给出安全的手动 token 提示,要么告诉您运行 openclaw dashboard --json 并打开其短时有效的 browserUrl;它绝不会在交互式日志中打印共享 token 值。
  • 如果 UI 提示输入共享密钥认证,请在登录屏幕或 Settings → Gateway 的 Gateway secret 字段中粘贴配置的 token 或输入密码。

认证基础(本地与远程)

  • 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 发放一个短时有效、单次使用的 bootstrap,而不是将共享 Gateway token 放入浏览器启动 URL 中。该 bootstrap 绑定到该浏览器的签名设备身份,并兑换为持久的管理员凭据。不同的浏览器配置文件无法兑换同一交接,也无法继承由此产生的访问权限。
  • 配置缺失时的运行时 token:如果启动时提示生成了运行时 token,该 token 是临时的且无法恢复。Loopback 仍然需要认证。运行 openclaw doctor --generate-gateway-token,重启 Gateway,然后在交互式终端中运行 openclaw gateway auth-token --show,并将输出粘贴到 Control UI 设置中。
  • 如果 gateway.auth.token 由 SecretRef 管理,交互式仪表盘交接仍然有效,因为它只携带短时有效的浏览器 bootstrap;外部共享 token 不会被放入终端输出、剪贴板历史或浏览器启动参数中。
  • 共享密钥密码:使用配置的 gateway.auth.password(或 OPENCLAW_GATEWAY_PASSWORD)。仪表盘不会在重新加载后保留密码。
  • 携带身份的模式:当 gateway.auth.allowTailscale: true 时,Tailscale Serve 通过身份头满足 Control UI/WebSocket 认证;当 gateway.auth.mode: "trusted-proxy" 时,非 loopback 的身份感知反向代理可满足认证。两者都不需要在 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 基础路径,则在其下)。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 机器人可以通过 /controlui 将 Control UI 作为 Telegram Mini App 打开。 单独的 /dashboard 聊天命令会创建或更新一个会话仪表盘。 如果你在早期版本中为 Mini App 使用了 /dashboard,请参见 迁移指南。

要求:

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

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

v1 的非目标:

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

如果看到 “unauthorized” / 1008

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw