Logging

OpenClaw는 두 곳에 로그를 남깁니다:

  • 파일 로그 (JSON 라인) 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 (web)

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

Channel 전용 로그

Channel 활동(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: 콘솔 상세 레벨.

--verbose는 콘솔 출력에만 영향을 미칩니다. 파일 로그 레벨을 변경하지 않습니다.

콘솔 스타일

logging.consoleStyle:

  • pretty: 사람 친화적, 컬러, 타임스탬프 포함.
  • compact: 더 타이트한 출력 (긴 세션에 가장 적합).
  • json: 라인당 JSON (로그 프로세서용).

Redaction

Tool 요약은 콘솔에 도달하기 전에 민감한 Token을 Redact할 수 있습니다:

  • logging.redactSensitive: off | tools (기본값: tools)
  • logging.redactPatterns: 기본 세트를 재정의하는 정규식 문자열 목록

Redaction은 콘솔 출력만 영향을 미치며 파일 로그를 변경하지 않습니다.

Diagnostics + OpenTelemetry

Diagnostics는 모델 실행 및 메시지 흐름 텔레메트리(Webhook, 큐잉, Session 상태)를 위한 구조화된 기계 판독 가능 이벤트입니다. 로그를 대체하지 않습니다. 메트릭, 추적 및 기타 Exporter를 공급하기 위해 존재합니다.

Diagnostics 이벤트는 프로세스 내에서 발생하지만 Exporter는 Diagnostics + Exporter Plugin이 활성화된 경우에만 연결됩니다.

OpenTelemetry vs OTLP

  • OpenTelemetry (OTel): 추적, 메트릭 및 로그를 위한 데이터 모델 + SDK.
  • OTLP: OTel 데이터를 Collector/백엔드로 내보내는 데 사용되는 와이어 프로토콜.
  • OpenClaw는 오늘 **OTLP/HTTP (protobuf)**를 통해 내보냅니다.

내보내는 신호

  • Metrics: 카운터 + 히스토그램 (Token 사용량, 메시지 흐름, 큐잉).
  • Traces: 모델 사용 + Webhook/메시지 처리를 위한 Span.
  • Logs: diagnostics.otel.logs가 활성화된 경우 OTLP를 통해 내보내집니다. 로그 볼륨이 높을 수 있습니다. logging.level 및 Exporter 필터를 염두에 두세요.

Diagnostic 이벤트 카탈로그

모델 사용:

  • model.usage: Token, 비용, 기간, 컨텍스트, Provider/모델/Channel, Session ID.

메시지 흐름:

  • webhook.received: Channel별 Webhook 수신.
  • webhook.processed: Webhook 처리 + 기간.
  • webhook.error: Webhook 핸들러 오류.
  • message.queued: 처리를 위해 대기 중인 메시지.
  • message.processed: 결과 + 기간 + 선택적 오류.

큐 + Session:

  • queue.lane.enqueue: 명령 큐 레인 대기열 + 깊이.
  • queue.lane.dequeue: 명령 큐 레인 대기열 해제 + 대기 시간.
  • session.state: Session 상태 전환 + 이유.
  • session.stuck: Session 정체 경고 + 나이.
  • run.attempt: 실행 재시도/시도 메타데이터.
  • diagnostic.heartbeat: 집계 카운터 (Webhook/큐/Session).

Diagnostics 활성화 (Exporter 없음)

Plugin이나 커스텀 싱크에서 Diagnostics 이벤트를 사용할 수 있도록 하려면 다음을 사용하세요:

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

Diagnostics 플래그 (대상 로그)

플래그를 사용하여 logging.level을 올리지 않고 추가적인 대상 디버그 로그를 켭니다. 플래그는 대소문자를 구분하지 않으며 와일드카드를 지원합니다 (예: telegram.* 또는 *).

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

환경 재정의 (일회성):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

참고:

  • 플래그 로그는 표준 로그 파일(logging.file과 동일)로 이동합니다.
  • 출력은 여전히 logging.redactSensitive에 따라 Redact됩니다.
  • 전체 가이드: /diagnostics/flags.

OpenTelemetry로 내보내기

Diagnostics는 diagnostics-otel Plugin (OTLP/HTTP)을 통해 내보낼 수 있습니다. OTLP/HTTP를 허용하는 모든 OpenTelemetry Collector/백엔드에서 작동합니다.

{
  "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로 Plugin을 활성화할 수도 있습니다.
  • protocol은 현재 http/protobuf만 지원합니다. grpc는 무시됩니다.
  • Metrics에는 Token 사용량, 비용, 컨텍스트 크기, 실행 기간 및 메시지 흐름 카운터/히스토그램 (Webhook, 큐잉, Session 상태, 큐 깊이/대기)이 포함됩니다.
  • Trace/메트릭은 traces / metrics로 전환할 수 있습니다 (기본값: on). Trace에는 모델 사용 Span과 활성화된 경우 Webhook/메시지 처리 Span이 포함됩니다.
  • Collector에 인증이 필요한 경우 headers를 설정하세요.
  • 지원되는 환경 변수: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

내보내는 Metric (이름 + 유형)

모델 사용:

  • openclaw.tokens (카운터, 속성: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.cost.usd (카운터, 속성: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.run.duration_ms (히스토그램, 속성: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.context.tokens (히스토그램, 속성: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)

메시지 흐름:

  • openclaw.webhook.received (카운터, 속성: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.error (카운터, 속성: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.duration_ms (히스토그램, 속성: openclaw.channel, openclaw.webhook)
  • openclaw.message.queued (카운터, 속성: openclaw.channel, openclaw.source)
  • openclaw.message.processed (카운터, 속성: openclaw.channel, openclaw.outcome)
  • openclaw.message.duration_ms (히스토그램, 속성: openclaw.channel, openclaw.outcome)

큐 + Session:

  • openclaw.queue.lane.enqueue (카운터, 속성: openclaw.lane)
  • openclaw.queue.lane.dequeue (카운터, 속성: openclaw.lane)
  • openclaw.queue.depth (히스토그램, 속성: openclaw.lane 또는 openclaw.channel=heartbeat)
  • openclaw.queue.wait_ms (히스토그램, 속성: openclaw.lane)
  • openclaw.session.state (카운터, 속성: openclaw.state, openclaw.reason)
  • openclaw.session.stuck (카운터, 속성: openclaw.state)
  • openclaw.session.stuck_age_ms (히스토그램, 속성: openclaw.state)
  • openclaw.run.attempt (카운터, 속성: openclaw.attempt)

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

  • 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

샘플링 + 플러싱

  • Trace 샘플링: diagnostics.otel.sampleRate (0.0–1.0, 루트 Span만).
  • Metric 내보내기 간격: diagnostics.otel.flushIntervalMs (최소 1000ms).

프로토콜 참고사항

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

로그 내보내기 동작

  • OTLP 로그는 logging.file에 작성된 것과 동일한 구조화된 레코드를 사용합니다.
  • logging.level (파일 로그 레벨)을 존중합니다. 콘솔 Redaction은 OTLP 로그에 적용되지 않습니다.
  • 대용량 설치에서는 OTLP Collector 샘플링/필터링을 선호해야 합니다.

문제 해결 팁

  • Gateway에 연결할 수 없습니까? 먼저 openclaw doctor를 실행하세요.
  • 로그가 비어 있습니까? Gateway가 실행 중이고 logging.file의 파일 경로에 작성 중인지 확인하세요.
  • 더 자세한 정보가 필요하십니까? logging.level을 debug 또는 trace로 설정하고 다시 시도하세요.
← 문서로 돌아가기