Audit Records CLI Reference

`openclaw audit`

Inspect the Gateway's metadata-only audit log for agent executions, tool invocations, and optionally recorded message lifecycle events.

Run and tool events are recorded in the ledger by default. To stop logging new events, set audit.enabled: false(/gateway/configuration-reference#audit) and restart the Gateway. Message events are turned off by default; enable them by setting audit.messages to direct or all and restarting the Gateway. Previously stored records remain available for queries until they expire after 30 days.

This ledger differs from conversation transcripts: it captures identity, ordering, provenance, action, status, and normalized outcome codes, but never stores content. Message identifiers appear only as installation-local keyed pseudonyms. The full data model, privacy semantics, storage and retention limits, and coverage constraints are documented in Audit history; this page describes the command interface.

openclaw audit
openclaw audit --agent main --status failed
openclaw audit --session "agent:main:main" --after 2026-07-01T00:00:00Z
openclaw audit --run 8c69f72e-8b11-4c54-98d5-1a3dd67450c3
openclaw audit --kind tool_action --limit 50 --json
openclaw audit --kind message --direction outbound --channel telegram --json

Filters

--agent <id>: specific agent identifier
--session <key>: specific session key
--run <id>: specific run identifier
--kind <kind>: agent_run, tool_action, or message
--status <status>: started, succeeded, failed, cancelled, timed_out, blocked, or unknown
--direction <direction>: message direction, either inbound or outbound
--channel <channel>: specific message channel
--after <timestamp> / --before <timestamp>: inclusive ISO timestamp or Unix milliseconds
--limit <count>: number of results per page, 1 to 500; default is 100
--cursor <sequence>: resume a previous newest-first query
--json: output the bounded page as JSON

The CLI queries the versioned activity RPC, so a single command displays the entire configured ledger. Text output includes time, kind, direction, channel, status, agent, run, and action. When message provenance is missing, it appears as -; OpenClaw does not fabricate agent or run identifiers. Tool actions additionally show the tool name. JSON output includes nextCursor when additional pages exist. Pass that value to --cursor to continue without disrupting the ordering of records added during paging.

These exports contain sensitive operational metadata, even though message bodies and raw message identity fields are excluded. Agent, session, and run identifiers, timestamps, channels, outcomes, and stable HMAC references can reveal activity patterns. Apply the same access controls and retention policies as with other operator records.

Recorded events

The Gateway projects trusted lifecycle streams into six actions:

agent.run.started
agent.run.finished
tool.action.started
tool.action.finished
message.inbound.processed
message.outbound.finished

Every returned record includes a stable event ID, a monotonically increasing ledger sequence number, a lifecycle timestamp, actor, action, status, a schemaVersion: 1 marker, source sequence, and redaction: "metadata_only". Agent, session, and run provenance, along with event-specific fields, appear only when provided by the trusted source. Message records intentionally omit sessionKey and sessionId, so --session filters only run and tool records.

Terminal run and tool records differentiate success, failure, cancellation, timeout, and policy blocks using closed status and error codes. unknown represents an explicit non-success result when the upstream runtime does not provide a definitive terminal outcome. Tool call IDs are exported only as stable fingerprints. Tool names must match the compact model-facing name contract; other values become unknown.

Message records include direction, channel, conversation kind, outcome, and optionally delivery kind, failure stage, duration, result count, normalized reason code, and keyed account, conversation, message, and target pseudonyms. The current inbound boundary covers accepted messages that reach core dispatch, including core duplicate and terminal processing outcomes. The outbound boundary writes one terminal row per original logical reply payload that reaches shared durable delivery; chunking and adapter fan-out are aggregated in resultCount. Queued retryable or ambiguous sends are recorded only after an acknowledgement, dead letter, or reconciliation makes the outcome terminal. Plugin-local and direct-send paths that bypass these shared boundaries are not yet covered; the absence of a row does not confirm that no message existed.

The audit ledger does not replace transcripts, task history, cron run history, or logs. It provides a compact cross-run index for operator investigations without duplicating conversation content in another store.

For inbound rows, durationMs measures core dispatch and resultCount counts finalized queued tool, block, and reply payloads. For outbound rows, durationMs includes delivery ownership through its terminal state (and therefore queued wait time), while resultCount counts identified physical platform sends. deliveryKind, when present, describes the effective post-hook, post-render payload; suppressed and crash-ambiguous rows omit it.

Gateway RPC

audit.activity.list requires operator.read and accepts the same filters. It returns the named V1 activity event union, which includes run, tool, inbound-message, and outbound-message records.

openclaw gateway call audit.activity.list --params '{"channel":"telegram","limit":50}'

The output is { "events": AuditActivityEventV1[], "nextCursor"?: string }. Entries appear with the most recent first, and each request returns up to 500 records.

For legacy run/tool clients, the pre‑installed audit.list RPC stays unchanged. When an older Gateway lacks audit.activity.list, the CLI only attempts audit.list if every filter in the request is supported by that older method. On an older Gateway, --kind message, --direction, and --channel produce an upgrade notice rather than being silently dropped.