OpenClaw Logs Command: Read, Filter & Debug Gateway Logs

Q: How do I tail OpenClaw logs in real time?

Run: openclaw logs --follow (or -f). This streams new log entries to your terminal as they're written, identical to tail -f. Press Ctrl+C to stop. Add --level error to see only errors while following, reducing noise from routine info messages.

Q: How do I filter OpenClaw logs by channel?

Use the --channel flag: openclaw logs --channel telegram. This shows only log entries tagged with that channel identifier. Combine with --follow to watch a specific channel's activity in real time. Channel names match the IDs registered in your gateway.yaml.

Q: Where are OpenClaw log files stored on disk?

OpenClaw writes logs to ~/.openclaw/logs/ by default on Linux and macOS, and %APPDATA%\openclaw\logs\ on Windows. The log directory is configurable via the log_dir key in gateway.yaml. Each day gets its own file: openclaw-2025-01-28.log.

Q: How do I set the log level for OpenClaw?

Set log_level in gateway.yaml: options are debug, info, warn, and error. debug is very verbose and useful for development. info is the recommended production level. warn and error reduce noise significantly but may miss useful context when debugging.

Q: Can I export OpenClaw logs to a file?

Yes. Pipe the output: openclaw logs --since 24h > openclaw-export.log. Or use --output json for structured JSON output: openclaw logs --output json > logs.json. JSON format is useful for ingesting into log aggregation systems like Elasticsearch or Datadog.

Q: How do I search for specific errors in OpenClaw logs?

Pipe through grep: openclaw logs --since 1h | grep ERROR. Or use the built-in --grep flag if available: openclaw logs --grep 'connection refused'. The --since flag limits the time window so grep processes a manageable amount of data rather than the full log history.

Key Takeaways

openclaw logs --follow streams live log output — identical to tail -f on the log file.

Filter by channel with --channel [name], by level with --level [debug|info|warn|error], and by time with --since [duration].

Use --output json for structured output suitable for log aggregation pipelines.

Log files are stored in ~/.openclaw/logs/ by default, one file per day.

Set log_level: debug in gateway.yaml temporarily when debugging — switch back to info in production.

The difference between a 5-minute fix and a 2-hour debug session is usually whether you knew how to read the logs. Every dropped message, failed channel connection, and LLM API error leaves a trace in OpenClaw's gateway logs. The openclaw logs command surfaces that trace without requiring you to find and manually open the log file.

Basic Usage

The simplest invocation shows the most recent log entries:

openclaw logs

By default this shows the last 50 lines. To follow logs in real time:

openclaw logs --follow
# shorthand:
openclaw logs -f

To show more historical entries:

openclaw logs --lines 200
# or show everything from the last hour:
openclaw logs --since 1h

Time duration formats accepted by --since: 30m, 2h, 24h, 7d. This covers most debugging scenarios without needing to specify exact timestamps.

All Flags Reference

Flag	Shorthand	Description
`--follow`	`-f`	Stream new log entries in real time
`--lines N`	`-n N`	Show last N lines (default: 50)
`--since DURATION`	—	Show logs from last N minutes/hours/days
`--level LEVEL`	`-l LEVEL`	Filter by log level (debug/info/warn/error)
`--channel NAME`	`-c NAME`	Filter to a specific channel
`--output FORMAT`	`-o FORMAT`	Output format: text (default) or json
`--config PATH`	—	Path to gateway.yaml (uses default if omitted)

Filtering Logs Effectively

The most useful filtering combination for debugging a specific channel issue:

openclaw logs --channel telegram --level error --follow

This streams only error-level entries from the Telegram channel. You see exactly what's going wrong without the noise of info-level messages from other channels.

For a post-incident review of the last 24 hours:

openclaw logs --since 24h --level warn

This surfaces all warnings and errors from the past day — useful for catching intermittent issues that aren't causing outright failures yet.

💡

Combine with grep for Pattern Search

Pipe the output to grep for pattern matching: openclaw logs --since 1h | grep "connection refused". This finds specific error strings without needing to open the log file in a text editor. Works with any grep expression including regex.

Understanding Log Levels

OpenClaw uses four log levels. Knowing what each produces helps you choose the right level for your situation:

debug — everything: request/response bodies, internal state changes, timing data. Very verbose. Use only when actively debugging a specific issue.
info — normal operation events: channel connections, message received/sent confirmations, skill executions. Recommended for production.
warn — conditions that aren't errors but indicate something worth watching: slow LLM responses, retried requests, approaching rate limits.
error — failures: channel disconnections, LLM API errors, failed skill executions, unhandled exceptions. Always investigate errors immediately.

Set the level in gateway.yaml:

log_level: info  # debug | info | warn | error

The --level flag on the CLI filters what's displayed from existing logs — it doesn't change what OpenClaw writes. To change what gets written, update gateway.yaml and restart the gateway.

Exporting Logs

Export logs to a file for sharing or archival:

# Plain text export
openclaw logs --since 7d > openclaw-week.log

# JSON export for log aggregation
openclaw logs --since 7d --output json > openclaw-week.json

JSON format includes structured fields that plain text doesn't — timestamp as ISO 8601, channel ID, log level as a machine-readable field, and message as a separate key. This makes JSON the right choice for ingesting into Elasticsearch, Datadog, Splunk, or any other log aggregation platform.

⚠️

Logs May Contain Sensitive Data

At debug level, OpenClaw logs request and response bodies including message content. Before sharing log exports externally, review for sensitive information: API keys (should be masked), user message content, LLM responses. Use --level info for exports you'll share with others.

Log File Location

OpenClaw writes log files to disk even when you're not running the logs command. Default locations:

Linux/macOS: ~/.openclaw/logs/openclaw-YYYY-MM-DD.log
Windows: %APPDATA%\openclaw\logs\openclaw-YYYY-MM-DD.log
Custom: set log_dir: /your/path in gateway.yaml

Log files rotate daily. Old files are not automatically deleted — if disk space is a concern, set up logrotate or a cron job to clean files older than 30 days.

Common Mistakes

Running at debug level in production — generates enormous log files quickly and may expose sensitive data; use info level for production
Not using --since to bound the query — without it, --lines 50 may show entries from days ago; always add --since when debugging recent issues
Forgetting to restart after changing log_level — the gateway reads gateway.yaml at startup; level changes don't apply without a restart
Exporting logs without checking for sensitive content — debug-level exports contain full message content; review before sharing

Frequently Asked Questions

How do I tail OpenClaw logs in real time?

Run: openclaw logs --follow (or -f). This streams new log entries to your terminal as they're written, identical to tail -f. Press Ctrl+C to stop. Add --level error to see only errors while following, reducing noise from routine info messages.

How do I filter OpenClaw logs by channel?

Use the --channel flag: openclaw logs --channel telegram. This shows only log entries tagged with that channel identifier. Combine with --follow to watch a specific channel's activity in real time. Channel names match the IDs registered in your gateway.yaml.

Where are OpenClaw log files stored on disk?

OpenClaw writes logs to ~/.openclaw/logs/ by default on Linux and macOS, and %APPDATA%\openclaw\logs\ on Windows. The log directory is configurable via the log_dir key in gateway.yaml. Each day gets its own file: openclaw-2025-01-28.log.

How do I set the log level for OpenClaw?

Set log_level in gateway.yaml: options are debug, info, warn, and error. debug is very verbose and useful for development. info is the recommended production level. warn and error reduce noise significantly but may miss useful context when debugging.

Can I export OpenClaw logs to a file?

Yes. Pipe the output: openclaw logs --since 24h > openclaw-export.log. Or use --output json for structured JSON output: openclaw logs --output json > logs.json. JSON format is useful for ingesting into log aggregation systems like Elasticsearch or Datadog.

How do I search for specific errors in OpenClaw logs?

Pipe through grep: openclaw logs --since 1h | grep ERROR. Or use the built-in --grep flag if available: openclaw logs --grep 'connection refused'. The --since flag limits the time window so grep processes a manageable amount of data rather than the full log history.

J. Donovan

Technical Writer

J. Donovan writes the official CLI reference documentation for the OpenClaw project and has debugged hundreds of gateway configurations across production deployments. Specializes in making complex diagnostic workflows accessible to builders at every experience level.