OpenClaw Logging 가이드: 로그로 문제 해결하기

시스템에 문제가 생겼을 때 로그만큼 확실한 해결사는 없죠. 터미널에서 로그 파일을 한 줄씩 따라가다 보면 어느새 정답을 발견하게 되는 경우가 정말 많아요.

OpenClaw는 로그를 두 곳에 기록해요. 기계가 읽기 좋은 JSON 파일과 사람이 읽기 편한 console(콘솔)이에요. 이 로그들을 어떻게 찾고 활용하는지 설명해 드릴게요.

필요한 것

• 실행 중인 OpenClaw Gateway
• OpenClaw 설정 파일 (JSON5)

빠른 시작

가장 빠르게 로그를 확인하는 방법은 CLI를 사용하는 거예요. 5분도 안 걸려요.

openclaw logs --follow

출력 모드 옵션:

• TTY: 색상이 입혀진 읽기 쉬운 구조화된 데이터
• Non-TTY: 일반 텍스트
• --json: 한 줄씩 구분된 JSON 형식
• --plain: 강제로 일반 텍스트 출력
• --no-color: ANSI 색상 제거

Where Logs Live

기본적으로 Gateway는 다음 경로에 롤링 로그 파일을 생성해요:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

경로를 바꾸고 싶다면 설정 파일에서 수정하세요:

{
  logging: {
    file: "/custom/path/openclaw.log"
  }
}

Reading Logs

Control UI 활용

Control UI의 Logs 탭에서도 동일한 로그를 실시간으로 볼 수 있어요. openclaw control 명령어로 실행하세요.

특정 채널 로그만 보기

특정 채널의 활동만 필터링해서 볼 수도 있어요:

openclaw channels logs --channel whatsapp

Log Levels

로그의 상세 정도를 조절할 수 있어요.

{
  logging: {
    level: "info",           // 파일 로그 레벨
    consoleLevel: "info",    // 콘솔 출력 레벨
    consoleStyle: "pretty"   // pretty | compact | json
  }
}

사용 가능한 레벨은 trace, debug, info, warn, error 순이에요. --verbose 플래그는 콘솔 출력에만 영향을 주고 파일 로그에는 영향을 주지 않아요.

Redaction (민감 정보 보호)

콘솔 출력에서 민감한 데이터를 가릴 수 있어요.

{
  logging: {
    redactSensitive: "tools",        // off | tools
    redactPatterns: ["sk-.*"]        // 커스텀 정규식 패턴
  }
}

이 설정은 콘솔에만 적용돼요. 파일 로그에는 모든 정보가 그대로 기록되니 주의하세요.

Diagnostics & OpenTelemetry

운영 환경에서 모니터링이 필요하다면 Metrics와 Traces를 외부 스택으로 내보낼 수 있어요.

Diagnostics 활성화

{
  diagnostics: {
    enabled: true
  }
}

OpenTelemetry 설정

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true }
    }
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true
    }
  }
}

내보내는 데이터 항목

Metrics:

• openclaw.tokens: Token 사용량 카운터
• openclaw.cost.usd: 비용 추적
• openclaw.run.duration_ms: 실행 시간 히스토그램
• openclaw.webhook.received: Webhook 활동
• openclaw.message.processed: 메시지 처리량

Traces:

• openclaw.model.usage: 모델 completion 구간
• openclaw.webhook.processed: Webhook 처리 과정
• openclaw.message.processed: 메시지 핸들링

Debug Flags

전체 로그 레벨을 높이지 않고도 특정 부분의 로그만 상세히 볼 수 있어요.

{
  diagnostics: {
    flags: ["telegram.http", "telegram.payload"]
  }
}

환경 변수로도 설정 가능해요:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

와일드카드(telegram.* 또는 *)도 지원해요.

문제 해결

”Gateway not reachable” 메시지가 떠요

다음 명령어를 실행해 보세요:

openclaw doctor

로그가 비어 있어요

• Gateway가 실제로 실행 중인지 확인하세요.
• logging.file 경로가 올바른지 확인하세요.

더 자세한 정보가 필요해요

logging.level을 debug나 trace로 설정해 보세요:

{
  logging: {
    level: "debug"
  }
}

JSON Mode Details

--json 모드에서 CLI는 다음과 같은 타입 태그가 붙은 객체를 출력해요.

Type	Description
meta	스트림 메타데이터 (file, cursor, size)
log	파싱된 로그 엔트리
notice	로그 잘림 또는 로테이션 힌트
raw	파싱되지 않은 원본 로그 라인

Protocol Notes

• OTLP/HTTP 엔드포인트는 diagnostics.otel.endpoint 또는 OTEL_EXPORTER_OTLP_ENDPOINT를 통해 설정해요.
• 엔드포인트에 /v1/traces, /v1/metrics, /v1/logs가 포함되어 있으면 그대로 사용해요.
• 현재 http/protobuf만 지원하며 grpc는 무시돼요.

Log Export Behavior

• OTLP 로그는 logging.file에 기록되는 것과 동일한 구조화된 레코드를 사용해요.
• logging.level 설정을 따릅니다.
• 콘솔 Redaction 설정은 OTLP 로그에 적용되지 않아요.

여전히 해결되지 않는 문제가 있나요? AI Setup Assistant가 로그 해석을 도와줄 수 있어요.

다음 단계

• Debugging → — Watch 모드 및 raw 스트림 로깅 확인하기
• Testing → — 테스트 스위트와 라이브 테스트 방법
• Gateway Configuration → — 전체 설정 레퍼런스