{
  "title": "Debugging",
  "content": "This page covers debugging helpers for streaming output, especially when a\nprovider mixes reasoning into normal text.\n\n## Runtime debug overrides\n\nUse `/debug` in chat to set **runtime-only** config overrides (memory, not disk).\n`/debug` is disabled by default; enable with `commands.debug: true`.\nThis is handy when you need to toggle obscure settings without editing `openclaw.json`.\n\n`/debug reset` clears all overrides and returns to the on-disk config.\n\n## Gateway watch mode\n\nFor fast iteration, run the gateway under the file watcher:\n\nAdd any gateway CLI flags after `gateway:watch` and they will be passed through\non each restart.\n\n## Dev profile + dev gateway (--dev)\n\nUse the dev profile to isolate state and spin up a safe, disposable setup for\ndebugging. There are **two** `--dev` flags:\n\n* **Global `--dev` (profile):** isolates state under `~/.openclaw-dev` and\n  defaults the gateway port to `19001` (derived ports shift with it).\n* **`gateway --dev`: tells the Gateway to auto-create a default config +\n  workspace** when missing (and skip BOOTSTRAP.md).\n\nRecommended flow (dev profile + dev bootstrap):\n\nIf you don’t have a global install yet, run the CLI via `pnpm openclaw ...`.\n\n1. **Profile isolation** (global `--dev`)\n   * `OPENCLAW_PROFILE=dev`\n   * `OPENCLAW_STATE_DIR=~/.openclaw-dev`\n   * `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`\n   * `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas shift accordingly)\n\n2. **Dev bootstrap** (`gateway --dev`)\n   * Writes a minimal config if missing (`gateway.mode=local`, bind loopback).\n   * Sets `agent.workspace` to the dev workspace.\n   * Sets `agent.skipBootstrap=true` (no BOOTSTRAP.md).\n   * Seeds the workspace files if missing:\n     `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`.\n   * Default identity: **C3‑PO** (protocol droid).\n   * Skips channel providers in dev mode (`OPENCLAW_SKIP_CHANNELS=1`).\n\nReset flow (fresh start):\n\nNote: `--dev` is a **global** profile flag and gets eaten by some runners.\nIf you need to spell it out, use the env var form:\n\n`--reset` wipes config, credentials, sessions, and the dev workspace (using\n`trash`, not `rm`), then recreates the default dev setup.\n\nTip: if a non‑dev gateway is already running (launchd/systemd), stop it first:\n\n## Raw stream logging (OpenClaw)\n\nOpenClaw can log the **raw assistant stream** before any filtering/formatting.\nThis is the best way to see whether reasoning is arriving as plain text deltas\n(or as separate thinking blocks).\n\nOptional path override:\n\n`~/.openclaw/logs/raw-stream.jsonl`\n\n## Raw chunk logging (pi-mono)\n\nTo capture **raw OpenAI-compat chunks** before they are parsed into blocks,\npi-mono exposes a separate logger:\n\n`~/.pi-mono/logs/raw-openai-completions.jsonl`\n\n> Note: this is only emitted by processes using pi-mono’s\n> `openai-completions` provider.\n\n* Raw stream logs can include full prompts, tool output, and user data.\n* Keep logs local and delete them after debugging.\n* If you share logs, scrub secrets and PII first.",
  "code_samples": [
    {
      "code": "/debug show\n/debug set messages.responsePrefix=\"[openclaw]\"\n/debug unset messages.responsePrefix\n/debug reset",
      "language": "unknown"
    },
    {
      "code": "This maps to:",
      "language": "unknown"
    },
    {
      "code": "Add any gateway CLI flags after `gateway:watch` and they will be passed through\non each restart.\n\n## Dev profile + dev gateway (--dev)\n\nUse the dev profile to isolate state and spin up a safe, disposable setup for\ndebugging. There are **two** `--dev` flags:\n\n* **Global `--dev` (profile):** isolates state under `~/.openclaw-dev` and\n  defaults the gateway port to `19001` (derived ports shift with it).\n* **`gateway --dev`: tells the Gateway to auto-create a default config +\n  workspace** when missing (and skip BOOTSTRAP.md).\n\nRecommended flow (dev profile + dev bootstrap):",
      "language": "unknown"
    },
    {
      "code": "If you don’t have a global install yet, run the CLI via `pnpm openclaw ...`.\n\nWhat this does:\n\n1. **Profile isolation** (global `--dev`)\n   * `OPENCLAW_PROFILE=dev`\n   * `OPENCLAW_STATE_DIR=~/.openclaw-dev`\n   * `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`\n   * `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas shift accordingly)\n\n2. **Dev bootstrap** (`gateway --dev`)\n   * Writes a minimal config if missing (`gateway.mode=local`, bind loopback).\n   * Sets `agent.workspace` to the dev workspace.\n   * Sets `agent.skipBootstrap=true` (no BOOTSTRAP.md).\n   * Seeds the workspace files if missing:\n     `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`.\n   * Default identity: **C3‑PO** (protocol droid).\n   * Skips channel providers in dev mode (`OPENCLAW_SKIP_CHANNELS=1`).\n\nReset flow (fresh start):",
      "language": "unknown"
    },
    {
      "code": "Note: `--dev` is a **global** profile flag and gets eaten by some runners.\nIf you need to spell it out, use the env var form:",
      "language": "unknown"
    },
    {
      "code": "`--reset` wipes config, credentials, sessions, and the dev workspace (using\n`trash`, not `rm`), then recreates the default dev setup.\n\nTip: if a non‑dev gateway is already running (launchd/systemd), stop it first:",
      "language": "unknown"
    },
    {
      "code": "## Raw stream logging (OpenClaw)\n\nOpenClaw can log the **raw assistant stream** before any filtering/formatting.\nThis is the best way to see whether reasoning is arriving as plain text deltas\n(or as separate thinking blocks).\n\nEnable it via CLI:",
      "language": "unknown"
    },
    {
      "code": "Optional path override:",
      "language": "unknown"
    },
    {
      "code": "Equivalent env vars:",
      "language": "unknown"
    },
    {
      "code": "Default file:\n\n`~/.openclaw/logs/raw-stream.jsonl`\n\n## Raw chunk logging (pi-mono)\n\nTo capture **raw OpenAI-compat chunks** before they are parsed into blocks,\npi-mono exposes a separate logger:",
      "language": "unknown"
    },
    {
      "code": "Optional path:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Runtime debug overrides",
      "id": "runtime-debug-overrides"
    },
    {
      "level": "h2",
      "text": "Gateway watch mode",
      "id": "gateway-watch-mode"
    },
    {
      "level": "h2",
      "text": "Dev profile + dev gateway (--dev)",
      "id": "dev-profile-+-dev-gateway-(--dev)"
    },
    {
      "level": "h2",
      "text": "Raw stream logging (OpenClaw)",
      "id": "raw-stream-logging-(openclaw)"
    },
    {
      "level": "h2",
      "text": "Raw chunk logging (pi-mono)",
      "id": "raw-chunk-logging-(pi-mono)"
    },
    {
      "level": "h2",
      "text": "Safety notes",
      "id": "safety-notes"
    }
  ],
  "url": "llms-txt#debugging",
  "links": []
}