仪表盘
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。
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 交接之前,该服务必须独立验证浏览器的身份和授权。仅返回其单次使用的浏览器凭据:
使用 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 容器,并将主机tailscaledsocket(/var/run/tailscale)以及tailscaleCLI 挂载到容器中。
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 语言选择器位于 设置 → 外观 → 语言。
相关¶
- Control UI
- WebChat
openclaw dashboard— 从 CLI 安全打开 Control UI
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw