Phase 2 / Ep 12: 日志系统 —— logs, sessions, 故障排查实战

⏱ 预计阅读 4 分钟 更新于 2026/4/13

🎯 学习目标：精通日志管理和故障排查方法。

1. 日志分层架构

graph TB
    subgraph Logs["📋 日志体系"]
        GWLog["🌐 Gateway 日志\n路由 · 认证 · 插件管道\n~/.openclaw/logs/gateway.log"]
        AgentLog["🤖 Agent 会话日志\n完整对话记录\nagents/xxx/sessions/*.jsonl"]
        LLMLog["🧪 LLM 调用日志\nToken 用量 · 延迟 · 错误\n嵌入 session 日志"]
        ToolLog["🔧 工具执行日志\nShell 输出 · 文件操作\n嵌入 session 日志"]
    end

2. 核心命令

# 查看 Gateway 日志（最近 50 行）
openclaw logs

# 实时跟踪日志
openclaw logs --follow

# 按级别过滤
openclaw logs --level error
openclaw logs --level warn

# 按时间范围
openclaw logs --since "2h"   # 最近 2 小时
openclaw logs --since "1d"   # 最近 1 天

# 会话管理
openclaw sessions list           # 列出所有会话
openclaw sessions show <id>      # 查看特定会话
openclaw sessions clear          # 清除当前会话

3. 常见故障排查

症状 可能原因 排查命令
Agent 不回复 Gateway 未启动 openclaw status
回复很慢 LLM API 限流 openclaw logs --level warn
工具调用失败 权限不足 openclaw logs --level error
Telegram 无反应 Bot Token 过期 openclaw channels status
429 Too Many Requests API 配额用尽 openclaw logs --follow

4. CLI vs Telegram 对照

操作 CLI 命令 Telegram
查看日志 openclaw logs /logs
实时跟踪 openclaw logs --follow N/A
错误过滤 openclaw logs --level error /logs errors
会话列表 openclaw sessions list /sessions
清除会话 openclaw sessions clear /clear

下节预告： Phase 3 开始！Ep 13，我们深入 OpenClaw 最重要的安全机制——权限模型。从 basic 到 full，理解每个等级的能力边界。