OpenClaw Debugging — Watch Mode, Raw Streams, and Dev Profiles

OpenClaw Debugging

When something breaks, you need to see what’s actually happening—not what should be happening. These debugging tools let you inspect raw model output, run fast iteration loops, and isolate your dev environment from production.

---

Runtime Debug Overrides

Use /debug in chat to set config overrides without editing files:

/debug show                                    # View current overrides
/debug set messages.responsePrefix="[test]"    # Set a value
/debug unset messages.responsePrefix           # Remove override
/debug reset                                   # Clear all overrides

Note: Enable with commands.debug: true in config. These are memory-only—they don’t persist.

---

Gateway Watch Mode

For fast iteration, run the Gateway with file watching:

pnpm gateway:watch --force

This restarts the Gateway automatically when you save files. Same as:

tsx watch src/entry.ts gateway --force

---

Dev Profile (Isolated State)

Use a dev profile to isolate your debugging from production state:

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

What dev profile does:

• State directory: ~/.openclaw-dev
• Gateway port: 19001
• Skips BOOTSTRAP.md
• Creates a minimal default config
• Default identity: C3-PO (protocol droid)
• Skips channel providers

Fresh start:

pnpm gateway:dev:reset

This wipes dev config, credentials, and sessions (uses trash, not rm).

---

Raw Stream Logging

See exactly what the model returns before any filtering:

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

Default file:

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

Custom path:

pnpm gateway:watch --force --raw-stream --raw-stream-path /custom/path.jsonl

Environment variables:

OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

This is the best way to see if reasoning content is leaking into regular text output.

---

Raw Chunk Logging (pi-mono)

To capture OpenAI-compatible chunks before parsing:

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

---

Environment Variable Reference

Variable	Description
OPENCLAW_PROFILE=dev	Use dev profile
OPENCLAW_STATE_DIR=~/.openclaw-dev	Override state directory
OPENCLAW_GATEWAY_PORT=19001	Override gateway port
OPENCLAW_RAW_STREAM=1	Enable raw stream logging
OPENCLAW_SKIP_CHANNELS=1	Skip channel providers

---

Safety Notes

• Raw stream logs can include prompts, tool output, and user data
• Keep logs local and delete after debugging
• Scrub secrets and PII before sharing

Still stuck? Our AI Setup Assistant can help debug your setup.

---

What’s Next?

• Logging → — File logs and console output
• Testing → — Test suites and live testing
• Gateway Configuration → — Full config reference

---

Need help? Join the OpenClaw Discord or check the GitHub Issues.