OpenClaw 디버깅은(는) 무엇을 하나요?
동작은 로컬 테스트, 라이브 모델, 프로바이더, 코드 모드, 도구 검색, Crabbox, CI에 따라 다릅니다. 추측하기 전에 디버그 신호를 확보하세요.
먼저 읽을 것
docs/logging.md: 로그 파일,openclaw logs, 대상 debug 플래그.docs/reference/test.md: 로컬 테스트 명령어.docs/tools/code-mode.md: 코드 모드 exec/wait + 도구 카탈로그 규칙.$openclaw-testing: 테스트 레인 선택.$crabbox: 광범위, Docker, 패키지, Linux, 라이브 키, CI 패리티 증명.
기본 루프
- 의심되는 경계를 명시: 구성, 도구 구성, 프로바이더 페이로드, fetch, 스트림/SSE, 대본 재생, 워커/런타임, 패키지/배포, CI.
- 경계를 증명하는 가장 좁은 신호를 추가/활성화.
- 동일한 프로바이더/모델/구성으로 재현. 모델 자체가 테스트 변수가 아닌 한 무작위로 모델을 전환하지 마세요.
- 구성된 상태와 실제 실행 활성화를 비교.
- 근본 원인 패치.
- 정확한 실패 프로브를 재실행; 계약에서 요구하는 경우에만 범위 확장.
모델 전송 로그
모델 요청 형태/스트림 타이밍: 전역 debug보다 대상 env 플래그 사용:
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway
유용한 플래그:
OPENCLAW_DEBUG_MODEL_TRANSPORT=1: 요청 시작, fetch 응답, SDK 헤더, 첫 번째 SSE 이벤트, 스트림 완료,info수준의 전송 오류.OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: 제한된 페이로드 요약.OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: 모든 모델 대상 도구 이름.OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: 제한된, 수정된 JSON 페이로드. 디버깅 중에만 사용; 프롬프트/메시지 텍스트가 여전히 나타날 수 있습니다.OPENCLAW_DEBUG_SSE=events: 첫 번째 이벤트 + 스트림 완료 타이밍.OPENCLAW_DEBUG_SSE=peek: 처음 5개의 수정된 SSE 이벤트.OPENCLAW_DEBUG_CODE_MODE=1: 코드 모드 툴 표면 진단.
로그 보기:
openclaw logs --follow
일반적인 경계
- 구성 vs 활성화: 활성화된 구성은 비활성화된 실행 도구, 원시 실행, 빈 허용 목록, 누락된 모델 도구 지원과 공존할 수 있습니다. 프로바이더 페이로드 불변성을 강제하기 전에 실제 보이는 도구를 확인하세요.
- 툴 표면: 레지스트리/구성만이 아니라 최종 모델에 보이는 도구 이름을 검사합니다. 코드 모드는 실제 활성화 후에만 정확히
exec+wait입니다. - 프로바이더 페이로드: SDK 호출 전에 필드, 모델 ID, 서비스 계층, 추론, 입력 크기, 메타데이터 키, 프롬프트 캐시 키 존재 여부, 도구 이름을 기록합니다.
- Fetch vs SSE: fetch 응답은 HTTP 헤더가 도착했음을 증명합니다. 첫 번째 SSE 이벤트는 프로바이더 본문 진행을 증명합니다. 이 간격은 도구 실행이 아닌 스트림/본문/프로바이더 문제입니다.
- 워커/배포: 워커, 동적 임포트, 패키지 내보내기, 지연 런타임 경계, 게시된 경로를 다루는 경우 →
pnpm build. - 라이브 키: 누락된 프로바이더 키 → 라이브 증명이 차단되었다고 선언하기 전에 구성된 비밀 워크플로우를 확인하세요. Env 검사는 존재 여부만 확인합니다. 절대 비밀을 출력하지 마세요.
세션 및 대본 가져오기
채팅 세션 버그 리포트: 실제 대본, 발신자 속성, 첨부 파일을 증거로 가져옵니다.
먼저 CLI 사용 (구성된 설치 필요; 라이브 게이트웨이에 안전):
openclaw sessions list --agent <agentId> --json
openclaw sessions tail
openclaw sessions export-trajectory
문서: 저장소 레이아웃 docs/reference/database-schemas.md;
CLI https://docs.openclaw.ai/cli/sessions.
원시 저장소: CLI를 사용할 수 없거나(예: SSH를 통한 원격 호스트) 이벤트 수준 세부 정보가 필요한 경우:
- 에이전트별 데이터 플레인:
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. 정식 스키마:src/state/openclaw-agent-schema.sql. - 호스팅/systemd 상태: 서비스 사용자의 홈 (예:
/home/openclaw/.openclaw/...), root가 아님. Root는 다른 에이전트가 있는 별도의 분리된 설치를 가질 수 있습니다. 예상 에이전트 디렉토리가 없는 경우:find / -maxdepth 6 -name openclaw-agent.sqlite로 실제 DB를 찾으세요. - 웹 채팅 URL 세션 ID 조각:
/chat/<agentId>/<slug>-<hex>.session_nodes에서 확인:session_key LIKE '%<hex>%'→current_session_id,display_name. 키 형태:agent:<agentId>:<surface>:<uuid>; 하위 에이전트 세션은 surfacesubagent를 사용합니다. - 대본:
transcript_events(session_id,seq,event_json).event_json.message:role(user/assistant/toolResult) +content(문자열 또는text/toolCall/image유형의 부분). - 발신자 출처: 실제 사용자 메시지는
message.__openclaw를 포함합니다. (senderId,senderName,senderIsOwner); 런타임 합성 입력은 포함하지 않습니다. 이로 운영자가 작성한 텍스트와 주입된 프롬프트를 구별하세요. - 전체 텍스트 대본 검색:
session_transcript_fts. - 첨부 파일:
media://inbound/<file>URL →<state-dir>/media/inbound/<file>. - 사용자 첨부 이미지 ≠
image콘텐츠 부분. 메시지 봉투는message.__openclaw.media[]항목을 포함합니다:url(media://inbound/<file>),contentType,kind,fileName. 부분만 추출하는 도구는 모든 이미지를 놓칩니다. 원시event_json에서media://를 grep하세요. 원격 호스트: scp로 파일을 로컬로 가져오고 (scp 인수당 하나의 원격 경로); 거기서 읽으세요.
sqlite3 바이너리가 없는 호스트에도 Node가 있습니다: node:sqlite는 종속성이 필요 없습니다.
node -e 'const {DatabaseSync}=require("node:sqlite");
const db=new DatabaseSync(process.argv[1],{readOnly:true});
console.log(JSON.stringify(db.prepare(
"SELECT seq,event_json FROM transcript_events WHERE session_id=? ORDER BY seq"
).all(process.argv[2])))' <db-path> <session-id>
- 항상 라이브 저장소를
readOnly: true로 열고; 실행 중인 게이트웨이의 상태에 절대 쓰지 마세요. (루트AGENTS.md유효성 검사 규칙). - 실제 데이터 작업: 먼저 DB를 개발 상태 디렉토리로 복사하세요.
코드 포인터
- 모델 페이로드 + Responses 스트림:
src/agents/openai-transport-stream.ts - 보호된 fetch/타이밍:
src/agents/provider-transport-fetch.ts - OpenAI/Codex 프로바이더 래퍼:
src/llm/providers/stream-wrappers/openai.ts - 도구 구성, 도구 검색, 코드 모드 활성화:
src/agents/embedded-agent-runner/run/attempt.ts - 코드 모드 런타임 및 워커:
src/agents/code-mode.tssrc/agents/code-mode.worker.ts - 도구 검색 카탈로그:
src/agents/tool-search.ts
증명 선택
- 단일 헬퍼/페이로드 버그: 로컬 대상 Vitest.
- 문서/로깅 전용:
pnpm check:docs+git diff --check. - 워커/배포/지연 임포트/패키지 표면: 대상 테스트 +
pnpm build. - 라이브 프로바이더/모델 동작: 동일한 프로바이더/모델, debug 플래그, 가능하면 실제 키.
- Docker/패키지/Linux/CI 패리티: 가능한 경우 현재 전용 Linux 워커 사용;
그렇지 않으면
$crabbox. - CI 실패: 정확한 SHA, 관련 작업만; 실패/완료 후에만 로그.
출력 습관
보고:
- 테스트된 경계
- 정확한 명령어/env 형태, 수정됨
- 관찰된 신호, 예: 도구 이름 또는 첫 번째 SSE 이벤트 타이밍
- 수정 위치
- 좁은 증명 + 남은 위험