> ## 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 狀態資料庫中維護一份有容量上限且僅含中繼資料的稽核帳本。它可回答「哪個代理程式在何時執行，以及如何結束」、「某次執行進行了哪些工具動作」等營運問題；啟用訊息稽核時，也可回答「已接受的傳入訊息是否到達分派階段」以及「傳出訊息是否到達終止傳遞狀態」。

帳本會儲存身分、順序、來源、動作、狀態及正規化結果代碼。它絕不儲存提示、訊息本文、工具引數、工具結果、附件、檔名、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)