로깅

OpenClaw는 두 곳에 로그를 기록합니다.

  • 파일 로그 (JSON lines) — Gateway가 기록합니다.
  • 콘솔 출력 — 터미널과 Control UI에 표시됩니다.

이 페이지에서는 로그 위치, 읽는 방법, 로그 레벨 및 형식 설정 방법을 설명합니다.

로그 위치

기본적으로 Gateway는 다음 경로에 롤링 로그 파일을 기록합니다.

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

날짜는 Gateway 호스트의 로컬 시간대를 사용합니다.

~/.openclaw/openclaw.json에서 경로를 변경할 수 있습니다.

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

로그 읽기

CLI: 실시간 테일링 (권장)

CLI를 사용해 RPC로 Gateway 로그 파일을 테일링합니다.

openclaw logs --follow

출력 모드:

  • TTY 세션: 색상이 적용된 구조화 로그.
  • 비TTY 세션: 일반 텍스트.
  • --json: 줄 단위 JSON (이벤트당 한 줄).
  • --plain: TTY 세션에서도 일반 텍스트 강제.
  • --no-color: ANSI 색상 비활성화.

JSON 모드에서 CLI는 type 태그가 달린 객체를 출력합니다.

  • meta: 스트림 메타데이터 (파일, 커서, 크기)
  • log: 파싱된 로그 항목
  • notice: 잘림/로테이션 힌트
  • raw: 파싱되지 않은 로그 줄

Gateway에 연결할 수 없으면 CLI가 다음을 실행하라는 안내를 출력합니다.

openclaw doctor

Control UI (웹)

Control UI의 Logs 탭은 logs.tail을 사용해 동일한 파일을 테일링합니다. 여는 방법은 /web/control-ui를 참고하세요.

채널 전용 로그

채널 활동(WhatsApp/Telegram 등)만 필터링하려면 다음을 사용합니다.

openclaw channels logs --channel whatsapp

로그 형식

파일 로그 (JSONL)

로그 파일의 각 줄은 JSON 객체입니다. CLI와 Control UI가 이 항목을 파싱해 구조화된 출력(시간, 레벨, 서브시스템, 메시지)을 렌더링합니다.

콘솔 출력

콘솔 로그는 TTY 인식 방식으로 가독성에 맞게 포맷됩니다.

  • 서브시스템 접두사 (예: gateway/channels/whatsapp)
  • 레벨별 색상 (info/warn/error)
  • 선택적 컴팩트 또는 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 (로그 프로세서용).

민감 정보 마스킹

도구 요약에서 콘솔에 출력하기 전에 민감한 토큰을 마스킹할 수 있습니다.

  • logging.redactSensitive: off | tools (기본값: tools)
  • logging.redactPatterns: 기본 세트를 대체할 정규식 문자열 목록

마스킹은 콘솔 출력에만 적용되며 파일 로그는 변경하지 않습니다.

진단 + OpenTelemetry

진단은 모델 실행 및 메시지 흐름 텔레메트리(웹훅, 큐, 세션 상태)를 위한 구조화된 머신 리더블 이벤트입니다. 로그를 대체하지 않으며, 메트릭, 트레이스 등 익스포터에 데이터를 제공하기 위해 존재합니다.

진단 이벤트는 프로세스 내부에서 생성되지만, 익스포터는 진단과 익스포터 플러그인이 모두 활성화된 경우에만 연결됩니다.

OpenTelemetry vs OTLP

  • OpenTelemetry (OTel): 트레이스, 메트릭, 로그를 위한 데이터 모델 + SDK.
  • OTLP: OTel 데이터를 컬렉터/백엔드로 내보내는 와이어 프로토콜.
  • OpenClaw는 현재 **OTLP/HTTP (protobuf)**로 내보냅니다.

내보내는 시그널

  • 메트릭: 카운터 + 히스토그램 (토큰 사용량, 메시지 흐름, 큐).
  • 트레이스: 모델 사용 + 웹훅/메시지 처리 스팬.
  • 로그: 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로 개별 전환할 수 있습니다(기본: 활성). 트레이스에는 모델 사용 스팬과 (활성화 시) 웹훅/메시지 처리 스팬이 포함됩니다.
  • 컬렉터가 인증을 요구하면 headers를 설정하세요.
  • 지원 환경 변수: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

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

모델 사용:

  • openclaw.tokens (counter, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.cost.usd (counter, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.run.duration_ms (histogram, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.context.tokens (histogram, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)

메시지 흐름:

  • openclaw.webhook.received (counter, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.error (counter, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.duration_ms (histogram, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.message.queued (counter, attrs: openclaw.channel, openclaw.source)
  • openclaw.message.processed (counter, attrs: openclaw.channel, openclaw.outcome)
  • openclaw.message.duration_ms (histogram, attrs: openclaw.channel, openclaw.outcome)

큐 + 세션:

  • openclaw.queue.lane.enqueue (counter, attrs: openclaw.lane)
  • openclaw.queue.lane.dequeue (counter, attrs: openclaw.lane)
  • openclaw.queue.depth (histogram, attrs: openclaw.lane 또는 openclaw.channel=heartbeat)
  • openclaw.queue.wait_ms (histogram, attrs: openclaw.lane)
  • openclaw.session.state (counter, attrs: openclaw.state, openclaw.reason)
  • openclaw.session.stuck (counter, attrs: openclaw.state)
  • openclaw.session.stuck_age_ms (histogram, attrs: openclaw.state)
  • openclaw.run.attempt (counter, attrs: openclaw.attempt)

내보내는 스팬 (이름 + 주요 속성)

  • openclaw.model.usage
    • openclaw.channel, openclaw.provider, openclaw.model
    • openclaw.sessionKey, openclaw.sessionId
    • openclaw.tokens.* (input/output/cache_read/cache_write/total)
  • openclaw.webhook.processed
    • openclaw.channel, openclaw.webhook, openclaw.chatId
  • openclaw.webhook.error
    • openclaw.channel, openclaw.webhook, openclaw.chatId, openclaw.error
  • openclaw.message.processed
    • openclaw.channel, openclaw.outcome, openclaw.chatId, openclaw.messageId, openclaw.sessionKey, openclaw.sessionId, openclaw.reason
  • openclaw.session.stuck
    • openclaw.state, openclaw.ageMs, openclaw.queueDepth, openclaw.sessionKey, openclaw.sessionId

샘플링 + 플러싱

  • 트레이스 샘플링: diagnostics.otel.sampleRate (0.0-1.0, 루트 스팬만).
  • 메트릭 내보내기 간격: diagnostics.otel.flushIntervalMs (최소 1000ms).

프로토콜 참고

  • OTLP/HTTP 엔드포인트는 diagnostics.otel.endpoint 또는 OTEL_EXPORTER_OTLP_ENDPOINT로 설정할 수 있습니다.
  • 엔드포인트에 이미 /v1/traces 또는 /v1/metrics가 포함되어 있으면 그대로 사용됩니다.
  • 엔드포인트에 이미 /v1/logs가 포함되어 있으면 로그에 그대로 사용됩니다.
  • diagnostics.otel.logs로 메인 로거 출력의 OTLP 로그 내보내기를 활성화합니다.

로그 내보내기 동작

  • OTLP 로그는 logging.file에 기록되는 것과 동일한 구조화 레코드를 사용합니다.
  • logging.level(파일 로그 레벨)을 따릅니다. 콘솔 마스킹은 OTLP 로그에 적용되지 않습니다.
  • 대용량 환경에서는 OTLP 컬렉터 샘플링/필터링을 사용하는 것이 좋습니다.

문제 해결 팁

  • Gateway에 접속할 수 없나요? 먼저 openclaw doctor를 실행하세요.
  • 로그가 비어있나요? Gateway가 실행 중이고 logging.file의 경로에 기록하고 있는지 확인하세요.
  • 더 자세한 정보가 필요한가요? logging.level을 debug 또는 trace로 설정하고 다시 시도하세요.
다음
Overview
arrow_forward