Skip to content
Lobster

Audit Logging

Audit Logging for OpenClaw Agents

Structured audit logging for all tool calls and commands performed by an OpenClaw agent. Useful for security review, debugging, and understanding what your agent has been doing.

Overview

An OpenClaw hook that captures all elevated operations to a structured JSON Lines log file. This gives you a complete audit trail of every tool call (MCP operations, exec commands, file writes) and slash command your agent executes.

Setup

1. Create the Hook

Create a directory for the hook with a HOOK.md file and handler.ts:

~/.openclaw/hooks/audit-logger/
├── HOOK.md      # Hook metadata and documentation
└── handler.ts   # Event handler implementation

HOOK.md frontmatter:

---
name: audit-logger
description: "Logs all tool calls and commands to a structured JSONL audit file"
metadata:
  openclaw:
    emoji: "📝"
    events: ["tool_result_persist", "command"]
    requires:
      os: ["darwin"]
---

The two key events:

  • tool_result_persist — fires after every tool call completes
  • command — fires when a slash command is executed

2. Enable the Hook

Terminal window
openclaw hooks enable audit-logger
openclaw hooks info audit-logger

Log Format

JSON Lines (one entry per line) at ~/.openclaw/logs/audit.jsonl:

{"ts":"2026-02-09T10:30:00.000Z","event":"tool_result","session":"abc123","sender":"+1XXXXXXXXXX","tool":"email-server.draft-create","result":"success"}
{"ts":"2026-02-09T10:31:00.000Z","event":"command","session":"abc123","sender":"+1XXXXXXXXXX","action":"new"}

Daily Rotation

Logs rotate daily to ~/.openclaw/logs/audit-YYYY-MM-DD.jsonl. Current day’s log is always audit.jsonl.

Permissions

All log files are created with 0600 (owner read/write only).

Querying

Terminal window
# All exec operations
cat ~/.openclaw/logs/audit.jsonl | jq 'select(.tool | startswith("exec"))'


# All email operations
cat ~/.openclaw/logs/audit.jsonl | jq 'select(.tool | startswith("email"))'


# Operations by sender
cat ~/.openclaw/logs/audit.jsonl | jq 'select(.sender == "+1XXXXXXXXXX")'


# Last 24 hours
cat ~/.openclaw/logs/audit.jsonl | jq 'select(.ts > "2026-02-10")'


# Count operations by tool
cat ~/.openclaw/logs/audit.jsonl | jq -r '.tool' | sort | uniq -c | sort -rn

If You’re Using a Git Repo

If your agent workspace is version-controlled (recommended), you can symlink the hook from your repo:

Terminal window
ln -s ~/GitHub/your-agent/hooks/audit-logger ~/.openclaw/hooks/audit-logger

This keeps the hook definition in source control while making it available to OpenClaw.

What to Watch For

  • Unexpected exec calls (could indicate prompt injection)
  • High-frequency tool calls in short periods (possible runaway loop)
  • Operations from unexpected senders
  • Tool calls during hours when no one should be interacting with the agent