跳转至

从新的浏览器、手机或网络访问 Control UI，并在连接失败时进行修复

设备配对（首次连接）

网关认证成功后，从新浏览器或设备连接通常需要一次性配对审批，显示为 disconnected (1008): pairing required。在 Gateway 主机上，openclaw dashboard 是首选的所有者路径：它会打开一个短期、一次性的配对链接，并为该特定已签名浏览器留下持久的管理员凭据。在同一浏览器中打开新链接还可以修复之前受限的凭据；其他浏览器配置文件无法继承或重放该授权。

1. 列出待处理请求

openclaw devices list

2. 按请求 ID 审批

openclaw devices approve <requestId>

等待审批期间请保持页面打开。请求获批后，它会自动重试并自行连接；点击立即检查可立即重试。

如果登录界面显示配对链接已失效，说明一次性 dashboard 链接可能已过期或已被使用。在 Gateway 主机上运行 openclaw dashboard，打开它打开或复制的新链接。如果该主机上没有浏览器或剪贴板访问权限，请运行 openclaw dashboard --json，并在十分钟内打开其 browserUrl。此错误并不表示共享的 Gateway token 或密码需要更改。

如果浏览器以更改后的认证详细信息（角色/范围/公钥）重试配对，之前的待处理请求将被取代，并生成新的 requestId；请先重新运行 openclaw devices list 再审批。

通过普通存储或共享凭据将已配对浏览器从只读访问切换为写/管理员访问，被视为审批升级，而非静默重连：OpenClaw 会保持旧审批有效、阻止权限更广的重连，并要求你明确审批新的权限范围集。少数例外是 openclaw dashboard 或图形化引导在 Gateway 主机上发出的全新所有者交接；它只能升级兑换该一次性交接的同一个已签名浏览器。

当已连接的 Control UI 报告访问受限时，打开收件箱 > 系统 > 访问受限，然后点击请求管理员。在移动设备上，打开侧边栏进入收件箱。浏览器会通过现有连接提交待处理的设备权限范围升级请求；在 Gateway 主机上运行显示的 openclaw devices approve <requestId> 命令，或在另一个具备管理员权限且具有 operator.pairing 的浏览器中从设备审批。审批完成期间请保持发起请求的标签页处于连接状态，以便它在重新连接前接收并存储新轮换的设备 token。重试会重新关联到待处理请求。取消会停止本地等待，但不会拒绝设备请求；如果你在审批前取消或断开连接，下次连接时请使用常规配对修复路径。

一旦获批，设备会被记住，无需再次审批，除非你使用 openclaw devices revoke --device <id> --role <role> 撤销它。有关 token 轮换、撤销以及 Paperclip / openclaw_gateway 首次运行审批流程，请参阅 Devices CLI。

如果 Gateway 因升级超出你被分配的 operator 角色而拒绝请求，访问详情会显示管理员更改指引，且没有重试按钮。管理员必须先更改角色，请求才能成功；设备审批无法超越该上限。重试仍可用于待处理、已拒绝或已过期的审批请求以及可重试的失败。取消会清除本地请求状态，以便在根本问题解决后发起新请求。

Note

  • 来自回环 TCP 对端（127.0.0.1 或 ::1，通常通过 localhost 访问）且未携带转发/代理头的直接本地 Control UI 连接，只有在网关认证成功且浏览器提供设备身份后，才能自动批准设备配对。在 token/密码模式下，首次连接仍需要配置的共享密钥；此自动批准并非 token 绕过。
  • 仅当显式配置 gateway.auth.mode: "none" 时，直接回环连接才不需要共享密钥。这会禁用网关认证，并非推荐的 Control UI 设置。Tailscale Serve 和可信代理模式只有在其各自的身份检查成功时，才能避免粘贴共享密钥。
  • 当 gateway.auth.allowTailscale: true、Tailscale 身份验证通过且浏览器提供其设备身份时，Tailscale Serve 可以跳过 Control UI 操作员会话的配对往返。无设备浏览器和节点角色连接仍遵循常规设备检查。
  • 直接 Tailnet 绑定和 LAN 浏览器连接仍需明确审批。没有设备身份的浏览器配置文件无法使用回环自动批准。
  • 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据需要重新配对。
  • 隐私窗口和退出时丢弃站点数据的浏览器配置文件（包括 Firefox 的“不记录历史记录”）也会丢弃已存储的设备身份和每设备 token。每次重启后它们都会显示为新浏览器；请使用持久化浏览器配置文件以保持配对，并在配对设备列表增长时使用 openclaw devices remove <deviceId> 删除过期条目。

配对移动设备

已配对的管理员无需打开终端即可创建 iOS/Android 连接二维码：

1. 打开移动配对

选择设备，然后在设备卡片中点击配对设备。

2. 连接手机

在 OpenClaw 移动应用中，打开设置 → Gateway 并扫描二维码。你也可以复制并粘贴设置代码。

3. 确认连接

官方 iOS/Android 应用会自动连接。如果待处理审批显示有请求，请先查看其角色和范围，然后再审批。

创建设置代码需要 operator.admin；没有该权限的会话会禁用此按钮。设置代码包含短期引导凭据，因此在有效期内请将二维码和复制的代码当作密码对待。对于远程配对，Gateway 必须可通过 wss:// 访问（例如通过 Tailscale Serve/Funnel）；纯 ws:// 仅限于回环和私有 LAN 地址。完整的安全和回退细节请参阅 Pairing。

运行时配置端点

Control UI 从 /control-ui-config.json 获取运行时设置，该路径相对于网关的 Control UI 基础路径解析（例如基础路径为 /__openclaw__/ 时，对应 /__openclaw__/control-ui-config.json）。该端点受网关 HTTP 认证保护：未认证的浏览器无法获取，成功获取需要有效的网关令牌/密码或受信任的代理身份。Tailscale 头认证适用于 Control UI WebSocket，而不适用于此 HTTP 端点。

本地及 data-URL agent 头像在此响应和浏览器身份 RPC 中使用经过认证的头像 URL，以保持启动 JSON 体积较小。原生和 CLI RPC 客户端保留其内联头像表示。

PWA 安装与 Web Push

Control UI 附带 manifest.webmanifest 和 service worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 让 Gateway 能够在标签页或浏览器窗口未打开时，通过通知唤醒已安装的 PWA。

在手机上，聊天和新建会话在设备安全区域内共享普通的侧边 gutter。已安装的应用使用完整的独立画布；浏览器标签页跟随动态视口。当浏览器报告键盘大小的视觉视口缩减时，shell 会将 composer 保持在其上方，并在键盘关闭时恢复底部安全区域，即使编辑器仍保持焦点。捏合缩放仍由浏览器控制。不支持 VisualViewport 的浏览器保留 CSS 布局。

在 macOS 应用中，通知设置页面显示应用的原生通知权限，而非浏览器推送，因为该应用原生地投递通知。

浏览器和 macOS 的设置步骤请参阅通知。

如果在 OpenClaw 更新后页面立即显示协议不匹配，请先用 openclaw dashboard 重新打开仪表盘并强制刷新。如果仍然失败，请清除仪表盘来源的站点数据或在隐私浏览器窗口中测试；旧的标签页或浏览器 service-worker 缓存可能会让更新前的 Control UI 包继续对接较新的 Gateway。

位置 作用
ui/public/manifest.webmanifest PWA 清单。浏览器在其可访问后会提供“安装应用”。
ui/public/sw.js 处理 push 事件和通知点击的 service worker。
state/openclaw.sqlite → config_machine_state (webPush.vapidKeys) 自动生成的 VAPID 密钥对，用于对 Web Push 载荷签名。
state/openclaw.sqlite → web_push_subscriptions 持久化的浏览器端点、密钥、设备/配置文件绑定和时间戳。

从已停用的 push/vapid-keys.json 和 push/web-push-subscriptions.json 存储升级时，相关数据由 openclaw doctor --fix 导入。运行该修复前请先停止 Gateway，以免旧进程在导入期间重新创建已停用的状态。升级后应在使用 Web Push 之前运行修复；只要仍存在任一已停用来源或中断的 Doctor 认领，注册、投递、删除和密钥解析都将拒绝继续。Gateway 运行时仅读写 SQLite。

当你希望固定密钥时（多主机部署、密钥轮换或测试），可通过 Gateway 进程上的环境变量覆盖 VAPID 密钥对：

  • OPENCLAW_VAPID_PUBLIC_KEY
  • OPENCLAW_VAPID_PRIVATE_KEY
  • OPENCLAW_VAPID_SUBJECT（默认为 https://openclaw.ai）

一个 service-worker 注册范围对应一个浏览器推送订阅，因此也对应一个应用服务器密钥。如果一个已安装的 PWA 在多个逻辑 Gateway 之间切换，请在每个 Gateway 上配置相同的 VAPID 公钥/私钥对，并设置每个 Gateway 的 gateway.publicOrigin；否则注册将因 VAPID 身份不匹配而失败关闭。共享 VAPID 私钥和浏览器端点会形成一个推送签名信任域，因此请仅在互相信任的 Gateway 之间这样做。从不同 HTTPS 源或基础路径范围安装的 PWA 拥有独立的注册，不需要共享密钥。

Control UI 使用这些按作用域门控的 Gateway 方法来注册和测试浏览器订阅：

  • push.web.vapidPublicKey：获取当前生效的 VAPID 公钥。
  • push.web.subscribe：注册一个 endpoint 以及 keys.p256dh/keys.auth；Gateway 会将其绑定到已认证的浏览器设备和当前用户配置文件。
  • push.web.unsubscribe：移除已注册的端点。
  • push.web.test：向已注册的浏览器订阅发送测试通知。

待处理的 exec 和插件审批也会触发 Web Push。审批投递的范围比 push.web.test 更窄：Gateway 只定向投递给那些其配对的设备、当前操作者令牌、配置文件角色和审批可见性仍然授权该请求的已绑定订阅。旧的未绑定订阅仅保持测试可用，直到 Control UI 重新连接并重新对齐它们。推送载荷只包含通用文本和一个经过认证的 /approve/<approvalId> 链接，而非审批详情。

Note

Web Push 独立于 iOS APNS 中继路径（参见配置了解中继推送）以及 push.test 方法，后者面向原生移动设备配对。

将 Gateway 保持在回环地址上，并让 Tailscale Serve 通过 HTTPS 代理它：

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 监听器上接受带有 Tailscale x-forwarded-* 头的请求。对于具有浏览器设备身份的 Control UI 操作者会话，这种经过验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍遵循正常的设备检查。如果你希望对 Serve 流量也要求显式的共享密钥凭据，请设置 gateway.auth.allowTailscale: false，然后使用 gateway.auth.mode: "token" 或 "password"。

对于该异步 Serve 身份路径，相同客户端 IP 和认证范围的失败认证尝试会在速率限制写入之前串行化。因此，来自同一浏览器的并发错误重试可能在第二个请求上显示 retry later，而不是两个普通不匹配错误并行竞争。

Warning

无 Token 的 Serve 认证假定网关主机是可信的。如果不可信的本地代码可能在该主机上运行，请要求使用 token/密码认证。

不安全 HTTP

通过明文 HTTP（http://<lan-ip> 或 http://<tailscale-ip>）打开仪表盘可以工作：设备身份使用纯 JS Ed25519 生成并签名，因此配对不依赖 WebCrypto 或安全上下文。签名密钥永远不会离开浏览器，这使它成为明文传输无法泄露的唯一凭据——不同于共享 token，任何 HTTP 连接路径上的观察者都可以读取它。

明文 HTTP 仍然是降级传输：路径上的主动攻击者可以修改页面并捕获其中的任何内容。尽可能优先使用 HTTPS——Tailscale Serve 无需配置即可提供真实证书——并将 HTTP 视为仅限 LAN 的便利方式。浏览器还会在 HTTP 上不提供安全上下文功能（例如 passkeys），并且 Chrome 的 Local Network Access 规则越来越限制明文本地请求。

受支持的无设备例外是通过 gateway.auth.mode: "trusted-proxy" 成功完成操作员 Control UI 认证。没有持久配置开关可以禁用设备身份。

推荐配置： 通过 https://<magicdns>/（Tailscale Serve）使用 HTTPS，或在网关主机上本地使用 http://127.0.0.1:18789/ 访问 UI。

可信代理说明
  • 成功的可信代理认证可以允许操作员 Control UI 会话无需设备身份。
  • 这不扩展到节点角色 Control UI 会话。
  • 同主机回环反向代理需要 gateway.trustedProxies 中包含回环，并且 gateway.auth.trustedProxy.allowLoopback: true；参见 可信代理认证。

有关 HTTPS 设置指南，请参见 Tailscale。

空白 Control UI 页面

如果浏览器加载了空白仪表盘，并且 DevTools 没有显示有用的错误，可能是扩展或早期内容脚本阻止了 JavaScript 模块应用求值。静态页面包含一个纯 HTML 恢复面板，当 <openclaw-app> 在启动后未完成首次渲染时会出现。在浏览器仍在下载初始应用模块期间，面板显示 Control UI 仍在加载，并让这些下载继续运行。一旦模块加载完成但没有渲染，自动恢复可以请求一个新页面。继续等待 会取消待处理的恢复请求，并给当前页面更多时间；重试 会显式重新加载它。

更改浏览器环境后，使用面板的 重试 操作，或在完成以下检查后手动重新加载：

  • 禁用注入到所有页面的扩展，尤其是带有 <all_urls> 内容脚本的扩展。
  • 尝试使用隐私窗口、干净的浏览器配置文件或其他浏览器。
  • 保持 Gateway 运行，并在更改浏览器后验证相同的仪表盘 URL。

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