跳转至

连接和配对

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

设备配对(首次连接)

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

1. 列出待处理的请求

openclaw devices list

2. 按请求 ID 审批

openclaw devices approve <requestId>

审批挂起期间请保持页面打开。页面会等待决策,并在请求获批后自动连接;立即检查可让您立即重试。

如果操作员通过 CLI 或设备拒绝此浏览器的请求,等待页面会显示访问请求已被拒绝,并停止自动重试。选择再次请求以提交另一个请求。未获应答的请求会显示访问请求已过期,而不是已被拒绝。这些结果属于实时连接,而非存储的拒绝历史:重新加载页面可能会再次请求审批。拒绝一个浏览器不会影响另一个浏览器的待处理请求。

如果登录屏幕显示配对链接已失效,则一次性仪表盘链接可能已过期或已被使用。在 Gateway 主机上运行 openclaw dashboard,然后打开它打开或复制的新链接。如果无法在该主机上访问浏览器或剪贴板,请运行 openclaw dashboard --json,并在十分钟内打开其 browserUrl。此错误并不意味着共享的 Gateway 令牌或密码需要更改。

如果浏览器使用已更改的认证详细信息(角色/作用域/公钥)重试配对,之前的待处理请求将被取代,并创建新的 requestId;在审批前请重新运行 openclaw devices list。

通过普通存储或共享凭据,将已配对浏览器从只读访问切换为写入/管理员访问,被视为审批升级,而非静默重连:OpenClaw 会保持旧审批处于活动状态,阻止权限范围更广的重连,并要求您明确审批新的作用域集合。唯一的例外是 openclaw dashboard 或图形化引导在 Gateway 主机上发出的新所有者交接;它只能升级赎回该一次性交接的同一个已签名浏览器。

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

如果设备之前已获批管理员访问权限,但其令牌随后被收窄,则审批该请求会保留该令牌限制。UI 会解释配对已获批但未恢复所请求的访问权限,而不会报告拒绝或提供无法解除该限制的重试。在 Gateway 主机上运行 openclaw dashboard --json,并在同一浏览器中打开其新的一次性 browserUrl,以通过所有者交接恢复管理员访问权限。

对于局域网或远程浏览器,请保持相同的 Control UI 源和 Gateway URL,以便交接修复现有的浏览器身份。如果 browserUrl 使用回环地址,请将其基础地址替换为当前 Control UI 地址,并将其 gatewayUrl 片段参数替换为当前 Gateway WebSocket URL。保留其余的一次性配对片段值,并在十分钟内打开该链接。请仅使用同一 Gateway 的地址;不要将配对链接发送到其他主机。

一旦获批,设备将被记住,除非您使用 openclaw devices revoke --device <id> --role <role> 撤销它,否则无需重新审批。有关令牌轮换、撤销以及 Paperclip / openclaw_gateway 首次运行审批流程,请参阅 Devices CLI。

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

Note

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

配对移动设备

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

1. 打开移动配对

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

2. 连接手机

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

3. 确认连接

官方 iOS/Android 应用会自动连接。如果 待批准 显示请求,请在批准前检查其角色和权限范围。

创建设置代码需要 operator.admin;对于没有该权限的会话,按钮将被禁用。设置代码包含短期引导凭据,因此在有效期内应将二维码和复制的代码视为密码。对于远程配对,Gateway 必须解析为 wss://(例如通过 Tailscale Serve/Funnel);普通 ws:// 仅限于环回地址和私有局域网地址。有关完整的安全和回退详情,请参阅 配对。

运行时配置端点

Control UI 从 /control-ui-config.json 获取其运行时设置,该路径相对于 Gateway 的 Control UI 基础路径解析(例如在基础路径 /__openclaw__/ 下为 /__openclaw__/control-ui-config.json)。该端点受 Gateway HTTP 身份验证保护:未认证浏览器无法获取它,成功获取需要有效的 Gateway token/密码或受信任代理身份。Tailscale 头部身份验证适用于 Control UI WebSocket,而不是此 HTTP 端点。

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

PWA 安装与 Web 推送

Control UI 附带一个 manifest.webmanifest 和一个 service worker,因此现代浏览器可以将其安装为独立 PWA。Web Push 允许 Gateway 通过通知唤醒已安装的 PWA,即使标签页或浏览器窗口未打开。

在手机上,聊天和新建会话在设备安全区域内共享普通侧边留白。已安装的应用使用完整的独立画布;浏览器标签页遵循动态视口。当浏览器报告键盘大小的可视视口缩减时,外壳会将输入框保持在键盘上方,并在键盘关闭时恢复底部安全区域,即使编辑器仍保持焦点。捏合缩放仍由浏览器控制。没有 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 仅针对绑定的订阅,且其配对设备、当前 operator token、配置文件角色和批准可见性仍授权该请求。旧版未绑定订阅保持仅测试状态,直到 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 路径还会跳过设备配对往返;无设备浏览器和 node-role 连接仍遵循常规设备检查。如果你希望即使对于 Serve 流量也要求显式的共享密钥凭据,请设置 gateway.auth.allowTailscale: false,然后使用 gateway.auth.mode: "token" 或 "password"。

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

Warning

无令牌 Serve 身份验证假定 gateway 主机是受信任的。如果不可信本地代码可能在该主机上运行,请要求 token/password 身份验证。

不安全 HTTP

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

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

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

推荐设置: 通过 https://<magicdns>/ 使用 HTTPS(Tailscale Serve),或在 gateway 主机上本地访问 UI:http://127.0.0.1:18789/。

可信代理说明
  • 成功的可信代理身份验证可以允许 操作员 Control UI 会话无需设备身份。
  • 这不扩展到 node-role Control UI 会话。
  • 同主机回环反向代理需要同时满足 gateway.trustedProxies 中的回环和 gateway.auth.trustedProxy.allowLoopback: true;参见 可信代理身份验证。

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

空白 Control UI 页面

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

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

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

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