OpenClaw 로그 설정 및 조회 튜토리얼

서문

로그는 문제를 해결하고 실행 상태를 모니터링하는 중요한 도구입니다. OpenClaw는 다양한 로그 레벨, 출력 형식 및 저장 전략을 지원하는 유연한 로그 시스템을 제공합니다. 이 글에서는 OpenClaw의 로그 기능을 설정하고 활용하는 방법을 전면적으로 소개합니다.

로그 레벨

OpenClaw는 상세한 것부터 간략한 것까지 네 가지 로그 레벨을 지원합니다:

로그 레벨 설정

설정 파일을 통한 설정:

// ~/.config/openclaw/openclaw.json5
{
  log: {
    level: "info"  // debug | info | warn | error
  }
}

커맨드 라인을 통한 설정:

openclaw config set log.level "debug"
openclaw restart

환경 변수를 통한 설정:

export OPENCLAW_LOG_LEVEL="debug"
openclaw up

각 레벨 출력 예시

debug 레벨 - 요청/응답 세부 정보를 포함한 모든 정보를 출력합니다:

[2026-03-22 10:30:15.123] [DEBUG] [gateway] WhatsApp에서 메시지 수신: {from: "+8613800138000", body: "안녕하세요"}
[2026-03-22 10:30:15.125] [DEBUG] [model] Claude API 요청 구성 중, tokens: 1250
[2026-03-22 10:30:15.126] [DEBUG] [model] 요청 헤더: {x-api-key: "sk-ant-***", content-type: "application/json"}
[2026-03-22 10:30:16.890] [DEBUG] [model] Claude API 응답, 소요 시간: 1765ms, tokens: 320
[2026-03-22 10:30:16.892] [DEBUG] [gateway] WhatsApp으로 응답 전송: {to: "+8613800138000", length: 480}

info 레벨 - 핵심 실행 노드를 출력합니다:

[2026-03-22 10:30:15.123] [INFO] [gateway] 메시지 수신 (WhatsApp)
[2026-03-22 10:30:16.890] [INFO] [model] Claude 응답 완료 (1765ms, 320 tokens)
[2026-03-22 10:30:16.895] [INFO] [gateway] 응답 전송 완료 (WhatsApp)

warn 레벨 - 주의가 필요한 상황만 출력합니다:

[2026-03-22 10:30:15.500] [WARN] [model] API 요청 속도가 제한에 근접 (85/100 RPM)
[2026-03-22 10:35:00.000] [WARN] [gateway] WhatsApp 연결이 불안정, 자동 재연결 중

error 레벨 - 오류만 출력합니다:

[2026-03-22 10:30:15.500] [ERROR] [model] Claude API 호출 실패: 401 Unauthorized
[2026-03-22 10:30:15.501] [ERROR] [model] 오류 상세: Invalid API key provided

로그 파일 위치

기본 로그 디렉토리

OpenClaw의 로그 파일은 기본적으로 다음 위치에 저장됩니다:

로그 파일 명명 규칙

로그 파일은 날짜와 유형별로 명명됩니다:

logs/
├── openclaw-2026-03-22.log        # 메인 로그
├── openclaw-2026-03-21.log        # 전날 로그
├── openclaw-error-2026-03-22.log  # 오류 전용 로그
├── openclaw-access-2026-03-22.log # 접근 로그
└── openclaw-2026-03-20.log.gz     # 압축 아카이브된 로그

사용자 정의 로그 디렉토리

로그 저장 위치를 변경할 수 있습니다:

// ~/.config/openclaw/openclaw.json5
{
  log: {
    level: "info",
    dir: "/var/log/openclaw"  // 사용자 정의 로그 디렉토리
  }
}

OpenClaw 프로세스가 해당 디렉토리에 대한 쓰기 권한을 가지고 있는지 확인합니다:

sudo mkdir -p /var/log/openclaw
sudo chown $(whoami) /var/log/openclaw

openclaw logs 명령 사용

openclaw logs는 로그를 조회하기 위한 내장 명령으로, 기능이 풍부하고 사용이 간편합니다.

기본 사용법

# 최근 로그 확인 (기본 마지막 50줄 표시)
openclaw logs

# 실시간 로그 추적 (tail -f와 유사)
openclaw logs -f

# 마지막 200줄 로그 표시
openclaw logs -n 200

레벨별 필터링

# 오류 로그만 표시
openclaw logs --level error

# 경고 이상 레벨 표시
openclaw logs --level warn

# 디버그 이상 레벨 표시 (모든 로그)
openclaw logs --level debug

시간 범위별 필터링

# 오늘의 로그 확인
openclaw logs --since today

# 최근 1시간의 로그 확인
openclaw logs --since 1h

# 지정된 시간 범위 확인
openclaw logs --since "2026-03-22 10:00" --until "2026-03-22 12:00"

컴포넌트별 필터링

# 게이트웨이 관련 로그만 확인
openclaw logs --component gateway

# 모델 호출 로그만 확인
openclaw logs --component model

# 특정 채널의 로그만 확인
openclaw logs --component channel:whatsapp

조합 필터링

여러 필터링 조건을 조합하여 사용할 수 있습니다:

# 오늘 WhatsApp 채널의 오류 로그를 실시간으로 추적
openclaw logs --level error --component channel:whatsapp --since today -f

로그 로테이션

로그 파일이 무한히 커지는 것을 방지하기 위해 OpenClaw에는 로그 로테이션 메커니즘이 내장되어 있습니다.

기본 로테이션 정책

{
  log: {
    rotation: {
      // 단일 로그 파일 최대 크기
      maxSize: "50MB",
      // 로그 파일 보존 일수
      maxAge: 30,
      // 최대 보존 로그 파일 수
      maxFiles: 90,
      // 아카이브된 로그를 압축할지 여부
      compress: true
    }
  }
}

로테이션 정책 설명

• 단일 로그 파일이 maxSize를 초과하면 자동으로 새 파일이 생성됩니다
• maxAge일이 지난 오래된 로그는 자동으로 삭제됩니다
• 로그 파일 총 수가 maxFiles를 초과하면 가장 오래된 파일이 삭제됩니다
• compress를 활성화하면 아카이브 로그가 gzip으로 압축되어 디스크 공간을 절약합니다

수동 로그 정리

로그 파일을 수동으로 정리해야 하는 경우:

# 로그 파일이 차지하는 디스크 공간 확인
du -sh ~/.local/share/openclaw/logs/

# 7일 이전의 로그 삭제
find ~/.local/share/openclaw/logs/ -name "*.log" -mtime +7 -delete

# 압축된 모든 오래된 로그 삭제
find ~/.local/share/openclaw/logs/ -name "*.gz" -delete

JSON 구조화 로그

로그 분석 도구(예: ELK, Grafana Loki)로 로그를 처리해야 하는 경우 OpenClaw는 JSON 형식 출력을 지원합니다.

JSON 형식 활성화

{
  log: {
    level: "info",
    format: "json"  // "text"(기본) 또는 "json"
  }
}

JSON 로그 예시

{
  "timestamp": "2026-03-22T10:30:15.123Z",
  "level": "info",
  "component": "gateway",
  "message": "메시지 수신",
  "meta": {
    "channel": "whatsapp",
    "from": "+8613800138000",
    "messageId": "msg_abc123",
    "messageType": "text"
  }
}

{
  "timestamp": "2026-03-22T10:30:16.890Z",
  "level": "info",
  "component": "model",
  "message": "API 호출 완료",
  "meta": {
    "model": "claude-3.5-sonnet",
    "latency": 1765,
    "inputTokens": 1250,
    "outputTokens": 320,
    "cost": 0.0058
  }
}

JSON 로그를 분석 도구로 가져오기

Filebeat와 연동하여 Elasticsearch로 로그를 전송합니다:

# filebeat.yml
filebeat.inputs:
  - type: log
    paths:
      - /home/user/.local/share/openclaw/logs/openclaw-*.log
    json.keys_under_root: true
    json.add_error_key: true

output.elasticsearch:
  hosts: ["localhost:9200"]
  index: "openclaw-logs-%{+yyyy.MM.dd}"

콘솔 출력 설정

파일 로그 외에도 터미널 출력 동작을 제어할 수 있습니다:

{
  log: {
    level: "info",
    console: {
      enabled: true,       // 터미널에 로그를 출력할지 여부
      colorize: true,      // 색상 출력 여부
      timestamp: true      // 타임스탬프 표시 여부
    }
  }
}

openclaw up -d(백그라운드 모드)로 실행할 때는 콘솔 출력이 자동으로 비활성화됩니다.

요약

적절한 로그 설정은 문제를 빠르게 발견하고 진단하는 데 도움이 됩니다. 다음은 권장하는 설정 방안입니다:

• 개발 환경: 로그 레벨을 debug로 설정하고, 텍스트 형식을 사용하여 실시간으로 편리하게 확인
• 운영 환경: 로그 레벨을 info로 설정하고, 로그 로테이션과 압축을 활성화
• 클러스터 배포: JSON 형식을 사용하고, 로그 수집 도구와 연동하여 중앙 관리
• 문제 해결: 임시로 debug 레벨로 전환하고, openclaw logs -f와 함께 실시간 추적

디스크 공간 사용량을 정기적으로 확인하여 로그 파일이 너무 커져 시스템 운영에 영향을 미치지 않도록 하십시오.