OpenClaw 감사 로그 및 작업 기록

서문

OpenClaw 서비스의 사용자가 늘어나고 팀 협업이 깊어짐에 따라, 누가 어떤 시간에 어떤 채널을 통해 어떤 작업을 수행했는지 명확히 알아야 합니다. 설정을 누가 수정했는지, 민감한 명령을 누가 실행했는지 파악해야 합니다. 감사 로그(Audit Log)는 이러한 질문에 답하는 핵심 도구입니다. 이 글에서는 OpenClaw의 감사 로그 설정 및 사용 방법을 전면적으로 설명합니다.

1. 감사 로그란

감사 로그는 운영 로그와 다릅니다. 운영 로그는 시스템의 기술적 상태(오류, 성능, 연결)를 기록하는 반면, 감사 로그는 사용자와 관리자의 작업 행위를 기록하며, **"누가(Who) 언제(When) 무엇을(What) 했는가"**라는 핵심 질문에 답합니다.

1.1 감사 로그가 기록하는 이벤트 유형

2. 감사 로그 활성화

2.1 기본 설정

// ~/.config/openclaw/openclaw.json5
{
  "audit": {
    "enabled": true,
    // 감사 로그 저장 경로
    "logDir": "~/.openclaw/audit/",
    // 로그 형식
    "format": "json",
    // 기록 레벨: minimal / standard / verbose
    "level": "standard",
    // 보존 일수
    "retention": 90
  }
}

2.2 기록 레벨 설명

2.3 선택적 기록

어떤 이벤트를 기록할지 세밀하게 제어할 수 있습니다:

{
  "audit": {
    "enabled": true,
    "events": {
      "message.received": true,
      "message.sent": true,
      "message.failed": true,
      "config.changed": true,
      "config.apiKeyRotated": true,
      "service.started": true,
      "service.stopped": true,
      "service.restarted": true,
      "auth.login": true,
      "auth.failed": true,
      "user.banned": true,
      "user.unbanned": true,
      "channel.connected": true,
      "channel.disconnected": true,
      "channel.added": true,
      "channel.removed": true,
      "skill.installed": true,
      "skill.executed": true
    }
  }
}

3. 감사 로그 형식

3.1 JSON 로그 구조

각 감사 기록에는 다음 표준 필드가 포함됩니다:

{
  "id": "audit_20260314_001",
  "timestamp": "2026-03-14T09:15:32.456Z",
  "event": "message.received",
  "actor": {
    "type": "user",
    "id": "telegram:123456789",
    "name": "홍길동"
  },
  "target": {
    "type": "channel",
    "id": "telegram",
    "name": "Telegram Bot"
  },
  "action": "send_message",
  "details": {
    "messageId": "msg_abc123",
    "messageType": "text",
    "length": 42
  },
  "result": "success",
  "ip": null,
  "userAgent": null
}

3.2 설정 변경 감사 기록

{
  "id": "audit_20260314_002",
  "timestamp": "2026-03-14T10:30:00.000Z",
  "event": "config.changed",
  "actor": {
    "type": "admin",
    "id": "dashboard:admin",
    "ip": "192.168.1.100"
  },
  "action": "update_config",
  "details": {
    "path": "model.model",
    "oldValue": "claude-3-5-haiku",
    "newValue": "claude-3.5-sonnet",
    "method": "dashboard"
  },
  "result": "success"
}

3.3 보안 이벤트 감사 기록

{
  "id": "audit_20260314_003",
  "timestamp": "2026-03-14T11:00:00.000Z",
  "event": "auth.failed",
  "actor": {
    "type": "unknown",
    "ip": "203.0.113.50"
  },
  "action": "dashboard_login",
  "details": {
    "reason": "invalid_password",
    "attemptCount": 3
  },
  "result": "failure"
}

4. 감사 로그 조회

4.1 openclaw audit 명령 사용

# 최근 감사 로그 확인
openclaw audit log

# 이벤트 유형별 필터링
openclaw audit log --event config.changed
openclaw audit log --event auth.failed

# 시간 범위별 필터링
openclaw audit log --since "2026-03-14 09:00" --until "2026-03-14 18:00"

# 수행자별 필터링
openclaw audit log --actor "telegram:123456789"

# 결과별 필터링
openclaw audit log --result failure

# 복합 필터링
openclaw audit log --event config.changed --since 7d --format table

4.2 테이블 형식 출력

openclaw audit log --since today --format table

┌──────────────────────┬──────────────────┬──────────────────┬─────────┐
│ 시간                  │ 이벤트           │ 수행자            │ 결과    │
├──────────────────────┼──────────────────┼──────────────────┼─────────┤
│ 2026-03-14 09:15:32  │ message.received │ telegram:123456  │ success │
│ 2026-03-14 09:15:34  │ message.sent     │ system           │ success │
│ 2026-03-14 10:30:00  │ config.changed   │ dashboard:admin  │ success │
│ 2026-03-14 11:00:00  │ auth.failed      │ 203.0.113.50     │ failure │
│ 2026-03-14 14:20:15  │ skill.installed  │ dashboard:admin  │ success │
└──────────────────────┴──────────────────┴──────────────────┴─────────┘

4.3 통계 분석

# 오늘 작업 통계
openclaw audit stats --since today

# 사용자별 메시지 양 통계
openclaw audit stats --group-by actor --since 7d

# 시간대별 메시지 분포 통계
openclaw audit stats --group-by hour --since today

5. Dashboard 감사 조회

5.1 감사 로그 패널

OpenClaw Web Dashboard는 시각적인 감사 로그 조회 인터페이스를 제공합니다:

1. Dashboard를 엽니다 (http://localhost:18789/dashboard)
2. "감사 로그" 페이지로 이동합니다
3. 필터를 사용하여 시간, 이벤트 유형, 수행자별로 필터링합니다
4. CSV/JSON 형식으로 내보내기를 지원합니다

5.2 실시간 이벤트 스트림

Dashboard에서 실시간으로 이벤트 스트림을 확인할 수 있습니다:

● [09:15:32] 홍길동 Telegram을 통해 메시지 전송
● [09:15:34] AI 홍길동에게 응답 (1.7s, 285 tokens)
● [10:30:00] 관리자 모델 설정 변경: haiku → sonnet
● [11:00:00] ⚠ 로그인 실패 출처 203.0.113.50 (3회차)

6. 감사 로그 저장 및 보관

6.1 로그 순환

{
  "audit": {
    "rotation": {
      "maxSize": "100MB",
      "maxAge": 90,
      "compress": true,
      "archiveDir": "~/.openclaw/audit/archive/"
    }
  }
}

6.2 외부 시스템으로 내보내기

{
  "audit": {
    "export": {
      "syslog": {
        "enabled": true,
        "host": "syslog.example.com",
        "port": 514,
        "facility": "auth"
      },
      "webhook": {
        "enabled": true,
        "url": "https://siem.example.com/api/audit",
        "headers": {
          "Authorization": "Bearer YOUR_TOKEN"
        },
        "batchSize": 100,
        "flushInterval": "30s"
      }
    }
  }
}

6.3 정기 보관

# 오래된 감사 로그 수동 보관
openclaw audit archive --older-than 30d

# 지정 시간 범위의 감사 기록 내보내기
openclaw audit export --since "2026-01-01" --until "2026-01-31" --output january-audit.json

7. 보안 및 규정 준수 권장사항

1. 감사 로그 변조 방지: 감사 로그를 독립된 저장 시스템으로 전송하여 변조나 삭제를 방지합니다
2. 보존 기간: 산업 규정 준수 요구에 따라 보존 기간을 설정합니다 (금융업은 보통 최소 1년 보존 필요)
3. 민감 정보 마스킹: 감사 로그에 완전한 API Key나 사용자 메시지 원문을 포함하지 않아야 합니다
4. 접근 제어: 감사 로그 조회 권한을 제한하여 관리자만 접근할 수 있도록 합니다
5. 정기 검토: 매월 보안 관련 이벤트를 검토합니다
6. 알림 연동: 이상 감사 이벤트에 대해 자동 알림을 설정합니다

{
  "audit": {
    "privacy": {
      "maskUserMessages": true,
      "maskApiKeys": true,
      "maskPhoneNumbers": true
    }
  }
}

감사 로그는 운영 모니터링 체계에서 필수적인 부분입니다. 문제 근본 원인 추적, 작업 이력 역추적은 물론, 보안 규정 준수 요구를 충족하는 기본 인프라입니다. standard 레벨부터 시작하여 실제 필요에 따라 기록 범위를 점진적으로 조정하는 것을 권장합니다.