All ClawAll Claw
Back to Blog
BlogMarch 21, 2026

OpenClaw "Device Identity Required" 错误完整解决教程

前置条件

开始之前请确保已准备好以下内容：

  • 已安装并运行最新版 OpenClaw（建议使用 openclaw --version 检查版本）
  • Gateway 正在运行（通常通过 openclaw start 或 systemd/Docker 启动）
  • 可以执行 openclaw 命令行
  • 使用支持现代 WebSocket 的浏览器（推荐 Chrome/Edge/Firefox）
  • 了解基本概念：WebSocket 断开码 1008、secure context（安全上下文）、设备指纹

错误表现：Control UI 显示 "device identity required" 或 WebSocket 连接失败，日志中出现类似 code:1008 的信息。

第1步：理解错误原因

OpenClaw Control UI 采用双重身份验证机制：

  1. Token 认证（通过 URL 中的 token 参数）
  2. 设备身份认证（浏览器生成签名 + 网关端手动/自动批准）

当浏览器无法提供有效的设备身份时，网关会主动断开连接并返回 1008 错误。常见触发场景：

  • 使用普通 http:// 而非 https:// 或 localhost
  • 新浏览器、新隐身窗口、清除过存储
  • 远程访问未完成配对
  • 设备请求被拒绝或超时

第2步：使用 Token 快速访问（大多数情况立即生效）

生成带 token 的控制面板链接：

openclaw dashboard --no-open

预期输出示例：

Control UI ready at:
http://127.0.0.1:18789/dashboard?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

直接复制完整链接在浏览器打开。

  • 本地访问（127.0.0.1 或 localhost）通常能绕过部分限制
  • 远程服务器建议替换为实际 IP/域名，并尽量使用 HTTPS

第3步：正确完成设备配对（推荐永久解决方案）

  1. 用上一步生成的 token 链接打开 Control UI
  2. 打开新终端，查看待批准设备列表：
openclaw devices list

示例输出：

ID          Status    Browser/OS            Requested
dev-7b9f2   pending   Chrome 128 / Windows   刚刚
...
  1. 批准该设备（把 ID 复制下来）：
openclaw devices approve dev-7b9f2
  1. 刷新浏览器中的 Control UI 页面，WebSocket 应正常连接。

小技巧：打开 UI 后立刻运行 devices list，能更快抓到刚发起的配对请求。

第4步：开发/本地测试时临时关闭设备身份验证

仅限本地测试，生产环境强烈不推荐。

编辑配置文件（通常是 ~/.openclaw/config.json 或通过环境变量）：

{
  "controlUi": {
    "allowInsecureAuth": true,
    "dangerouslyDisableDeviceAuth": true
  }
}

重启服务：

openclaw restart
# 或 docker restart openclaw-gateway

刷新页面后，设备身份检查将被跳过。

注意：部分新版本即使设置了该选项，仍要求 secure context（https 或 localhost）。

第5步：确保安全上下文（远程访问推荐做法）

现代浏览器对设备指纹相关 API 要求安全上下文：

  • 使用 HTTPS（推荐使用 Caddy/Nginx + Let's Encrypt 反向代理）
  • 或通过 localhost 访问（可使用 SSH 隧道）

快速建立 SSH 隧道示例：

ssh -L 18789:localhost:18789 user@你的服务器IP

然后在本地浏览器打开：http://localhost:18789/dashboard?token=...

常见问题与排查

  • 批准后仍然报错 → 清除浏览器针对该站点的数据（存储、Cookie、IndexedDB）后重新用新 token 打开
  • 每次刷新都要重新配对 → 检查是否使用了隐身模式，或 token 已过期；建议固定一个标签页
  • Docker 环境下看不到设备 → 确认使用 --network host 或正确端口映射
  • 远程 IP 始终未授权 → 确保是从目标浏览器发起的配对请求（身份基于浏览器+操作系统指纹）
  • 出现 "nonce required" → 几乎总是安全上下文缺失导致
  • 查看详细日志：openclaw logs --tail 200 | grep -i auth\|device\|websocket

下一步建议

  • 通过 ClawHub 安装更多 技能 扩展功能
  • 配置 Telegram / WhatsApp 移动端控制
  • 使用 systemd 或 docker-compose 设置开机自启
  • 深入阅读官方安全文档：https://docs.openclaw.ai/gateway/security
  • 加入 Discord 社区获取最新技巧：https://discord.gg/clawd

完成以上步骤后，OpenClaw Control UI 应该能稳定连接，不再频繁出现 "device identity required" 错误。

Share this article
XFacebookLinkedInRedditHacker News