Logging

Scope

This page is an operator view of Clawdbot logging: where logs go, how to tail them, and what knobs matter when debugging.

For a user-facing overview (CLI + Control UI), see /en/docs/logging/.

Two log surfaces

Console output: what you see in the terminal (TTY-aware, formatted).
File logs: JSONL records written by the gateway logger (best for support/forensics).

File logs (default)

By default, the gateway writes one rolling log file per day under /tmp/clawdbot/:

clawdbot-YYYY-MM-DD.log

Config keys (in ~/.clawdbot/clawdbot.json):

logging.file
logging.level

Tail logs:

clawdbot logs --follow

`--verbose` vs `logging.level`

--verbose increases console verbosity (and WS protocol logging style).
File log detail is controlled by logging.level (set to debug/trace if you need deep details in files).

Console capture (CLI)

The CLI can capture console.* from the running process and mirror it into file logs while still printing to stdout/stderr.

Common knobs:

logging.consoleLevel (console-only verbosity)
logging.consoleStyle (pretty | compact | json)

Redaction (tool summaries)

Verbose tool summaries can redact sensitive strings before they hit the terminal stream:

logging.redactSensitive (off | tools)
logging.redactPatterns (custom regex list)

This is a console UX feature; it does not rewrite historical file logs.

Gateway WebSocket protocol logs

The gateway prints WS protocol logs in two practical modes:

normal: show errors / slow calls / parse failures
verbose: show all request/response traffic

Examples:

clawdbot gateway                 # optimized output
clawdbot gateway --verbose       # show all WS traffic
clawdbot gateway --verbose --ws-log compact
clawdbot gateway --verbose --ws-log full

What to collect for a bug report

clawdbot status --json (or clawdbot gateway status --json)
last ~200 lines from clawdbot logs around the failure
exact command you ran (including --dev / --profile)