如何解决 OpenClaw “Pairing required” 报错：两种官方解决方案详解

如何解决 OpenClaw "Pairing required" 报错：两种官方解决方案详解

当你第一次连接 OpenClaw Gateway 或在新的浏览器/设备上访问控制面板时，系统会抛出 disconnected (1008): pairing required 错误。这是 OpenClaw 的安全配对机制在起作用------类似于 SSH 的已知主机验证，确保只有授权设备能访问你的 AI 代理网关。

本文提供两种官方认可的解决方案：命令行审批法 （推荐用于生产环境）和配置文件修改法（适用于开发/本地测试）。

文章目录

[如何解决 OpenClaw "Pairing required" 报错：两种官方解决方案详解](#如何解决 OpenClaw "Pairing required" 报错：两种官方解决方案详解)
- [错误背景：为什么会出现 "Pairing required"？](#错误背景：为什么会出现 "Pairing required"？)
- 方法一：命令行审批法（生产环境推荐）
- - [步骤 1：查看待审批设备列表](#步骤 1：查看待审批设备列表)
  - [步骤 2：批准指定设备](#步骤 2：批准指定设备)
  - [Docker 环境特殊命令](#Docker 环境特殊命令)
  - 进阶：批量与脚本化处理
- 方法二：配置文件修改法（开发环境适用）
- 方案对比与选型建议
- 故障排查：如果上述方法无效
- - [症状 1：批准后仍然报错](#症状 1：批准后仍然报错)
  - [症状 2：找不到 pending.json](#症状 2：找不到 pending.json)
  - [症状 3：Docker 中 `devices approve` 提示权限错误](#症状 3：Docker 中 devices approve 提示权限错误)
- 安全加固建议
- 总结

错误背景：为什么会出现 "Pairing required"？

OpenClaw 采用基于设备的访问控制模型。当任何客户端（浏览器、CLI、手机 App 或 Node 节点）首次连接到 Gateway 时：

Gateway 生成唯一的设备身份标识
创建待审批的配对请求（Pending Request）
连接被挂起，等待管理员显式批准
若 30 秒内未批准，WebSocket 返回 1008 错误码并断开

这种设计防止了未授权访问，即使有人获取了你的 Gateway URL 或 Token，没有设备配对批准也无法执行操作。

方法一：命令行审批法（生产环境推荐）

这是最标准、最安全的解决方案，适用于 Docker 部署和原生安装。

步骤 1：查看待审批设备列表

新开一个终端窗口（保持 Gateway 运行），执行：

bash 复制代码

openclaw devices list

预期输出示例：

复制代码

┌──────────────────────────────────────┬──────────────┬─────────────────────┐
│ Request ID                           │ Role         │ Created At          │
├──────────────────────────────────────┼──────────────┼─────────────────────┤
│ 6f9db1bd-a1cc-4d3f-b643-2c195262464e │ browser      │ 2026-02-06 10:23:18 │
│ a2f8c1de-9b4a-4e7c-8d21-3f5a9b7c2e1f │ node         │ 2026-02-06 10:24:33 │
└──────────────────────────────────────┴──────────────┴─────────────────────┘

注意事项：

若列表为空，说明请求已过期，需刷新浏览器或重启 CLI 重新触发配对
Role 列显示设备类型：browser（浏览器）、node（macOS/iOS/Android 节点）、cli（命令行）

步骤 2：批准指定设备

复制你要批准的 Request ID （例如 6f9db1bd-a1cc-4d3f-b643-2c195262464e），执行：

bash 复制代码

openclaw devices approve 6f9db1bd-a1cc-4d3f-b643-2c195262464e

成功响应：

复制代码

✓ Approved device 6f9db1bd-a1cc-4d3f-b643-2c195262464e (browser)
  Access granted. Device can now connect to Gateway.

此时返回浏览器/客户端，错误应立即消失，连接自动恢复。

Docker 环境特殊命令

如果你使用 Docker Compose 部署，需在容器内执行：

bash 复制代码

# 查看待审批列表
docker compose run --rm openclaw-cli devices list

# 批准设备（在容器内执行 Node 命令）
docker compose exec openclaw-gateway node dist/index.js devices approve <Request ID>

或更简洁的方式：

bash 复制代码

docker compose run --rm openclaw-cli devices approve <Request ID>

进阶：批量与脚本化处理

对于自动化部署，可结合 jq 实现无人值守批准（慎用，有安全风险）：

bash 复制代码

# 自动批准所有待处理的浏览器设备
openclaw devices list --json | jq -r '.[] | select(.role=="browser") | .id' | \
  xargs -I {} openclaw devices approve {}

方法二：配置文件修改法（开发环境适用）

如果你厌倦了每次新设备都要手动批准（例如频繁重启浏览器或本地开发测试），可以通过修改配置文件静默自动批准所有配对请求。

配置文件定位

找到 pending.json 文件：

bash 复制代码

# 默认路径
~/.openclaw/devices/pending.json

# 若使用自定义配置目录，可通过以下命令查找
openclaw config get paths.devicesDir

修改配置内容

使用你喜欢的编辑器打开文件：

bash 复制代码

nano ~/.openclaw/devices/pending.json

原文件内容示例：

json 复制代码

{
  "silent": false,
  "autoApprove": [],
  "logLevel": "info"
}

修改为：

json 复制代码

{
  "silent": true,
  "autoApprove": ["browser", "cli"],
  "logLevel": "warn"
}

参数详解：

参数	类型	说明
`silent`	Boolean	`true` 时自动批准所有配对请求，不提示用户；`false` 时保持手动审批
`autoApprove`	Array	可选，限定自动批准的设备类型，如 `["browser"]` 仅自动批准浏览器，`["*"]` 批准所有
`logLevel`	String	建议改为 `warn` 减少日志噪音

立即生效

修改后无需重启 Gateway ，下次设备连接时自动生效。已存在的 pairing required 错误需刷新页面或重连 CLI。

方案对比与选型建议

维度	方法一：命令行审批	方法二：配置修改
安全性	⭐⭐⭐⭐⭐ 显式控制每个设备	⭐⭐⭐ 降低未授权访问门槛
便捷性	需手动操作，适合低频变更	一劳永逸，适合高频测试
适用场景	生产环境、VPS 公网部署	本地开发、Docker 内网环境
审计追踪	有完整日志记录批准操作	静默通过，日志较少
团队协作	可区分批准者身份	无法区分

官方推荐实践：

公网 VPS ：必须使用方法一，且配合 gateway.remote.token 加固
Tailscale/内网 ：可酌情使用方法二，但建议限定 autoApprove 范围
CI/CD 自动化 ：通过环境变量注入 OPENCLAW_SILENT_PAIRING=true 临时启用方法二

故障排查：如果上述方法无效

症状 1：批准后仍然报错

可能原因： 设备 ID 绑定到了错误的 IP 或 User-Agent
解决方案：

bash 复制代码

# 清除该设备的所有历史记录，强制重新配对
openclaw devices reject <Request ID>  # 先拒绝
# 然后刷新页面，获取新的 Request ID 再批准

症状 2：找不到 pending.json

可能原因： 使用了 Docker 部署，配置文件在容器内
解决方案：

bash 复制代码

# 进入容器查找
docker compose exec openclaw-gateway find /app -name "pending.json"

# 或在宿主机映射卷中查找
ls -la ~/.openclaw/devices/

症状 3：Docker 中 `devices approve` 提示权限错误

解决方案：

bash 复制代码

# 确保容器内 Node 用户有权限访问设备存储
docker compose exec openclaw-gateway chown -R node:node /app/.openclaw/devices

安全加固建议

解决了配对问题后，建议立即进行以下安全配置：

启用 Token 认证（即使配对通过也需 Token）：

json 复制代码

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "auth": {
      "type": "token",
      "token": "your-secure-random-string"
    }
  }
}

限制 Control UI 访问：

json 复制代码

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": false,  // 强制 HTTPS 或 localhost
      "dangerouslyDisableDeviceAuth": false  // 永远不要启用！
    }
  }
}

定期审计已配对设备：

bash 复制代码

openclaw devices list --approved  # 查看已批准设备
openclaw devices revoke <ID>      # 撤销可疑设备

总结

OpenClaw 的 Pairing required 机制是安全设计的体现 ，而非缺陷。方法一（openclaw devices approve）提供了零信任安全模型 ，适合所有生产环境；方法二（silent: true）则是开发者体验优化，适用于受信任的本地环境。

根据你的部署场景选择合适方案，并记得定期运行 openclaw security audit 检查配置安全性。

:
Simon Willison's TIL - Running OpenClaw in Docker
:
OpenClaw Docs - Nodes & Pairing
:
PromptLayer - How to Install OpenClaw
:
CSDN - OpenClaw Nginx 反代与 Pairing Required 解决
:
Popupsmart Community - OpenClaw WebSocket Error 1008
:
OpenClaw Docker 中文文档

如何解决 OpenClaw “Pairing required” 报错：两种官方解决方案详解