OpenClaw 控制台 Control UI 无法连接时如何排查 URL、认证与设备身份【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawControl UI 是 Gateway 在浏览器里提供的控制台聊天、节点、配置等管理界面默认地址为http://host:18789/它通过同一个端口上的 Gateway WebSocket 直接通信。当页面打不开、一直报unauthorized或卡在disconnected (1008): pairing required时问题通常落在三类之一URL/端口目标不对、Gateway 认证token/password不匹配、设备身份pairing未满足。本文按 docs 中 “Dashboard control UI connectivity” 的排障路径给出从确认服务到恢复连接的完整检查顺序。第一步确认 Gateway 在运行拿到正确的连接信息在 Gateway 主机上依次运行openclaw gateway status openclaw status openclaw logs --follow openclaw doctor openclaw gateway status --json健康信号openclaw gateway status显示Runtime: running、Connectivity probe: ok以及一行Capability: ...。排障时重点核对三件事文档明确要求 “validate URL, auth mode, and secure context assumptions”客户端实际连接的 probe URL 与 dashboard URL 是否一致客户端使用的 auth mode/token 与 Gateway 配置是否匹配是否存在 “HTTP usage where device identity is required” 的情况即在不满足设备身份要求的环境下走 HTTP。本地浏览器连不上 127.0.0.1:18789更新后本地浏览器打不开http://127.0.0.1:18789时先恢复本地 Gateway 服务并确认它正在提供 dashboardopenclaw gateway restart lsof -i :18789 curl http://127.0.0.1:18789lsof -i :18789用于确认端口上有监听进程curl是只读探测。判断方式curl返回 OpenClaw HTMLGateway 本身工作正常剩余问题多为浏览器缓存、旧 deep link 或陈旧 tab 状态。直接打开http://127.0.0.1:18789从 dashboard 内部导航不要复用旧链接。重启后服务没有保持运行执行openclaw gateway start再重新检查openclaw gateway status。如果配置了gateway.tls.enabled: truedashboard 和 WebSocket 分别使用https://127.0.0.1:18789/与wss://127.0.0.1:18789HTTP 链接自然连不上。另外OpenClaw 更新后立即出现Protocol mismatch的先用openclaw dashboard重新打开并强制刷新仍失败则清除该 dashboard origin 的站点数据或用无痕窗口测试——旧 tab 或 service worker 缓存可能还在运行更新前的 UI 包。URL 排错目标、模式与端口报错gateway connect failed:表示 host/port/url 目标本身错了不是认证问题。更新后配置行为变化时用以下命令核对目标与模式openclaw config get gateway.mode openclaw config get gateway.remote.url openclaw config get gateway.auth.mode判断要点gateway.moderemote时CLI 调用可能指向远端而本地服务本身是正常的显式--url调用不会回退到已保存的凭据必须显式带--token或--password否则命令直接报错unauthorized则说明端点可达但认证不正确应转入下一节的认证排错。若从外部网络访问远程 Gateway 可走 SSH 隧道ssh -N -L 18789:127.0.0.1:18789 usergateway-host然后本地打开http://127.0.0.1:18789/推荐方案仍是 Tailscale Serveopenclaw gateway --tailscale serve后打开https://magicdns/。认证排错token / password 与 token driftControl UI 的认证发生在 WebSocket 握手阶段gateway.auth.mode决定取gateway.auth.token还是gateway.auth.password粘贴位置是登录界面或Settings → Gateway的同一个Gateway secret字段粘贴 token 或输入 password。token 模式下连接成功后secret 只保存在当前 tab 的 sessionStorage 中password 只保留在内存里。获取当前有效 token 的正规方式是在 Gateway 主机的交互式终端运行openclaw gateway auth-token --show其输出是敏感信息应像密码一样对待粘贴进Gateway secret后重试连接。一个特殊情况如果 Gateway 以 token 模式启动但配置中没有 token进程会生成一个临时 runtime token——它不写入配置、无法找回loopback 浏览器没有它就会一直被拒。恢复路径是openclaw doctor --generate-gateway-token openclaw gateway restart openclaw gateway auth-token --show生成后重启 Gateway再把--show的输出粘贴进Gateway secret。反复 unauthorizedtoken drift 恢复清单当缓存的设备 token 反复报AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH或AUTH_SCOPE_MISMATCH时按 docs/cli/devices.md 的 token drift 恢复清单操作确认当前 gateway token 来源openclaw gateway auth-token --show在 Gateway 主机交互式终端openclaw devices list列出已配对设备找到受影响设备的deviceId轮换该设备的 operator tokenopenclaw devices rotate --device deviceId --role operatordeviceId替换为上一步列出的设备 ID。若调用者正是用该设备 token 认证响应会包含替换 token客户端需先保存再重连轮换仍不够时移除旧配对并重新批准requestId来自devices list中新的 pending 请求openclaw devices remove deviceId openclaw devices list openclaw devices approve requestId用当前共享 token/password 重试客户端连接。注意重连的认证优先级是显式共享 token/password 优先然后显式deviceToken再是已存储的 device token最后是 bootstrap tokenAUTH_SCOPE_MISMATCH表示设备 token 本身被识别、只是已批准的 scope 不覆盖本次请求应重新配对或批准新的 scope 契约而不是去轮换共享 gateway token。设备身份排错pairing 与 detail code网关认证gateway auth通过后新浏览器/设备的首次连接通常需要一次性的配对批准表现为disconnected (1008): pairing required。在 Gateway 主机上openclaw devices list openclaw devices approve requestIdrequestId替换为devices list输出中 pending 请求的 ID省略 ID 或加--latest只会预览最新请求而不会批准。浏览器页面保持打开即可——批准后页面会自动重试并完成连接也可以点Check now立即重试。如果设备以变更后的认证细节role/scopes/公钥重试配对旧的 pending 请求会被新requestId取代批准前重新运行openclaw devices list拿当前 ID。在 Gateway 主机上openclaw dashboard是推荐的所有者路径它发出一次性配对链接只把管理员凭据授予那一个已签名的浏览器。失败响应里带error.details.code按它决定下一步来自 docs/gateway/troubleshooting.md 的 detail code 速查表Detail code含义建议操作AUTH_TOKEN_MISSING客户端没发送必需的共享 token在 Gateway 主机交互式终端运行openclaw gateway auth-token --show把输出粘贴进客户端重试AUTH_TOKEN_MISMATCH共享 token 与 gateway 不一致若canRetryWithDeviceTokentrue允许一次受信重试仍失败按上面的 token drift 清单处理AUTH_DEVICE_TOKEN_MISMATCH缓存的每设备 token 已过期或被吊销用 devices CLI 轮换/重新批准设备 token 后重连AUTH_SCOPE_MISMATCH设备 token 有效但已批准 scope 不覆盖本次请求重新配对或批准请求的 scope 契约不要当作共享 token drift 处理PAIRING_REQUIRED设备身份需要批准查看error.details.reasonnot-paired、scope-upgrade、role-upgrade、metadata-upgradeopenclaw devices list后openclaw devices approve requestId连接层签名还可以帮你进一步定位device identity required非安全上下文或缺少设备认证origin not allowed浏览器Origin不在gateway.controlUi.allowedOrigins或以非 loopback 浏览器 origin 连接且没有显式白名单device nonce required/device nonce mismatch客户端没有完成挑战式设备认证流程等待connect.challenge→ 签名 challenge 绑定载荷 → 以同一 challenge nonce 发送connect.params.device.noncedevice signature invalid/device signature expired客户端签错了载荷或时间戳过期通常需要更新连接端客户端too many failed authentication attempts (retry later)同一规范化Origin的失败次数触发临时锁定另一个 localhost origin 使用独立的计数桶gateway connect failed:host/port/url 目标错误回到 URL 排错一节。设备身份在浏览器里的几个边界每个浏览器 profile 生成唯一设备 ID换浏览器或清空浏览器数据就需要重新配对隐私窗口/退出即清数据的 profile 会丢设备身份与每设备 token会每次都像新浏览器出现需要openclaw devices remove deviceId清理陈旧条目。loopback 直连127.0.0.1或::1、无代理头在网关认证成功后且浏览器呈现设备身份时可以自动批准配对但这不是 token 豁免仅当显式配置gateway.auth.mode: none时 loopback 才免共享密钥文档明确这不推荐。验证连接是否恢复完成对应修复后用两个层面确认主机侧openclaw gateway status恢复显示Runtime: running与Connectivity probe: ok浏览器侧dashboard 页面加载出控制台界面且设备已配对——之后不会重复要求批准除非你用openclaw devices revoke --device id --role role吊销。如果服务已监听、curl也返回 OpenClaw HTML但浏览器仍是空白页且 DevTools 无有用报错这属于另一类问题浏览器扩展/早期内容脚本阻止了 JS 模块求值可禁用注入所有页面的扩展、换无痕窗口或干净的浏览器 profile 重试详见 Connect and pair 的 “Blank Control UI page” 一节。参考文档Gateway troubleshootingDashboard control UI connectivityControl UIConnect and pairDevices CLI 与 token drift 恢复清单Dashboardunauthorized / 1008【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenClaw 控制台 Control UI 无法连接时如何排查 URL、认证与设备身份？
OpenClaw 控制台 Control UI 无法连接时如何排查 URL、认证与设备身份【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawControl UI 是 Gateway 在浏览器里提供的控制台聊天、节点、配置等管理界面默认地址为http://host:18789/它通过同一个端口上的 Gateway WebSocket 直接通信。当页面打不开、一直报unauthorized或卡在disconnected (1008): pairing required时问题通常落在三类之一URL/端口目标不对、Gateway 认证token/password不匹配、设备身份pairing未满足。本文按 docs 中 “Dashboard control UI connectivity” 的排障路径给出从确认服务到恢复连接的完整检查顺序。第一步确认 Gateway 在运行拿到正确的连接信息在 Gateway 主机上依次运行openclaw gateway status openclaw status openclaw logs --follow openclaw doctor openclaw gateway status --json健康信号openclaw gateway status显示Runtime: running、Connectivity probe: ok以及一行Capability: ...。排障时重点核对三件事文档明确要求 “validate URL, auth mode, and secure context assumptions”客户端实际连接的 probe URL 与 dashboard URL 是否一致客户端使用的 auth mode/token 与 Gateway 配置是否匹配是否存在 “HTTP usage where device identity is required” 的情况即在不满足设备身份要求的环境下走 HTTP。本地浏览器连不上 127.0.0.1:18789更新后本地浏览器打不开http://127.0.0.1:18789时先恢复本地 Gateway 服务并确认它正在提供 dashboardopenclaw gateway restart lsof -i :18789 curl http://127.0.0.1:18789lsof -i :18789用于确认端口上有监听进程curl是只读探测。判断方式curl返回 OpenClaw HTMLGateway 本身工作正常剩余问题多为浏览器缓存、旧 deep link 或陈旧 tab 状态。直接打开http://127.0.0.1:18789从 dashboard 内部导航不要复用旧链接。重启后服务没有保持运行执行openclaw gateway start再重新检查openclaw gateway status。如果配置了gateway.tls.enabled: truedashboard 和 WebSocket 分别使用https://127.0.0.1:18789/与wss://127.0.0.1:18789HTTP 链接自然连不上。另外OpenClaw 更新后立即出现Protocol mismatch的先用openclaw dashboard重新打开并强制刷新仍失败则清除该 dashboard origin 的站点数据或用无痕窗口测试——旧 tab 或 service worker 缓存可能还在运行更新前的 UI 包。URL 排错目标、模式与端口报错gateway connect failed:表示 host/port/url 目标本身错了不是认证问题。更新后配置行为变化时用以下命令核对目标与模式openclaw config get gateway.mode openclaw config get gateway.remote.url openclaw config get gateway.auth.mode判断要点gateway.moderemote时CLI 调用可能指向远端而本地服务本身是正常的显式--url调用不会回退到已保存的凭据必须显式带--token或--password否则命令直接报错unauthorized则说明端点可达但认证不正确应转入下一节的认证排错。若从外部网络访问远程 Gateway 可走 SSH 隧道ssh -N -L 18789:127.0.0.1:18789 usergateway-host然后本地打开http://127.0.0.1:18789/推荐方案仍是 Tailscale Serveopenclaw gateway --tailscale serve后打开https://magicdns/。认证排错token / password 与 token driftControl UI 的认证发生在 WebSocket 握手阶段gateway.auth.mode决定取gateway.auth.token还是gateway.auth.password粘贴位置是登录界面或Settings → Gateway的同一个Gateway secret字段粘贴 token 或输入 password。token 模式下连接成功后secret 只保存在当前 tab 的 sessionStorage 中password 只保留在内存里。获取当前有效 token 的正规方式是在 Gateway 主机的交互式终端运行openclaw gateway auth-token --show其输出是敏感信息应像密码一样对待粘贴进Gateway secret后重试连接。一个特殊情况如果 Gateway 以 token 模式启动但配置中没有 token进程会生成一个临时 runtime token——它不写入配置、无法找回loopback 浏览器没有它就会一直被拒。恢复路径是openclaw doctor --generate-gateway-token openclaw gateway restart openclaw gateway auth-token --show生成后重启 Gateway再把--show的输出粘贴进Gateway secret。反复 unauthorizedtoken drift 恢复清单当缓存的设备 token 反复报AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH或AUTH_SCOPE_MISMATCH时按 docs/cli/devices.md 的 token drift 恢复清单操作确认当前 gateway token 来源openclaw gateway auth-token --show在 Gateway 主机交互式终端openclaw devices list列出已配对设备找到受影响设备的deviceId轮换该设备的 operator tokenopenclaw devices rotate --device deviceId --role operatordeviceId替换为上一步列出的设备 ID。若调用者正是用该设备 token 认证响应会包含替换 token客户端需先保存再重连轮换仍不够时移除旧配对并重新批准requestId来自devices list中新的 pending 请求openclaw devices remove deviceId openclaw devices list openclaw devices approve requestId用当前共享 token/password 重试客户端连接。注意重连的认证优先级是显式共享 token/password 优先然后显式deviceToken再是已存储的 device token最后是 bootstrap tokenAUTH_SCOPE_MISMATCH表示设备 token 本身被识别、只是已批准的 scope 不覆盖本次请求应重新配对或批准新的 scope 契约而不是去轮换共享 gateway token。设备身份排错pairing 与 detail code网关认证gateway auth通过后新浏览器/设备的首次连接通常需要一次性的配对批准表现为disconnected (1008): pairing required。在 Gateway 主机上openclaw devices list openclaw devices approve requestIdrequestId替换为devices list输出中 pending 请求的 ID省略 ID 或加--latest只会预览最新请求而不会批准。浏览器页面保持打开即可——批准后页面会自动重试并完成连接也可以点Check now立即重试。如果设备以变更后的认证细节role/scopes/公钥重试配对旧的 pending 请求会被新requestId取代批准前重新运行openclaw devices list拿当前 ID。在 Gateway 主机上openclaw dashboard是推荐的所有者路径它发出一次性配对链接只把管理员凭据授予那一个已签名的浏览器。失败响应里带error.details.code按它决定下一步来自 docs/gateway/troubleshooting.md 的 detail code 速查表Detail code含义建议操作AUTH_TOKEN_MISSING客户端没发送必需的共享 token在 Gateway 主机交互式终端运行openclaw gateway auth-token --show把输出粘贴进客户端重试AUTH_TOKEN_MISMATCH共享 token 与 gateway 不一致若canRetryWithDeviceTokentrue允许一次受信重试仍失败按上面的 token drift 清单处理AUTH_DEVICE_TOKEN_MISMATCH缓存的每设备 token 已过期或被吊销用 devices CLI 轮换/重新批准设备 token 后重连AUTH_SCOPE_MISMATCH设备 token 有效但已批准 scope 不覆盖本次请求重新配对或批准请求的 scope 契约不要当作共享 token drift 处理PAIRING_REQUIRED设备身份需要批准查看error.details.reasonnot-paired、scope-upgrade、role-upgrade、metadata-upgradeopenclaw devices list后openclaw devices approve requestId连接层签名还可以帮你进一步定位device identity required非安全上下文或缺少设备认证origin not allowed浏览器Origin不在gateway.controlUi.allowedOrigins或以非 loopback 浏览器 origin 连接且没有显式白名单device nonce required/device nonce mismatch客户端没有完成挑战式设备认证流程等待connect.challenge→ 签名 challenge 绑定载荷 → 以同一 challenge nonce 发送connect.params.device.noncedevice signature invalid/device signature expired客户端签错了载荷或时间戳过期通常需要更新连接端客户端too many failed authentication attempts (retry later)同一规范化Origin的失败次数触发临时锁定另一个 localhost origin 使用独立的计数桶gateway connect failed:host/port/url 目标错误回到 URL 排错一节。设备身份在浏览器里的几个边界每个浏览器 profile 生成唯一设备 ID换浏览器或清空浏览器数据就需要重新配对隐私窗口/退出即清数据的 profile 会丢设备身份与每设备 token会每次都像新浏览器出现需要openclaw devices remove deviceId清理陈旧条目。loopback 直连127.0.0.1或::1、无代理头在网关认证成功后且浏览器呈现设备身份时可以自动批准配对但这不是 token 豁免仅当显式配置gateway.auth.mode: none时 loopback 才免共享密钥文档明确这不推荐。验证连接是否恢复完成对应修复后用两个层面确认主机侧openclaw gateway status恢复显示Runtime: running与Connectivity probe: ok浏览器侧dashboard 页面加载出控制台界面且设备已配对——之后不会重复要求批准除非你用openclaw devices revoke --device id --role role吊销。如果服务已监听、curl也返回 OpenClaw HTML但浏览器仍是空白页且 DevTools 无有用报错这属于另一类问题浏览器扩展/早期内容脚本阻止了 JS 模块求值可禁用注入所有页面的扩展、换无痕窗口或干净的浏览器 profile 重试详见 Connect and pair 的 “Blank Control UI page” 一节。参考文档Gateway troubleshootingDashboard control UI connectivityControl UIConnect and pairDevices CLI 与 token drift 恢复清单Dashboardunauthorized / 1008【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考