How to Debug OpenClaw Without Losing Your Mind

Debugging streaming output is a headache. You see text appearing, but you don’t know if the provider is sending reasoning blocks or just plain text. It feels like poking a black box until something works, and usually, that involves a lot of trial and error that wastes time.

I find it much easier to peek under the hood using the built-in debug tools. Whether you need to toggle a setting on the fly or see the raw JSON chunks coming from an API, these methods help you see exactly what is happening.

What You’ll Need

OpenClaw installed and configured.
pnpm for running gateway scripts.
A terminal to run the TUI or CLI.

Quick Start

The fastest way to debug is to use a fresh, isolated environment. I recommend the dev profile because it won’t mess up your main configuration.

Start the dev gateway:
Terminal window
```
pnpm gateway:dev
```
Launch the TUI with the dev profile:
Terminal window
```
OPENCLAW_PROFILE=dev openclaw tui
```

This sets up a protocol droid named C3-PO in a safe workspace at ~/.openclaw-dev. It uses port 19001 so it won’t clash with your normal setup.

Runtime Debug Overrides

Sometimes you just want to test a setting without opening openclaw.json. I use the /debug command in chat for this. It only changes things in memory, so your disk config stays clean.

First, make sure you enable it by setting commands.debug: true. Then you can use these in chat:

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

The /debug reset command is my favorite because it clears everything and takes you back to your original on-disk configuration.

Gateway Watch Mode

For fast iteration, I run the gateway under the file watcher. It automatically restarts whenever you change the code.

pnpm gateway:watch --force

If you need to pass specific flags, just add them at the end. They will stick around every time the gateway restarts.

Raw Stream Logging

When you need to see if reasoning is arriving as plain text or separate blocks, you need the raw logs. OpenClaw can save the assistant stream before any filtering happens.

To enable this via the CLI:

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

If you want to save it somewhere specific, use the path flag:

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

If you are using the pi-mono provider, you can also capture the OpenAI-compatible chunks before they are parsed:

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

Safety Note: These logs contain full prompts and tool outputs. I suggest keeping them local and deleting them once you finish debugging. Scrub any secrets before sharing them.

Troubleshooting

Gateway won’t start: If a non-dev gateway is already running (via launchd or systemd), you need to stop it first using openclaw gateway stop.
Flags are ignored: Some runners eat the --dev flag. If that happens, use the environment variable form: OPENCLAW_PROFILE=dev openclaw gateway --dev --reset.
Wipe and restart: If things are totally broken, pnpm gateway:dev:reset wipes the dev workspace and starts fresh.
Resetting overrides: If your chat behavior gets weird after using /debug, run /debug reset to clear the memory.

Still stuck? Ask the AI Setup Assistant for help.

What’s Next

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.