> ## 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.

# 审计历史

# 审计历史

Gateway 网关在共享的 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-CN/cli/audit)。

## 消息生命周期事件

设置 [`audit.messages`](/zh-CN/gateway/configuration-reference#audit) 以选择要记录的内容，然后重启 Gateway 网关：

* `off`（默认）：不记录消息。
* `direct`：仅记录私聊会话中的消息。
* `all`：记录私聊、群组和频道消息。

两个权威边界会生成消息记录：

* **入站**记录会在已接受的消息到达核心分派阶段时写入，包括重复处理结果和最终处理结果。
* **出站**记录会在共享持久投递到达最终结果时写入：已发送、已阻止、失败，或对于崩溃导致结果不明确的发送，写入明确的 `unknown`。其中包括队列恢复和死信结果。每个原始逻辑回复载荷只会生成一条最终记录；分块和适配器扇出会汇总到 `resultCount` 中。

### 会话类型分类

`direct` 模式是一项隐私边界，因此仅当目标事实能够证明确为私聊会话时，消息才会被归类为私聊会话：发送路径声明了目标会话类型，或者投递会话路由准确指定了正在投递到的频道和对端。较弱的信号（例如策略状态或来源会话）可以将消息归类为 `group`（将其排除在 `direct` 收集范围之外），但绝不能断言其为 `direct`。无法证明确为私聊的消息会被归类为 `unknown`，并且不会在 `direct` 模式下记录。因此，未声明聊天类型的频道在 `direct` 模式下记录的行数可能少于在 `all` 模式下记录的行数。

## 隐私模型

消息记录绝不会存储原始平台标识符。如果存在可用于关联的信息，账号、会话、消息和目标标识符只会导出为当前安装实例本地使用密钥生成的假名（`hmac-sha256:v1:<keyId>:<digest>`）：

* HMAC 密钥会在首次使用时生成，按标识符类型进行域分离，并与账本存储在同一个状态数据库中。
* 假名在单个安装实例内保持稳定，因此可以关联同一会话的记录，同时不会泄露平台标识符。
* 这只是**关联，而非匿名化**：任何拥有状态数据库读取权限的人也能获取该密钥，并可用候选原始标识符与假名进行匹配测试。RPC 和 CLI 导出绝不会包含该密钥。
* 如果保留了消息记录，但密钥材料丢失或损坏，Gateway 网关会采用故障关闭策略并丢弃新的消息记录，而不会静默轮换为新密钥，否则会导致关联关系断裂。

运行和工具记录会保留 `sessionKey` 和 `sessionId` 以便关联；规范会话键本身可能包含平台账号或对端 ID。消息记录会有意省略这两项。

即使不含内容，审计导出仍然属于敏感的运维元数据：时间、频道、结果和稳定假名都可用于关联活动。请采用与其他操作员记录相同的访问控制和保留措施来保护导出数据。

## 覆盖范围和证明限制

该账本以尽力而为方式运行，并且刻意设置了容量上限。应将其视为已记录内容的证据，而不是实际发生情况的证明：

* \*\*缺少记录不能证明任何事情。\*\*准入前丢弃的入站消息、在没有运行 Gateway 网关记录器的 CLI 进程中执行的发送，以及绕过共享持久投递的插件本地路径或直接发送路径都不会留下记录。
* 写入操作通过有界后台工作线程执行；工作线程失败或队列饱和时会丢弃记录，并记录一条运维警告。
* 因崩溃而结果不明确的出站发送会记录为 `unknown`，而不会编造结果。

该账本用于支持调试和运维审查。它不是无损的合规归档；如果需要此类归档，请使用由 [OpenTelemetry](/zh-CN/gateway/opentelemetry) 或频道级工具提供数据的外部系统。

## 存储、保留和迁移

记录存储在共享状态数据库（`state/openclaw.sqlite`）中，并在投递热路径之外写入。查询绝不会返回超过 30 天的记录，且账本上限为 100,000 行；过期记录会在启动时、每小时维护期间以及后续写入时清理。即使禁用收集，保留期维护仍会继续运行。

从使用早期仅包含运行和工具记录的账本版本升级 Gateway 网关时，系统会在启动时（或通过 `openclaw doctor --fix`）自动迁移架构；现有记录及其账本序列号会予以保留。

## 查询

* CLI：[`openclaw audit`](/zh-CN/cli/audit)，支持按智能体、会话、运行、类型、状态、方向、频道、时间范围进行过滤，并支持游标分页。
* Gateway 网关 RPC：`audit.activity.list`（需要 `operator.read`）返回带版本的 V1 活动事件联合类型；已发布的 `audit.list` RPC 对旧版运行和工具客户端保持不变。请参阅 [Gateway 网关协议](/zh-CN/gateway/protocol#audit-ledger-rpc)。

## 相关内容

* [审计记录 CLI](/zh-CN/cli/audit)
* [配置参考](/zh-CN/gateway/configuration-reference#audit)
* [Gateway 网关协议](/zh-CN/gateway/protocol#audit-ledger-rpc)
* [OpenTelemetry](/zh-CN/gateway/opentelemetry)