Audit Logging for AI Agents

What to Log and Why

An effective audit log records:

• Agent actions — every task started, completed, or failed
• Tool calls — which tools were invoked, with what arguments, and the result
• API requests — provider API calls (without sensitive content if configured)
• File operations — every read and write to the filesystem
• Permission violations — denied tool calls, blocked paths
• Cost events — token usage, budget threshold hits

Enabling Audit Logging

# config.yaml
audit:
  enabled: true
  log_file: "/var/log/openclaw/audit.json"
  log_format: json        # json | text
  log_level: info         # debug | info | warning | error
  rotate:
    max_size_mb: 100      # rotate when file hits 100MB
    max_files: 30         # keep last 30 rotated files
    compress: true        # gzip rotated files

Enable on the fly for a specific run:

openclaw run "your task" \
  --audit \
  --audit-file /tmp/task-audit.json \
  --audit-level debug

Log Format and Fields

Each audit log entry is a JSON object with standard fields:

{
  "timestamp": "2026-03-13T14:22:01.234Z",
  "level": "info",
  "event": "tool_call",
  "task_id": "task-abc123def",
  "session_id": "sess-xyz789",
  "agent": "main",
  "tool": "read_file",
  "args": { "path": "/workspace/src/main.py" },
  "result": "success",
  "duration_ms": 23,
  "tokens_used": 0,
  "cost_usd": 0.0,
  "user": "alice"
}

SIEM Integrations

Elasticsearch + Kibana (ELK Stack)

audit:
  output:
    type: elasticsearch
    hosts: ["https://elasticsearch:9200"]
    index: "openclaw-audit-%{+yyyy.MM.dd}"
    username: "${ES_USER}"
    password: "${ES_PASSWORD}"

Splunk HEC

audit:
  output:
    type: splunk_hec
    endpoint: "https://splunk.example.com:8088/services/collector"
    token: "${SPLUNK_HEC_TOKEN}"
    source: "openclaw"
    sourcetype: "openclaw_audit"

Datadog Logs

# Forward audit logs to Datadog via the Datadog Agent
# In /etc/datadog-agent/conf.d/openclaw.yaml:
logs:
  - type: file
    path: /var/log/openclaw/audit.json
    service: openclaw
    source: openclaw
    tags: ["env:production"]

Log Retention Policies

GDPR & Privacy Considerations

audit:
  privacy:
    mask_pii: true
    pii_fields:
      - email
      - ip_address
      - phone_number
    mask_pattern: "***REDACTED***"
    exclude_content_from_logs: true  # don't log full LLM responses

What's Next

• Secrets Management — Vault and AWS Secrets Manager
• Structured Logging — Application logging (vs security audit logging)
• Alerting — Set up alerts on audit log events

What to Log and Why

Effective audit logging answers the question: "what did this agent do, when, and why?" Log every agent invocation with a unique run ID that can be traced through all subsequent log entries for that run. Log the input task (sanitized of any PII if needed), the tools called in order, the arguments passed to each tool, the result of each tool call, and the final output. This level of detail enables you to reconstruct the exact sequence of actions an agent took, which is essential for debugging misbehavior and for meeting compliance requirements in regulated industries.

Store logs in append-only storage. If an attacker compromises the agent runtime, you want an immutable audit trail of what happened before they could cover their tracks. Cloud logging services like CloudWatch Logs, Google Cloud Logging, and Azure Monitor provide this by default. If you use a self-hosted logging stack, configure your log collection agent to ship logs off the machine in near-real-time — don't let logs accumulate only locally where they can be deleted.

Set appropriate retention periods. Compliance requirements vary — financial services often require seven years, healthcare requires six years under HIPAA. For general enterprise use, 90 days of hot storage plus one year in cold archive is a reasonable default. Shorter retention reduces storage costs but may leave you without evidence when investigating slow-moving incidents that were initially undetected.

Analyzing Audit Logs

Logs are only useful if someone reviews them. Set up automated alerting for anomalous patterns: an agent making an unusually high number of tool calls in a short period, an agent contacting a domain it has never contacted before, or a sudden spike in error rates for a specific tool. These patterns can indicate a prompt injection attack in progress, a misconfigured prompt causing runaway behavior, or a third-party API returning unexpected responses. Automated alerts give you a chance to investigate before minor anomalies become serious incidents.

Schedule regular manual log reviews for high-risk agents. Automated alerting catches obvious anomalies, but a human reviewer can notice subtle patterns — an agent that is slowly drifting in its behavior over time, or a class of inputs that consistently produces off-policy outputs. Monthly reviews of sampled agent runs for your most critical agents is a lightweight process with significant security and quality benefits. It also keeps your team familiar with normal agent behavior, making anomalies easier to recognize when they occur.

Log Format Recommendations

Use structured logging (JSON) rather than free-text log lines. Structured logs are far easier to query, filter, and alert on. Include a consistent set of fields in every log entry: timestamp in ISO 8601 format, agent name, run ID, event type, and a details object for event-specific fields. Consistent field names across all agents let you write generic queries that work across your entire fleet rather than maintaining agent-specific query patterns for each deployment.