OpenClaw Audit Logs: Tracking What Your AI Agent Does

OpenClaw audit logs record every tool call, skill invocation, and external action your AI agent performs. If you're running DenchClaw in a team environment — or just want to understand what your agent did last Tuesday — audit logs are the first thing to check. This guide covers how they work, where to find them, and how to use them effectively.

Why Audit Logs Matter for AI Agents#

Traditional software does what you code. AI agents do what they infer. That's powerful, but it creates a new problem: traceability. When something goes wrong — a record gets updated, an email gets sent, a webhook fires — you need to know whether it was your agent, when, and why.

OpenClaw's audit log system exists precisely for this. It's not bolted on after the fact; it's part of how the gateway handles every agent session. Every tool call goes through a structured log entry before and after execution.

This matters for:

• Debugging — "Why did my agent update that field?" has a clear answer
• Compliance — Enterprise teams need records of what AI touched
• Trust — Showing stakeholders a readable log of agent actions builds confidence
• Reproducibility — Replaying agent behavior requires knowing exactly what happened

Where OpenClaw Stores Logs#

By default, DenchClaw writes logs to the workspace at:

~/.openclaw-dench/workspace/.openclaw/logs/

Each session gets its own log file named by session ID and timestamp:

~/.openclaw-dench/workspace/.openclaw/logs/agent-main-<session-id>.jsonl

Logs are stored in JSONL format — one JSON object per line. This makes them easy to parse with standard tools (jq, Python, DuckDB) without loading the entire file into memory.

Here's what a single log entry looks like:

{
  "ts": "2026-03-26T14:23:01.842Z",
  "session": "agent:main:subagent:abc123",
  "tool": "exec",
  "status": "ok",
  "durationMs": 312,
  "input": { "command": "ls ~/.openclaw-dench/workspace" },
  "output": { "stdout": "apps\ndocs\nskills\n", "exitCode": 0 }
}

Every entry includes a timestamp, session ID, tool name, status (ok or error), duration, and the input/output pair. That last part is key — you can see exactly what the agent passed to a tool and what it got back.

Reading Audit Logs#

With jq#

The fastest way to browse logs:

# See all tool calls in the last session
cat ~/.openclaw-dench/workspace/.openclaw/logs/agent-main-*.jsonl | jq '.tool'
 
# Find all exec calls
cat ~/.openclaw-dench/workspace/.openclaw/logs/agent-main-*.jsonl \
  | jq 'select(.tool == "exec")'
 
# Find errors
cat ~/.openclaw-dench/workspace/.openclaw/logs/agent-main-*.jsonl \
  | jq 'select(.status == "error")'

With DuckDB#

DenchClaw's local DuckDB instance is ideal for querying logs at scale:

-- Load a log file into a query
SELECT ts, tool, status, durationMs
FROM read_json_auto('~/.openclaw-dench/workspace/.openclaw/logs/*.jsonl')
ORDER BY ts DESC
LIMIT 50;
 
-- Slowest tool calls
SELECT tool, AVG(durationMs) as avg_ms, COUNT(*) as calls
FROM read_json_auto('~/.openclaw-dench/workspace/.openclaw/logs/*.jsonl')
GROUP BY tool
ORDER BY avg_ms DESC;

This is one of the concrete advantages of DenchClaw's local-first architecture — your logs live alongside your data and you can query them with the same DuckDB instance you use for everything else. No log aggregation service required.

With the DenchClaw UI#

The frontend at localhost:3100 shows a session timeline view. Click any session in the sidebar to see its tool calls rendered as a readable list. You'll see inputs, outputs, and timing without needing to open a terminal.

Understanding Log Entries#

Tool Call Lifecycle#

Each tool call produces two entries: one when the call is initiated (status: "pending") and one when it completes (status: "ok" or status: "error"). This lets you see how long each tool call took and whether it completed.

// Initiation
{"ts": "...T14:23:01.530Z", "tool": "read", "status": "pending", "input": {"file": "SOUL.md"}}
 
// Completion
{"ts": "...T14:23:01.712Z", "tool": "read", "status": "ok", "durationMs": 182, "output": {...}}

Skill Invocations#

When your agent loads a skill, that's logged too:

{
  "ts": "2026-03-26T14:23:00.100Z",
  "event": "skill_loaded",
  "skill": "crm",
  "path": "/Users/kumareth/.openclaw-dench/workspace/skills/crm/SKILL.md"
}

External Actions#

External actions (email, webhooks, writes to third-party APIs) get flagged with an external: true field. This makes filtering for compliance purposes straightforward:

cat *.jsonl | jq 'select(.external == true)'

Setting Up Structured Log Retention#

For teams using DenchClaw over time, raw JSONL logs accumulate. Here's a simple retention setup:

1. Rotate logs by date#

Add a daily cron that archives old logs:

# Archive logs older than 30 days
find ~/.openclaw-dench/workspace/.openclaw/logs/ \
  -name "*.jsonl" \
  -mtime +30 \
  -exec gzip {} \;

2. Import into DuckDB for long-term querying#

# Create a persistent audit table in your workspace DB
duckdb ~/.openclaw-dench/workspace/workspace.duckdb << 'EOF'
CREATE TABLE IF NOT EXISTS audit_log AS
SELECT * FROM read_json_auto('~/.openclaw-dench/workspace/.openclaw/logs/*.jsonl');
EOF

3. Export to your SIEM#

If your enterprise team uses a SIEM (Splunk, Datadog, etc.), JSONL logs are trivially shippable:

# Tail and ship to Datadog
tail -F ~/.openclaw-dench/workspace/.openclaw/logs/agent-main-current.jsonl \
  | jq -c '.' \
  | while read line; do
      curl -X POST "https://http-intake.logs.datadoghq.com/api/v2/logs" \
        -H "DD-API-KEY: $DD_API_KEY" \
        -d "$line"
    done

Using Logs for Debugging#

The most common debugging workflow: something unexpected happened, and you want to know why.

Step 1: Find the session. Check the session list in the DenchClaw UI or look at log filenames. Sessions are timestamped, so finding the right one is usually quick.

Step 2: Look for errors first.

jq 'select(.status == "error")' session-id.jsonl

Step 3: Reconstruct the agent's reasoning. Log entries include both the tool input (what the agent decided to do) and the tool output (what it got back). Reading these in sequence shows you the agent's decision path.

Step 4: Check external calls. If the issue involved a third-party API:

jq 'select(.external == true)' session-id.jsonl

You'll see exactly what was sent and what came back.

Audit Logs for Enterprise Compliance#

If you're deploying DenchClaw in an enterprise context — regulated industries, SOC 2 requirements, internal security policies — here's what to configure:

1. Immutable log storage. Write logs to a WORM-compliant storage backend. This means piping your JSONL logs to S3 with Object Lock, or to a dedicated audit log service.

2. Log signing. Add a hash of each log entry using a signing key. This lets you prove a log hasn't been tampered with.

3. Access controls. The log directory should only be readable by the agent process and designated audit principals. On Linux:

   Copy

   chmod 750 ~/.openclaw-dench/workspace/.openclaw/logs/
   chown openclaw:audit-team ~/.openclaw-dench/workspace/.openclaw/logs/

4. Alert on sensitive actions. Set up a simple watcher that alerts when specific tools fire — like message (sends external messages) or exec with elevated permissions.

See the enterprise deployment guide for the full picture on running DenchClaw in team environments.

What's Not in the Logs#

It's worth being explicit about what audit logs don't capture:

• Agent reasoning/thinking. The internal chain-of-thought that leads to a tool call is separate from the tool call itself. If you need this, enable reasoning output in the session config.
• LLM token counts. Token usage is tracked in a separate usage log, not the audit trail.
• File contents in full. For large file reads/writes, the log captures metadata but may truncate the payload to keep log files manageable.

FAQ#

Q: Can I disable audit logging for performance? A: You can reduce log verbosity by setting LOG_LEVEL=warn in your environment, which only logs errors and warnings. Full disable isn't recommended — the logs have minimal overhead and you'll want them when something goes wrong.

Q: How do I correlate logs across multiple agents or sessions? A: Each log entry includes a session field with the full session ID (e.g., agent:main:subagent:abc123). Parent-child session relationships are visible in the session ID hierarchy.

Q: Are log files encrypted at rest? A: Not by default. If you're on a shared machine or have compliance requirements, encrypt your workspace directory using your OS's full-disk encryption or a tool like age.

Q: How long are logs kept by default? A: DenchClaw doesn't auto-rotate logs. They accumulate until you clean them up. The rotation strategy in this guide (archive after 30 days) is a sensible starting point.

Q: Can I add custom fields to log entries? A: Not directly, but you can add a post-processing step that enriches JSONL entries with custom metadata before importing to your long-term store.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →