OpenClaw Audit Logs and Operation Records

Introduction

As your OpenClaw service gains more users and team collaboration deepens, you need clear answers to questions like: Who performed what action, through which channel, and at what time? Who modified the configuration? Who executed sensitive commands? Audit logs are the key tool for answering these questions. This article provides a comprehensive guide to configuring and using OpenClaw's audit logging capabilities.

1. What Are Audit Logs

Audit logs differ from runtime logs. Runtime logs record the system's technical state (errors, performance, connections), while audit logs record user and administrator actions, answering the core question of "Who (Who) did What (What) and When (When)".

1.1 Event Types Recorded by Audit Logs

Category	Example Events
Message Operations	User sends message, AI replies to message
Configuration Changes	Model settings modified, channel added, API key updated
Administrative Actions	Start/stop service, restart, upgrade
Security Events	Dashboard login, authentication failure, user banned
Channel Operations	Channel connected/disconnected, channel added/removed
Skill Operations	Skill installed/uninstalled, skill execution records

2. Enabling Audit Logs

2.1 Basic Configuration

// ~/.config/openclaw/openclaw.json5
{
  "audit": {
    "enabled": true,
    // Audit log storage path
    "logDir": "~/.openclaw/audit/",
    // Log format
    "format": "json",
    // Recording level: minimal / standard / verbose
    "level": "standard",
    // Retention days
    "retention": 90
  }
}

2.2 Recording Level Descriptions

Level	What's Recorded	Disk Usage	Use Case
`minimal`	Configuration changes and administrative actions only	Very low	Personal use
`standard`	Configuration changes + message summaries + security events	Moderate	Team use
`verbose`	All events, including message content summaries	Higher	Strict compliance scenarios

2.3 Selective Recording

You can fine-tune which events to record:

{
  "audit": {
    "enabled": true,
    "events": {
      // Message operations
      "message.received": true,
      "message.sent": true,
      "message.failed": true,
      // Configuration changes
      "config.changed": true,
      "config.apiKeyRotated": true,
      // Administrative actions
      "service.started": true,
      "service.stopped": true,
      "service.restarted": true,
      // Security events
      "auth.login": true,
      "auth.failed": true,
      "user.banned": true,
      "user.unbanned": true,
      // Channel operations
      "channel.connected": true,
      "channel.disconnected": true,
      "channel.added": true,
      "channel.removed": true,
      // Skill operations
      "skill.installed": true,
      "skill.executed": true
    }
  }
}

3. Audit Log Format

3.1 JSON Log Structure

Each audit record contains the following standard fields:

{
  "id": "audit_20260314_001",
  "timestamp": "2026-03-14T09:15:32.456Z",
  "event": "message.received",
  "actor": {
    "type": "user",
    "id": "telegram:123456789",
    "name": "John"
  },
  "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 Configuration Change Audit Record

{
  "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 Security Event Audit Record

{
  "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. Querying Audit Logs

4.1 Using the openclaw audit Command

# View recent audit logs
openclaw audit log

# Filter by event type
openclaw audit log --event config.changed
openclaw audit log --event auth.failed

# Filter by time range
openclaw audit log --since "2026-03-14 09:00" --until "2026-03-14 18:00"

# Filter by actor
openclaw audit log --actor "telegram:123456789"
openclaw audit log --actor "dashboard:admin"

# Filter by result
openclaw audit log --result failure

# Combined filters
openclaw audit log --event config.changed --since 7d --format table

4.2 Table Format Output

openclaw audit log --since today --format table

┌──────────────────────┬──────────────────┬──────────────────┬─────────┐
│ Time                 │ Event            │ Actor            │ Result  │
├──────────────────────┼──────────────────┼──────────────────┼─────────┤
│ 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 Statistical Analysis

# Today's operation statistics
openclaw audit stats --since today

# Output
# Today's Audit Statistics (2026-03-14)
# ─────────────────────────
# Messages sent/received: 342
# Configuration changes:  2
# Successful logins:      3
# Failed logins:          1
# Skill executions:       85
# Active users:           28
# Most active user:       telegram:123456 (52 messages)

# Message count by user
openclaw audit stats --group-by actor --since 7d

# Message distribution by hour
openclaw audit stats --group-by hour --since today

5. Dashboard Audit Viewer

5.1 Audit Log Panel

The OpenClaw Web Dashboard provides a visual audit log viewing interface:

Open the Dashboard (http://localhost:18789/dashboard)
Navigate to the "Audit Logs" page
Use filters to search by time, event type, or actor
Supports export to CSV/JSON formats

5.2 Real-Time Event Stream

The Dashboard allows you to view the event stream in real time:

● [09:15:32] John sent a message via Telegram
● [09:15:34] AI replied to John (1.7s, 285 tokens)
● [10:30:00] Admin changed model config: haiku → sonnet
● [11:00:00] ⚠ Login failed from 203.0.113.50 (3rd attempt)

6. Audit Log Storage and Archival

6.1 Log Rotation

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

6.2 Export to External Systems

Send audit logs to a centralized log management platform:

{
  "audit": {
    "export": {
      // Send to Syslog
      "syslog": {
        "enabled": true,
        "host": "syslog.example.com",
        "port": 514,
        "facility": "auth"
      },
      // Send to Webhook (can integrate with SIEM systems)
      "webhook": {
        "enabled": true,
        "url": "https://siem.example.com/api/audit",
        "headers": {
          "Authorization": "Bearer YOUR_TOKEN"
        },
        "batchSize": 100,
        "flushInterval": "30s"
      }
    }
  }
}

6.3 Periodic Archival

# Manually archive old audit logs
openclaw audit archive --older-than 30d

# Export audit records for a specific time range
openclaw audit export --since "2026-01-01" --until "2026-01-31" --output january-audit.json

7. Security and Compliance Recommendations

Audit log immutability: Send audit logs to an independent storage system to prevent tampering or deletion
Retention period: Set retention periods according to industry compliance requirements (financial industries typically require at least 1 year)
Sensitive data masking: Audit logs should not contain full API keys or raw user message content
Access control: Restrict audit log viewing permissions to administrators only
Regular review: Review security-related events monthly (failed logins, configuration changes, unusual activity patterns)
Alert integration: Configure automatic alerts for anomalous audit events (such as multiple failed login attempts)

{
  "audit": {
    // Privacy protection: mask sensitive fields
    "privacy": {
      "maskUserMessages": true,   // Do not log raw message content
      "maskApiKeys": true,        // Show only first and last few characters of API keys
      "maskPhoneNumbers": true    // Replace middle digits of phone numbers with *
    }
  }
}

Audit logs are an indispensable part of any operations monitoring system. They not only help you trace the root cause of issues and review operation history, but also serve as foundational infrastructure for meeting security compliance requirements. It is recommended to start with the standard level and gradually adjust the recording scope based on your actual needs.