你打開瀏覽器，連到你的 OpenClaw，結果看到的不是熟悉的聊天介面，而是：

Pairing Required
Enter the pairing code displayed in your terminal.

或者更糟，你的 Telegram 機器人突然不回訊息了，日誌裡顯示：

WARN  device not paired — rejecting connection from device abc123

這是 OpenClaw 的裝置配對系統正在按照設計運作：拒絕未經認可的連線。好消息是，一旦你理解發生了什麼，大約 30 秒就能修好。

為什麼 OpenClaw 需要裝置配對

OpenClaw 是一個有權存取你的電子郵件、行事曆、檔案以及其他敏感資料的個人助理。裝置配對是一個安全機制，確保只有你明確授權的裝置能連接到你的 gateway^[1]。

當一個新裝置（瀏覽器、Telegram 客戶端或 API 連線）首次連接到 gateway 時，它會被放入「待審核」狀態。在你從命令列核准之前，該裝置無法收發訊息。即使有人發現了你的 gateway 網址，這個機制也能防止未授權的存取。

「Pairing Required」出現的時機與原因

這個錯誤會在以下幾種情境出現。了解你屬於哪種情境，就能找到最快的修復方法。

情境一：全新的瀏覽器或裝置

最直接的情況。你正從一個從未配對過的裝置連線——新筆電、新手機，或你之前沒有用來存取 OpenClaw 的瀏覽器。

情境二：清除了瀏覽器 Cookie 或資料

OpenClaw 會在瀏覽器的 local storage 中儲存裝置 token。如果你清除了 Cookie 和網站資料、執行了隱私清理工具，或使用無痕模式，裝置 token 就會消失。Gateway 會把你當成一個全新的裝置。

情境三：容器重啟但未設定 OPENCLAW_GATEWAY_TOKEN

這是最常見的原因，也是最不明顯的一個。在 Docker 部署中，除非明確設定 OPENCLAW_GATEWAY_TOKEN 環境變數，否則 gateway 會在每次容器重啟時重新產生認證 token^[2]。當 token 改變後，所有先前配對的裝置在 gateway 眼中都變成「未知」——它們仍在呈現舊的 token。

情境四：更新後的 Gateway Token 格式不符

OpenClaw 更新後，內部的 token 格式偶爾會改變。現有的裝置配對可能因此失效。

情境五：反向代理過濾掉了 Header

如果你在 Nginx、Caddy 或其他反向代理後面運行 OpenClaw，設定錯誤可能會過濾掉 X-Device-Token header。Gateway 永遠收不到裝置的認證資訊，因此把每個請求都當作新的未配對裝置。

修復方法一：openclaw doctor --fix（推薦）

最快的解決途徑。openclaw doctor 指令能偵測配對問題，而 --fix 旗標會自動修復：

openclaw doctor --fix

範例輸出：

CHECK  device pairing status
FAIL   2 devices pending approval
FIX    approving all pending devices...
OK     2 devices approved

CHECK  gateway token consistency
FAIL   device token mismatch detected
FIX    regenerating tokens and re-pairing...
OK     tokens synchronized

--fix 旗標能在一次執行中同時處理待審核的裝置核准和 token 不匹配問題。執行後，重新整理你的瀏覽器或重啟 Telegram 客戶端。

修復方法二：手動核准裝置

如果你想逐一核准裝置（在你想確認每個連線時推薦使用）：

# 列出所有裝置及其狀態
openclaw devices list

輸出：

ID          STATUS     TYPE       LAST SEEN
abc123      pending    browser    2026-02-24 10:30
def456      approved   telegram   2026-02-24 09:15
ghi789      pending    browser    2026-02-24 10:32

核准特定裝置：

# 依裝置 ID 核准
openclaw devices approve abc123

# 一次核准所有待審核裝置
openclaw devices approve --all

特別針對 Telegram 配對，你可能需要使用配對碼流程：

# 從你的 bot 取得 Telegram 配對碼
# 然後核准它
openclaw pairing approve telegram <CODE>

修復方法三：設定 OPENCLAW_GATEWAY_TOKEN（防止復發）

如果你在 Docker 中運行，而且這個錯誤在每次容器重啟後都會出現，這是永久性的修復：

# 產生一個穩定的 token
openssl rand -hex 32

然後在你的 Docker run 指令或 docker-compose 檔案中設定：

# docker-compose.yml
services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_TOKEN=你產生的token放這裡
    volumes:
      - openclaw_data:/data

或用 docker run：

docker run -d \
  -e OPENCLAW_GATEWAY_TOKEN=你產生的token放這裡 \
  -v openclaw_data:/data \
  openclaw-stack

設定這個變數後，gateway 在重啟時會使用相同的 token，裝置配對就能持久保存^[3]。

修復方法四：檢查反向代理設定

如果即使設了 OPENCLAW_GATEWAY_TOKEN，裝置還是不斷需要重新配對，你的反向代理可能過濾掉了裝置 token header。

Caddy 的設定：

yourdomain.com {
    reverse_proxy localhost:3001 {
        # 確保 WebSocket 升級正常運作
        header_up X-Real-IP {remote_host}
    }
}

Caddy 預設會傳遞所有 header，所以這很少是問題所在。但請確認 WebSocket 升級有正常運作——gateway 使用 WebSocket 進行持久連線。

Nginx 的設定：

location / {
    proxy_pass http://localhost:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    # 關鍵：不要過濾自訂 header
    proxy_pass_request_headers on;
}

另外檢查 OpenClaw 中是否有設定 gateway.trustedProxies：

openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw restart

預防：防止問題再次發生

解決了當下的錯誤後，採取以下步驟來防止復發：

1. Docker 中務必設定 OPENCLAW_GATEWAY_TOKEN

這點怎麼強調都不為過。它是容器化部署中造成配對問題反覆出現的頭號原因。

2. 避免清除 OpenClaw 網域的網站資料

如果你使用瀏覽器清理工具，將你的 OpenClaw 網域加入排除清單。儲存在 local storage 中的裝置 token 是維持配對的關鍵。

3. 使用專用的瀏覽器設定檔

考慮建立一個專門用於 OpenClaw 的瀏覽器設定檔。這樣可以將它的資料與你日常的瀏覽器清理作業隔開。

4. 用 openclaw doctor 做監控

定期執行 openclaw doctor（或設定排程工作）來在問題發生前就發現異常：

# 加入 crontab 做每日健康檢查
0 8 * * * openclaw doctor >> /var/log/openclaw-health.log 2>&1

託管服務完全避開這個問題

裝置配對系統的存在是為了保護可能暴露在網路上的自架實例。使用 ClawTank 的託管服務，gateway token、反向代理 header 和裝置管理都是自動處理的。配對機制仍然存在，但初始配對在一鍵設定過程中就已完成——你永遠不會看到「pairing required」的畫面。

快速對照表

症狀	可能原因	修復方法
新瀏覽器出現「pairing required」	正常——新裝置	`openclaw devices approve --all`
重啟後所有裝置配對失效	缺少 `OPENCLAW_GATEWAY_TOKEN`	設定環境變數，重新配對一次
Telegram 機器人不回應	Token 不匹配	`openclaw doctor --fix`
配對成功但重新整理後又壞掉	反向代理過濾了 header	修復代理設定，設定 `trustedProxies`
間歇性的配對錯誤	清除了 Cookie/local storage	將 OpenClaw 網域排除在清理之外

修復 OpenClaw「Pairing Required」錯誤：openclaw doctor --fix 完整教學（2026）