Debugging Agent Workflows with Logs in OpenClaw

When your agent isn't behaving, logs are your first and most reliable tool. OpenClaw provides comprehensive logging to help you trace agent behavior, diagnose issues, and understand system state. This guide shows you where to find logs and how to use them effectively.

Finding Your Logs

OpenClaw writes logs to a rolling file on your Gateway host machine. By default, this is:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

The filename includes the current date in the system's timezone. You can customize this path by setting logging.file in your ~/.openclaw/openclaw.json config.

For Mac users, app-level logging also goes to ~/Library/Logs/OpenClaw/diagnostics.jsonl, which you can enable in the Debug pane.

Reading Logs via CLI

The easiest way to inspect logs is via the openclaw logs CLI command. This connects to your Gateway and streams the log file.

Tail the log continuously:

openclaw logs --follow

This shows colorized output in a terminal. For structured data processing, use JSON mode:

openclaw logs --follow --json

Each line in JSON mode is a structured event:

• meta: Stream info (file, cursor)
• log: A parsed log entry
• raw: An unparsed line
• notice: Rotation/truncation events

Filter for specific channels (like WhatsApp):

openclaw channels logs --channel whatsapp --follow

Using the Control UI

If you prefer a web interface, OpenClaw's Control UI has a dedicated Logs tab. It uses the same underlying logs.tail RPC to stream the log file from your Gateway, providing a clean, scrollable view in your browser.

Configuring Log Levels

Control the verbosity of your logs with the logging.level setting in ~/.openclaw/openclaw.json. Options are error, warn, info, debug, and trace.

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log"
  }
}

The CLI's --verbose flag only affects what is printed locally—it does not change the file log level.

You can also configure console output separately with logging.consoleLevel and logging.consoleStyle (pretty, compact, json).

Enabling Diagnostic Flags

For targeted debugging, use diagnostic flags. These let you enable verbose logging for specific subsystems without raising the global log level.

Enable HTTP debugging for the WhatsApp channel:

{
  "diagnostics": {
    "flags": ["whatsapp.http"]
  }
}

Flags are case-insensitive and support wildcards (e.g., whatsapp.*). They output to the standard log file and respect your configured redaction settings.

Troubleshooting Tips

• Gateway unreachable? Run openclaw doctor first.
• Logs empty? Verify the Gateway is running and writing to the correct logging.file path.
• Need more detail? Set logging.level to debug or trace.
• Sensitive data in logs? Use logging.redactSensitive and logging.redactPatterns to mask tokens.
• Message flow issues? Check the diagnostic events webhook.received, message.queued, and message.processed.

Logs are your window into OpenClaw's operation. Use them to move from guesswork to confident system understanding.