clawdbot/docs/logging.md

summary, read_when

summary	read_when
Logging overview: file logs, console output, CLI tailing, and the Control UI	You need a beginner-friendly overview of logging You want to configure log levels or formats You are troubleshooting and need to find logs quickly

Logging

Clawdbot logs in two places:

• File logs (JSON lines) written by the Gateway.
• Console output shown in terminals and the Control UI.

This page explains where logs live, how to read them, and how to configure log levels and formats.

Where logs live

By default, the Gateway writes a rolling log file under:

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

You can override this in ~/.clawdbot/clawdbot.json:

{
  "logging": {
    "file": "/path/to/clawdbot.log"
  }
}

How to read logs

CLI: live tail (recommended)

Use the CLI to tail the gateway log file via RPC:

clawdbot logs --follow

Output modes:

• TTY sessions: pretty, colorized, structured log lines.
• Non-TTY sessions: plain text.
• --json: line-delimited JSON (one log event per line).
• --plain: force plain text in TTY sessions.
• --no-color: disable ANSI colors.

In JSON mode, the CLI emits type-tagged objects:

• meta: stream metadata (file, cursor, size)
• log: parsed log entry
• notice: truncation / rotation hints
• raw: unparsed log line

If the Gateway is unreachable, the CLI prints a short hint to run:

clawdbot doctor

Control UI (web)

The Control UI’s Logs tab tails the same file using logs.tail. See /web/control-ui for how to open it.

Channel-only logs

To filter channel activity (WhatsApp/Telegram/etc), use:

clawdbot channels logs --channel whatsapp

Log formats

File logs (JSONL)

Each line in the log file is a JSON object. The CLI and Control UI parse these entries to render structured output (time, level, subsystem, message).

Console output

Console logs are TTY-aware and formatted for readability:

• Subsystem prefixes (e.g. gateway/channels/whatsapp)
• Level coloring (info/warn/error)
• Optional compact or JSON mode

Console formatting is controlled by logging.consoleStyle.

Configuring logging

All logging configuration lives under logging in ~/.clawdbot/clawdbot.json.

{
  "logging": {
    "level": "info",
    "file": "/tmp/clawdbot/clawdbot-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": [
      "sk-.*"
    ]
  }
}

Log levels

• logging.level: file logs (JSONL) level.
• logging.consoleLevel: console verbosity level.

--verbose only affects console output; it does not change file log levels.

Console styles

logging.consoleStyle:

• pretty: human-friendly, colored, with timestamps.
• compact: tighter output (best for long sessions).
• json: JSON per line (for log processors).

Redaction

Tool summaries can redact sensitive tokens before they hit the console:

• logging.redactSensitive: off | tools (default: tools)
• logging.redactPatterns: list of regex strings to override the default set

Redaction affects console output only and does not alter file logs.

Diagnostics + OpenTelemetry

Diagnostics are opt-in structured events for model runs (usage + cost + context + duration). They do not replace logs; they exist to feed metrics, traces, and other exporters.

Clawdbot currently emits a model.usage event after each agent run with:

• Token counts (input/output/cache/prompt/total)
• Estimated cost (USD)
• Context window used/limit
• Duration (ms)
• Provider/channel/model + session identifiers

Enable diagnostics (no exporter)

Use this if you want diagnostics events available to plugins or custom sinks:

{
  "diagnostics": {
    "enabled": true
  }
}

Export to OpenTelemetry

Diagnostics can be exported via the diagnostics-otel plugin (OTLP/HTTP). This works with any OpenTelemetry collector/backend that accepts OTLP/HTTP.

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "clawdbot-gateway",
      "traces": true,
      "metrics": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

Notes:

• You can also enable the plugin with clawdbot plugins enable diagnostics-otel.
• protocol currently supports http/protobuf.
• Metrics include token usage, cost, context size, and run duration.
• Traces/metrics can be toggled with traces / metrics (default: on).
• Set headers when your collector requires auth.
• Environment variables supported: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

Troubleshooting tips

• Gateway not reachable? Run clawdbot doctor first.
• Logs empty? Check that the Gateway is running and writing to the file path in logging.file.
• Need more detail? Set logging.level to debug or trace and retry.