OpenClaw 디버깅 가이드

코드를 작성하다 보면 분명히 실행되어야 할 로직이 예상과 다르게 동작할 때가 있죠. 로그를 뒤져봐도 원인을 알 수 없고, 그렇다고 실서비스 환경을 직접 수정하며 테스트하기에는 위험 부담이 커서 답답했던 경험이 있을 거예요.

OpenClaw는 이런 상황에서 개발자가 모델의 원시 출력을 직접 확인하고, 로컬 환경을 안전하게 분리해 빠르게 반복 테스트할 수 있는 디버깅 도구들을 제공합니다.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• OpenClaw 설치 및 기본 설정
• pnpm 패키지 매니저
• 설정 파일 내 commands.debug: true 활성화 (런타임 오버라이드 사용 시)

빠른 시작

가장 빠르게 디버깅을 시작하는 방법은 Gateway를 Watch 모드로 실행하는 것입니다. 파일을 저장할 때마다 Gateway가 자동으로 재시작되어 변경 사항을 즉시 확인할 수 있습니다.

pnpm gateway:watch --force

또는 다음 명령어를 사용해도 동일하게 동작합니다.

tsx watch src/entry.ts gateway --force

Runtime Debug Overrides

파일을 직접 수정하지 않고 채팅창에서 바로 설정을 변경하고 싶다면 /debug 커맨드를 사용해 보세요. 이 설정은 메모리에만 저장되며 실제 파일에는 영향을 주지 않습니다.

/debug show                                    # 현재 오버라이드된 설정 보기
/debug set messages.responsePrefix="[test]"    # 값 설정하기
/debug unset messages.responsePrefix           # 오버라이드 제거하기
/debug reset                                   # 모든 오버라이드 초기화

Dev Profile (독립된 상태 관리)

개발 중인 내용이 실제 운영 데이터에 영향을 주지 않도록 Dev Profile을 사용하는 것이 좋습니다.

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Dev Profile의 특징:

• 상태 저장 디렉토리: ~/.openclaw-dev
• Gateway 포트: 19001
• BOOTSTRAP.md 실행 건너뛰기
• 최소한의 기본 설정 생성
• 기본 Identity: C3-PO (프로토콜 드로이드)
• 채널 공급자(Channel Providers) 건너뛰기

만약 설정을 완전히 초기화하고 깨끗하게 다시 시작하고 싶다면 다음 명령어를 실행하세요. rm 대신 trash를 사용하여 안전하게 삭제합니다.

pnpm gateway:dev:reset

Raw Stream Logging

모델이 필터링을 거치기 전에 실제로 어떤 데이터를 반환하는지 확인해야 할 때가 있습니다. 특히 추론(Reasoning) 내용이 일반 텍스트 출력으로 새어 나가는지 확인할 때 유용합니다.

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

기본 로그 파일 위치는 ~/.openclaw/logs/raw-stream.jsonl입니다. 저장 경로를 직접 지정하고 싶다면 다음 옵션을 추가하세요.

pnpm gateway:watch --force --raw-stream --raw-stream-path /custom/path.jsonl

환경 변수로도 설정할 수 있습니다.

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

pi-mono Raw Chunk Logging

OpenAI와 호환되는 청크 데이터를 파싱 전 단계에서 캡처하려면 다음 환경 변수를 사용하세요.

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

Environment Variable Reference

디버깅 시 유용하게 사용할 수 있는 환경 변수 목록입니다.

변수명	설명
OPENCLAW_PROFILE=dev	Dev Profile 사용
OPENCLAW_STATE_DIR=~/.openclaw-dev	상태 저장 디렉토리 변경
OPENCLAW_GATEWAY_PORT=19001	Gateway 포트 변경
OPENCLAW_RAW_STREAM=1	Raw Stream 로깅 활성화
OPENCLAW_SKIP_CHANNELS=1	채널 공급자 건너뛰기

문제 해결

디버깅 과정에서 발생할 수 있는 주의 사항입니다.

• 보안 주의: Raw Stream 로그에는 프롬프트, 도구 출력 결과, 사용자 데이터가 포함될 수 있습니다.
• 데이터 관리: 로그 파일은 반드시 로컬에만 보관하고, 디버깅이 끝나면 삭제하세요.
• 정보 공유: 로그를 외부에 공유해야 한다면 비밀 키나 개인정보(PII)가 포함되어 있지 않은지 반드시 확인해야 합니다.

여전히 문제가 해결되지 않나요? AI Setup Assistant가 설정을 디버깅하는 데 도움을 줄 수 있습니다.

다음 단계

• Logging → — 파일 로그 및 콘솔 출력 확인하기
• Testing → — 테스트 스위트 및 라이브 테스트 실행하기
• Gateway Configuration → — 전체 설정 레퍼런스 보기