---
read_when:
    - 你需要一份可長期保存的記錄，記載閘道執行了哪些操作，但不儲存內容
    - 你正在決定是否啟用訊息生命週期稽核
    - 你需要說明稽核記錄能證明與不能證明的事項
summary: 僅限中繼資料的稽核歷程，涵蓋代理程式執行、工具動作，以及選擇加入的訊息生命週期
title: 稽核歷程
x-i18n:
    generated_at: "2026-07-12T14:29:58Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 15
    provider: openai
    source_hash: 1005b214a674f0f888d759837bd627be458cefcf9ed61bda722499333361dc45
    source_path: gateway/audit.md
    workflow: 16
---

# 稽核歷程

閘道會在共用 OpenClaw 狀態資料庫中維護一份有界、僅含中繼資料的稽核紀錄。它可回答「哪個代理程式在何時執行，以及如何結束」、「某次執行執行了哪些工具動作」，以及在啟用訊息稽核時，「已接受的傳入訊息是否送達分派階段」和「傳出訊息是否到達終止傳遞狀態」等操作問題。

此紀錄會儲存身分、順序、來源、動作、狀態，以及正規化的結果代碼。它絕不儲存提示詞、訊息本文、工具引數、工具結果、附件、檔名、URL、命令輸出或原始錯誤文字。

## 紀錄類別

啟用稽核時（預設為啟用），一律記錄執行和工具事件。訊息生命週期事件須選擇啟用，且預設為停用。

| 類別         | 動作                                                     | 預設值 |
| ------------ | -------------------------------------------------------- | ------ |
| 代理程式執行 | `agent.run.started`, `agent.run.finished`                | 開啟   |
| 工具動作     | `tool.action.started`, `tool.action.finished`            | 開啟   |
| 訊息         | `message.inbound.processed`, `message.outbound.finished` | 關閉   |

每筆紀錄都包含穩定的事件 ID、單調遞增的紀錄序號、生命週期時間戳記、執行者、動作、狀態、`schemaVersion: 1`，以及 `redaction: "metadata_only"`。如需完整的欄位參考資料和查詢篩選條件，請參閱[稽核紀錄](/zh-TW/cli/audit)。

## 訊息生命週期事件

設定 [`audit.messages`](/zh-TW/gateway/configuration-reference#audit) 以選擇要記錄的內容，然後重新啟動閘道：

- `off`（預設）：不記錄訊息。
- `direct`：僅記錄直接對話中的訊息。
- `all`：記錄直接對話、群組和頻道訊息。

有兩個權威邊界會產生訊息紀錄：

- **傳入**資料列會在已接受的訊息到達核心分派階段時寫入，包括重複訊息和終止處理結果。
- **傳出**資料列會在共用的持久傳遞到達終止結果時寫入：已傳送、已抑制、失敗，或因當機導致傳送結果不明確時明確記為 `unknown`。其中也包括佇列復原和無法投遞結果。每個原始邏輯回覆承載內容會有一筆終止資料列；分塊和介接器扇出會彙總至 `resultCount`。

### 對話種類分類

`direct` 模式是一項隱私邊界，因此只有在目的地事實足以證明時，才會將訊息分類為直接對話：傳送路徑已宣告目的地對話種類，或傳遞工作階段路由明確指出正在傳遞的頻道和對象。較弱的訊號（例如原則狀態或來源對話）可以將訊息分類為 `group`（使其不納入 `direct` 收集），但絕不能據此判定為 `direct`。無法證明為直接對話的訊息會分類為 `unknown`，且不會在 `direct` 模式中記錄。因此，未宣告聊天類型的頻道在 `direct` 模式下記錄的資料列可能少於 `all` 模式。

## 隱私權模型

訊息資料列絕不儲存原始平台識別碼。當可進行關聯時，帳號、對話、訊息和目標識別碼只會匯出為安裝環境本機的加密金鑰假名
（`hmac-sha256:v1:<keyId>:<digest>`）：

- HMAC 金鑰會在首次使用時產生，依識別碼種類進行網域分隔，並儲存在與稽核紀錄相同的狀態資料庫中。
- 假名在同一個安裝環境中維持穩定，因此關於相同對話的資料列可以互相關聯，而不會揭露平台識別碼。
- 這是**關聯，而非匿名化**：任何擁有狀態資料庫讀取權限的人也會取得該金鑰，並可針對假名測試候選的原始識別碼。RPC 和命令列介面匯出內容絕不包含該金鑰。
- 如果保留訊息資料列時，金鑰內容遺失或損毀，閘道會採取故障關閉策略並捨棄新的訊息紀錄，而不會悄悄輪替為新金鑰，避免關聯遭到分割。

執行和工具紀錄會保留 `sessionKey` 和 `sessionId` 以供關聯；標準工作階段金鑰本身可能包含平台帳號或對象 ID。訊息紀錄會刻意省略這兩者。

即使不包含內容，稽核匯出資料仍是敏感的操作中繼資料：時間、頻道、結果和穩定假名皆可用來關聯活動。請使用與其他操作員紀錄相同的存取控制和保留措施來保護匯出資料。

## 涵蓋範圍與證明限制

此紀錄採盡力而為的方式，且刻意設有界限。請將它視為已記錄內容的證據，而非實際發生事項的證明：

- **缺少資料列並不能證明任何事。** 進入許可前遭捨棄的傳入訊息、沒有執行中閘道記錄器的命令列介面程序所進行的傳送，以及略過共用持久傳遞的外掛本機或直接傳送路徑，都不會留下紀錄。
- 寫入會經過有界的背景工作程序；工作程序失敗或佇列飽和時會捨棄紀錄，並記錄一次操作警告。
- 當機導致結果不明確的傳出傳送會記錄為 `unknown`，而不會捏造結果。

此紀錄可支援偵錯和操作審查，但不是無損的合規封存；若你需要此類封存，請使用由 [OpenTelemetry](/zh-TW/gateway/opentelemetry) 或頻道層級工具提供資料的外部系統。

## 儲存、保留與遷移

紀錄儲存在共用狀態資料庫（`state/openclaw.sqlite`）中，並在傳遞熱門路徑之外寫入。查詢絕不會傳回超過 30 天的紀錄，而且紀錄上限為 100,000 筆資料列；過期資料列會在啟動、每小時維護和後續寫入時清除。即使停用收集，保留維護仍會繼續執行。

從使用較早版本僅限執行／工具紀錄的閘道升級時，會在啟動時（或透過 `openclaw doctor --fix`）自動遷移結構描述；現有資料列及其紀錄序號會予以保留。

## 查詢

- 命令列介面：[`openclaw audit`](/zh-TW/cli/audit)，可依代理程式、工作階段、執行、種類、狀態、方向、頻道、時間範圍及游標分頁進行篩選。
- 閘道 RPC：`audit.activity.list`（需要 `operator.read`）會傳回具版本的 V1 活動事件聯集；已發布的 `audit.list` RPC 對舊版執行／工具用戶端維持不變。請參閱[閘道通訊協定](/zh-TW/gateway/protocol#audit-ledger-rpc)。

## 相關內容

- [稽核紀錄命令列介面](/zh-TW/cli/audit)
- [設定參考資料](/zh-TW/gateway/configuration-reference#audit)
- [閘道通訊協定](/zh-TW/gateway/protocol#audit-ledger-rpc)
- [OpenTelemetry](/zh-TW/gateway/opentelemetry)