Gateway

Gateway 로깅

로깅

사용자 대상 개요(CLI + Control UI + 구성)는 /logging을 참조하세요.

OpenClaw에는 두 가지 로그 표면이 있습니다.

콘솔 출력 - 터미널/디버그 UI에 표시되는 내용입니다.
파일 로그 - Gateway 로거가 기록하는 JSON 라인입니다.

시작 시 Gateway는 확인된 기본 에이전트 모델과 새 세션에 영향을 주는 모드 기본값을 기록합니다.

text

agent model: openai/gpt-5.6-sol (thinking=medium, fast=on)

thinking은 기본 에이전트, 모델 매개변수 또는 전역 에이전트 기본값에서 가져오며, 설정되지 않은 경우 medium으로 표시됩니다. fast는 기본 에이전트 또는 모델의 fastMode 매개변수에서 가져옵니다.

파일 기반 로거

기본 롤링 로그 파일은 /tmp/openclaw/ 아래에 있으며(하루에 파일 하나), 파일명은 openclaw-YYYY-MM-DD.log이고 Gateway 호스트의 현지 시간대를 기준으로 날짜가 지정됩니다. 해당 디렉터리가 안전하지 않거나 쓸 수 없는 경우(소유자가 잘못되었거나, 누구나 쓸 수 있거나, 심볼릭 링크인 경우) OpenClaw는 사용자 범위의 os.tmpdir()/openclaw-<uid> 경로를 대신 사용합니다. Windows에서는 항상 이 OS 임시 디렉터리 대체 경로를 사용합니다.
활성 로그 파일은 logging.maxFileBytes(기본값: 100MB)에 도달하면 순환되며, 번호가 지정된 보관 파일을 최대 5개(.1부터 .5까지) 유지하고 새로운 활성 파일에 계속 기록합니다.
~/.openclaw/openclaw.json에서 logging.file, logging.level을 사용해 로그 파일 경로와 수준을 구성합니다.
파일 형식은 한 줄당 하나의 JSON 객체입니다.

대화, 실시간 음성 및 관리형 룸 코드 경로는 운영 디버깅과 OTLP 로그 내보내기를 위한 제한된 수명 주기 레코드에 공유 파일 로거를 사용합니다. 대화 기록 텍스트, 오디오 페이로드, 턴 ID, 호출 ID 및 제공자 항목 ID는 로그 레코드에 절대 복사되지 않습니다.

Control UI의 로그 탭은 Gateway(logs.tail)를 통해 이 파일의 후속 내용을 실시간으로 표시합니다. CLI도 동일하게 작동합니다.

bash

openclaw logs --follow

상세 출력과 로그 수준

파일 로그는 logging.level로만 제어됩니다.
--verbose는 콘솔 상세도(및 WS 로그 형식)에만 영향을 주며, 파일 로그 수준을 높이지 않습니다.
상세 출력 전용 세부 정보를 파일 로그에 기록하려면 logging.level을 debug 또는 trace로 설정하세요.
추적 로깅에는 Plugin 도구 팩터리 준비와 같이 선택된 핫 패스의 진단 타이밍 요약도 포함됩니다. /tools/plugin#slow-plugin-tool-setup을 참조하세요.

콘솔 캡처

CLI는 console.log/info/warn/error/debug/trace를 캡처해 파일 로그에 기록하면서 stdout/stderr에도 계속 출력합니다.

콘솔 상세도는 독립적으로 조정할 수 있습니다.

logging.consoleLevel(기본값: info)
logging.consoleStyle(pretty | compact | json; TTY에서는 기본값이 pretty이고, 그 외에는 compact)

민감 정보 가림

OpenClaw는 로그 또는 대화 기록 출력이 프로세스를 벗어나기 전에 민감한 토큰을 가립니다. 이 민감 정보 가림 정책은 콘솔, 파일 로그, OTLP 로그 레코드 및 세션 대화 기록 텍스트 출력 대상에 적용되므로, 일치하는 비밀 값은 JSONL 라인이나 메시지가 디스크에 기록되기 전에 가려집니다.

logging.redactSensitive: off | tools(기본값: tools)
logging.redactPatterns: 정규식 문자열 배열(기본값 재정의)
- 원시 정규식 문자열(자동 gi)을 사용하거나 사용자 지정 플래그를 지정하려면 /pattern/flags를 사용합니다.
- 일치 항목은 처음 6자와 마지막 4자를 유지한 채 가려집니다(18자 이상인 값). 더 짧은 값은 ***가 됩니다.
- 기본 패턴은 일반적인 키 할당, CLI 플래그, JSON 필드, 베어러 헤더, PEM 블록, 널리 사용되는 공급업체 토큰 접두사 및 결제 자격 증명 필드 이름(카드 번호, CVC/CVV, 공유 결제 토큰, 결제 자격 증명)을 포함합니다.

일부 안전 경계에서는 logging.redactSensitive 설정과 관계없이 항상 민감 정보를 가립니다. 여기에는 Control UI 도구 호출 이벤트, sessions_history 도구 출력, 진단 지원 내보내기, 제공자 오류 관찰, 실행 승인 명령 표시 및 Gateway WebSocket 프로토콜 로그가 포함됩니다. 이러한 표면에서도 추가 패턴으로 logging.redactPatterns가 적용되지만, redactSensitive: "off"로 설정해도 원시 비밀 정보가 출력되지는 않습니다.

Gateway WebSocket 로그

Gateway는 WebSocket 프로토콜 로그를 두 가지 모드로 출력합니다.

일반 모드(--verbose 없음): 오류(ok=false), 느린 호출(기본 임계값: >= 50ms) 및 구문 분석 오류와 같은 "주목할 만한" RPC 결과만 출력합니다.
상세 모드(--verbose): 모든 WS 요청/응답 트래픽을 출력합니다.

WS 로그 형식

openclaw gateway는 Gateway별 형식 전환 옵션을 지원합니다.

--ws-log auto(기본값): 일반 모드는 최적화된 형식을 사용하고, 상세 모드는 간결한 출력을 사용합니다.
--ws-log compact: 상세 모드에서 간결한 출력(요청/응답 쌍)을 사용합니다.
--ws-log full: 상세 모드에서 프레임별 전체 출력을 사용합니다.
--compact: --ws-log compact의 별칭입니다.

bash

# 최적화됨(오류/느린 호출만)openclaw gateway # 모든 WS 트래픽 표시(요청/응답 쌍)openclaw gateway --verbose --ws-log compact # 모든 WS 트래픽 표시(전체 메타데이터)openclaw gateway --verbose --ws-log full

콘솔 서식 지정(하위 시스템 로깅)

콘솔 포매터는 TTY를 인식하며 일관된 접두사가 있는 라인을 출력합니다. 하위 시스템 로거는 출력을 그룹화해 쉽게 훑어볼 수 있도록 유지합니다.

모든 라인에 하위 시스템 접두사를 표시합니다(예: [gateway], [canvas], [tailscale]).
하위 시스템 색상(이름을 해시해 하위 시스템별로 고정)과 로그 수준 색상을 사용합니다.
출력이 TTY이거나 환경이 리치 터미널처럼 보이는 경우(TERM/COLORTERM/TERM_PROGRAM) 색상을 사용하며, NO_COLOR와 FORCE_COLOR를 따릅니다.
축약된 하위 시스템 접두사: 선행 gateway/, channels/ 또는 providers/ 세그먼트를 제거한 다음, 나머지 세그먼트 중 마지막 2개까지만 유지합니다(예: channels/turn/kernel은 turn/kernel로 표시). 알려진 채널 하위 시스템(telegram, whatsapp, slack 등)은 항상 채널 이름만 남도록 축약됩니다.
하위 시스템별 하위 로거(자동 접두사 + 구조화된 필드 { subsystem })를 사용합니다.
QR/UX 출력에는 **logRaw()**를 사용합니다(접두사 및 서식 없음).
콘솔 형식: pretty | compact | json.
콘솔 로그 수준은 파일 로그 수준과 별개입니다(logging.level이 debug/trace인 경우 파일에는 전체 세부 정보가 유지됨).
WhatsApp 메시지 본문은 debug 수준으로 기록됩니다(표시하려면 --verbose 사용).

이를 통해 파일 로그를 안정적으로 유지하면서 대화형 출력을 쉽게 훑어볼 수 있습니다.