修復 OpenClaw「Device Token Mismatch」錯誤 [2026 指南]

你是否遇到以下錯誤？

device token mismatch

connect failed: device token mismatch

disconnected (4008): connect failed

disconnected (4008): connect failed — device token mismatch

openclaw gateway device token mismatch

Error: device token mismatch — please re-pair this device

WebSocket connection failed: device token mismatch

connect failed (4008): device identity rejected

這些錯誤都代表同一件事：你裝置上儲存的 token 與 OpenClaw gateway 預期的不一致。本指南涵蓋所有修復方法。

TL;DR——快速修復

在你的 OpenClaw 環境中執行以下指令：

openclaw doctor --fix && openclaw restart

這一行指令會偵測 token 不一致、重新產生匹配的 token，並重新啟動 gateway。如果這樣無法解決問題，請繼續閱讀完整的逐步教學。

逐步修復 OpenClaw Device Token Mismatch

步驟 1：執行內建診斷工具

openclaw doctor --fix

openclaw doctor --fix 會掃描包含 device token mismatch 在內的設定問題，並自動重新產生 token 及更新 gateway 設定。

步驟 2：重新啟動 gateway

openclaw restart

修復需要在重新啟動後才會生效。請等到 log 中出現 [gateway] listening on 後再嘗試重新連線。

步驟 3：驗證修復結果

openclaw status

你應該會看到 gateway: running 且沒有任何錯誤。如果有裝置仍顯示斷線，請繼續步驟 4。

步驟 4：重新核准斷線的裝置

列出所有已註冊的裝置：

openclaw devices list

如果你的裝置顯示 pending 或 rejected，請核准它：

openclaw devices approve DEVICE_ID

如果裝置卡在異常狀態，先移除再重新配對：

openclaw devices remove DEVICE_ID

然後打開瀏覽器或 Telegram bot 重新連線。系統會出現新的配對請求，使用 openclaw devices approve 加上新的裝置 ID 來核准。

步驟 5：確認所有裝置已連線

openclaw devices list

每個裝置都應該顯示 connected 狀態。

為什麼會發生這種情況

Device token mismatch 錯誤有四個常見原因。

1. Gateway 重啟時重新產生了 token

除非你固定 token，否則 OpenClaw 每次重啟都會重新產生 gateway token。這會立即使所有現有的裝置連線失效。

這是最常見的原因。只要你的伺服器重新開機、process manager 重新啟動，或在沒有固定 token 的情況下執行 openclaw restart，所有已配對的裝置都會出現不一致。

2. 容器被重建（Docker 使用者）

重建 Docker 容器會產生全新的 gateway 身份。所有先前配對的裝置——瀏覽器、Telegram bot、行動應用程式——都會失效，因為新容器沒有這些裝置的記錄。

使用 docker run、docker-compose up --build 或會在部署時重建容器的 CI/CD pipeline 都會遇到這個問題。

3. 同時運行多個 OpenClaw 實例

在同一台機器上運行兩個 OpenClaw 實例會造成 token 衝突。每個實例都會讀取相同的預設資料目錄，因此會互相覆蓋 token。

你會看到時好時壞的 mismatch 錯誤，看起來自己修好了但又復發。如果你的錯誤不穩定，很可能就是這個原因。

4. 瀏覽器快取過期

有時瀏覽器會在 localStorage 中保留舊的 device token。即使伺服器端的設定已經修復，瀏覽器仍會傳送過期的 token。

修復方法： 在瀏覽器設定中清除你 OpenClaw URL 的網站資料，然後重新連線並核准新裝置。

Docker 專用的 Device Token Mismatch 修復方法

如果你在 Docker 中運行 OpenClaw，需要進入容器來修復：

# 進入運行中的容器
docker exec -it YOUR_CONTAINER_NAME bash

# 執行診斷工具
openclaw doctor --fix

# 離開容器
exit

# 重新啟動容器以套用變更
docker restart YOUR_CONTAINER_NAME

若要在 Docker 中手動重設 device token：

docker exec -it YOUR_CONTAINER_NAME bash

# 設定固定的 gateway token
openclaw config set gateway.token "your-stable-token-here"

# 移除所有過期的裝置配對
openclaw devices list
openclaw devices remove DEVICE_ID

exit
docker restart YOUR_CONTAINER_NAME

容器重新啟動後，從瀏覽器或 Telegram 重新連線並核准新裝置。

Docker Compose 使用者

如果你使用 Docker Compose，請在 docker-compose.yml 中加入環境變數：

services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-stable-token-here
    volumes:
      - openclaw-data:/app/data

volumes:
  openclaw-data:

然後重建而不遺失資料：

docker compose down && docker compose up -d

預防檢查清單

防止 device token mismatch 再次發生：

• 固定你的 gateway token。 設定 OPENCLAW_GATEWAY_TOKEN 環境變數，或執行 openclaw config set gateway.token "your-stable-token"。這可以防止重啟時重新產生 token。
• 持久化你的資料目錄。 將 Docker volume 掛載到 /app/data，這樣容器重建不會清除裝置配對記錄。
• 每台機器一個實例。 如果必須運行多個實例，請為每個實例設定不同的資料目錄和連接埠。
• 升級後執行 openclaw doctor。 主要版本升級可能會更改 token 格式。執行 openclaw doctor --fix 可以在問題影響使用者之前發現並修復。
• 重大變更後清除瀏覽器快取。 如果你更改了 gateway URL、網域或 token，請在所有連線的瀏覽器中清除網站資料。

仍然無法解決？

如果 openclaw doctor --fix 和手動 token 重設都無法解決錯誤：

1. 檢查你的 OpenClaw 版本。 執行 openclaw --version，確認你使用的是最新版本。舊版本有已修復的 token 輪替 bug。
2. 檢查連接埠衝突。 執行 openclaw status，確認 gateway 連接埠沒有被其他程式佔用。
3. 檢查 gateway log。 執行 openclaw logs gateway，尋找包含 token 或 device 的行。Log 輸出會顯示 gateway 預期的 token 與用戶端傳送的 token 之間的差異。
4. 終極手段——完全重設。 如果其他方法都無效，移除所有裝置配對並重新開始：

openclaw devices list
# 移除所有裝置
openclaw devices remove DEVICE_ID_1
openclaw devices remove DEVICE_ID_2

# 設定新的固定 token
openclaw config set gateway.token "new-token-here"

# 重新啟動
openclaw restart

然後重新連線並重新核准每個裝置。

5. 向社群求助。 將你的 openclaw doctor 輸出和 gateway log 張貼到 OpenClaw GitHub Discussions 或 Discord 伺服器。

徹底跳過 Token 管理

ClawTank 開箱即用地處理 gateway token、裝置配對、容器持久化和自動 TLS。不需要手動固定 token、不需要設定 Docker volume、不需要每次重啟後執行 openclaw doctor。部署一次，從任何裝置連線即可。