mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-09 23:43:54 +00:00
f53346944d
* feat: correlate native search outcomes in audit history Metadata-only audit ledger for agent runs and tool actions in the shared state DB: stable event identity, closed action/status/error vocabularies, one-way-hashed tool-call ids, never-inferred terminal outcomes for native web-search (explicit completed/failed only; otherwise unknown), bounded retention, audit.list gateway RPC and openclaw audit CLI. Squashed from the 82-commit audit stack for replay onto current main. * feat(audit): add audit.enabled config gate (default on) The metadata-only audit ledger records by default: an audit trail enabled only after an incident cannot explain the incident, and the rows are strictly less sensitive than the transcripts every install already stores. audit.enabled=false stops new writes at the gateway subscription seam; audit.list and openclaw audit keep serving existing records until they expire. Documented in the configuration reference, protocol page, and CLI reference. * fix: repair full-matrix CI findings after rebase - break the dynamic-tools/dynamic-tool-execution import cycle by extracting resolveCodexToolAbortTerminalReason into a leaf module - restore main's session-worktree protocol exports lost in the index.ts auto-merge - register the audit event writer worker as a knip entry point - docs table formatting; subagent wait-cancellation test scoped to its audit intent (outcome + timing) and advanced past main's new lifecycle-timeout retry grace
94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
---
|
|
summary: "CLI reference for metadata-only agent run and tool action audit records"
|
|
read_when:
|
|
- You need to answer who ran an agent or tool, when it ran, and how it ended
|
|
- You need a bounded, redaction-safe activity export
|
|
title: "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`](/gateway/configuration-reference#audit)
|
|
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 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
|
|
```
|
|
|
|
## 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.
|
|
|
|
## Related
|
|
|
|
- [Gateway protocol](/gateway/protocol#audit-ledger-rpc)
|
|
- [Sessions](/cli/sessions)
|
|
- [Tasks](/cli/tasks)
|
|
- [Cron jobs](/automation/cron-jobs)
|