> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 稽核記錄

# `openclaw audit`

查詢閘道中僅含中繼資料的稽核帳本，以檢視代理程式執行與工具動作。

記錄預設為啟用；設定 [`audit.enabled: false`](/zh-TW/gateway/configuration-reference#audit)
即可停止新的寫入。既有記錄在到期前（30 天）仍可查詢。
此帳本與對話逐字稿分開：它會記錄身分、
排序、來源、動作、狀態與正規化錯誤碼，但絕不
儲存提示、訊息、工具引數、工具結果、命令輸出或原始
錯誤文字。

閘道會透過有界背景寫入器，將記錄寫入共用的 OpenClaw 狀態資料庫。
查詢絕不會回傳超過 30 天的記錄，
且帳本上限為 100,000 列。到期列會在
閘道啟動、每小時維護以及後續寫入時刪除。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

## 篩選器

* `--agent <id>`：精確的代理程式 id
* `--session <key>`：精確的工作階段鍵
* `--run <id>`：精確的執行 id
* `--kind <kind>`：`agent_run` 或 `tool_action`
* `--status <status>`：`started`、`succeeded`、`failed`、`cancelled`、
  `timed_out`、`blocked` 或 `unknown`
* `--after <timestamp>` / `--before <timestamp>`：包含邊界的 ISO 時間戳記或
  Unix 毫秒
* `--limit <count>`：頁面大小為 1 到 500；預設為 `100`
* `--cursor <sequence>`：接續先前由新到舊的查詢
* `--json`：將有界頁面列印為 JSON

文字輸出會顯示時間、種類、狀態、代理程式、執行與動作。工具動作也會
顯示工具名稱。JSON 輸出是相同中繼資料的安全有界匯出，
並在存在下一頁時包含 `nextCursor`。將該值傳給
`--cursor`，即可在不重新排序分頁期間抵達的記錄下繼續查詢。

## 已記錄事件

閘道會將既有代理程式事件串流投影為四種動作：

* `agent.run.started`
* `agent.run.finished`
* `tool.action.started`
* `tool.action.finished`

每筆記錄都有穩定的事件 id、單調遞增的帳本序列、
原始執行事件序列、執行階段提供時的生命週期時間戳記
（否則為觀測時間）、代理程式/執行來源、操作者，以及
`redaction: "metadata_only"` 標記。終端記錄會使用封閉狀態與錯誤
碼來區分成功、失敗、取消、逾時與政策封鎖。當上游執行階段
未公開權威的終端結果時，`unknown` 是明確的非成功結果。工具呼叫 id 僅會以
穩定的單向指紋匯出。工具名稱必須符合精簡的
模型面向名稱契約；其他值會變成 `unknown`。工作階段 id、工作階段
鍵、執行 id 與保留的工具名稱屬於操作員中繼資料；請將匯出內容
作為作業記錄保護。

稽核帳本不會取代逐字稿、任務歷史、排程執行歷史
或記錄檔。它提供小型跨執行索引，讓操作員能在不將
對話內容複製到另一個儲存區的情況下提出查詢。

## 閘道 RPC

`audit.list` 需要 `operator.read`，並接受相同的篩選器。範例：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway call audit.list --params '{"agentId":"main","status":"failed","limit":50}'
```

結果為 `{ "events": AuditEvent[], "nextCursor"?: string }`。結果會
由新到舊排序，且每次請求最多限制為 500 筆記錄。

## 相關

* [閘道協定](/zh-TW/gateway/protocol#audit-ledger-rpc)
* [工作階段](/zh-TW/cli/sessions)
* [任務](/zh-TW/cli/tasks)
* [排程工作](/zh-TW/automation/cron-jobs)