OpenClaw日志配置和查看教程

前言

日志是排查问题和监控运行状态的重要工具。OpenClaw 提供了灵活的日志系统，支持多种日志级别、输出格式和存储策略。本文将全面介绍如何配置和利用 OpenClaw 的日志功能。

日志级别

OpenClaw 支持四个日志级别，从详细到精简依次为：

设置日志级别

通过配置文件设置：

// ~/.config/openclaw/openclaw.json5
{
  log: {
    level: "info"  // debug | info | warn | error
  }
}

通过命令行设置：

openclaw config set log.level "debug"
openclaw restart

通过环境变量设置：

export OPENCLAW_LOG_LEVEL="debug"
openclaw up

各级别输出示例

debug 级别 - 输出所有信息，包括请求/响应细节：

[2026-03-22 10:30:15.123] [DEBUG] [gateway] 收到来自 WhatsApp 的消息: {from: "+8613800138000", body: "你好"}
[2026-03-22 10:30:15.125] [DEBUG] [model] 构建 Claude API 请求, tokens: 1250
[2026-03-22 10:30:15.126] [DEBUG] [model] 请求头: {x-api-key: "sk-ant-***", content-type: "application/json"}
[2026-03-22 10:30:16.890] [DEBUG] [model] Claude API 响应, 耗时: 1765ms, tokens: 320
[2026-03-22 10:30:16.892] [DEBUG] [gateway] 发送回复到 WhatsApp: {to: "+8613800138000", length: 480}

info 级别 - 输出关键运行节点：

[2026-03-22 10:30:15.123] [INFO] [gateway] 收到消息 (WhatsApp)
[2026-03-22 10:30:16.890] [INFO] [model] Claude 回复完成 (1765ms, 320 tokens)
[2026-03-22 10:30:16.895] [INFO] [gateway] 回复已发送 (WhatsApp)

warn 级别 - 仅输出需要注意的情况：

[2026-03-22 10:30:15.500] [WARN] [model] API 请求速率接近限制 (85/100 RPM)
[2026-03-22 10:35:00.000] [WARN] [gateway] WhatsApp 连接不稳定, 自动重连中

error 级别 - 仅输出错误：

[2026-03-22 10:30:15.500] [ERROR] [model] Claude API 调用失败: 401 Unauthorized
[2026-03-22 10:30:15.501] [ERROR] [model] 错误详情: Invalid API key provided

日志文件位置

默认日志目录

OpenClaw 的日志文件默认存储在以下位置：

日志文件命名

日志文件按日期和类型命名：

logs/
├── openclaw-2026-03-22.log        # 主日志
├── openclaw-2026-03-21.log        # 前一天的日志
├── openclaw-error-2026-03-22.log  # 错误专用日志
├── openclaw-access-2026-03-22.log # 访问日志
└── openclaw-2026-03-20.log.gz     # 已压缩归档的日志

自定义日志目录

你可以修改日志存储位置：

// ~/.config/openclaw/openclaw.json5
{
  log: {
    level: "info",
    dir: "/var/log/openclaw"  // 自定义日志目录
  }
}

确保 OpenClaw 进程对该目录有写入权限：

sudo mkdir -p /var/log/openclaw
sudo chown $(whoami) /var/log/openclaw

使用 openclaw logs 命令

openclaw logs 是查看日志的内置命令，功能丰富且易用。

基本用法

# 查看最近的日志（默认显示最后 50 行）
openclaw logs

# 实时跟踪日志（类似 tail -f）
openclaw logs -f

# 显示最后 200 行日志
openclaw logs -n 200

按级别筛选

# 仅显示错误日志
openclaw logs --level error

# 显示警告及以上级别
openclaw logs --level warn

# 显示调试及以上级别（所有日志）
openclaw logs --level debug

按时间范围筛选

# 查看今天的日志
openclaw logs --since today

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

# 查看指定时间范围
openclaw logs --since "2026-03-22 10:00" --until "2026-03-22 12:00"

按组件筛选

# 只查看网关相关日志
openclaw logs --component gateway

# 只查看模型调用日志
openclaw logs --component model

# 只查看特定频道的日志
openclaw logs --component channel:whatsapp

组合筛选

多个筛选条件可以组合使用：

# 查看今天 WhatsApp 频道的错误日志，实时跟踪
openclaw logs --level error --component channel:whatsapp --since today -f

日志轮转

为了避免日志文件无限增长，OpenClaw 内置了日志轮转机制。

默认轮转策略

{
  log: {
    rotation: {
      // 单个日志文件最大大小
      maxSize: "50MB",
      // 保留日志文件天数
      maxAge: 30,
      // 最多保留的日志文件数量
      maxFiles: 90,
      // 归档的日志是否压缩
      compress: true
    }
  }
}

轮转策略说明

• 当单个日志文件超过 maxSize 时，会自动创建新文件
• 超过 maxAge 天的旧日志会被自动删除
• 当日志文件总数超过 maxFiles 时，最旧的文件会被删除
• 开启 compress 后，归档日志会被 gzip 压缩，节省磁盘空间

手动清理日志

如果需要手动清理日志文件：

# 查看日志文件占用的磁盘空间
du -sh ~/.local/share/openclaw/logs/

# 删除 7 天前的日志
find ~/.local/share/openclaw/logs/ -name "*.log" -mtime +7 -delete

# 删除所有已压缩的旧日志
find ~/.local/share/openclaw/logs/ -name "*.gz" -delete

JSON 结构化日志

对于需要用日志分析工具（如 ELK、Grafana Loki）处理日志的场景，OpenClaw 支持 JSON 格式输出。

启用 JSON 格式

{
  log: {
    level: "info",
    format: "json"  // "text"（默认） 或 "json"
  }
}

JSON 日志示例

{
  "timestamp": "2026-03-22T10:30:15.123Z",
  "level": "info",
  "component": "gateway",
  "message": "收到消息",
  "meta": {
    "channel": "whatsapp",
    "from": "+8613800138000",
    "messageId": "msg_abc123",
    "messageType": "text"
  }
}

{
  "timestamp": "2026-03-22T10:30:16.890Z",
  "level": "info",
  "component": "model",
  "message": "API 调用完成",
  "meta": {
    "model": "claude-3.5-sonnet",
    "latency": 1765,
    "inputTokens": 1250,
    "outputTokens": 320,
    "cost": 0.0058
  }
}

将 JSON 日志导入分析工具

配合 Filebeat 将日志发送到 Elasticsearch：

# filebeat.yml
filebeat.inputs:
  - type: log
    paths:
      - /home/user/.local/share/openclaw/logs/openclaw-*.log
    json.keys_under_root: true
    json.add_error_key: true

output.elasticsearch:
  hosts: ["localhost:9200"]
  index: "openclaw-logs-%{+yyyy.MM.dd}"

控制台输出设置

除了文件日志，你还可以控制终端输出的行为：

{
  log: {
    level: "info",
    console: {
      enabled: true,       // 是否在终端输出日志
      colorize: true,      // 是否着色输出
      timestamp: true      // 是否显示时间戳
    }
  }
}

当使用 openclaw up -d（后台模式）运行时，控制台输出会自动禁用。

总结

合理的日志配置能帮助你快速发现和定位问题。以下是推荐的配置方案：

• 开发环境：日志级别设为 debug，使用文本格式，方便实时查看
• 生产环境：日志级别设为 info，开启日志轮转和压缩
• 集群部署：使用 JSON 格式，配合日志收集工具集中管理
• 排查问题：临时调到 debug 级别，配合 openclaw logs -f 实时跟踪

记得定期检查磁盘空间占用，避免日志文件过大影响系统运行。