---
read_when:
    - 你需要一份不存储内容、但能持久记录 Gateway 网关操作的记录
    - 你正在决定是否启用消息生命周期审计
    - 你需要说明审计记录能够证明什么，以及不能证明什么
summary: 智能体运行、工具操作和可选消息生命周期的纯元数据审计历史
title: 审计历史
x-i18n:
    generated_at: "2026-07-12T14:28:03Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 15
    provider: openai
    source_hash: 1005b214a674f0f888d759837bd627be458cefcf9ed61bda722499333361dc45
    source_path: gateway/audit.md
    workflow: 16
---

# 审计历史

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)