故障排除

出問題了？別慌！按照下面的方法一步步排查，大部分問題都能自己解決。

🔍 診斷階梯（按順序來）

當 OpenClaw 出現問題時，按照以下順序逐步排查：

檢查執行狀態

openclaw status

看看 OpenClaw 是否還在執行。如果顯示 "stopped" 或報錯，請先嘗試重新啟動。

檢查閘道狀態

openclaw gateway status

閘道是 OpenClaw 連接聊天平台的橋樑。如果閘道狀態異常，聊天訊息就無法收發。

查看日誌

openclaw logs

日誌裡記錄了 OpenClaw 執行的所有細節。如果有錯誤，日誌裡通常會有紅色的錯誤訊息告訴你哪裡出了問題。

執行健康檢查

openclaw doctor

全面的健康檢查，會告訴你哪些元件正常、哪些有問題。

檢查頻道連線

openclaw channels status

查看各個聊天頻道的連線狀態，看看是不是某個頻道斷線了。

🐛 常見錯誤和解決方法

錯誤："openclaw: command not found"

原因：系統找不到 openclaw 指令，通常是 PATH 環境變數的問題。

解決：

# 檢查 openclaw 安裝位置
npm list -g openclaw

# 將 npm 全域目錄加入 PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# 將上面的指令新增到你的 shell 設定檔中以永久生效
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

錯誤：連接埠衝突（EADDRINUSE: address already in use :::18789）

原因：連接埠 18789 已經被另一個程式佔用了。

解決：

# 查找佔用連接埠的程序
lsof -i :18789

# 停止舊的 OpenClaw 程序
openclaw stop

# 如果不是 OpenClaw 程序，你可以在設定中更換連接埠
# 編輯 ~/.openclaw/openclaw.json，修改 port 值

錯誤：429 Too Many Requests（速率限制）

原因：你傳送的請求太頻繁了，AI 模型提供商對 API 呼叫有頻率限制。

解決：

等幾分鐘後再試
減少傳送訊息的頻率
升級你的 API 付費方案以取得更高的速率限制
考慮切換到限制更寬鬆的模型提供商

錯誤：閘道無法啟動

原因：可能是 Bot Token 無效、網路連線問題、或聊天平台 API 變更。

解決：

# 檢查閘道日誌
openclaw gateway logs

# 驗證 Bot Token 是否有效
openclaw channels verify

# 重新啟動閘道
openclaw gateway restart

錯誤：訊息發不出去

原因：可能是頻道設定錯誤、網路問題、或 Bot 權限不足。

解決：

檢查頻道狀態：openclaw channels status
確認 Bot 在對應平台上有傳送訊息的權限
檢查網路連線是否正常
查看日誌中是否有具體的錯誤訊息

錯誤：控制面板打不開

原因：OpenClaw 服務可能沒有在執行，或者連接埠設定有誤。

解決：

# 確認 OpenClaw 正在執行
openclaw status

# 如果沒有執行，啟動它
openclaw start

# 然後嘗試開啟控制面板
openclaw dashboard

# 或者直接在瀏覽器存取
# http://127.0.0.1:18789/

🆘 還是解決不了？

如果按照上面的方法還是無法解決問題，你可以：

去 GitHub Issues 搜尋或提交問題
加入 OpenClaw 的 Discord 社群尋求幫助
在提問時請附上 openclaw doctor 和 openclaw logs 的輸出