上篇回顾

上一篇〖OpenClaw系列〗openclaw doctor 诊断工具详解，我们详细介绍了 doctor 诊断工具的 24 个检查项。doctor 能发现配置问题、环境问题，但 Gateway 运行时的行为问题——比如消息为什么没发出去、AI 为什么没回复——需要看日志才能定位。

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

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

一、OpenClaw 日志系统架构

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

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

三种查看方式对比

日志文件位置

默认日志文件位置：

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

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

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

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

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

日志轮转

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

轮转后的文件名：

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

二、日志级别详解

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

默认级别

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

如何设置日志级别

方式1：环境变量

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

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

方式2：命令行选项

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

方式3：配置文件（Gateway）

{
  gateway: {
    logLevel: "debug"
  }
}

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

三、查看日志的方法

方法1：CLI logs 命令

最常用的日志查看方式：

# 查看最近 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：直接查看日志文件

# 使用 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 启动失败

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

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

DEBUG 级别会输出：

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

场景2：运行时问题排查

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

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

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

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

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

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

五、常见问题日志排查

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

问题1：Gateway 启动失败

症状：openclaw gateway start 后立刻退出

排查步骤：

# 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 没有回复

排查步骤：

# 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 过了很久才回复，或提示超时

排查步骤：

# 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 运行一段时间后，某个渠道不再接收消息

排查：

# 查看 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：日志过滤

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

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

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

技巧2：日志导出和分析

# 导出到文件
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，可以追踪一个请求的完整生命周期：

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

技巧4：日志与 doctor 结合

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

# 验证修复结果
openclaw logs -f

七、踩坑

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

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

解决：

# 使用 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

解决：

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

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

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

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

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

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

排查：

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

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

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

常见原因：

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

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

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

解决：

# 过滤掉非 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：

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

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

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

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

openclaw -v debug logs

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

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

openclaw logs --local-time

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

A：可以用脚本监控：

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

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

A：

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

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

总结

OpenClaw 日志系统的核心要点：

再看两张图：

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

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

运维速查：日志排障 SOP

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

黄金排查三步：

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

下一篇预告

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

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

本文是系列第8篇，前序文章：

〖OpenClaw系列〗openclaw doctor 诊断工具详解

〖OpenClaw系列〗Control UI 与 WebChat 使用指南

〖OpenClaw系列〗Gateway网关深度剖析

〖OpenClaw系列〗onboard新手引导全流程拆解

〖OpenClaw系列〗配置文件 openclaw.json 详解

📌 觉得有用？点个「在看」 👇 👨‍💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货 ⭐ 收藏这篇文章，遇到问题时知道该看什么日志