Skip to main content

Logs

Logs are essential for troubleshooting issues. This guide explains where to find logs and how to interpret them.

Log Locations​

Log TypeLocationPurpose
Application/var/log/openclaw/app.logMain application events
Access/var/log/openclaw/access.logHTTP requests
Error/var/log/openclaw/error.logErrors only
WhatsApp/var/log/openclaw/whatsapp.logWhatsApp integration
Telegram/var/log/openclaw/telegram.logTelegram integration
Discord/var/log/openclaw/discord.logDiscord integration
Backup/var/log/openclaw/backup.logBackup operations
Security/var/log/openclaw/security.logSecurity events
System/var/log/syslogOS-level events
SSH/var/log/auth.logSSH login attempts

Viewing Logs​

Real-Time Viewing​

# Follow single log
tail -f /var/log/openclaw/app.log

# Follow all OpenClaw logs
tail -f /var/log/openclaw/*.log

# Follow with highlighting
tail -f /var/log/openclaw/app.log | grep --color -E 'ERROR|WARNING|$'

Recent Entries​

# Last 100 lines
tail -100 /var/log/openclaw/app.log

# Last 50 errors
tail -100 /var/log/openclaw/error.log

Search Logs​

# Find specific pattern
grep "user_id:12345" /var/log/openclaw/app.log

# Search all logs
grep -r "error" /var/log/openclaw/

# Case-insensitive search
grep -i "timeout" /var/log/openclaw/app.log

# Search with context (3 lines before/after)
grep -C 3 "ERROR" /var/log/openclaw/app.log
# Logs from specific date
grep "2026-01-30" /var/log/openclaw/app.log

# Logs from specific hour
grep "2026-01-30 14:" /var/log/openclaw/app.log

Log Formats​

Application Log Format​

[TIMESTAMP] [LEVEL] [COMPONENT] MESSAGE {metadata}

Example:

[2026-01-30 14:23:45] [INFO] [whatsapp] Message received from +1234567890 {msg_id: "ABC123", length: 45}
[2026-01-30 14:23:46] [INFO] [ai] Processing request {provider: "anthropic", model: "claude-3-5-sonnet"}
[2026-01-30 14:23:48] [INFO] [ai] Response generated {tokens: 234, time_ms: 1250}
[2026-01-30 14:23:48] [INFO] [whatsapp] Message sent {msg_id: "ABC123", response_id: "DEF456"}

Log Levels​

LevelMeaningAction
DEBUGDetailed debugging infoDevelopment only
INFONormal operationsInformational
WARNINGPotential issuesMonitor
ERRORFailures requiring attentionInvestigate
CRITICALSystem-breaking issuesImmediate action

Access Log Format​

IP - USER [TIMESTAMP] "METHOD PATH PROTOCOL" STATUS BYTES "REFERER" "USER_AGENT"

Example:

192.168.1.100 - admin [30/Jan/2026:14:23:45 +0000] "GET /api/status HTTP/2" 200 156 "-" "Mozilla/5.0..."

Common Log Patterns​

Successful Message Flow​

[14:23:45] [INFO] [whatsapp] Message received from +1234567890
[14:23:45] [INFO] [processor] Processing message {platform: "whatsapp"}
[14:23:46] [INFO] [ai] Sending to Anthropic {model: "claude-3-5-sonnet"}
[14:23:48] [INFO] [ai] Response received {tokens: 234, time: 1.8s}
[14:23:48] [INFO] [whatsapp] Sending response to +1234567890
[14:23:48] [INFO] [whatsapp] Message delivered successfully

Failed AI Request​

[14:23:45] [INFO] [ai] Sending to Anthropic
[14:23:46] [WARNING] [ai] Request timeout, retrying (1/3)
[14:23:48] [WARNING] [ai] Request timeout, retrying (2/3)
[14:23:50] [WARNING] [ai] Request timeout, retrying (3/3)
[14:23:52] [ERROR] [ai] All retries failed {error: "timeout", provider: "anthropic"}
[14:23:52] [ERROR] [processor] Failed to generate response for message ABC123

Authentication Failure​

[14:23:45] [WARNING] [auth] Failed login attempt {user: "admin", ip: "45.33.32.156"}
[14:23:50] [WARNING] [auth] Failed login attempt {user: "admin", ip: "45.33.32.156"}
[14:23:55] [WARNING] [auth] Failed login attempt {user: "admin", ip: "45.33.32.156"}
[14:23:55] [WARNING] [auth] Account locked due to failed attempts {user: "admin"}

WhatsApp Disconnection​

[14:23:45] [WARNING] [whatsapp] Connection lost
[14:23:46] [INFO] [whatsapp] Attempting reconnect (1/5)
[14:23:51] [INFO] [whatsapp] Attempting reconnect (2/5)
[14:23:56] [WARNING] [whatsapp] Reconnect failed, phone may be offline
[14:24:01] [ERROR] [whatsapp] All reconnect attempts failed

Log Analysis Tools​

Built-in Analysis​

# Summary of today's errors
clawbook-logs summary --period today

# Output:
# Log Summary (2026-01-30)
# ========================
# Total entries: 15,432
# INFO: 14,890 (96.5%)
# WARNING: 489 (3.2%)
# ERROR: 53 (0.3%)
#
# Top Errors:
# - API timeout: 23 occurrences
# - WhatsApp disconnection: 12 occurrences
# - Rate limit exceeded: 8 occurrences

Error Report​

# Generate error report
clawbook-logs errors --period 24h --output report.txt

# View unique errors
clawbook-logs errors --unique

Search by User​

# Find all activity for a user
clawbook-logs search --user "+1234567890" --period 7d

Log Rotation​

Default Configuration​

# /etc/logrotate.d/openclaw
/var/log/openclaw/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 openclaw openclaw
    postrotate
        systemctl reload openclaw
    endscript
}

Manual Rotation​

sudo logrotate -f /etc/logrotate.d/openclaw

Adjusting Retention​

Edit /etc/logrotate.d/openclaw:

rotate 14  # Keep 14 days instead of 7

Centralized Logging​

Export to External Service​

# /etc/openclaw/config.yaml
logging:
  external:
    enabled: true
    type: syslog
    host: logs.example.com
    port: 514

Supported Services​

  • Papertrail
  • Loggly
  • Datadog
  • ELK Stack
  • Graylog

Privacy Considerations​

What's Logged​

By default:

  • ✅ Timestamps
  • ✅ Log levels
  • ✅ User IDs (not names)
  • ✅ Message IDs
  • ✅ Response times
  • ❌ Message content
  • ❌ API keys
  • ❌ Passwords

Enabling Content Logging​

For debugging (use carefully):

# /etc/openclaw/config.yaml
logging:
  include_content: true  # ⚠️ Privacy risk

Disabling Content Logging​

logging:
  include_content: false  # Default
  redact_patterns:
    - "api_key"
    - "password"
    - "token"

Troubleshooting with Logs​

Debug Mode​

Enable verbose logging temporarily:

# Enable debug
clawbook-config set logging.level DEBUG
systemctl restart openclaw

# View debug output
tail -f /var/log/openclaw/app.log

# Remember to disable after
clawbook-config set logging.level INFO
systemctl restart openclaw

Correlating Logs​

Find related entries across logs:

# Get message ID from one log
grep "ABC123" /var/log/openclaw/whatsapp.log

# Find in all logs
grep -r "ABC123" /var/log/openclaw/

Creating Debug Bundle​

For support requests:

clawbook-logs export --period 24h --output debug-logs.tar.gz

# Includes:
# - Recent logs (sanitized)
# - System info
# - Configuration (no secrets)

Common Log Issues​

Log File Too Large​

# Check sizes
du -sh /var/log/openclaw/*

# Force rotation
sudo logrotate -f /etc/logrotate.d/openclaw

# Clear old rotated logs
rm /var/log/openclaw/*.gz

Missing Logs​

# Check permissions
ls -la /var/log/openclaw/

# Fix permissions
sudo chown -R openclaw:openclaw /var/log/openclaw/
sudo chmod 755 /var/log/openclaw/

Service Not Writing Logs​

# Check service status
systemctl status openclaw

# Check disk space
df -h /var/log

# Restart logging
systemctl restart rsyslog
systemctl restart openclaw

Next Steps​