디버깅

스트리밍 출력 디버깅 도우미입니다. 특히 공급자가 추론을 일반 텍스트에 섞어 넣을 때 유용합니다.

런타임 디버그 재정의

채팅에서 /debug를 사용해 런타임 전용 구성 재정의(메모리, 디스크 아님)를 설정합니다. /debug는 기본적으로 비활성화되어 있습니다. commands.debug: true로 활성화하세요. openclaw.json을 편집하지 않고 잘 드러나지 않는 설정을 전환해야 할 때 편리합니다.

예:

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

/debug reset은 모든 재정의를 지우고 디스크의 구성으로 돌아갑니다.

세션 추적 출력

전체 상세 모드를 켜지 않고 한 세션에서 Plugin 소유 추적/디버그 줄을 보고 싶을 때는 /trace를 사용합니다.

예:

/trace/trace on/trace off

Active Memory 디버그 요약 같은 Plugin 진단에는 /trace를 사용하세요. 일반적인 상세 상태/도구 출력에는 계속 /verbose를 사용하고, 런타임 전용 구성 재정의에는 계속 /debug를 사용하세요.

Plugin 수명 주기 추적

Plugin 수명 주기 명령이 느리게 느껴지고 Plugin 메타데이터, 검색, 레지스트리, 런타임 미러, 구성 변경, 새로 고침 작업에 대한 내장 단계별 분석이 필요할 때는 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1을 사용합니다. 추적은 선택 사항이며 stderr에 기록되므로 JSON 명령 출력은 계속 파싱할 수 있습니다.

예:

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"

CPU 프로파일러를 사용하기 전에 Plugin 수명 주기 조사에 이것을 사용하세요. 명령이 소스 체크아웃에서 실행 중이라면 pnpm build 후 node dist/entry.js ...로 빌드된 런타임을 측정하는 것을 권장합니다. pnpm openclaw ...도 소스 러너 오버헤드를 함께 측정합니다.

CLI 시작 및 명령 프로파일링

명령이 느리게 느껴질 때는 체크인된 시작 벤치마크를 사용하세요.

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

일반 소스 러너를 통한 일회성 프로파일링에는 OPENCLAW_RUN_NODE_CPU_PROF_DIR를 설정합니다.

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

소스 러너는 Node CPU 프로파일 플래그를 추가하고 해당 명령의 .cpuprofile을 기록합니다. 명령 코드에 임시 계측을 추가하기 전에 이것을 사용하세요.

동기 파일 시스템 또는 모듈 로더 작업처럼 보이는 시작 지연에는 소스 러너를 통해 Node의 동기 I/O 추적 플래그를 추가합니다.

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch는 감시 중인 Gateway 자식 프로세스에 대해 이 플래그를 기본적으로 비활성화합니다. 감시 모드에서 Node 동기 I/O 추적 출력을 명시적으로 원할 때 OPENCLAW_TRACE_SYNC_IO=1을 설정하세요.

Gateway 감시 모드

빠른 반복 작업을 위해 파일 감시기 아래에서 Gateway를 실행하세요.

pnpm gateway:watch

기본적으로 이는 openclaw-gateway-watch-main이라는 tmux 세션(또는 openclaw-gateway-watch-dev-19001 같은 프로필/포트별 변형)을 시작하거나 재시작하고, 대화형 터미널에서는 자동으로 연결합니다. 비대화형 셸, CI, 에이전트 exec 호출은 분리 상태로 유지되며 대신 연결 지침을 출력합니다. 필요할 때 수동으로 연결하세요.

tmux attach -t openclaw-gateway-watch-main

tmux 창은 원시 감시기를 실행합니다.

node scripts/watch-node.mjs gateway --force

tmux를 원하지 않을 때는 포그라운드 모드를 사용하세요.

pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

tmux 관리는 유지하면서 자동 연결을 비활성화합니다.

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

시작/런타임 핫스팟을 디버깅할 때 감시 중인 Gateway CPU 시간을 프로파일링합니다.

pnpm gateway:watch --benchmark

감시 래퍼는 Gateway를 호출하기 전에 --benchmark를 소비하고, 각 Gateway 자식 프로세스 종료마다 V8 .cpuprofile 하나를 .artifacts/gateway-watch-profiles/ 아래에 기록합니다. 현재 프로파일을 플러시하려면 감시 중인 Gateway를 중지하거나 재시작한 다음 Chrome DevTools 또는 Speedscope로 여세요.

npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile

프로파일을 다른 위치에 두고 싶을 때는 --benchmark-dir <path>를 사용하세요. 벤치마크된 자식 프로세스가 기본 --force 포트 정리를 건너뛰고 Gateway 포트가 이미 사용 중이면 빠르게 실패하게 하려면 --benchmark-no-force를 사용하세요. 벤치마크 모드는 기본적으로 동기 I/O 추적 스팸을 억제합니다. CPU 프로파일과 Node 동기 I/O 스택 추적을 모두 명시적으로 원할 때는 --benchmark와 함께 OPENCLAW_TRACE_SYNC_IO=1을 설정하세요. 벤치마크 모드에서는 이러한 추적 블록이 벤치마크 디렉터리 아래의 gateway-watch-output.log에 기록되고 터미널 창에서는 필터링됩니다. 일반 Gateway 로그는 계속 표시됩니다.

tmux 래퍼는 OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT, OPENCLAW_SKIP_CHANNELS 같은 일반적인 비밀이 아닌 런타임 선택자를 창으로 전달합니다. 공급자 자격 증명은 일반 프로필/구성에 넣거나, 일회성 임시 비밀에는 원시 포그라운드 모드를 사용하세요. 감시 중인 Gateway가 시작 중 종료되면 감시기는 openclaw doctor --fix --non-interactive를 한 번 실행하고 Gateway 자식 프로세스를 재시작합니다. 개발 전용 복구 패스 없이 원래의 시작 실패를 보고 싶을 때는 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0을 사용하세요. 관리되는 tmux 창은 가독성을 위해 기본적으로 색상 있는 Gateway 로그도 사용합니다. ANSI 출력을 비활성화하려면 pnpm gateway:watch를 시작할 때 FORCE_COLOR=0을 설정하세요.

감시기는 src/ 아래의 빌드 관련 파일, 확장 소스 파일, 확장 package.json 및 openclaw.plugin.json 메타데이터, tsconfig.json, package.json, tsdown.config.ts 변경 시 재시작합니다. 확장 메타데이터 변경은 tsdown 재빌드를 강제하지 않고 Gateway를 재시작합니다. 소스 및 구성 변경은 여전히 먼저 dist를 재빌드합니다.

gateway:watch 뒤에 Gateway CLI 플래그를 추가하면 각 재시작 때 그대로 전달됩니다. 동일한 감시 명령을 다시 실행하면 이름이 지정된 tmux 창이 다시 생성되고, 원시 감시기는 여전히 단일 감시기 잠금을 유지하므로 중복 감시기 부모가 쌓이는 대신 교체됩니다.

개발 프로필 + 개발 Gateway(--dev)

디버깅을 위해 상태를 격리하고 안전하게 폐기 가능한 설정을 시작하려면 개발 프로필을 사용하세요. --dev 플래그는 두 가지가 있습니다.

• 전역 --dev(프로필): 상태를 ~/.openclaw-dev 아래로 격리하고 Gateway 포트를 기본값 19001로 설정합니다(파생 포트도 함께 이동).
• gateway --dev: 누락된 경우 Gateway에 기본 구성 + 작업 영역을 자동 생성하도록 지시합니다(그리고 BOOTSTRAP.md를 건너뜁니다).

권장 흐름(개발 프로필 + 개발 부트스트랩):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

아직 전역 설치가 없다면 pnpm openclaw ...로 CLI를 실행하세요.

이 작업이 수행하는 것:

1. 프로필 격리(전역 --dev)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001(브라우저/캔버스도 그에 맞게 이동)

2. 개발 부트스트랩(gateway --dev)

   • 누락된 경우 최소 구성을 기록합니다(gateway.mode=local, loopback 바인딩).
   • agent.workspace를 개발 작업 영역으로 설정합니다.
   • agent.skipBootstrap=true를 설정합니다(BOOTSTRAP.md 없음).
   • 누락된 경우 작업 영역 파일을 시드합니다: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
   • 기본 ID: C3-PO(프로토콜 드로이드).
   • 개발 모드에서 채널 공급자를 건너뜁니다(OPENCLAW_SKIP_CHANNELS=1).

재설정 흐름(새로 시작):

pnpm gateway:dev:reset

--reset은 구성, 자격 증명, 세션, 개발 작업 영역을 지운 다음(rm이 아니라 trash 사용) 기본 개발 설정을 다시 만듭니다.

원시 스트림 로깅(OpenClaw)

OpenClaw는 필터링/포맷팅 전에 원시 어시스턴트 스트림을 기록할 수 있습니다. 이는 추론이 일반 텍스트 델타로 도착하는지(또는 별도의 사고 블록으로 도착하는지) 확인하는 가장 좋은 방법입니다.

CLI로 활성화:

pnpm gateway:watch --raw-stream

선택적 경로 재정의:

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

동등한 환경 변수:

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

기본 파일:

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

원시 OpenAI 호환 청크 로깅

블록으로 파싱되기 전에 원시 OpenAI 호환 청크를 캡처하려면 전송 로거를 활성화하세요.

OPENCLAW_RAW_STREAM=1

선택적 경로:

OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl

기본 파일:

~/.openclaw/logs/raw-openai-completions.jsonl

안전 참고 사항

• 원시 스트림 로그에는 전체 프롬프트, 도구 출력, 사용자 데이터가 포함될 수 있습니다.
• 로그는 로컬에 보관하고 디버깅 후 삭제하세요.
• 로그를 공유하는 경우 먼저 비밀 정보와 PII를 제거하세요.

VSCode에서 디버깅

빌드 프로세스의 일부로 생성된 많은 파일이 해시된 이름을 갖게 되므로 VSCode 기반 IDE에서 디버깅을 활성화하려면 소스 맵이 필요합니다. 포함된 launch.json 구성은 Gateway 서비스를 대상으로 하지만 다른 목적에도 빠르게 조정할 수 있습니다.

1. Gateway 재빌드 및 디버그 - 새 빌드를 만든 후 Gateway 서비스를 디버그합니다
2. Gateway 디버그 - 기존 빌드의 Gateway 서비스를 디버그합니다

설정

기본 Gateway 재빌드 및 디버그 구성은 필요한 요소가 모두 포함되어 있으며, 자동으로 /dist 폴더를 삭제하고 디버깅이 활성화된 상태로 프로젝트를 재빌드합니다.

1. Activity Bar에서 실행 및 디버그 패널을 열거나 Ctrl+Shift+D를 누릅니다
2. IDE에서 구성 드롭다운에 Gateway 재빌드 및 디버그가 선택되어 있는지 확인한 다음 디버깅 시작 버튼을 누릅니다

또는 빌드와 디버그 프로세스를 수동으로 관리하려면:

1. 터미널을 열고 소스 맵을 활성화합니다.
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. 같은 터미널에서 프로젝트를 재빌드합니다: pnpm clean:dist && pnpm build
3. IDE에서 실행 및 디버그 구성 드롭다운의 Gateway 디버그 옵션을 선택한 다음 디버깅 시작 버튼을 누릅니다

이제 TypeScript 소스 파일(src/ 디렉터리)에 중단점을 설정할 수 있으며, 디버거는 소스 맵을 통해 중단점을 컴파일된 JavaScript에 올바르게 매핑합니다. 예상대로 변수를 검사하고, 코드를 단계별로 실행하고, 호출 스택을 살펴볼 수 있습니다.

참고 사항

• "Gateway 재빌드 및 디버그" 옵션을 사용하는 경우 - 디버거가 시작될 때마다 /dist 폴더를 완전히 삭제하고 Gateway를 시작하기 전에 소스 맵이 활성화된 전체 pnpm build를 실행합니다
• "Gateway 디버그" 옵션을 사용하는 경우 - 디버그 세션은 /dist 폴더에 영향을 주지 않고 언제든 시작 및 중지할 수 있지만, 디버깅 활성화와 빌드 주기 관리를 모두 별도의 터미널 프로세스에서 수행해야 합니다
• 프로젝트의 다른 섹션을 디버그하려면 args에 대한 launch.json 설정을 수정하세요
• 다른 작업에 빌드된 OpenClaw CLI를 사용해야 하는 경우(예: 디버그 세션이 새 인증 토큰을 생성할 때 dashboard --no-open), 다른 터미널에서 node ./openclaw.mjs로 실행하거나 alias openclaw-build="node $(pwd)/openclaw.mjs" 같은 셸 별칭을 만들 수 있습니다

관련 항목

• 문제 해결
• FAQ