OpenClaw 디버깅 가이드

스트리밍 출력을 디버깅하다 보면 머리가 아플 때가 많아요. 특히 AI 모델이 추론 과정과 실제 응답을 뒤섞어서 보낼 때는 어디가 문제인지 파악하기 정말 어렵죠. 설정을 하나 바꿀 때마다 서비스를 매번 재시작해야 하는 번거로움도 개발 속도를 늦추는 주범이에요.

이 가이드에서는 OpenClaw의 다양한 디버깅 도구를 사용해 문제를 빠르게 찾고 해결하는 방법을 설명할게요.

필요한 것

• OpenClaw 설치 및 기본 설정
• pnpm 패키지 매니저
• openclaw.json 설정 파일

빠른 시작

가장 빠르게 디버깅을 시작하는 방법은 채팅창에서 /debug 커맨드를 사용하는 거예요. openclaw.json 파일을 직접 수정하지 않고도 메모리상에서 설정을 즉시 바꿀 수 있습니다.

1. 먼저 commands.debug: true를 설정해 디버깅을 활성화하세요.
2. 채팅창에 다음 커맨드들을 입력해 보세요:

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

/debug reset을 입력하면 모든 오버라이드가 삭제되고 디스크에 저장된 원래 설정으로 돌아갑니다.

Gateway watch mode

코드 수정을 빠르게 반영하고 싶다면 Gateway를 watch mode로 실행하세요.

pnpm gateway:watch --force

이 명령어는 내부적으로 tsx watch src/entry.ts gateway --force를 실행합니다. gateway:watch 뒤에 CLI flag를 추가하면 Gateway가 재시작될 때마다 해당 플래그가 전달됩니다.

Dev Profile + Dev Gateway (—dev)

데이터를 격리하고 안전한 테스트 환경을 만들고 싶을 때는 --dev 플래그를 사용하세요. 여기에는 두 가지 방식이 있습니다.

• Global --dev (profile): 상태를 ~/.openclaw-dev에 격리하고 Gateway 포트를 19001로 설정합니다.
• gateway --dev: 설정이나 workspace가 없을 때 기본값을 자동으로 생성하고 BOOTSTRAP.md 과정을 건너뜁니다.

추천하는 실행 흐름은 다음과 같아요:

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

이 명령어를 실행하면 다음과 같은 변화가 일어납니다:

1. OPENCLAW_PROFILE=dev 환경 변수가 적용되어 설정 경로가 변경됩니다.
2. IDENTITY.md, TOOLS.md 등 기본 workspace 파일들이 자동으로 생성됩니다.
3. 기본 identity가 C3-PO로 설정됩니다.
4. 개발 모드에서는 channel provider를 건너뜁니다.

완전히 새로 시작하고 싶다면 리셋 명령어를 사용하세요:

pnpm gateway:dev:reset

Raw stream logging

응답이 필터링되거나 포맷팅되기 전의 raw assistant stream을 확인하는 것이 디버깅에 가장 효과적이에요.

OpenClaw 로깅

CLI에서 직접 활성화할 수 있습니다:

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

로그 저장 경로를 바꾸고 싶다면 이 명령어를 사용하세요:

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

pi-mono 로깅

openai-completions provider를 사용하는 경우, 파싱 전의 raw chunk를 캡처할 수 있습니다:

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

문제 해결

이미 Gateway가 실행 중이라는 오류가 발생하나요? 만약 launchd나 systemd를 통해 일반 Gateway가 실행 중이라면, 개발용 Gateway를 켜기 전에 먼저 중지해야 합니다:

openclaw gateway stop

보안 주의사항

• Raw stream 로그에는 전체 프롬프트와 유저 데이터가 포함될 수 있어요.
• 디버깅이 끝나면 로그를 삭제하고, 외부에 공유할 때는 비밀번호나 개인정보를 반드시 지워주세요.

더 자세한 설정 방법이 궁금하다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Gateway Configuration
• CLI Reference