OpenClaw 除錯指南：快速排查日誌與修復常見錯誤

寫程式最煩的就是遇到「明明沒報錯，但就是不動」的情況。當你的機器人突然安靜得可怕，或者行為不如預期時，翻閱日誌（logs）通常是找回理智的最快方法。

這份指南會帶你掌握 OpenClaw 的日誌系統，讓你從盲目猜測轉向精準除錯。

OpenClaw 的日誌存放在哪裡？

日誌預設存放在 $OPENCLAW_STATE_DIR/logs（通常是 ~/.openclaw/logs）。

你可以透過以下指令快速存取：

# Open logs directory
openclaw logs --path

# Tail live
openclaw logs --follow

# Show last 500 lines
openclaw logs

日誌每天會自動輪替，也支援 JSON 格式方便你進行結構化解析。

如何即時讀取日誌？

如果你想邊操作邊觀察發生了什麼事，可以使用 --follow 參數：

openclaw logs --follow

# Filter JSON logs
openclaw logs --follow --json | jq 'select(.level == "error")'

收到訊息但沒回覆？該如何除錯？

這是最常見的問題，請依照以下步驟排查：

1. 檢查日誌：

   openclaw logs --follow

2. 暫時開啟 debug 模式：

   openclaw gateway stop
   OPENCLAW_DEBUG=1 openclaw gateway start

3. 確認 channel 狀態，確保訊息沒有被忽略：

   openclaw channels status

4. 檢查 session 和 model 狀態：

   openclaw status
   openclaw models status

5. 在日誌中尋找 rate-limit、auth 或 model 相關的錯誤訊息。

日誌太多或不夠詳細？該如何調整？

你可以調整 gateway.logLevel（預設為 info）來過濾資訊：

• debug = 非常詳細
• info = 正常
• warn = 僅顯示警告與錯誤
• error = 僅顯示錯誤

{
  gateway: { logLevel: "debug" }
}

程式當掉後沒有自動重啟？哪裡出錯了？

請檢查你的服務管理器（launchd 或 systemd）設定：

• launchd: KeepAlive 必須設為 true
• systemd: 確保有 Restart=on-failure 與 WantedBy=multi-user.target

驗證服務狀態：

# macOS
launchctl list | grep openclaw

# Linux
systemctl --user status openclaw
journalctl --user -u openclaw -n 100

如何用程式檢查 Gateway 的健康狀態？

如果你需要自動化監控，可以呼叫 API 或使用 CLI：

curl http://localhost:18789/health

# Or via CLI
openclaw health
openclaw health --json

不小心搞砸了？該如何重設？

如果你把設定改壞了想重頭來過，可以使用 reset 指令：

# Full reset (wipes config, creds, sessions)
openclaw reset --scope full --yes

# Or just sessions
openclaw reset --scope sessions --yes

接著重新執行 onboarding 流程：

openclaw onboard --install-daemon

如何回報 bug？

如果你發現了程式本身的缺陷，請按照以下步驟操作：

1. 使用 debug 日誌重現問題：

   OPENCLAW_DEBUG=1 openclaw gateway restart

2. 先到 GitHub Issues 檢查是否為已知問題。
3. 如果不是，請開一個新的 issue 並附上：
   • OpenClaw 版本 (openclaw --version)
   • OS 與 Node.js 版本
   • 相關的日誌片段（請記得遮蓋 API keys 或 tokens）
   • 具體的重現步驟

如果你在設定過程中遇到困難，可以詢問我們的 AI Setup Assistant。

下一步

• CLI 參考指南
• 設定 Gateway