clawdbot/docs/debugging.md

summary, read_when

summary	read_when
Debugging tools: watch mode, raw model streams, and tracing reasoning leakage	You need to inspect raw model output for reasoning leakage You want to run the Gateway in watch mode while iterating You need a repeatable debugging workflow

Debugging

This page covers debugging helpers for streaming output, especially when a provider mixes reasoning into normal text.

Runtime debug overrides

Use /debug in chat to set runtime-only config overrides (memory, not disk). /debug is disabled by default; enable with commands.debug: true. This is handy when you need to toggle obscure settings without editing moltbot.json.

Examples:

/debug show
/debug set messages.responsePrefix="[moltbot]"
/debug unset messages.responsePrefix
/debug reset

/debug reset clears all overrides and returns to the on-disk config.

Gateway watch mode

For fast iteration, run the gateway under the file watcher:

pnpm gateway:watch --force

This maps to:

tsx watch src/entry.ts gateway --force

Add any gateway CLI flags after gateway:watch and they will be passed through on each restart.

Dev profile + dev gateway (--dev)

Use the dev profile to isolate state and spin up a safe, disposable setup for debugging. There are two --dev flags:

• Global --dev (profile): isolates state under ~/.clawdbot-dev and defaults the gateway port to 19001 (derived ports shift with it).
• gateway --dev: tells the Gateway to auto-create a default config + workspace when missing (and skip BOOTSTRAP.md).

Recommended flow (dev profile + dev bootstrap):

pnpm gateway:dev
CLAWDBOT_PROFILE=dev moltbot tui

If you don’t have a global install yet, run the CLI via pnpm moltbot ....

What this does:

1. Profile isolation (global --dev)

   • CLAWDBOT_PROFILE=dev
   • CLAWDBOT_STATE_DIR=~/.clawdbot-dev
   • CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/moltbot.json
   • CLAWDBOT_GATEWAY_PORT=19001 (browser/canvas shift accordingly)

2. Dev bootstrap (gateway --dev)

   • Writes a minimal config if missing (gateway.mode=local, bind loopback).
   • Sets agent.workspace to the dev workspace.
   • Sets agent.skipBootstrap=true (no BOOTSTRAP.md).
   • Seeds the workspace files if missing: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
   • Default identity: C3‑PO (protocol droid).
   • Skips channel providers in dev mode (CLAWDBOT_SKIP_CHANNELS=1).

Reset flow (fresh start):

pnpm gateway:dev:reset

Note: --dev is a global profile flag and gets eaten by some runners. If you need to spell it out, use the env var form:

CLAWDBOT_PROFILE=dev moltbot gateway --dev --reset

--reset wipes config, credentials, sessions, and the dev workspace (using trash, not rm), then recreates the default dev setup.

Tip: if a non‑dev gateway is already running (launchd/systemd), stop it first:

moltbot gateway stop

Raw stream logging (Moltbot)

Moltbot can log the raw assistant stream before any filtering/formatting. This is the best way to see whether reasoning is arriving as plain text deltas (or as separate thinking blocks).

Enable it via CLI:

pnpm gateway:watch --force --raw-stream

Optional path override:

pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.clawdbot/logs/raw-stream.jsonl

Equivalent env vars:

CLAWDBOT_RAW_STREAM=1
CLAWDBOT_RAW_STREAM_PATH=~/.clawdbot/logs/raw-stream.jsonl

Default file:

~/.clawdbot/logs/raw-stream.jsonl

Raw chunk logging (pi-mono)

To capture raw OpenAI-compat chunks before they are parsed into blocks, pi-mono exposes a separate logger:

PI_RAW_STREAM=1

Optional path:

PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

Default file:

~/.pi-mono/logs/raw-openai-completions.jsonl

Note: this is only emitted by processes using pi-mono’s openai-completions provider.

Safety notes

• Raw stream logs can include full prompts, tool output, and user data.
• Keep logs local and delete them after debugging.
• If you share logs, scrub secrets and PII first.