14.10 日志系统

OpenClaw 在 macOS 上使用 swift-log 和统一日志系统(Unified Logging)记录应用运行状态和调试信息。

日志系统架构

日志框架

• swift-log: Swift 标准日志库
• Unified Logging: macOS 系统级日志框架
• 诊断日志: 可选的 JSONL 格式滚动日志

诊断日志

启用诊断日志

诊断日志默认关闭,可以在调试面板中启用:

• 打开 OpenClaw 设置
• 切换到 Debug(调试)标签
• 启用 "Enable Diagnostics Log" 选项

日志位置

~/Library/Logs/OpenClaw/diagnostics.jsonl

日志以 JSONL(JSON Lines)格式存储,每行一个 JSON 对象。支持滚动记录,自动管理文件大小。

查看诊断日志

# 查看完整日志
cat ~/Library/Logs/OpenClaw/diagnostics.jsonl

# 实时监控日志
tail -f ~/Library/Logs/OpenClaw/diagnostics.jsonl

# 格式化输出
cat ~/Library/Logs/OpenClaw/diagnostics.jsonl | jq .

统一日志系统

隐私数据保护

Unified Logging 默认会对敏感数据进行脱敏处理。要查看完整的私有数据,需要启用私有数据显示。

启用私有数据显示

1. 创建子系统配置文件

为 OpenClaw 子系统(bot.molt)创建配置文件:

# 创建配置文件
sudo mkdir -p /Library/Preferences/Logging/Subsystems/
sudo nano /Library/Preferences/Logging/Subsystems/bot.molt.plist

2. 添加配置内容

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Enable-Private-Data</key>
    <true/>
</dict>
</plist>

3. 重新加载配置

sudo log config --reload

禁用私有数据显示

# 删除配置文件
sudo rm /Library/Preferences/Logging/Subsystems/bot.molt.plist

# 重新加载配置(可选)
sudo log config --reload

查看日志

使用系统日志工具

# 查看 OpenClaw 日志
log show --predicate 'subsystem == "bot.molt"' --last 1h

# 实时监控日志
log stream --predicate 'subsystem == "bot.molt"'

使用 OpenClaw 日志脚本

OpenClaw 提供了便捷的日志查看脚本:

# 查看 WebChat 分类的最近 5 分钟日志
./scripts/clawlog.sh --category WebChat --last 5m

# 查看所有分类的日志
./scripts/clawlog.sh --last 10m

# 实时监控日志
./scripts/clawlog.sh --follow

使用控制台应用

• 打开 macOS 控制台应用(Console.app)
• 在左侧选择设备
• 搜索 "bot.molt" 或 "OpenClaw"
• 使用过滤器筛选特定类型的日志

日志级别

日志系统支持多个级别:

• trace: 详细的跟踪信息
• debug: 调试信息
• info: 一般信息
• notice: 需要注意的信息
• warning: 警告信息
• error: 错误信息
• critical: 严重错误

最佳实践

• 默认情况下关闭诊断日志和私有数据显示
• 仅在主动调试时启用详细日志
• 使用日志脚本(clawlog.sh)获取增强格式的日志
• 调试完成后立即禁用私有数据显示
• 定期清理诊断日志文件以节省磁盘空间