OpenClaw故障排查之如何读懂调用日志快速定位问题

在揭秘 OpenClaw 架构设计系列文章中，我详细介绍了 OpenClaw 架构及构建、部署与日常运维。但再稳定的系统，也难免会遇到问题——AI 不响应、工具调用失败、成本异常飙升……这时候，日志就是我们最重要的“案发现场”。本文基于社区最新实践，手把手教你如何利用 OpenClaw 的日志系统，快速定位并解决常见问题。

1. 两类日志：分清“系统运行”和“AI 调用”

OpenClaw 的日志主要分为两大类，它们的用途和查看方式完全不同，先记住这张表：

一句话区分：Application 日志告诉你“系统跑没跑起来”，Session 日志告诉你“AI 到底干了什么”。

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

OpenClaw 的 CLI 提供了非常方便的日志查看命令，无需手动翻文件，适合第一时间快速定位。

2.1 实时跟随最新日志

openclaw logs --follow

这是我最常用的命令，它会实时输出 Application 日志，同时也会显示每个会话的关键摘要（如工具调用、错误）。如果你刚遇到一个问题，立刻执行它，往往能看到最新的错误信息。

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   # 自动修复一些常见问题（如权限、配置缺失）

doctor 命令会检查 Gateway 状态、Docker 是否运行、关键端口是否被占用、配置是否正确等。强烈建议遇到任何问题第一步都先跑它。

2.5 查看整体状态

openclaw status

显示当前有多少活跃会话、各通道是否在线、Agent 运行情况等。

3. 深入现场：直接查看日志文件

当命令行信息不够详细时，我们需要直接查看日志文件。这里才是“最完整”的调用记录。

3.1 Session 日志：AI 调用的“黑匣子”

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

<agent_id> 通常是你在配置中定义的默认 Agent 名称（如 main），或者通过 ls ~/.openclaw/agents/ 查看。每个会话（一个聊天对话）对应一个 .jsonl 文件，文件名是会话 ID。

文件格式：JSON Lines，每行一个 JSON 对象，代表一次交互。典型内容示例：

{
  "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
# 统计每个工具被调用的次数
cat ~/.openclaw/agents/*/sessions/*.jsonl | jq -r 'select(.toolCall) | .toolCall.name' | sort | uniq -c

3.2 Application 日志：系统运行“心电图”

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

文件按天滚动，保留最近 24 小时，总大小不超过 500MB（可配置）。查看方式：

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

内容示例：

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）

官方现状：无论是 openclaw logs 还是 Session 日志文件，都不会输出发给 OpenAI、Anthropic 等 Provider 的完整 HTTP 请求。这是出于隐私和安全考虑（避免日志中泄露 API key）。

社区解决方案：

方法一：使用代理拦截（推荐）

配置一个 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、响应。

方法二：源码修改（开发环境）

如果你在开发环境，可以修改 src/agents/providers/ 下的 HTTP 客户端代码，增加日志输出。但注意不要提交到生产环境。

4.2 Agent 卡住 / 工具调用失败

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

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

常见的错误原因：

• 工具所需的依赖未安装（如 Python 脚本缺少库）
• 沙箱执行超时（可调整 agents.defaults.sandbox.timeout）
• 工具白名单拦截（查看 toolCall.name 是否在 security.toolDenylist 中）

4.3 成本/调用量监控

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

openclaw plugins enable diagnostics-otel

启用后，你可以在配置中设置导出端点（如 Jaeger、Prometheus），从而监控：

• 每个会话的 Token 消耗
• 各模型的调用次数和延迟
• 工具调用成功率
• 估算成本

4.4 日志太多，磁盘快满了

默认日志保留策略是 24 小时，500MB 上限，一般不需要手动清理。但如果想调整：

# config.yaml
logging:
  appLog:
    maxSize: "1GB"       # 最大总大小
    maxAge: "72h"        # 保留时间
  sessionLog:
    maxAge: "168h"       # 会话日志保留 7 天

5. 排查流程图：一张图看懂排查步骤

下面是我总结的 OpenClaw 问题排查流程，遇到问题按图索骥即可：

6. 实用小贴士

• 用 jq 处理 JSONL：日志文件是 JSON Lines 格式，配合 jq 简直如虎添翼。如果还没安装，赶紧 apt install jq 或 brew install jq。
• 用 ripgrep (rg) 搜索：比 grep 更快，语法更友好。例如搜索所有包含“error”的日志：rg -i error ~/.openclaw/agents/。
• 第三方工具：社区有一些辅助工具，比如 Agent Sessions macOS App 可以用 GUI 浏览历史会话；还有 Skill “session-logs” 可以直接在聊天中让 AI 帮你分析日志（需要授权）。
• Docker 部署的日志位置：如果使用 Docker，日志默认在容器内的 /tmp/openclaw/，但通常你会挂载一个宿主机目录。检查你的 docker-compose.yml 中 volumes 的映射。

7. 最后：如果还是解决不了

如果上述方法都试过了还是找不到原因，别慌，你可以在我博客留言或私信，或者去 GitHub 社区求助：

• 在 Discussions 发帖，附上：
  • openclaw doctor 的输出
  • 相关的 Session 日志片段（注意隐藏个人敏感信息）
  • 你做了哪些尝试
• 或者在 Issues 搜索类似问题。

社区很活跃，通常半天内就有人回复。

总结：OpenClaw 的日志体系虽然简单，但足够强大。只要你分清楚 Application 日志和 Session 日志，掌握命令行三板斧，再学会用代理拦截 LLM 请求，95% 的问题都能自己搞定。希望本文能帮你成为 OpenClaw 的“日志侦探”，遇到问题不再抓瞎。

到此这篇关于OpenClaw故障排查之如何读懂调用日志快速定位问题的文章就介绍到这了,更多相关OpenClaw故障排查内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论