coderClaw

Logging

CoderClaw (built on CoderClaw) logs in two places:

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/coderclaw/coderclaw-YYYY-MM-DD.log

The date uses the gateway host’s local timezone.

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

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

How to read logs

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

coderclaw logs --follow

Output modes:

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

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

coderclaw 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:

coderclaw 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:

Console formatting is controlled by logging.consoleStyle.

Configuring logging

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

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

Log levels

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

Console styles

logging.consoleStyle:

Redaction

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

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

Diagnostics + OpenTelemetry

Diagnostics are structured, machine-readable events for model runs and message-flow telemetry (webhooks, queueing, session state). They do not replace logs; they exist to feed metrics, traces, and other exporters.

Diagnostics events are emitted in-process, but exporters only attach when diagnostics + the exporter plugin are enabled.

OpenTelemetry vs OTLP

Signals exported

Diagnostic event catalog

Model usage:

Message flow:

Queue + session:

Enable diagnostics (no exporter)

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

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

Diagnostics flags (targeted logs)

Use flags to turn on extra, targeted debug logs without raising logging.level. Flags are case-insensitive and support wildcards (e.g. telegram.* or *).

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

Env override (one-off):

CODERCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Notes:

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": "coderclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

Notes:

Exported metrics (names + types)

Model usage:

Message flow:

Queues + sessions:

Exported spans (names + key attributes)

Sampling + flushing

Protocol notes

Log export behavior

Troubleshooting tips

This site is open source. Improve this page.