Gateway 日志系统配置教程

日志系统概述

OpenClaw Gateway 的日志系统记录了服务运行的所有关键事件，是故障排查和安全审计的基础。合理配置日志系统可以在提供充足信息的同时控制存储开销。

基础配置

{
  "logging": {
    "level": "info",
    "format": "json",
    "console": true,
    "file": {
      "enabled": true,
      "path": "~/.openclaw/logs/gateway.log",
      "maxSize": "50m",
      "maxFiles": 10
    }
  }
}

日志级别

可用日志级别（从详细到简洁）：

级别	说明	适用场景
debug	详细调试信息	开发和排查问题
info	一般运行信息	日常运行（推荐）
warn	警告信息	生产环境最低建议
error	错误信息	只关注异常

# 运行时修改日志级别
openclaw configure set logging.level debug

# 临时启用 debug
openclaw start --log-level debug

查看日志

# 查看实时日志
openclaw logs --follow

# 查看最近100行
openclaw logs --lines 100

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

# 按时间过滤
openclaw logs --since "1h"
openclaw logs --since "2026-03-20" --until "2026-03-21"

# 按关键词搜索
openclaw logs --grep "timeout"
openclaw logs --grep "telegram" --level error

结构化日志格式

JSON 格式日志便于机器解析：

{
  "timestamp": "2026-03-21T10:30:01.234Z",
  "level": "info",
  "module": "channel",
  "channel": "telegram-main",
  "event": "message.received",
  "user": "user001",
  "messageLength": 45,
  "sessionId": "sess_abc123"
}

文本格式日志便于人类阅读：

2026-03-21 10:30:01 [INFO] [channel] Message received from telegram-main/user001 (45 chars)

切换格式：

{
  "logging": {
    "format": "text"
  }
}

日志轮转

防止日志文件无限增长：

{
  "logging": {
    "file": {
      "maxSize": "50m",
      "maxFiles": 10,
      "compress": true
    }
  }
}

maxSize：单个文件最大大小，超过后创建新文件
maxFiles：保留的日志文件数量
compress：旧日志文件使用 gzip 压缩

也可以使用系统的 logrotate：

# /etc/logrotate.d/openclaw
/home/user/.openclaw/logs/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

分类日志

将不同类型的日志输出到不同文件：

{
  "logging": {
    "files": {
      "gateway": {
        "path": "~/.openclaw/logs/gateway.log",
        "level": "info"
      },
      "access": {
        "path": "~/.openclaw/logs/access.log",
        "level": "info",
        "events": ["request", "response"]
      },
      "error": {
        "path": "~/.openclaw/logs/error.log",
        "level": "error"
      },
      "audit": {
        "path": "~/.openclaw/logs/audit.log",
        "events": ["auth", "config_change", "secret_access"]
      }
    }
  }
}

日志发送到外部系统

Syslog

{
  "logging": {
    "syslog": {
      "enabled": true,
      "host": "syslog.example.com",
      "port": 514,
      "protocol": "udp",
      "facility": "local0"
    }
  }
}

Loki

{
  "logging": {
    "loki": {
      "enabled": true,
      "url": "http://loki.example.com:3100/loki/api/v1/push",
      "labels": {
        "app": "openclaw",
        "env": "production"
      }
    }
  }
}

敏感信息屏蔽

日志中自动屏蔽敏感信息：

{
  "logging": {
    "redact": {
      "enabled": true,
      "patterns": [
        "apiKey",
        "token",
        "password",
        "Authorization"
      ],
      "replacement": "***REDACTED***"
    }
  }
}

性能日志

记录请求处理时间：

{
  "logging": {
    "performance": {
      "enabled": true,
      "slowThreshold": 5000,
      "logTimings": true
    }
  }
}

当请求处理时间超过阈值时，会记录详细的时间分布：

{
  "event": "slow_request",
  "totalTime": 6500,
  "timings": {
    "receive": 5,
    "auth": 10,
    "model": 6200,
    "format": 15,
    "send": 270
  }
}

日志分析

# 统计错误类型
openclaw logs --level error --since "24h" --stats

# 统计请求量
openclaw logs --event "message.received" --since "24h" --count

# 导出用于分析
openclaw logs --since "7d" --format json --output weekly-logs.json

总结

日志系统是 OpenClaw 运维的眼睛。合理配置日志级别、启用日志轮转、屏蔽敏感信息，并将日志发送到集中存储系统，是构建可观测性平台的基础。