Mastering OpenClaw Logs: From Console to Files

I have spent way too many hours staring at a terminal trying to figure out why a request failed, only to realize the information I needed was buried in a messy file or suppressed by a default setting. It is a common headache for any developer: you either get a wall of text that is impossible to parse, or you get nothing at all.

Getting your logging right means you can stop guessing and start fixing. I want to show you how OpenClaw handles logs across the console and file system so you can find exactly what you are looking for without the noise.

What You’ll Need

Before you start tweaking your log settings, make sure you have these two things ready:

• A running OpenClaw gateway instance.
• Access to the ~/.openclaw/openclaw.json configuration file on your host.

Quick Start

You can get a handle on your logs in about five minutes by following these four steps:

1. View live logs: Run the CLI command openclaw logs --follow to tail the gateway logs directly in your terminal.
2. Locate the log files: OpenClaw writes JSON lines to /tmp/openclaw/. Look for files named openclaw-YYYY-MM-DD.log.
3. Adjust console verbosity: If you need more detail in your terminal, use the --verbose flag when starting the gateway.
4. Check the Control UI: Open the Logs tab in the Control UI to see a real-time feed powered by the same file-tailing logic.

How Logging Works

OpenClaw uses two different “surfaces” for logs. Understanding the difference between them will save you a lot of confusion.

File-based Logs

The gateway writes structured JSON logs to your disk. By default, these are stored in /tmp/openclaw/ and roll over every day based on your local timezone. You can change the path or the log level by editing ~/.openclaw/openclaw.json:

{
  "logging": {
    "file": "/your/custom/path.log",
    "level": "info"
  }
}

Console Output

The console is what you see in your terminal. It is designed to be readable, using colors and subsystem prefixes like [gateway] or [canvas]. It captures everything from console.log to console.error.

You can change how this looks using logging.consoleStyle with options like pretty, compact, or json.

Managing WebSocket Traffic

If you are debugging the gateway specifically, you might want to see the WebSocket protocol logs. You have a few ways to run the gateway depending on how much data you want:

# Only shows errors and slow calls (>= 50ms)
openclaw gateway

# Shows all WebSocket traffic in a paired format
openclaw gateway --verbose --ws-log compact

# Shows full metadata for every frame
openclaw gateway --verbose --ws-log full

# Shortcut for compact mode
openclaw gateway --compact

Sensitive Data Redaction

I recommend keeping logging.redactSensitive set to tools (which is the default). This masks sensitive tokens in the console output so they do not show up in your terminal history or screen shares. It keeps the first 6 and last 4 characters of a string if it is long enough, otherwise it uses ***.

Note that this only affects the console; your file logs will still contain the full data for debugging purposes.

Troubleshooting

I added --verbose but my log files didn’t change. The --verbose flag only changes what you see in the terminal. If you want more detail in your JSON log files, you must set logging.level to debug or trace in your openclaw.json file.

I can’t see WhatsApp message bodies in the console. WhatsApp message bodies are logged at the debug level. To see them in your terminal, you need to use the --verbose flag.

If you hit a wall or need help with a specific configuration, check out the AI Setup Assistant.

What’s Next

• CLI Reference
• Configuration Guide