English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

CLI commands

Audit records

openclaw audit

Query the Gateway's metadata-only audit ledger for agent runs and tool actions.

Recording is on by default; set audit.enabled: false to stop new writes. Existing records stay queryable until they expire (30 days). The ledger is separate from conversation transcripts: it records identity, ordering, provenance, action, status, and normalized error codes, but never stores prompts, messages, tool arguments, tool results, command output, or raw error text.

The Gateway writes records to the shared OpenClaw state database through a bounded background writer. Queries never return records older than 30 days, and the ledger is capped at 100,000 rows. Expired rows are deleted during Gateway startup, hourly maintenance, and later writes.

bash
openclaw auditopenclaw audit --agent main --status failedopenclaw audit --session "agent:main:main" --after 2026-07-01T00:00:00Zopenclaw audit --run 8c69f72e-8b11-4c54-98d5-1a3dd67450c3openclaw audit --kind tool_action --limit 50 --json

Filters

  • --agent <id>: exact agent id
  • --session <key>: exact session key
  • --run <id>: exact run id
  • --kind <kind>: agent_run or tool_action
  • --status <status>: started, succeeded, failed, cancelled, timed_out, blocked, or unknown
  • --after <timestamp> / --before <timestamp>: inclusive ISO timestamp or Unix milliseconds
  • --limit <count>: page size from 1 to 500; default 100
  • --cursor <sequence>: continue a previous newest-first query
  • --json: print the bounded page as JSON

Text output shows time, kind, status, agent, run, and action. Tool actions also show the tool name. JSON output is a safe bounded export of the same metadata and includes nextCursor when another page exists. Pass that value to --cursor to continue without reordering records that arrive during paging.

Recorded events

The Gateway projects existing agent event streams into four actions:

  • agent.run.started
  • agent.run.finished
  • tool.action.started
  • tool.action.finished

Every record has a stable event id, a monotonically increasing ledger sequence, the original run event sequence, lifecycle timestamp when the runtime provides one (otherwise observation time), agent/run provenance, actor, and a redaction: "metadata_only" marker. Terminal records distinguish success, failure, cancellation, timeout, and policy blocks with closed status and error codes. unknown is an explicit non-success result when an upstream runtime does not expose an authoritative terminal outcome. Tool call ids are exported only as stable one-way fingerprints. Tool names must match the compact model-facing name contract; other values become unknown. Session ids, session keys, run ids, and retained tool names are operator metadata; protect exports as operational records.

The audit ledger does not replace transcripts, task history, cron run history, or logs. It provides a small cross-run index for operator questions without copying conversation content into another store.

Gateway RPC

audit.list requires operator.read and accepts the same filters. Example:

bash
openclaw gateway call audit.list --params '{"agentId":"main","status":"failed","limit":50}'

The result is { "events": AuditEvent[], "nextCursor"?: string }. Results are newest first and limited to 500 records per request.

Was this useful?
On this page

On this page