使用 OpenClaw 遇到問題了嗎？你不是唯一一個。以下是最常見的錯誤以及修復方法。
Gateway 錯誤
"Gateway connect failed"
原因： 主機、連接埠或 URL 設定錯誤。
修復方法：
openclaw config set gateway.host "localhost"
openclaw config set gateway.port 3001
openclaw restart
如果你在反向代理（如 Caddy 或 Nginx）後面運行，請確保 gateway.trustedProxies 包含你的代理 IP：
openclaw config set gateway.trustedProxies '["127.0.0.1"]'
"Gateway start blocked"
原因： Gateway 模式設定不正確。
修復方法：
openclaw config set gateway.mode "local"
openclaw restart
Gateway 持續重啟
原因： 通常是連接埠衝突或狀態損壞。
修復方法：
openclaw gateway stop
# 等待 5 秒
openclaw gateway start
如果仍然無效，執行診斷工具：
openclaw doctor --fix
裝置配對問題
"Device identity required"
原因： 每個新的瀏覽器或用戶端連線都需要核准。
修復方法：
# 列出待核准的裝置
openclaw devices list
# 核准特定裝置
openclaw devices approve DEVICE_ID
配對碼沒有出現
原因： Telegram 頻道可能尚未完全連接。
修復方法：
- 確認你的 bot token 正確：
openclaw config get telegram.token
- 重新啟動 gateway：
openclaw gateway restart
- 傳送訊息給你的 bot——配對碼應該會出現在你的終端機中。
Telegram 問題
Bot 沒有回應
原因： 可能有多種原因。
檢查清單：
- OpenClaw 是否正在運行？用
openclaw status確認 - Gateway 是否就緒？在日誌中尋找
[gateway] listening on - Bot token 是否正確？用 BotFather 確認
- 是否有另一個實例正在輪詢？同一個 bot 的更新只能由一個程序輪詢
快速修復：
openclaw restart
"Telegram getUpdates returned empty"
原因： 如果 OpenClaw 已經在輪詢更新，Telegram API 就不會把更新回傳給其他呼叫者。
修復方法： 這是正常行為。同一個 bot 只應由一個程序輪詢。如果你之前在同一個 token 上運行過其他 bot，請先停止那個程序。
訊息延遲
原因： 通常是 AI 供應商的 API 負載較高或速率限制。
修復方法：
- 檢查你的 API 供應商儀表板是否有速率限制錯誤
- 考慮切換到更快的模型（例如用 Sonnet 取代 Opus）
- 檢查
openclaw logs是否有逾時錯誤
Docker 問題
容器啟動了但 OpenClaw 無法運作
原因： Gateway 需要約 40 秒才能完全啟動。
修復方法： 等待日誌中出現 [gateway] listening on 這行——這才是真正的就緒訊號。較早出現的 [entrypoint] Starting OpenClaw gateway 並不代表已經準備好了。
Docker 中出現 "Permission denied" 錯誤
原因： 容器內的檔案所有權不匹配。
修復方法：
docker exec -it YOUR_CONTAINER_ID chown -R node:node /app
docker restart YOUR_CONTAINER_ID
Gateway token 在重啟後改變
原因： OpenClaw 每次重啟都會重新產生 gateway token，除非你明確設定它。
修復方法：
# 設定永久 token
docker exec YOUR_CONTAINER_ID openclaw config set gateway.token "YOUR_FIXED_TOKEN"
# 或透過環境變數設定
OPENCLAW_GATEWAY_TOKEN=your-token docker-compose up -d
設定錯誤
"Configuration validation error"
原因： openclaw.json 中的 JSON 格式無效。
修復方法：
# 驗證你的設定
openclaw config validate
# 或重設為預設值
openclaw config reset
"Unknown configuration key"
原因： 設定鍵名打錯字或使用了過時的鍵名。
修復方法： 查閱官方設定參考文件以確認有效的鍵名。常見錯誤：
telegramToken應該是telegram.tokenmodel應該是ai.model
一般除錯
終極手段：openclaw doctor
當其他方法都無效時：
openclaw doctor --fix
這會執行健康檢查並自動修復常見問題（權限、設定、缺少的目錄）。
檢查日誌
永遠先檢查日誌：
# 串流即時日誌
openclaw logs --follow
# 最後 100 行
openclaw logs --tail 100
Node.js 版本
OpenClaw 需要 Node.js 22+。檢查你的版本：
node --version
直接跳過故障排除
這些錯誤大多來自自架的複雜性——Docker 設定、反向代理配置、連接埠衝突、token 管理。
ClawTank 幫你處理所有這些。一鍵完成，不需要終端機，不需要除錯。你的 OpenClaw 實例已預先配置好，1 分鐘內即可就緒。