OpenClaw 로그 관리: 파일 위치 확인 및 실시간 모니터링 가이드

복잡한 시스템을 운영하다 보면 “대체 어디서 메시지가 누락된 거지?” 또는 “왜 API 응답이 늦어지는 걸까?” 하는 의문이 생길 때가 있죠. 로그는 개발자에게 있어 어둠 속의 등불 같은 존재예요. OpenClaw가 제공하는 강력한 로깅 시스템을 통해 문제를 빠르게 파악하고 시스템의 흐름을 한눈에 확인하는 방법을 알아볼게요.

OpenClaw 로그는 두 곳에 기록돼요.

Gateway가 작성하는 File logs (JSON lines).
터미널과 Control UI에 표시되는 Console output.

이 페이지에서는 로그가 저장되는 위치, 읽는 방법, 그리고 로그 레벨과 형식을 설정하는 방법을 설명할게요.

로그 저장 위치

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

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

날짜는 Gateway 호스트의 로컬 시간대를 사용해요.

이 경로는 ~/.openclaw/openclaw.json에서 변경할 수 있어요.

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

로그 확인 방법

CLI: 실시간 tail (권장)

CLI를 사용하면 RPC를 통해 Gateway 로그 파일을 실시간으로 확인할 수 있어요.

openclaw logs --follow

출력 모드는 다음과 같아요.

TTY sessions: 보기 좋게 색상이 입혀진 구조화된 로그 라인.
Non-TTY sessions: 일반 텍스트.
--json: 라인 단위 JSON (로그 이벤트당 한 라인).
--plain: TTY 세션에서 일반 텍스트 강제 사용.
--no-color: ANSI 색상 비활성화.

JSON 모드에서 CLI는 type 태그가 붙은 객체를 내보내요.

meta: 스트림 메타데이터 (파일, 커서, 크기)
log: 파싱된 로그 엔트리
notice: 잘림(truncation) / 로테이션 힌트
raw: 파싱되지 않은 로그 라인

만약 Gateway에 연결할 수 없다면, CLI는 다음 명령어를 실행하라는 힌트를 보여줄 거예요.

openclaw doctor

Control UI (웹)

Control UI의 Logs 탭은 logs.tail을 사용해 동일한 파일을 추적해요. 여는 방법은 /web/control-ui 문서를 참고하세요.

채널 전용 로그

특정 채널(WhatsApp/Telegram 등)의 활동만 필터링하려면 다음 명령어를 사용하세요.

openclaw channels logs --channel whatsapp

로그 형식

File logs (JSONL)

로그 파일의 각 라인은 JSON 객체예요. CLI와 Control UI는 이 엔트리들을 파싱해서 구조화된 정보(시간, 레벨, 서브시스템, 메시지)로 보여줘요.

Console output

콘솔 로그는 TTY를 인식하며 가독성을 위해 다음과 같이 포맷팅돼요.

서브시스템 접두사 (예: gateway/channels/whatsapp)
레벨별 색상 (info/warn/error)
선택 사항인 compact 또는 JSON 모드

콘솔 포맷팅은 logging.consoleStyle 설정으로 제어해요.

로깅 설정

모든 로깅 설정은 ~/.openclaw/openclaw.json의 logging 항목 아래에 위치해요.

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

로그 레벨

logging.level: 파일 로그 (JSONL) 레벨.
logging.consoleLevel: 콘솔 출력 상세 레벨.

두 설정 모두 OPENCLAW_LOG_LEVEL 환경 변수로 덮어쓸 수 있어요 (예: OPENCLAW_LOG_LEVEL=debug). 환경 변수는 설정 파일보다 우선순위가 높아서, openclaw.json을 수정하지 않고도 일시적으로 상세 로그를 확인할 수 있죠. 또한 글로벌 CLI 옵션인 **--log-level <level>**을 전달할 수도 있어요 (예: openclaw --log-level debug gateway run). 이 옵션은 환경 변수보다도 우선해요.

--verbose 옵션은 콘솔 출력에만 영향을 주며, 파일 로그 레벨은 변경하지 않아요.

콘솔 스타일

logging.consoleStyle 옵션은 다음과 같아요.

pretty: 타임스탬프와 색상이 포함된 읽기 쉬운 형식.
compact: 더 간결한 출력 (긴 세션에 적합).
json: 라인당 JSON 형식 (로그 프로세서용).

민감 정보 마스킹 (Redaction)

도구 요약 정보가 콘솔에 찍히기 전에 민감한 토큰을 마스킹할 수 있어요.

logging.redactSensitive: off | tools (기본값: tools)
logging.redactPatterns: 기본 설정을 대체할 정규식 문자열 리스트

마스킹은 콘솔 출력에만 영향을 주며 파일 로그는 변경하지 않아요.

진단 및 OpenTelemetry

진단(Diagnostics)은 모델 실행 및 메시지 흐름 텔레메트리(웹훅, 큐잉, 세션 상태)를 위한 구조화된 머신러닝 이벤트예요. 로그를 대체하는 것이 아니라 메트릭, 트레이스 및 기타 익스포터에 데이터를 공급하기 위해 존재해요.

진단 이벤트는 프로세스 내부에서 발생하지만, 진단 기능과 익스포터 플러그인이 활성화되었을 때만 익스포터가 연결돼요.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): 트레이스, 메트릭, 로그를 위한 데이터 모델과 SDK.
OTLP: OTel 데이터를 컬렉터나 백엔드로 전송하는 데 사용되는 통신 프로토콜.
OpenClaw는 현재 **OTLP/HTTP (protobuf)**를 통해 데이터를 내보내요.

내보내는 신호 (Signals)

Metrics: 카운터 및 히스토그램 (토큰 사용량, 메시지 흐름, 큐잉).
Traces: 모델 사용 및 웹훅/메시지 처리를 위한 스팬(span).
Logs: diagnostics.otel.logs가 활성화되면 OTLP를 통해 로그를 내보내요. 로그 양이 많을 수 있으니 logging.level과 익스포터 필터를 고려하세요.

진단 이벤트 카탈로그

모델 사용량:

model.usage: 토큰, 비용, 소요 시간, 컨텍스트, 프로바이더/모델/채널, 세션 ID.

메시지 흐름:

webhook.received: 채널별 웹훅 수신.
webhook.processed: 웹훅 처리 완료 및 소요 시간.
webhook.error: 웹훅 핸들러 에러.
message.queued: 처리를 위해 대기열에 추가된 메시지.
message.processed: 결과, 소요 시간 및 선택적 에러.

큐 및 세션:

queue.lane.enqueue: 커맨드 큐 레인 추가 및 깊이.
queue.lane.dequeue: 커맨드 큐 레인 제거 및 대기 시간.
session.state: 세션 상태 전환 및 이유.
session.stuck: 세션 정체 경고 및 경과 시간.
run.attempt: 실행 재시도/시도 메타데이터.
diagnostic.heartbeat: 집계 카운터 (웹훅/큐/세션).

진단 활성화 (익스포터 없음)

플러그인이나 커스텀 싱크에서 진단 이벤트를 사용하고 싶을 때 설정하세요.

{
  "diagnostics": {
    "enabled": true
  }
}

진단 플래그 (타겟 로그)

logging.level을 높이지 않고도 특정 부분의 디버그 로그를 추가로 확인하려면 플래그를 사용하세요. 플래그는 대소문자를 구분하지 않으며 와일드카드(예: telegram.* 또는 *)를 지원해요.

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

환경 변수로 일시적 적용:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

참고:

플래그 로그는 표준 로그 파일(logging.file)에 기록돼요.
출력은 여전히 logging.redactSensitive 설정에 따라 마스킹돼요.
전체 가이드: /diagnostics/flags.

OpenTelemetry로 내보내기

diagnostics-otel 플러그인(OTLP/HTTP)을 통해 진단 데이터를 내보낼 수 있어요. OTLP/HTTP를 수락하는 모든 OpenTelemetry 컬렉터나 백엔드와 호환돼요.

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

참고:

openclaw plugins enable diagnostics-otel 명령어로도 플러그인을 활성화할 수 있어요.
protocol은 현재 http/protobuf만 지원해요. grpc는 무시돼요.
메트릭에는 토큰 사용량, 비용, 컨텍스트 크기, 실행 시간, 메시지 흐름 카운터/히스토그램이 포함돼요.
트레이스와 메트릭은 traces / metrics 옵션으로 켜고 끌 수 있어요 (기본값: on).
컬렉터에서 인증이 필요한 경우 headers를 설정하세요.
지원되는 환경 변수: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

내보내는 메트릭 (이름 및 타입)