Debugging

Debugging 문서는 OpenClaw 공식 문서(help/debugging)를 한국어로 정리한 가이드입니다. Debugging tools: watch mode, raw model streams, and tracing reasoning leakage 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Debugging tools: watch mode, raw model streams, and tracing reasoning leakage

한국어 가이드 범위: help/debugging 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Runtime debug overrides
Session trace output
Plugin lifecycle trace
CLI startup and command profiling
Gateway watch mode
Read recent output without attaching
or
Dev profile + dev gateway (--dev)
Raw stream logging
Safety notes
Debugging in VSCode
설정
참고
관련 문서

상세 내용

본문

Debugging helpers for streaming output, gateway iteration, and startup profiling.

Runtime debug overrides

/debug sets runtime-only config overrides (memory, not disk). Disabled by default; enable with commands.debug: true.

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

Session trace output

/trace shows plugin-owned trace/debug lines for one session without enabling full verbose mode. Use it for plugin diagnostics such as Active Memory debug summaries; use /verbose for normal status/tool output.

/trace
/trace on
/trace off

Plugin lifecycle trace

Set OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 for a phase-by-phase breakdown of plugin metadata, discovery, registry, runtime mirror, config mutation, and refresh work. Writes to stderr, so JSON command output stays parseable. Plugin load failures include their stack trace while this trace is enabled.

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

OPENCLAW_DIAGNOSTICS=plugin.load-profile openclaw plugins list

CLI startup and command profiling

For one-off profiling through the normal source runner, set OPENCLAW_RUN_NODE_CPU_PROF_DIR:

pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

Gateway watch mode

By default this starts or restarts a tmux session named openclaw-gateway-watch- (for example openclaw-gateway-watch-main), with a port suffix such as openclaw-gateway-watch-dev-19001 added only when OPENCLAW_GATEWAY_PORT differs from the default port 18789. It auto-attaches from interactive terminals; non-interactive shells, CI, and agent exec calls stay detached and print attach instructions instead:

pnpm gateway:watch

Read recent output without attaching

tmux capture-pane -ep -t openclaw-gateway-watch-main -S -200 bash node scripts/watch-node.mjs gateway --force bash pnpm openclaw gateway start bash pnpm gateway:watch:raw

The pane uses tmux `remain-on-exit`, so startup failures stay available for attach or capture instead of deleting the session. Re-running `pnpm gateway:watch` respawns that pane.

The tmux pane runs the raw watcher:

Before watching the configured/default port, the tmux wrapper stops the active profile's installed Gateway service. This hands the port to the source watcher without launchd, systemd, or Scheduled Task respawning and replacing it. The service stays installed; restore it after the watch session with:

When an explicit `--port` or `OPENCLAW_GATEWAY_PORT` differs from the installed service's effective port, the wrapper leaves the service running so both Gateways can run side by side.

Foreground mode without tmux:

or

OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch bash OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch bash pnpm gateway:watch --benchmark bash npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile ```

주요 항목:

--benchmark-dir <path>: write profiles somewhere else.
--benchmark-no-force: skip the default --force port cleanup and fail fast if the Gateway port is already in use.

Raw mode does not manage the installed service. Run `pnpm openclaw gateway stop` first when it uses the same port.

Keep tmux management but disable auto-attach:

Profile watched Gateway CPU time when debugging startup/runtime hotspots:

The watch wrapper consumes `--benchmark` before invoking the Gateway and writes one V8 `.cpuprofile` per Gateway child exit under `.artifacts/gateway-watch-profiles/`. Stop or restart the watched gateway to flush the current profile, then open it with Chrome DevTools or Speedscope:

Dev profile + dev gateway (--dev)

Recommended flow (dev profile + dev bootstrap):

주요 항목:

Global --dev (profile): isolates state under ~/.openclaw-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).
OPENCLAW_PROFILE=dev
OPENCLAW_STATE_DIR=~/.openclaw-dev
OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
OPENCLAW_GATEWAY_PORT=19001 (browser/canvas ports shift accordingly)
Writes a minimal config if missing (gateway.mode=local, bind loopback).
Sets agents.defaults.workspace to the dev workspace and agents.defaults.skipBootstrap=true.
Seeds the workspace files if missing: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md.
Default identity: C3-PO (protocol droid).
pnpm gateway:dev also sets OPENCLAW_SKIP_CHANNELS=1 to skip channel providers.

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

pnpm gateway:dev:reset

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

openclaw gateway stop

Raw stream logging

OpenClaw 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).

pnpm gateway:watch --raw-stream

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

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

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.

Debugging in VSCode

Source maps are required because the build hashes generated filenames. The included launch.json targets the Gateway service:

설정

Open Run and Debug (Activity Bar, or Ctrl+Shift+D). 2. Select Rebuild and Debug Gateway and press Start Debugging.

주요 항목:

Linux/macOS: export OUTPUT_SOURCE_MAPS=1
Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
Windows (CMD): set OUTPUT_SOURCE_MAPS=1

참고

주요 항목:

Rebuild and Debug Gateway deletes /dist and runs a full pnpm build with source maps on every launch.
Debug Gateway can start/stop without affecting /dist, but you manage the build cycle in a separate terminal.
Edit launch.json args to debug other CLI subcommands.
To use the built CLI for other tasks (for example dashboard --no-open if your debug session spawns a new auth token), run it from another terminal: node ./openclaw.mjs or an alias like alias openclaw-build="node $(pwd)/openclaw.mjs".

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/help/debugging
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

/trace
/trace on
/trace off

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

OPENCLAW_DIAGNOSTICS=plugin.load-profile openclaw plugins list

pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

Debugging

핵심 요약

Debugging tools: watch mode, raw model streams, and tracing reasoning leakage

한국어 가이드 범위: help/debugging 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Runtime debug overrides
Session trace output
Plugin lifecycle trace
CLI startup and command profiling
Gateway watch mode
Read recent output without attaching
or
Dev profile + dev gateway (--dev)
Raw stream logging
Safety notes
Debugging in VSCode
설정
참고
관련 문서

상세 내용

본문

Debugging helpers for streaming output, gateway iteration, and startup profiling.

Runtime debug overrides

/debug sets runtime-only config overrides (memory, not disk). Disabled by default; enable with commands.debug: true.

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

Session trace output

/trace
/trace on
/trace off

Plugin lifecycle trace

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

OPENCLAW_DIAGNOSTICS=plugin.load-profile openclaw plugins list

CLI startup and command profiling

For one-off profiling through the normal source runner, set OPENCLAW_RUN_NODE_CPU_PROF_DIR:

pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

Gateway watch mode

pnpm gateway:watch

Read recent output without attaching

tmux capture-pane -ep -t openclaw-gateway-watch-main -S -200 bash node scripts/watch-node.mjs gateway --force bash pnpm openclaw gateway start bash pnpm gateway:watch:raw

The pane uses tmux `remain-on-exit`, so startup failures stay available for attach or capture instead of deleting the session. Re-running `pnpm gateway:watch` respawns that pane.

The tmux pane runs the raw watcher:

Before watching the configured/default port, the tmux wrapper stops the active profile's installed Gateway service. This hands the port to the source watcher without launchd, systemd, or Scheduled Task respawning and replacing it. The service stays installed; restore it after the watch session with:

When an explicit `--port` or `OPENCLAW_GATEWAY_PORT` differs from the installed service's effective port, the wrapper leaves the service running so both Gateways can run side by side.

Foreground mode without tmux:

or

주요 항목:

--benchmark-dir <path>: write profiles somewhere else.
--benchmark-no-force: skip the default --force port cleanup and fail fast if the Gateway port is already in use.

Raw mode does not manage the installed service. Run `pnpm openclaw gateway stop` first when it uses the same port.

Keep tmux management but disable auto-attach:

Profile watched Gateway CPU time when debugging startup/runtime hotspots:

The watch wrapper consumes `--benchmark` before invoking the Gateway and writes one V8 `.cpuprofile` per Gateway child exit under `.artifacts/gateway-watch-profiles/`. Stop or restart the watched gateway to flush the current profile, then open it with Chrome DevTools or Speedscope:

Dev profile + dev gateway (--dev)

Recommended flow (dev profile + dev bootstrap):

주요 항목:

Global --dev (profile): isolates state under ~/.openclaw-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).
OPENCLAW_PROFILE=dev
OPENCLAW_STATE_DIR=~/.openclaw-dev
OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
OPENCLAW_GATEWAY_PORT=19001 (browser/canvas ports shift accordingly)
Writes a minimal config if missing (gateway.mode=local, bind loopback).
Sets agents.defaults.workspace to the dev workspace and agents.defaults.skipBootstrap=true.
Seeds the workspace files if missing: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md.
Default identity: C3-PO (protocol droid).
pnpm gateway:dev also sets OPENCLAW_SKIP_CHANNELS=1 to skip channel providers.

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

pnpm gateway:dev:reset

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

openclaw gateway stop

Raw stream logging

OpenClaw 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).

pnpm gateway:watch --raw-stream

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

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

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.

Debugging in VSCode

Source maps are required because the build hashes generated filenames. The included launch.json targets the Gateway service:

설정

Open Run and Debug (Activity Bar, or Ctrl+Shift+D). 2. Select Rebuild and Debug Gateway and press Start Debugging.

주요 항목:

Linux/macOS: export OUTPUT_SOURCE_MAPS=1
Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
Windows (CMD): set OUTPUT_SOURCE_MAPS=1

참고

주요 항목:

Rebuild and Debug Gateway deletes /dist and runs a full pnpm build with source maps on every launch.
Debug Gateway can start/stop without affecting /dist, but you manage the build cycle in a separate terminal.
Edit launch.json args to debug other CLI subcommands.
To use the built CLI for other tasks (for example dashboard --no-open if your debug session spawns a new auth token), run it from another terminal: node ./openclaw.mjs or an alias like alias openclaw-build="node $(pwd)/openclaw.mjs".

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/help/debugging
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

/trace
/trace on
/trace off

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

OPENCLAW_DIAGNOSTICS=plugin.load-profile openclaw plugins list

pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

Debugging

핵심 요약

문서 구성

상세 내용

본문

Runtime debug overrides

Session trace output

Plugin lifecycle trace

CLI startup and command profiling

Gateway watch mode

Read recent output without attaching

or

Dev profile + dev gateway (--dev)

Raw stream logging

Safety notes

Debugging in VSCode

설정

참고

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Debugging

핵심 요약

문서 구성

상세 내용

본문

Runtime debug overrides

Session trace output

Plugin lifecycle trace

CLI startup and command profiling

Gateway watch mode

Read recent output without attaching

or

Dev profile + dev gateway (--dev)

Raw stream logging

Safety notes

Debugging in VSCode

설정

참고

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드