Skip to main content

​
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 velaclaw.json. Examples:
/debug reset clears all overrides and returns to the on-disk config.

​
Session trace output

Use /trace when you want to see plugin-owned trace/debug lines in one session without turning on full verbose mode. Examples:
Use /trace for plugin diagnostics such as Active Memory debug summaries. Keep using /verbose for normal verbose status/tool output, and keep using /debug for runtime-only config overrides.

​
Gateway watch mode

For fast iteration, run the gateway under the file watcher:
This maps to:
The watcher restarts on build-relevant files under src/, extension source files, extension package.json and velaclaw.plugin.json metadata, tsconfig.json, package.json, and tsdown.config.ts. Extension metadata changes restart the gateway without forcing a tsdown rebuild; source and config changes still rebuild dist first. Add any gateway CLI flags after gateway:watch and they will be passed through on each restart. Re-running the same watch command for the same repo/flag set now replaces the older watcher instead of leaving duplicate watcher parents behind.

​
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 ~/.velaclaw-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):
If you don’t have a global install yet, run the CLI via pnpm velaclaw .... What this does:
  1. Profile isolation (global --dev)
    • VELACLAW_PROFILE=dev
    • VELACLAW_STATE_DIR=~/.velaclaw-dev
    • VELACLAW_CONFIG_PATH=~/.velaclaw-dev/velaclaw.json
    • VELACLAW_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 (VELACLAW_SKIP_CHANNELS=1).
Reset flow (fresh start):
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:
--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:

​
Raw stream logging (Velaclaw)

Velaclaw 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:
Optional path override:
Equivalent env vars:
Default file: ~/.velaclaw/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:
Optional path:
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.