引言

當你第一次連接 OpenClaw Gateway 或在新的瀏覽器/設備上 訪問控制面板時，系統(tǒng)會拋出 disconnected (1008): pairing required 錯誤。這是 OpenClaw 的安全配對機制在起作用——類似于 SSH 的已知主機驗證，確保只有授權(quán)設備能訪問你的 AI 代理網(wǎng)關。

本文提供兩種官方認可的解決方案：命令行審批法（推薦用于生產(chǎn)環(huán)境）和配置文件修改法（適用于開發(fā)/本地測試）。

錯誤背景：為什么會出現(xiàn) “Pairing required”？

OpenClaw 采用基于設備的訪問控制模型。當任何客戶端（瀏覽器、CLI、手機 App 或 Node 節(jié)點）首次連接到 Gateway 時：

1. Gateway 生成唯一的設備身份標識
2. 創(chuàng)建待審批的配對請求（Pending Request）
3. 連接被掛起，等待管理員顯式批準
4. 若 30 秒內(nèi)未批準，WebSocket 返回 1008 錯誤碼并斷開

這種設計防止了未授權(quán)訪問，即使有人獲取了你的 Gateway URL 或 Token，沒有設備配對批準也無法執(zhí)行操作。

方法一：命令行審批法（生產(chǎn)環(huán)境推薦）

這是最標準、最安全的解決方案，適用于 Docker 部署和原生安裝。

步驟 1：查看待審批設備列表

新開一個終端窗口（保持 Gateway 運行），執(zhí)行：

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 重新觸發(fā)配對
• Role 列顯示設備類型：browser（瀏覽器）、node（macOS/iOS/Android 節(jié)點）、cli（命令行）

步驟 2：批準指定設備

復制你要批準的 Request ID（例如 6f9db1bd-a1cc-4d3f-b643-2c195262464e），執(zhí)行：

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 環(huán)境特殊命令

如果你使用 Docker Compose 部署，需在容器內(nèi)執(zhí)行：

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

# 批準設備（在容器內(nèi)執(zhí)行 Node 命令）
docker compose exec openclaw-gateway node dist/index.js devices approve <Request ID>

或更簡潔的方式：

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

進階：批量與腳本化處理

對于自動化部署，可結(jié)合 jq 實現(xiàn)無人值守批準（慎用，有安全風險）：

# 自動批準所有待處理的瀏覽器設備
openclaw devices list --json | jq -r '.[] | select(.role=="browser") | .id' | \
  xargs -I {} openclaw devices approve {}

方法二：配置文件修改法（開發(fā)環(huán)境適用）

如果你厭倦了每次新設備都要手動批準（例如頻繁重啟瀏覽器或本地開發(fā)測試），可以通過修改配置文件靜默自動批準所有配對請求。

配置文件定位

找到 pending.json 文件：

# 默認路徑
~/.openclaw/devices/pending.json

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

修改配置內(nèi)容

使用你喜歡的編輯器打開文件：

nano ~/.openclaw/devices/pending.json

原文件內(nèi)容示例：

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

修改為：

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

參數(shù)詳解：

立即生效

修改后無需重啟 Gateway，下次設備連接時自動生效。已存在的 pairing required 錯誤需刷新頁面或重連 CLI。

方案對比與選型建議

官方推薦實踐：

• 公網(wǎng) VPS：必須使用方法一，且配合 gateway.remote.token 加固
• Tailscale/內(nèi)網(wǎng)：可酌情使用方法二，但建議限定 autoApprove 范圍
• CI/CD 自動化：通過環(huán)境變量注入 OPENCLAW_SILENT_PAIRING=true 臨時啟用方法二

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

癥狀 1：批準后仍然報錯

可能原因： 設備 ID 綁定到了錯誤的 IP 或 User-Agent
解決方案：

# 清除該設備的所有歷史記錄，強制重新配對
openclaw devices reject <Request ID>  # 先拒絕
# 然后刷新頁面，獲取新的 Request ID 再批準

癥狀 2：找不到 pending.json

可能原因： 使用了 Docker 部署，配置文件在容器內(nèi)
解決方案：

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

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

癥狀 3：Docker 中devices approve提示權(quán)限錯誤

解決方案：

# 確保容器內(nèi) Node 用戶有權(quán)限訪問設備存儲
docker compose exec openclaw-gateway chown -R node:node /app/.openclaw/devices

安全加固建議

解決了配對問題后，建議立即進行以下安全配置：

啟用 Token 認證（即使配對通過也需 Token）：

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

限制 Control UI 訪問：

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": false,  // 強制 HTTPS 或 localhost
      "dangerouslyDisableDeviceAuth": false  // 永遠不要啟用！
    }
  }
}

定期審計已配對設備：

openclaw devices list --approved  # 查看已批準設備
openclaw devices revoke <ID>      # 撤銷可疑設備

總結(jié)

OpenClaw 的 Pairing required 機制是安全設計的體現(xiàn)，而非缺陷。方法一（openclaw devices approve）提供了零信任安全模型，適合所有生產(chǎn)環(huán)境；方法二（silent: true）則是開發(fā)者體驗優(yōu)化，適用于受信任的本地環(huán)境。

根據(jù)你的部署場景選擇合適方案，并記得定期運行 openclaw security audit 檢查配置安全性。

以上就是OpenClaw報錯Pairing required的兩種官方解決方案的詳細內(nèi)容，更多關于OpenClaw報錯Pairing required的資料請關注腳本之家其它相關文章！

最新評論