跳轉到內容
最近更新

文件 / 疑難排解指南

OpenClaw 疑難排解指南：網關、Telegram 與瀏覽器中繼問題

集中處理 OpenClaw 安裝、網關令牌、Telegram 通道、瀏覽器中繼、Docker 與運行時故障。

安裝與環境

安裝前

安裝腳本下載失敗（網絡/代理）

展開

現象: curl 或 npm 下載失敗/超時。

原因: 網絡受限或未設置代理。

解決方案

命令

curl -I https://openclaw.bot/install.sh
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

設定差異

+ https_proxy=http://127.0.0.1:7890
+ http_proxy=http://127.0.0.1:7890

為什麼有效: 通過代理轉發請求，確保安裝腳本和依賴可訪問。

驗證方式: 重新執行安裝命令，能正常下載。

截圖:

安裝腳本下載失敗（網絡/代理） screenshot

Docker 服務未運行

展開

現象: Docker 命令報錯或容器啟動即退出。

原因: Docker 服務未啟動或未啟用。

解決方案

命令

sudo systemctl status docker
sudo systemctl enable --now docker

設定差異

- restart: "no"
+ restart: unless-stopped

為什麼有效: 確保 Docker 服務可用，並讓容器重啟後自動拉起。

驗證方式: 重啟後 docker ps 仍有容器運行。

截圖:

Docker 服務未運行 screenshot

資料目錄權限不足

展開

現象: 寫入時報 Permission denied 或 EACCES。

原因: 資料目錄歸屬不正確或掛載路徑不一致。

解決方案

命令

sudo chown -R $USER:$USER ~/.openclaw
ls -la ~/.openclaw

設定差異

- ./openclaw-data:/root/.openclaw
+ ~/.openclaw:/root/.openclaw

為什麼有效: 使用使用者目錄持久化，避免權限問題。

驗證方式: 重啟後能正常寫入資料。

截圖:

資料目錄權限不足 screenshot

初始化與啟動

安裝中

onboarding 卡住或通道無響應

展開

現象: 嚮導卡住或通道消息不回覆。

原因: API Key 無效或網絡被攔截。

解決方案

命令

openclaw config get | head -n 20
openclaw gateway restart

設定差異

+ ANTHROPIC_API_KEY=sk-REPLACE_ME

為什麼有效: 確保模型提供商鑑權資訊正確。

驗證方式: openclaw health 返回 OK，通道能回覆。

截圖:

onboarding 卡住或通道無響應 screenshot

Control UI 端口衝突

展開

現象: SSH 隧道/Control UI 報 EADDRINUSE。

原因: 18789 端口被佔用。

解決方案

命令

sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 18789

設定差異

- "18789:18789"
+ "18790:18789"

為什麼有效: 把宿主機端口映射改為新端口避免衝突。

驗證方式: 新端口可以正常打開 UI。

截圖:

Control UI 端口衝突 screenshot

改了設定沒生效

展開

現象: 修改設定後行為沒有變化。

原因: 編輯了錯誤的設定文件或未重啟網關。

解決方案

命令

openclaw config get
openclaw gateway restart

設定差異

+ OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json

為什麼有效: 強制網關讀取正確的設定路徑。

驗證方式: 重啟後設定值與修改一致。

截圖:

改了設定沒生效 screenshot

通道與訪問控制

首次安裝成功之後

Telegram 機器人能啟動但不回覆

展開

現象: Telegram 裡 /start 正常，但發送普通消息沒有響應。

原因: Bot Token 填錯、網關沒有重啟，或服務器無法訪問 Telegram 接口。

解決方案

命令

openclaw config get channels.telegram.botToken
openclaw gateway restart
curl -I https://api.telegram.org

設定差異

- channels.telegram.enabled: false
+ channels.telegram.enabled: true
+ channels.telegram.botToken: "YOUR_TELEGRAM_BOT_TOKEN"

為什麼有效: 這一步可以同時確認 Telegram 通道已啟用、Bot Token 已寫入，以及網關已經加載新設定並具備基礎網絡訪問能力。

驗證方式: 重新在 Telegram 裡執行 /start，並確認發送普通文本消息後能收到回覆。

截圖:

Telegram 機器人能啟動但不回覆 screenshot

Gateway token 無效、缺失或被拒絕

展開

現象: 調用網關時出現 unauthorized、forbidden 或 token missing 之類的報錯。

原因: 運行時 token 沒有設置、設置不一致，或者代理和客戶端拿到的是舊值。

解決方案

命令

openclaw config get gateway.token
openclaw gateway restart
printenv | grep -i OPENCLAW

設定差異

- gateway.token: ""
+ gateway.token: "REPLACE_WITH_A_STRONG_SECRET"

為什麼有效: 確保運行時設定、客戶端請求和代理層使用的是同一個 gateway token，能避免鑑權失敗和舊設定殘留。

驗證方式: 確認 health 檢查和需要鑑權的網關調用僅在正確 token 存在時才成功。

截圖:

Gateway token 無效、缺失或被拒絕 screenshot

Browser relay 無法連接或請求經常超時

展開

現象: 需要瀏覽器能力的流程無法啟動，或 browser relay 相關步驟頻繁超時。

原因: browser relay 未啟用、目標服務不可達，或宿主機無法解析 relay 地址。

解決方案

命令

openclaw config get browserRelay
curl -I http://127.0.0.1:3000 || true
openclaw gateway restart

設定差異

- browserRelay.enabled: false
+ browserRelay.enabled: true
+ browserRelay.baseUrl: "http://127.0.0.1:3000"

為什麼有效: browser relay 依賴一個可訪問的中繼服務和一致的運行時設定。重啟網關可以強制重新加載 browser relay 設置。

驗證方式: 運行一個依賴瀏覽器能力的技能或工作流，確認不再出現 relay timeout 類錯誤。

截圖:

Browser relay 無法連接或請求經常超時 screenshot

運行穩定性

運行後

重啟後資料丟失

展開

現象: 重啟後設置丟失或歷史為空。

原因: 未掛載持久化目錄。

解決方案

命令

ls -la ~/.openclaw
docker compose ps

設定差異

- volumes:
-   - ./openclaw-data:/root/.openclaw
+ volumes:
+   - ~/.openclaw:/root/.openclaw

為什麼有效: 把狀態寫到宿主機，重啟後仍可讀取。

驗證方式: 重啟後設置與歷史仍存在。

截圖:

重啟後資料丟失 screenshot

內存不足 / OOM

展開

現象: 高負載下進程被殺。

原因: VPS 設定不足。

解決方案

命令

free -m
journalctl -k | grep -i oom

設定差異

- plan: entry
+ plan: standard

為什麼有效: 升級內存或設定能避免 OOM。

驗證方式: 高峰期不再出現 OOM。

截圖:

內存不足 / OOM screenshot

繼續查看