Logging System Overview
The OpenClaw Gateway logging system records all key service events and is the foundation for troubleshooting and security auditing. Proper configuration provides sufficient information while keeping storage costs under control.
Basic Configuration
{
"logging": {
"level": "info",
"format": "json",
"console": true,
"file": {
"enabled": true,
"path": "~/.openclaw/logs/gateway.log",
"maxSize": "50m",
"maxFiles": 10
}
}
}
Log Levels
| Level | Description | Use Case |
|---|---|---|
| debug | Detailed debug info | Development and troubleshooting |
| info | General runtime info | Daily operation (recommended) |
| warn | Warning messages | Minimum recommended for production |
| error | Error messages | Errors only |
# Change log level at runtime
openclaw configure set logging.level debug
# Temporarily enable debug
openclaw start --log-level debug
Viewing Logs
openclaw logs --follow
openclaw logs --lines 100
openclaw logs --level error
openclaw logs --since "1h"
openclaw logs --grep "timeout"
Structured Log Format
JSON format for machine parsing:
{
"timestamp": "2026-03-21T10:30:01.234Z",
"level": "info",
"module": "channel",
"channel": "telegram-main",
"event": "message.received",
"user": "user001",
"messageLength": 45,
"sessionId": "sess_abc123"
}
Text format for human reading:
2026-03-21 10:30:01 [INFO] [channel] Message received from telegram-main/user001 (45 chars)
Log Rotation
Prevent log files from growing indefinitely:
{
"logging": {
"file": {
"maxSize": "50m",
"maxFiles": 10,
"compress": true
}
}
}
You can also use the system's logrotate:
# /etc/logrotate.d/openclaw
/home/user/.openclaw/logs/*.log {
daily
rotate 14
compress
delaycompress
missingok
notifempty
copytruncate
}
Categorized Logs
Route different log types to different files:
{
"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"] }
}
}
}
Sending Logs to External Systems
Syslog
{
"logging": {
"syslog": { "enabled": true, "host": "syslog.example.com", "port": 514, "protocol": "udp" }
}
}
Loki
{
"logging": {
"loki": { "enabled": true, "url": "http://loki.example.com:3100/loki/api/v1/push", "labels": { "app": "openclaw", "env": "production" } }
}
}
Sensitive Information Redaction
Automatically redact sensitive information in logs:
{
"logging": {
"redact": {
"enabled": true,
"patterns": ["apiKey", "token", "password", "Authorization"],
"replacement": "***REDACTED***"
}
}
}
Performance Logging
{
"logging": {
"performance": {
"enabled": true,
"slowThreshold": 5000,
"logTimings": true
}
}
}
When request processing time exceeds the threshold, detailed timing breakdowns are logged.
Summary
The logging system is the eyes of OpenClaw operations. Properly configuring log levels, enabling rotation, redacting sensitive information, and sending logs to a centralized storage system are the foundations of building an observability platform.