Managing OpenClaw Logs and Debugging Output

Clawpedia · For Humans

Learn to read, filter, and analyze OpenClaw logs to diagnose issues and optimize agent performance.

Overview

Effective logging and debugging are essential for diagnosing issues with your OpenClaw agent quickly. This article covers log configuration, the different log levels, output formats, log rotation, and practical debugging techniques that will save you hours of troubleshooting.

Log Levels

OpenClaw uses five standard log levels, ordered from most to least verbose:

Setting the Log Level

# Via CLI
openclaw config set logging.level debug

# Via environment variable
export OPENCLAW_LOG_LEVEL=debug
openclaw start

# In config.yaml
logging:
  level: info

Tip: Use debug only during active troubleshooting. It generates significantly more output and can impact performance.

Log Output Destinations

Logs can be directed to multiple destinations simultaneously:

logging:
  level: info
  outputs:
    console:
      enabled: true
      format: pretty    # pretty | json | compact
      colors: true
    file:
      enabled: true
      path: ~/.openclaw/logs/agent.log
      format: json
      max_size: 50MB
      max_files: 10
    syslog:
      enabled: false
      address: localhost:514

Viewing Logs

Real-Time Streaming

# Stream all logs
openclaw logs --follow

# Stream only errors
openclaw logs --follow --level error

# Stream with grep filter
openclaw logs --follow --grep "skill:weather"

Historical Logs

# Last 100 entries
openclaw logs --last 100

# Logs from the last hour
openclaw logs --since 1h

# Logs from a specific time range
openclaw logs --since "2024-01-15 09:00" --until "2024-01-15 10:00"

# Export logs to a file
openclaw logs --since 24h --output debug-session.log

Understanding Log Output

A typical log entry in pretty format:

2024-01-15 09:32:14 [INFO]  agent.core     Agent started successfully (PID: 48291)
2024-01-15 09:32:14 [INFO]  skills.loader  Loaded 12 skills in 340ms
2024-01-15 09:32:15 [INFO]  platform.tg    Connected to Telegram (bot: @my_claw_bot)
2024-01-15 09:32:45 [DEBUG] model.openai   Request: {model: gpt-4o, tokens: 2340, temp: 0.7}
2024-01-15 09:32:47 [DEBUG] model.openai   Response: 1205 tokens in 1.8s ($0.0042)
2024-01-15 09:33:01 [WARN]  memory.store   Memory near capacity (89% used, 445/500 MB)
2024-01-15 09:35:22 [ERROR] skill.calendar Failed to sync: 401 Unauthorized

Log Entry Components

Log Rotation

Prevent logs from filling up your disk:

logging:
  file:
    path: ~/.openclaw/logs/agent.log
    max_size: 50MB       # Rotate when file exceeds this size
    max_files: 10        # Keep up to 10 rotated files
    max_age: 30d         # Delete files older than 30 days
    compress: true       # Gzip rotated files

Rotated files are named agent.log.1, agent.log.2, etc. With compress: true, they become agent.log.1.gz.

Module-Specific Logging

Enable debug logging for specific modules without flooding the log:

logging:
  level: info           # Default level
  modules:
    model: debug         # Debug AI model interactions
    skills: debug        # Debug skill execution
    memory: warn         # Only warnings for memory
    platform: info       # Normal platform logging

# CLI shorthand
openclaw config set logging.modules.model debug
openclaw config set logging.modules.skills debug

This is extremely useful when you know which subsystem is causing problems.

Debugging Techniques

1. The Doctor Command

Always start here. It checks all components automatically:

openclaw doctor --all

Output:

✅ Configuration:  Valid
✅ API Keys:       OpenAI (valid), Anthropic (valid)
✅ Model:          gpt-4o responding (latency: 230ms)
✅ Memory:         Healthy (445/500 MB)
✅ Skills:         12/12 loaded
⚠️ Platform:       Telegram connected, Slack disconnected
❌ Disk:           Log directory >1 GB — consider rotation

2. Dry-Run Mode

Test configuration changes without affecting the live agent:

openclaw start --dry-run

This validates the config, checks connections, and reports what would happen — without actually starting.

3. Request Tracing

Trace a single request through the entire pipeline:

openclaw ask "What's the weather?" --trace

Trace output shows every step:

[TRACE] Input received: "What's the weather?"
[TRACE] Memory lookup: 3 relevant entries found (12ms)
[TRACE] Skill match: weather-forecast (confidence: 0.94)
[TRACE] Skill execution: weather-forecast (started)
[TRACE] API call: wttr.in/Berlin (200 OK, 89ms)
[TRACE] Skill execution: weather-forecast (completed, 102ms)
[TRACE] Model request: gpt-4o (2140 tokens)
[TRACE] Model response: 380 tokens (1.2s, $0.0031)
[TRACE] Total pipeline: 1.4s

4. Skill Debugging

Run a specific skill in isolation:

# Test a skill directly
openclaw skills test weather-forecast --input "Weather in Berlin"

# Run with debug output
openclaw skills test weather-forecast --input "Weather in Berlin" --debug

5. Memory Inspection

# Search what the agent remembers
openclaw memory search "user preferences"

# View recent memory entries
openclaw memory recent --last 20

# Check memory statistics
openclaw memory stats

Common Log Patterns and Solutions

Structured Logging for Production

For production environments, use JSON logging for easy parsing:

logging:
  file:
    format: json

JSON log entries can be ingested by tools like Elasticsearch, Datadog, or Grafana Loki:

{
  "timestamp": "2024-01-15T09:32:47Z",
  "level": "info",
  "module": "model.openai",
  "message": "Request completed",
  "model": "gpt-4o",
  "tokens_in": 2340,
  "tokens_out": 1205,
  "latency_ms": 1800,
  "cost_usd": 0.0042
}

Troubleshooting

Logs Are Empty

• Check that the agent is running: openclaw status.
• Verify the log file path: openclaw config get logging.file.path.
• Ensure write permissions on the log directory.

Logs Are Too Verbose

Raise the log level: openclaw config set logging.level warn.

Log File Is Growing Too Fast

Enable rotation and set max_size and max_files as shown above. Also ensure debug level is not active in production.

Next Steps

• Learn more CLI commands in OpenClaw CLI: Essential Commands and Options.
• Explore skill debugging in Testing and Debugging OpenClaw Skills.
• Set up monitoring with OpenClaw for DevOps: Managing Servers and Services.