OpenClaw Log Configuration and Viewing Guide

Introduction

Logs are an essential tool for troubleshooting issues and monitoring runtime status. OpenClaw provides a flexible logging system that supports multiple log levels, output formats, and storage strategies. This article covers everything you need to know about configuring and using OpenClaw's logging capabilities.

Log Levels

OpenClaw supports four log levels, from most verbose to most concise:

Level	Description	Use Case
`debug`	Debug information, most verbose	Development, troubleshooting complex issues
`info`	General runtime information	Day-to-day monitoring (default level)
`warn`	Warning messages	Tracking potential issues
`error`	Error messages, most concise	Focusing solely on errors

Setting the Log Level

Via the configuration file:

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

Via the command line:

openclaw config set log.level "debug"
openclaw restart

Via environment variables:

export OPENCLAW_LOG_LEVEL="debug"
openclaw up

Output Examples by Level

debug level — Outputs all information, including request/response details:

[2026-03-22 10:30:15.123] [DEBUG] [gateway] Received message from WhatsApp: {from: "+8613800138000", body: "你好"}
[2026-03-22 10:30:15.125] [DEBUG] [model] Building Claude API request, tokens: 1250
[2026-03-22 10:30:15.126] [DEBUG] [model] Request headers: {x-api-key: "sk-ant-***", content-type: "application/json"}
[2026-03-22 10:30:16.890] [DEBUG] [model] Claude API response, duration: 1765ms, tokens: 320
[2026-03-22 10:30:16.892] [DEBUG] [gateway] Sending reply to WhatsApp: {to: "+8613800138000", length: 480}

info level — Outputs key runtime milestones:

[2026-03-22 10:30:15.123] [INFO] [gateway] Message received (WhatsApp)
[2026-03-22 10:30:16.890] [INFO] [model] Claude reply complete (1765ms, 320 tokens)
[2026-03-22 10:30:16.895] [INFO] [gateway] Reply sent (WhatsApp)

warn level — Outputs only situations that need attention:

[2026-03-22 10:30:15.500] [WARN] [model] API request rate approaching limit (85/100 RPM)
[2026-03-22 10:35:00.000] [WARN] [gateway] WhatsApp connection unstable, auto-reconnecting

error level — Outputs only errors:

[2026-03-22 10:30:15.500] [ERROR] [model] Claude API call failed: 401 Unauthorized
[2026-03-22 10:30:15.501] [ERROR] [model] Error details: Invalid API key provided

Log File Locations

Default Log Directory

OpenClaw log files are stored in the following default locations:

OS	Log Directory
Linux	`~/.local/share/openclaw/logs/`
macOS	`~/Library/Logs/openclaw/`
Windows	`%LOCALAPPDATA%\openclaw\logs\`

Log File Naming

Log files are named by date and type:

logs/
├── openclaw-2026-03-22.log        # Main log
├── openclaw-2026-03-21.log        # Previous day's log
├── openclaw-error-2026-03-22.log  # Error-only log
├── openclaw-access-2026-03-22.log # Access log
└── openclaw-2026-03-20.log.gz     # Compressed archived log

Custom Log Directory

You can change the log storage location:

// ~/.config/openclaw/openclaw.json5
{
  log: {
    level: "info",
    dir: "/var/log/openclaw"  // Custom log directory
  }
}

Make sure the OpenClaw process has write permissions to the directory:

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

Using the openclaw logs Command

openclaw logs is the built-in command for viewing logs, offering rich functionality and ease of use.

Basic Usage

# View recent logs (displays the last 50 lines by default)
openclaw logs

# Follow logs in real time (similar to tail -f)
openclaw logs -f

# Display the last 200 lines of logs
openclaw logs -n 200

Filtering by Level

# Show only error logs
openclaw logs --level error

# Show warnings and above
openclaw logs --level warn

# Show debug and above (all logs)
openclaw logs --level debug

Filtering by Time Range

# View today's logs
openclaw logs --since today

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

# View logs within a specific time range
openclaw logs --since "2026-03-22 10:00" --until "2026-03-22 12:00"

Filtering by Component

# View only gateway-related logs
openclaw logs --component gateway

# View only model invocation logs
openclaw logs --component model

# View logs for a specific channel
openclaw logs --component channel:whatsapp

Combined Filters

Multiple filter criteria can be combined:

# View today's WhatsApp channel error logs with real-time following
openclaw logs --level error --component channel:whatsapp --since today -f

Log Rotation

To prevent log files from growing indefinitely, OpenClaw includes a built-in log rotation mechanism.

Default Rotation Policy

{
  log: {
    rotation: {
      // Maximum size of a single log file
      maxSize: "50MB",
      // Number of days to retain log files
      maxAge: 30,
      // Maximum number of log files to keep
      maxFiles: 90,
      // Whether to compress archived logs
      compress: true
    }
  }
}

Rotation Policy Details

When a single log file exceeds maxSize, a new file is automatically created
Logs older than maxAge days are automatically deleted
When the total number of log files exceeds maxFiles, the oldest files are removed
When compress is enabled, archived logs are gzip-compressed to save disk space

Manual Log Cleanup

If you need to manually clean up log files:

# Check disk space used by log files
du -sh ~/.local/share/openclaw/logs/

# Delete logs older than 7 days
find ~/.local/share/openclaw/logs/ -name "*.log" -mtime +7 -delete

# Delete all compressed old logs
find ~/.local/share/openclaw/logs/ -name "*.gz" -delete

JSON Structured Logging

For scenarios that require log analysis tools (such as ELK or Grafana Loki), OpenClaw supports JSON-formatted output.

Enabling JSON Format

{
  log: {
    level: "info",
    format: "json"  // "text" (default) or "json"
  }
}

JSON Log Examples

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

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

Importing JSON Logs into Analysis Tools

Use Filebeat to ship logs to 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}"

Console Output Settings

In addition to file logging, you can control terminal output behavior:

{
  log: {
    level: "info",
    console: {
      enabled: true,       // Whether to output logs to the terminal
      colorize: true,      // Whether to colorize output
      timestamp: true      // Whether to show timestamps
    }
  }
}

When running with openclaw up -d (background mode), console output is automatically disabled.

Summary

Proper log configuration helps you quickly identify and locate issues. Here are the recommended configurations:

Development environment: Set log level to debug, use text format for easy real-time viewing
Production environment: Set log level to info, enable log rotation and compression
Cluster deployments: Use JSON format with log collection tools for centralized management
Troubleshooting: Temporarily switch to debug level and use openclaw logs -f for real-time monitoring

Remember to periodically check disk space usage to prevent oversized log files from affecting system performance.