在揭秘 OpenClaw 架構(gòu)設(shè)計系列文章中，我詳細介紹了 OpenClaw 架構(gòu)及構(gòu)建、部署與日常運維。但再穩(wěn)定的系統(tǒng)，也難免會遇到問題——AI 不響應(yīng)、工具調(diào)用失敗、成本異常飆升……這時候，日志就是我們最重要的“案發(fā)現(xiàn)場”。本文基于社區(qū)最新實踐，手把手教你如何利用 OpenClaw 的日志系統(tǒng)，快速定位并解決常見問題。

1. 兩類日志：分清“系統(tǒng)運行”和“AI 調(diào)用”

OpenClaw 的日志主要分為兩大類，它們的用途和查看方式完全不同，先記住這張表：

一句話區(qū)分：Application 日志告訴你“系統(tǒng)跑沒跑起來”，Session 日志告訴你“AI 到底干了什么”。

2. 快速上手：命令行排查三板斧

OpenClaw 的 CLI 提供了非常方便的日志查看命令，無需手動翻文件，適合第一時間快速定位。

2.1 實時跟隨最新日志

openclaw logs --follow

這是我最常用的命令，它會實時輸出 Application 日志，同時也會顯示每個會話的關(guān)鍵摘要（如工具調(diào)用、錯誤）。如果你剛遇到一個問題，立刻執(zhí)行它，往往能看到最新的錯誤信息。

2.2 輸出為 JSON，配合 jq 分析

openclaw logs --json | jq '.'

如果你熟悉 jq，可以用這種方式過濾出特定字段。例如，只看所有包含“error”的日志：

openclaw logs --json | jq 'select(.level == "ERROR")'

2.3 只看警告和錯誤

openclaw logs --level warn

當日志刷得很快時，用這個命令可以過濾掉 INFO 和 DEBUG 信息，直接看到問題。

2.4 先跑診斷，自動檢查常見問題

openclaw doctor
openclaw doctor --fix   # 自動修復一些常見問題（如權(quán)限、配置缺失）

doctor 命令會檢查 Gateway 狀態(tài)、Docker 是否運行、關(guān)鍵端口是否被占用、配置是否正確等。強烈建議遇到任何問題第一步都先跑它。

2.5 查看整體狀態(tài)

openclaw status

顯示當前有多少活躍會話、各通道是否在線、Agent 運行情況等。

3. 深入現(xiàn)場：直接查看日志文件

當命令行信息不夠詳細時，我們需要直接查看日志文件。這里才是“最完整”的調(diào)用記錄。

3.1 Session 日志：AI 調(diào)用的“黑匣子”

路徑：~/.openclaw/agents/<agent_id>/sessions/*.jsonl

<agent_id> 通常是你在配置中定義的默認 Agent 名稱（如 main），或者通過 ls ~/.openclaw/agents/ 查看。每個會話（一個聊天對話）對應(yīng)一個 .jsonl 文件，文件名是會話 ID。

文件格式：JSON Lines，每行一個 JSON 對象，代表一次交互。典型內(nèi)容示例：

{
  "timestamp": "2026-03-09T10:23:45Z",
  "type": "message",
  "direction": "incoming",
  "content": "今天天氣怎么樣？"
}
{
  "timestamp": "2026-03-09T10:23:46Z",
  "type": "llm_request",
  "model": "openai/gpt-4",
  "prompt": "...",
  "usage": { "prompt_tokens": 120, "completion_tokens": 45, "total_tokens": 165 },
  "cost": { "total": 0.0023 }
}
{
  "timestamp": "2026-03-09T10:23:47Z",
  "type": "tool_call",
  "toolCall": { "name": "get_weather", "arguments": { "city": "北京" } },
  "toolResult": { "content": "北京今天晴，10-22℃", "isError": false },
  "duration_ms": 234
}

常用查看技巧：

# 查看最新會話的最后 100 條記錄
tail -100 ~/.openclaw/agents/main/sessions/$(ls -t ~/.openclaw/agents/main/sessions/ | head -1) | jq .
# 搜索所有會話中包含 "toolCall" 的記錄
rg 'toolCall' ~/.openclaw/agents/*/sessions/*.jsonl
# 統(tǒng)計每個工具被調(diào)用的次數(shù)
cat ~/.openclaw/agents/*/sessions/*.jsonl | jq -r 'select(.toolCall) | .toolCall.name' | sort | uniq -c

3.2 Application 日志：系統(tǒng)運行“心電圖”

路徑：/tmp/openclaw/openclaw-YYYY-MM-DD.log（Linux/macOS 默認）

文件按天滾動，保留最近 24 小時，總大小不超過 500MB（可配置）。查看方式：

tail -f /tmp/openclaw/openclaw-*.log

內(nèi)容示例：

2026-03-09 10:23:45 INFO [gateway] Server started on port 18789
2026-03-09 10:23:46 DEBUG [channels.telegram] Received message: Hello
2026-03-09 10:23:47 ERROR [agents] Tool execution failed: get_weather: API key not configured

4. 進階排查：特殊場景

4.1 想看 LLM API 的完整請求（CURL/Header/Body）

官方現(xiàn)狀：無論是 openclaw logs 還是 Session 日志文件，都不會輸出發(fā)給 OpenAI、Anthropic 等 Provider 的完整 HTTP 請求。這是出于隱私和安全考慮（避免日志中泄露 API key）。

社區(qū)解決方案：

方法一：使用代理攔截（推薦）

配置一個 HTTP 代理工具（如 mitmproxy、Charles），讓 OpenClaw 的請求走代理。步驟如下：

1.啟動 mitmproxy：mitmproxy --mode regular --listen-port 8080

2.配置 OpenClaw 使用代理（在 ~/.openclaw/config.yaml 中添加）：

agents:
  defaults:
    httpProxy: "http://127.0.0.1:8080"

3.重啟 Gateway，所有 LLM 請求就會在 mitmproxy 界面中完整顯示，包括 Header、Payload、響應(yīng)。

方法二：源碼修改（開發(fā)環(huán)境）

如果你在開發(fā)環(huán)境，可以修改 src/agents/providers/ 下的 HTTP 客戶端代碼，增加日志輸出。但注意不要提交到生產(chǎn)環(huán)境。

4.2 Agent 卡住 / 工具調(diào)用失敗

先跑 openclaw doctor，然后查看 Session 日志中 toolResult.isError 字段：

cat ~/.openclaw/agents/main/sessions/*.jsonl | jq 'select(.toolResult and .toolResult.isError == true)'

常見的錯誤原因：

• 工具所需的依賴未安裝（如 Python 腳本缺少庫）
• 沙箱執(zhí)行超時（可調(diào)整 agents.defaults.sandbox.timeout）
• 工具白名單攔截（查看 toolCall.name 是否在 security.toolDenylist 中）

4.3 成本/調(diào)用量監(jiān)控

OpenClaw 官方提供了 OTEL（OpenTelemetry）插件，可以導出 Metrics 和 Traces：

openclaw plugins enable diagnostics-otel

啟用后，你可以在配置中設(shè)置導出端點（如 Jaeger、Prometheus），從而監(jiān)控：

• 每個會話的 Token 消耗
• 各模型的調(diào)用次數(shù)和延遲
• 工具調(diào)用成功率
• 估算成本

4.4 日志太多，磁盤快滿了

默認日志保留策略是 24 小時，500MB 上限，一般不需要手動清理。但如果想調(diào)整：

# config.yaml
logging:
  appLog:
    maxSize: "1GB"       # 最大總大小
    maxAge: "72h"        # 保留時間
  sessionLog:
    maxAge: "168h"       # 會話日志保留 7 天

5. 排查流程圖：一張圖看懂排查步驟

下面是我總結(jié)的 OpenClaw 問題排查流程，遇到問題按圖索驥即可：

6. 實用小貼士

• 用 jq 處理 JSONL：日志文件是 JSON Lines 格式，配合 jq 簡直如虎添翼。如果還沒安裝，趕緊 apt install jq 或 brew install jq。
• 用 ripgrep (rg) 搜索：比 grep 更快，語法更友好。例如搜索所有包含“error”的日志：rg -i error ~/.openclaw/agents/。
• 第三方工具：社區(qū)有一些輔助工具，比如 Agent Sessions macOS App 可以用 GUI 瀏覽歷史會話；還有 Skill “session-logs” 可以直接在聊天中讓 AI 幫你分析日志（需要授權(quán)）。
• Docker 部署的日志位置：如果使用 Docker，日志默認在容器內(nèi)的 /tmp/openclaw/，但通常你會掛載一個宿主機目錄。檢查你的 docker-compose.yml 中 volumes 的映射。

7. 最后：如果還是解決不了

如果上述方法都試過了還是找不到原因，別慌，你可以在我博客留言或私信，或者去 GitHub 社區(qū)求助：

• 在 Discussions 發(fā)帖，附上：
  • openclaw doctor 的輸出
  • 相關(guān)的 Session 日志片段（注意隱藏個人敏感信息）
  • 你做了哪些嘗試
• 或者在 Issues 搜索類似問題。

社區(qū)很活躍，通常半天內(nèi)就有人回復。

總結(jié)：OpenClaw 的日志體系雖然簡單，但足夠強大。只要你分清楚 Application 日志和 Session 日志，掌握命令行三板斧，再學會用代理攔截 LLM 請求，95% 的問題都能自己搞定。希望本文能幫你成為 OpenClaw 的“日志偵探”，遇到問題不再抓瞎。

到此這篇關(guān)于OpenClaw故障排查之如何讀懂調(diào)用日志快速定位問題的文章就介紹到這了,更多相關(guān)OpenClaw故障排查內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論