Skip to main content

​
openclaw logs

View and follow OpenClaw Gateway logs in real-time.

​
Usage

openclaw logs [options]

​
Options

​
--limit <n>
number
Maximum lines to return per fetch (default: 200)
​
--max-bytes <n>
number
Maximum bytes to read per fetch (default: 250000)
​
--follow
boolean
Follow log output continuously (like tail -f)
​
--interval <ms>
number
Polling interval in milliseconds when following (default: 1000)
​
--json
boolean
Output structured JSON log lines
​
--plain
boolean
Plain text output without ANSI styling
​
--no-color
boolean
Disable ANSI colors
​
--local-time
boolean
Display timestamps in local timezone instead of UTC
​
--url <url>
string
Gateway WebSocket URL (overrides config)
​
--token <token>
string
Gateway authentication token
​
--timeout <ms>
number
RPC timeout in milliseconds

​
Examples

# View recent logs
openclaw logs

# View last 500 lines
openclaw logs --limit 500

# Follow logs in real-time
openclaw logs --follow

​
Log Format

​
Pretty Format (Default)

When connected to a TTY, logs are formatted for readability: 
12:34:56 info  gateway   Starting WebSocket server
12:34:57 info  telegram  Connected to Telegram API
12:34:58 warn  agent     High token usage detected
12:34:59 error discord   Failed to send message
Format: TIME LEVEL MODULE MESSAGE

​
Plain Format

With --plain or when piped: 
2026-02-19T12:34:56.789Z info gateway Starting WebSocket server
2026-02-19T12:34:57.123Z info telegram Connected to Telegram API

​
JSON Format

With --json: 
{"type":"log","time":"2026-02-19T12:34:56.789Z","level":"info","subsystem":"gateway","message":"Starting WebSocket server"}
{"type":"log","time":"2026-02-19T12:34:57.123Z","level":"info","subsystem":"telegram","message":"Connected to Telegram API"}

​
Log Levels

Logs are categorized by severity:
  • trace: Detailed debug information
  • debug: Debug messages
  • info: Informational messages (default)
  • warn: Warning messages
  • error: Error messages
  • fatal: Fatal errors

​
Level Colors

In pretty mode, levels are color-coded:
  • error/fatal: Red
  • warn: Yellow
  • info: Cyan
  • debug/trace: Gray

​
Following Logs

Use --follow to continuously monitor logs: 
openclaw logs --follow
This behaves like tail -f, polling the gateway every second (configurable with --interval). To stop following, press Ctrl+C.

​
Remote Gateway

To view logs from a remote gateway: 
# Direct connection
openclaw logs --url ws://remote-host:18789 --token mytoken

# Via SSH tunnel (set up tunnel first)
ssh -L 18789:localhost:18789 user@remote-host
openclaw logs

​
Log Rotation

The gateway rotates log files automatically:
  • Maximum file size: 10 MB
  • Keeps 5 rotated files
  • Rotated files: gateway.log.1, gateway.log.2, etc.
When rotation occurs, the logs command:
  1. Detects the rotation
  2. Resets the cursor
  3. Continues from the new file

​
Structured Logging

Logs include structured metadata: 
{
  "time": "2026-02-19T12:34:56.789Z",
  "level": "info",
  "subsystem": "gateway",
  "module": "websocket",
  "message": "Client connected",
  "clientId": "abc123",
  "remoteAddress": "127.0.0.1"
}
Use --json to process structured logs with tools like jq: 
# Extract all error messages
openclaw logs --json | jq -r 'select(.level=="error") | .message'

# Count log entries by level
openclaw logs --json | jq -r '.level' | sort | uniq -c

# Filter by subsystem
openclaw logs --json | jq 'select(.subsystem=="telegram")'

​
Performance

The logs command:
  • Fetches logs via Gateway RPC (requires running gateway)
  • Uses cursor-based pagination for efficiency
  • Streams output to avoid buffering
  • Handles backpressure from slow terminals

​
Limits

  • —limit: Controls lines per fetch (affects latency)
  • —max-bytes: Prevents excessive memory usage
  • —interval: Controls polling frequency when following
For high-throughput scenarios: 
# More frequent updates
openclaw logs --follow --interval 250 --limit 500

​
Troubleshooting

​
Gateway Not Reachable

If logs fail to connect: 
Gateway not reachable. Is it running and accessible?
  1. Check gateway status: 
    openclaw gateway status
  2. Verify gateway is running: 
    openclaw daemon status
  3. Check authentication: 
    openclaw config get gateway.auth
  4. Run diagnostics: 
    openclaw doctor

​
Log Truncation

If you see “Log tail truncated”: 
# Increase max bytes
openclaw logs --max-bytes 500000

​
Broken Pipe

If piping to a command that exits early (like head): 
openclaw logs --plain | head -100
# openclaw logs: output stdout closed (EPIPE). Stopping tail.
This is expected behavior when the pipe consumer closes.

​
Alternative Log Access

​
Direct File Access

Logs are stored in: 
~/.openclaw/logs/gateway.log
You can read them directly: 
tail -f ~/.openclaw/logs/gateway.log

​
Platform-Specific Logs

​
macOS (Unified Logs)

log show --predicate 'subsystem == "ai.openclaw"' --last 1h
log stream --predicate 'subsystem == "ai.openclaw"'

​
Linux (systemd Journal)

journalctl --user -u openclaw-gateway -f
journalctl --user -u openclaw-gateway --since "1 hour ago"

​
Channel-Specific Logs

For channel-specific logs: 
openclaw channels logs --channel telegram