mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-02 23:31:34 +00:00
1e20cc814e
* docs: correct retired cron/audit config keys, cron failure-alert default, memory recall default, and tool-search telemetry claims - configuration-reference: cron block documented cron.webhook and cron.failureDestination, both retired by the config-surface reduction tranches (58452de711,edecdbd05e); the cron schema is strict so a copied snippet is rejected. Document only the live keys and note the doctor --fix migrations. - configuration-reference: root-level audit block is retired; canonical path is logging.audit (src/config/zod-schema.root-shape.ts). - configuration-reference: cron.failureAlert.after default is 2, not 3 (src/cron/service/failure-alerts.ts). - memory-config: rememberAcrossConversations defaults on for personal installs (packages/memory-host-sdk/src/host/config-utils.ts), matching the canonical table earlier in the page. - tool-search: telemetry records catalogSize, per-source counts, and search/describe/call counts, and only on tool_search_code results. No byte accounting exists in the runtime. * docs: retire remaining references to removed cron, audit, and logging config keys Sweep follow-up to the previous commit, covering the same bug class in the pages that still contradicted it. - cron-jobs/cli-cron: global cron.failureDestination is retired; the destination fields now live on cron.failureAlert (src/config/zod-schema.root-shape.ts, merged by legacy-config-migrations.runtime.retired.ts:379). Per-job delivery.failureDestination bullets left intact. - gateway/audit, cli/audit, gateway/protocol: root-level audit.* is retired; canonical path is logging.audit.*. - logging: logging.redactSensitive is retired (dead-config-keys.test.ts:198; removed by legacy-config-migrations.runtime.tier-eval.ts:12). resolveConfigRedaction hardcodes DEFAULT_REDACT_MODE = tools, so redaction is unconditional. Also documented that redactPatterns replaces the defaults on the log path (redact.ts:419) while tool payloads always merge them. - logging: consoleStyle accepts only pretty|json (zod-schema.root-shape.ts:106); compact remains the automatic non-TTY rendering style (logging/console.ts:40) but is no longer settable, and doctor maps a stored one to pretty. - security: security --fix no longer touches redaction and the logging.redact_off audit check is retired (src/security/audit-loopback-logging.test.ts asserts it never fires). * chore(docs): regenerate docs map after retired-key cleanup
140 lines
6.5 KiB
Markdown
140 lines
6.5 KiB
Markdown
---
|
|
summary: "CLI reference for metadata-only run, tool, and message lifecycle audit records"
|
|
read_when:
|
|
- You need to answer who ran an agent or tool, when it ran, and how it ended
|
|
- You need content-free inbound or outbound message lifecycle metadata
|
|
- You need a bounded, redaction-safe activity export
|
|
title: "Audit records"
|
|
---
|
|
|
|
# `openclaw audit`
|
|
|
|
Query the Gateway's metadata-only audit ledger for agent runs, tool actions, and
|
|
opt-in message lifecycle records.
|
|
|
|
The ledger is on by default for run and tool events. Set
|
|
[`logging.audit.enabled: false`](/gateway/configuration-reference#audit) and
|
|
restart the Gateway to stop all new event records. Message records are
|
|
separately disabled by default; set `logging.audit.messages` to `direct` or
|
|
`all` and restart the Gateway to record them. 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 outcome codes, but never
|
|
stores content, and message identifiers appear only as installation-local
|
|
keyed pseudonyms. [Audit history](/gateway/audit) owns the full data model,
|
|
privacy semantics, storage/retention bounds, and coverage limits; this page
|
|
covers the command surface.
|
|
|
|
```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
|
|
openclaw audit --kind message --direction outbound --channel telegram --json
|
|
```
|
|
|
|
## Filters
|
|
|
|
- `--agent <id>`: exact agent id
|
|
- `--session <key>`: exact session key
|
|
- `--run <id>`: exact run id
|
|
- `--kind <kind>`: `agent_run`, `tool_action`, or `message`
|
|
- `--status <status>`: `started`, `succeeded`, `failed`, `cancelled`,
|
|
`timed_out`, `blocked`, or `unknown`
|
|
- `--direction <direction>`: message direction, `inbound` or `outbound`
|
|
- `--channel <channel>`: exact message channel
|
|
- `--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
|
|
|
|
The CLI queries the versioned activity RPC so one command shows the complete
|
|
configured ledger. Text output shows time, kind, direction, channel, status,
|
|
agent, run, and action. Missing message provenance renders as `-`; OpenClaw
|
|
does not invent agent or run ids. Tool actions also show the tool name. JSON
|
|
output includes `nextCursor` when another page exists. Pass that value to
|
|
`--cursor` to continue without reordering records that arrive during paging.
|
|
|
|
These exports remain sensitive operational metadata even though message bodies
|
|
and raw message identity fields are absent. Agent, session, and run ids, timing,
|
|
channels, outcomes, and stable HMAC references can correlate activity. Protect
|
|
them with the same access controls and retention practices as 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 has a stable event id, a monotonically increasing ledger
|
|
sequence, a lifecycle timestamp, actor, action, status, a
|
|
`schemaVersion: 1` marker, source sequence, and `redaction: "metadata_only"`.
|
|
Agent/session/run provenance and event-specific fields are present only when
|
|
the trusted source provides them. Message records intentionally omit
|
|
`sessionKey` and `sessionId`, so `--session` filters run and tool records only.
|
|
|
|
Terminal run and tool 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
|
|
fingerprints. Tool names must match the compact model-facing name
|
|
contract; other values become `unknown`.
|
|
|
|
Message records add direction, channel, conversation kind, outcome, and
|
|
optional delivery kind, failure stage, duration, result count, normalized
|
|
reason code, and keyed account/conversation/message/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 those shared boundaries are not
|
|
yet covered; absence of a row does not prove that no message existed.
|
|
|
|
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.
|
|
|
|
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 (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, including run, tool, inbound-message,
|
|
and outbound-message records.
|
|
|
|
```bash
|
|
openclaw gateway call audit.activity.list --params '{"channel":"telegram","limit":50}'
|
|
```
|
|
|
|
The result is `{ "events": AuditActivityEventV1[], "nextCursor"?: string }`.
|
|
Results are newest first and limited to 500 records per request.
|
|
|
|
The shipped `audit.list` RPC remains unchanged for older run/tool clients. When
|
|
`audit.activity.list` is unavailable on an older Gateway, the CLI retries
|
|
`audit.list` only if every requested filter is supported by that legacy method. `--kind message`,
|
|
`--direction`, and `--channel` fail with an upgrade message on an older Gateway
|
|
instead of being silently discarded.
|
|
|
|
## Related
|
|
|
|
- [Audit history](/gateway/audit)
|
|
- [Gateway protocol](/gateway/protocol#audit-ledger-rpc)
|
|
- [Sessions](/cli/sessions)
|
|
- [Tasks](/cli/tasks)
|
|
- [Cron jobs](/automation/cron-jobs)
|