OpenClaw 로그 마스터하기: 효율적인 디버깅과 모니터링 가이드

개발을 하다 보면 로그가 너무 많아서 정작 필요한 정보를 찾기 힘들 때가 있죠. 반대로 중요한 순간에 로그가 부족해서 디버깅이 막막해지기도 하고요. 특히 보안이 중요한 프로젝트에서는 로그에 민감한 정보가 찍히지 않을까 걱정되기도 합니다. OpenClaw는 이런 고민을 해결할 수 있도록 체계적이고 유연한 로깅 시스템을 갖추고 있어요.

필요한 것

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

• OpenClaw CLI 설치
• ~/.openclaw/openclaw.json 설정 파일에 대한 접근 권한
• Gateway 호스트의 /tmp/openclaw/ 디렉토리 접근 권한

빠른 시작

OpenClaw 로그를 확인하고 설정하는 가장 빠른 방법입니다.

1. 실시간 로그 확인: 터미널에서 다음 명령어를 입력하면 현재 발생하는 로그를 바로 스트리밍할 수 있어요.

   openclaw logs --follow

2. 로그 파일 위치: 기본적으로 로그는 /tmp/openclaw/ 폴더에 openclaw-YYYY-MM-DD.log 형식으로 저장돼요. 날짜는 Gateway 호스트의 로컬 시간대를 따릅니다.

3. 기본 설정 변경: ~/.openclaw/openclaw.json 파일에서 로그 경로와 레벨을 바꿀 수 있어요.

   {
     "logging": {
       "file": "/your/custom/path.log",
       "level": "info"
     }
   }

4. 콘솔 스타일 변경: 콘솔 출력을 더 보기 편하게 만들고 싶다면 logging.consoleStyle을 pretty, compact, 또는 json으로 설정해 보세요.

주요 로깅 기능 살펴보기

파일 기반 로거

파일 로그는 JSON lines 형식으로 기록되어 나중에 분석하기 좋습니다. logging.level 설정으로 기록되는 정보의 양을 조절할 수 있어요. Control UI의 Logs 탭은 Gateway의 logs.tail 기능을 통해 이 파일을 읽어와서 보여줍니다.

콘솔 캡처 및 스타일

CLI는 console.log부터 console.trace까지 모든 출력을 캡처해서 파일 로그에 기록하는 동시에 터미널에도 출력해요. 특히 TTY를 인식하기 때문에 터미널 환경에 맞춰 subsystem별로 색상과 프리픽스(예: [gateway], [canvas])를 붙여서 가독성을 높여줍니다.

민감 정보 마스킹 (Redaction)

콘솔에 도구 실행 요약(예: 🛠️ Exec: ...)이 찍힐 때 API 키나 토큰 같은 민감한 정보가 노출되지 않도록 마스킹할 수 있어요.

• logging.redactSensitive: tools가 기본값이며, off로 끌 수 있어요.
• logging.redactPatterns: 커스텀 정규표현식을 사용해 마스킹할 패턴을 직접 지정할 수 있습니다. 참고: 이 기능은 콘솔 출력에만 적용되며 파일 로그에는 원본 데이터가 기록됩니다.

Gateway WebSocket 로그

Gateway의 WebSocket 통신 로그는 두 가지 모드로 작동해요.

• 일반 모드: 에러, 느린 호출(50ms 이상), 파싱 에러 등 중요한 RPC 결과만 출력해요.
• Verbose 모드: --verbose 플래그를 사용하면 모든 WS 요청과 응답 트래픽을 보여줍니다.

# 에러와 느린 호출만 확인
openclaw gateway

# 모든 WS 트래픽을 압축된 형태로 확인
openclaw gateway --verbose --ws-log compact

# 모든 WS 트래픽의 상세 메타데이터 확인
openclaw gateway --verbose --ws-log full

문제 해결

Q: --verbose 옵션을 켰는데 왜 파일 로그에는 상세한 내용이 안 나오나요? A: --verbose는 콘솔 출력의 상세도에만 영향을 줍니다. 파일 로그에 더 자세한 내용을 담고 싶다면 ~/.openclaw/openclaw.json 파일에서 logging.level을 debug나 trace로 직접 변경해야 해요.

Q: 로그 프리픽스가 너무 길어서 보기 불편해요. A: OpenClaw는 자동으로 프리픽스를 줄여서 보여줍니다. 예를 들어 gateway/channels/whatsapp/outbound는 whatsapp/outbound로 짧게 표시되어 가독성을 유지해 줍니다.

설정 과정에서 도움이 필요하다면 AI Setup Assistant에게 언제든 물어보세요!

다음 단계

• Logging 상세 개념 및 설정 가이드