第08篇-日志系统与调试技巧

〖OpenClaw系列〗日志系统与调试技巧

上篇回顾

上一篇《 $openclaw doctor 诊断工具详解$ (./第07篇-openclaw doctor 诊断工具详解.md)》，我们详细介绍了 doctor 诊断工具的 24 个检查项。doctor 能发现配置问题、环境问题，但 Gateway 运行时的行为问题------比如消息为什么没发出去、AI 为什么没回复------需要看日志才能定位。

这篇深入 OpenClaw 的日志系统：日志存在哪里、有几种查看方式、如何开启 DEBUG 模式、以及常见问题的日志排查方法。

本文定位：日志系统的完全指南。读完这篇，你能熟练查看和分析 OpenClaw 日志，用日志定位 Gateway 启动失败、消息发送失败、模型调用失败等问题。

一、OpenClaw 日志系统架构

OpenClaw 的日志系统分三层：CLI 日志命令 、Gateway 日志 API 、日志文件。

这张图展示了三种查看方式的关系。上方三个彩色区域 是日志的三种入口，下方绿色区域是日志级别从低到高的排列。

三种查看方式对比

方式	适用场景	实时性	历史数据
CLI logs 命令	日常查看、排查问题	支持实时跟随（-f）	最近 24 小时
Gateway Logs API	Control UI 展示、程序化获取	WebSocket 实时推送	可配置
日志文件	深度分析、离线查看、长期存档	文件追加	完整历史

日志文件位置

默认日志文件位置：

bash 复制代码

# macOS
~/Library/Caches/openclaw/openclaw.log

# Linux
~/.cache/openclaw/openclaw.log

# 或统一路径
~/.openclaw/tmp/openclaw.log

日志文件采用 JSON Lines 格式，每行一条 JSON 记录：

json 复制代码

{"time":"2026-05-24T08:30:00.123Z","level":"info","module":"gateway","message":"Gateway ready on :18789"}

日志轮转

日志文件自动轮转，防止无限增长：

触发条件	行为
时间	每 24 小时创建新文件
大小	单文件超过 500MB 时轮转
清理	保留最近 7 天的日志

轮转后的文件名：

复制代码

openclaw.log           # 当前日志
openclaw-20260523.log  # 昨天日志
openclaw-20260522.log  # 前天日志

二、日志级别详解

OpenClaw 使用 7 级日志，从静默到最详细：

级别	数值	说明	使用场景
silent	∞	完全不输出	性能测试时
fatal	0	致命错误，程序即将崩溃	严重故障
error	1	错误，功能无法正常执行	排查问题
warn	2	警告，可能影响功能	关注潜在问题
info	3	一般信息（默认）	日常运行
debug	4	调试信息	开发调试
trace	5	最详细的追踪信息	深度排查

默认级别

CLI 命令：info
Gateway 控制台：info
日志文件：debug（记录更详细，方便事后分析）

如何设置日志级别

方式1：环境变量

bash 复制代码

# 当前终端会话有效
export OPENCLAW_LOG_LEVEL=debug
openclaw gateway start

# 单次命令有效
OPENCLAW_LOG_LEVEL=trace openclaw logs --follow

方式2：命令行选项

bash 复制代码

# CLI 命令使用 -v 或 --verbose
openclaw -v debug logs
openclaw --verbose trace gateway start

方式3：配置文件（Gateway）

json5 复制代码

{
  gateway: {
    logLevel: "debug"
  }
}

注意：OPENCLAW_LOG_LEVEL 环境变量优先级最高，会覆盖配置文件设置。

三、查看日志的方法

方法1：CLI logs 命令

最常用的日志查看方式：

bash 复制代码

# 查看最近 200 行
openclaw logs

# 查看最近 50 行
openclaw logs --limit 50

# 实时跟随（类似 tail -f）
openclaw logs --follow
# 或简写
openclaw logs -f

# 查看最近 1 小时的日志
openclaw logs --since 1h

# 查看特定时间范围
openclaw logs --from "2026-05-24T08:00:00" --to "2026-05-24T09:00:00"

# JSON 格式输出（便于程序处理）
openclaw logs --json

# 纯文本格式（无颜色）
openclaw logs --plain

# 本地时间（默认是 UTC）
openclaw logs --local-time

方法2：Control UI 日志查看器

在浏览器打开 Control UI（http://localhost:18789），点击左侧「Logs」菜单：

实时日志流（自动滚动）
日志级别筛选（ERROR/WARN/INFO/DEBUG）
关键词搜索（Ctrl+F）
暂停/恢复自动滚动

方法3：直接查看日志文件

bash 复制代码

# 使用 tail 查看最新内容
tail -f ~/.openclaw/tmp/openclaw.log

# 使用 cat 查看全部
cat ~/.openclaw/tmp/openclaw.log | jq '.'  # 格式化 JSON

# 使用 grep 过滤
grep "ERROR" ~/.openclaw/tmp/openclaw.log
grep "telegram:" ~/.openclaw/tmp/openclaw.log

四、如何开启 DEBUG 模式

排查复杂问题时，需要开启 DEBUG 或 TRACE 级别获取更详细的信息。

场景1：Gateway 启动失败

bash 复制代码

# 在 DEBUG 级别启动 Gateway
OPENCLAW_LOG_LEVEL=debug openclaw gateway start

# 或 TRACE 级别（最详细）
OPENCLAW_LOG_LEVEL=trace openclaw gateway start

DEBUG 级别会输出：

配置加载的详细过程
每个渠道的连接步骤
Agent 初始化的详细信息
WebSocket 连接的握手过程

场景2：运行时问题排查

Gateway 已经在运行，想看 DEBUG 日志：

bash 复制代码

# 终端1：保持 Gateway 运行（如果还没开 DEBUG）
openclaw gateway stop
OPENCLAW_LOG_LEVEL=debug openclaw gateway start

# 终端2：查看 DEBUG 日志
openclaw logs -f

场景3：仅查看特定模块的 DEBUG 日志

OpenClaw 支持子系统（subsystem）日志过滤：

bash 复制代码

# 只查看 gateway 模块的 DEBUG 日志
# 目前 CLI logs 命令不支持按模块过滤
# 可以直接查看日志文件并过滤
tail -f ~/.openclaw/tmp/openclaw.log | grep '"module":"gateway"'

五、常见问题日志排查

这张图展示了四类常见问题的日志排查流程。上方四个彩色区域 是问题类型，下方绿色区域是通用调试技巧。

问题1：Gateway 启动失败

症状：openclaw gateway start 后立刻退出

排查步骤：

bash 复制代码

# 1. 查看最近 50 行日志
openclaw logs --limit 50

常见错误日志：

复制代码

[ERROR] Schema validation failed:
  - agents.defaults.model: expected string, got number

→ 配置语法错误，检查 openclaw.json

复制代码

[ERROR] Port 18789 is already in use

→ 端口被占用，lsof -i :18789 查看占用进程

复制代码

[FATAL] Uncaught exception: Cannot find module 'pino'

→ 依赖损坏，重新安装 npm install -g @openclaw/cli

问题2：消息发送失败

症状：在 Telegram 发送消息，AI 没有回复

排查步骤：

bash 复制代码

# 1. 开启实时日志跟随
openclaw logs -f

# 2. 在 Telegram 发送测试消息
# 3. 观察日志输出

正常流程日志：

复制代码

[INFO] telegram: received message from user 123456789
[INFO] router: message routed to agent default
[INFO] agent: sending request to model anthropic/claude-sonnet-4-6
[INFO] agent: received response (_tokens: 45)
[INFO] telegram: sending reply to user 123456789

异常日志示例：

复制代码

[WARN] telegram: webhook verification failed

→ Bot Token 错误，检查 channels.telegram.bot_token

复制代码

[ERROR] agent: model request failed (status: 401)

→ API Key 无效，检查 agents.defaults.model.apiKey

复制代码

[WARN] agent: tool exec not allowed (skill: shell)

→ 工具未授权，检查 tools.allow 配置

问题3：AI 回复慢或超时

症状：AI 过了很久才回复，或提示超时

排查步骤：

bash 复制代码

# 1. 开启 DEBUG 级别日志
OPENCLAW_LOG_LEVEL=debug openclaw logs -f

# 2. 观察时间戳，定位慢在哪一步

关键日志点：

复制代码

[DEBUG] agent: model request started (timeout: 600s)
[DEBUG] agent: model response chunk received (+2.3s)
[DEBUG] agent: model response complete (+45.2s)

如果「request started」到「response chunk」间隔很长：

→ 模型 API 响应慢，检查网络或更换模型

如果「response complete」后很久才发送：

→ Gateway 处理慢，检查服务器负载

问题4：渠道连接断开

症状：Gateway 运行一段时间后，某个渠道不再接收消息

排查：

bash 复制代码

# 查看 ERROR 级别日志
openclaw logs | grep ERROR

常见错误：

复制代码

[ERROR] telegram: polling error (429 Too Many Requests)

→ Telegram 频率限制，检查是否有循环消息

复制代码

[ERROR] whatsapp: session expired

→ WhatsApp 会话过期，需要重新扫码登录

复制代码

[WARN] discord: websocket closed (code: 1006)
[INFO] discord: reconnecting...

→ 正常重连，观察是否能自动恢复

六、日志高级技巧

技巧1：日志过滤

bash 复制代码

# 只查看错误
openclaw logs | grep "ERROR"

# 查看特定模块
openclaw logs | grep "telegram:"

# 排除某些信息
openclaw logs | grep -v "heartbeat"

技巧2：日志导出和分析

bash 复制代码

# 导出到文件
openclaw logs --json > openclaw-logs.json

# 使用 jq 分析
cat openclaw-logs.json | jq 'select(.level == "error") | .message'
cat openclaw-logs.json | jq 'group_by(.level) | map({level: .[0].level, count: length})'

# 统计各模块日志数量
cat openclaw-logs.json | jq -r '.module' | sort | uniq -c | sort -rn

技巧3：关联请求追踪

DEBUG 级别日志包含 requestId，可以追踪一个请求的完整生命周期：

bash 复制代码

# 找到特定请求的日志
openclaw logs --json | jq 'select(.requestId == "req-abc123")'

技巧4：日志与 doctor 结合

bash 复制代码

# 发现问题 → 查看日志 → 运行 doctor
openclaw logs --limit 20 | grep ERROR
openclaw doctor --fix

# 验证修复结果
openclaw logs -f

七、踩坑

坑1：DEBUG 日志太多，看不到关键信息

现象：开启 DEBUG 后，日志刷屏，找不到有用信息

解决：

bash 复制代码

# 使用 grep 过滤关键模块
OPENCLAW_LOG_LEVEL=debug openclaw gateway start 2>&1 | grep -E "(ERROR|WARN|telegram:|agent:model)"

# 或使用 jq 过滤 JSON 日志
tail -f ~/.openclaw/tmp/openclaw.log | jq 'select(.level != "debug" or .module == "agent")'

坑2：日志文件占用磁盘空间过大

现象：~/.openclaw/tmp/ 目录占用几个 GB

解决：

bash 复制代码

# 查看日志文件大小
du -sh ~/.openclaw/tmp/

# 手动清理旧日志
rm ~/.openclaw/tmp/openclaw-*.log

# 或配置更短的保留时间（目前不支持配置，需手动清理）

注意：日志轮转只保留 7 天，如果还在涨，可能是 DEBUG 级别产生了太多日志。

坑3：Control UI 日志不实时更新

现象：Control UI 的 Logs 页面卡住，不显示新日志

排查：

bash 复制代码

# 1. 检查 Gateway 是否还在运行
openclaw gateway status

# 2. 直接用 CLI 查看是否正常
openclaw logs -f

# 3. 刷新浏览器页面
# 4. 检查浏览器控制台是否有 WebSocket 错误

常见原因：

Gateway 进程崩溃
浏览器 WebSocket 连接断开
日志级别设置为 silent

坑4：JSON 格式日志中的特殊字符

现象：用 jq 解析日志时出错

解决：

bash 复制代码

# 过滤掉非 JSON 行（如启动时的 banner）
cat openclaw.log | grep "^{" | jq '.'

# 或使用 sed 清理
sed -n '/^{/p' openclaw.log | jq '.'

八、常见问题（FAQ）

Q：日志文件在哪里？

A：默认位置：

macOS: ~/Library/Caches/openclaw/openclaw.log
Linux: ~/.cache/openclaw/openclaw.log
或统一: ~/.openclaw/tmp/openclaw.log

可以用 openclaw doctor 查看实际路径。

Q：如何清空日志？

A：

bash 复制代码

# 清空当前日志文件（Gateway 重启后会重新创建）
> ~/.openclaw/tmp/openclaw.log

# 删除所有历史日志
rm ~/.openclaw/tmp/openclaw-*.log

Q：为什么 DEBUG 日志在 CLI 看不到，但在文件里有？

A：CLI logs 命令默认只显示 info 及以上级别。文件日志默认记录 debug 级别。可以用 -v debug 选项查看 DEBUG 日志：

bash 复制代码

openclaw -v debug logs

Q：日志中的时间戳是 UTC 还是本地时间？

A：默认是 UTC（ISO 8601 格式）。使用 --local-time 选项显示本地时间：

bash 复制代码

openclaw logs --local-time

Q：如何监控日志中的错误并告警？

A：可以用脚本监控：

bash 复制代码

#!/bin/bash
# 监控 ERROR 日志并发送通知
openclaw logs -f | while read line; do
  if echo "$line" | grep -q "ERROR"; then
    # 发送通知（macOS）
    osascript -e "display notification \"$line\" with title \"OpenClaw Error\""
  fi
done

Q：Gateway 崩溃后如何查看最后的日志？

A：

bash 复制代码

# 查看日志文件最后 100 行
tail -n 100 ~/.openclaw/tmp/openclaw.log

# 查找 FATAL 或 Uncaught exception
grep -E "(FATAL|Uncaught|crash)" ~/.openclaw/tmp/openclaw.log

总结

OpenClaw 日志系统的核心要点：

维度	要点
三种查看方式	CLI logs 命令、Gateway Logs API、日志文件
日志级别	silent/fatal/error/warn/info/debug/trace
文件位置	`~/.openclaw/tmp/openclaw.log`
轮转策略	24h / 500MB，保留 7 天
常用命令	`logs -f`、`logs --limit 50`、`logs

再看两张图：

架构图（第一章）：三种查看方式的关系和日志级别
排查流程图（第五章）：四类常见问题的排查步骤

一句话记住 ：日常用 openclaw logs -f 实时查看，问题排查开 OPENCLAW_LOG_LEVEL=debug，历史分析直接看日志文件。

运维速查：日志排障 SOP

出问题时按故障类型选排查路径。

故障类型	排查命令	看什么
Gateway 起不来	`tail -50 ~/.openclaw/logs/gateway-stderr.log`	找 `FATAL` 或 `ERROR`，通常是配置或端口问题
AI 不回复	`openclaw logs -f` 然后发一条消息	看消息是否进站、路由是否匹配、模型是否返回
模型报错	`openclaw logs	grep -i "model
渠道断开	`openclaw logs	grep -i "channel
性能问题	`OPENCLAW_LOG_LEVEL=debug openclaw gateway start`	开 debug 看每个环节耗时
历史问题追溯	`grep "2026-06-06" ~/.openclaw/tmp/openclaw.log`	按时间过滤日志文件

黄金排查三步：

openclaw doctor --fix（先排除配置问题）
openclaw logs -f（实时看运行日志）
OPENCLAW_LOG_LEVEL=debug（看不够就开 debug）

下一篇预告

〖OpenClaw系列〗CLI 命令行完全手册

日志排查只是 CLI 的一部分功能。下一篇全面介绍 OpenClaw CLI：所有命令的分类速查、常用选项、环境变量、以及自动化脚本技巧。

本文是系列第8篇，前序文章： $第7篇：openclaw doctor 诊断工具详解$ (./第07篇-openclaw doctor 诊断工具详解.md) | $第6篇：Control UI 与 WebChat 使用指南$ (./第06篇-Control UI 与 WebChat 使用指南.md)

📌 觉得有用？点个「在看」 👇

👨‍💻 关注「敏叔侃技术 」，每周更新 OpenClaw 实战干货

⭐ 收藏这篇文章，遇到问题时知道该看什么日志