Ledger RPCs

审计账本可通过 Gateway 协议访问。

审计账本 RPC¶

audit.activity.list 为操作员客户端提供稳定的最新优先视图，展示代理运行、工具操作、入站消息以及终结出站消息的元数据。它需要 operator.read。查询会排除 30 天前的记录，且共享 SQLite 账本上限为 100,000 条记录。过期行会在 Gateway 启动、每小时维护以及后续写入期间删除。有关数据模型和隐私语义，请参阅 审计历史。

• 参数：可选的精确 agentId、sessionKey 或 runId；可选 kind（"agent_run"、"tool_action" 或 "message"）；可选 status（"started"、"succeeded"、"failed"、"cancelled"、"timed_out"、"blocked" 或 "unknown"）；可选消息 direction（"inbound" 或 "outbound"）以及精确 channel；可选的包含式 after / before Unix 毫秒边界；可选从 1 到 500 的 limit；以及来自上一页的可选字符串 cursor。
• 结果：{ "events": AuditActivityEventV1[], "nextCursor"?: string }。

具名 V1 结果联合类型分别具有代理运行、工具操作、入站消息和出站消息模式。eventType 判别字段分别为 agent_run、tool_action、inbound_message 或 outbound_message；kind 和消息 direction 仍可用于过滤和显示。每个事件都具有整数 schemaVersion: 1。消息身份引用使用精确的 hmac-sha256:v1:<32 hex key id>:<64 hex digest> 格式；频道发送者 actor id 使用相同格式。

所有变体都要求 eventType、schemaVersion、eventId、sequence、sourceSequence、occurredAt、kind、action、status、actor 和 redaction。变体字段如下：

封闭的消息枚举如下：

• conversationKind：direct、group、channel 或 unknown。
• 入站 outcome：completed、skipped 或 failed；可选 reasonCode：duplicate、reply_operation_active、reply_operation_aborted、fast_abort、plugin_bound_handled、plugin_bound_unavailable、plugin_bound_declined、plugin_bound_error、before_dispatch_handled、acp_dispatch_completed、acp_dispatch_failed、acp_dispatch_empty 或 acp_dispatch_aborted。
• 出站 outcome：sent、suppressed、failed 或 unknown；可选 reasonCode：cancelled_by_message_sending_hook、cancelled_by_reply_payload_sending_hook、empty_after_message_sending_hook、empty_after_reply_payload_sending_hook 或 no_visible_payload。返回无平台身份的适配器为 unknown，因为无法证伪外部副作用。
• deliveryKind：text、media 或 other；failureStage：platform_send、queue 或 unknown。

终结字段是相互关联的，而不是各自可选的：

每个活动事件都包含稳定的事件 id、单调递增的账本序列、源事件序列、时间戳、actor、action、status、整数 schemaVersion: 1 以及 redaction: "metadata_only"。运行和工具记录要求代理和运行溯源，并可包含会话溯源。消息记录可以包含代理和运行 id，但有意从不包含 sessionKey 或 sessionId；因此 sessionKey 查询过滤器仅适用于运行和工具行。工具事件可以包含工具调用 id 和工具名称。

活动账本返回 message.inbound.processed 和 message.outbound.finished 记录，并添加 direction、channel、conversation kind、规范化 outcome，以及可选的 delivery kind、failure stage、duration、result count、reason code，以及安装本地密钥化的 account/conversation/message/target 伪名。这些伪名有助于关联，但不是匿名化：状态数据库包含它们的密钥，而 RPC 和 CLI 导出则不包含。账本不存储提示、消息正文、工具参数、工具结果、命令输出或原始错误文本。运行/工具 sessionKey 值仍为原始关联元数据，并且可以嵌入平台账户或 peer id；消息记录省略会话键。

对于入站行，durationMs 衡量核心分发直至其终态，resultCount 统计已最终确定的排队工具、块和回复负载。对于出站行，durationMs 涵盖从投递所有权开始，直至确认、死信或对账（包括排队等待时间），resultCount 统计已识别的物理平台发送次数。deliveryKind 当存在时，描述经过钩子和渲染后的有效负载；被抑制或崩溃歧义的行会省略它。

当前消息覆盖范围包括到达核心分发的已接受入站消息，包括核心重复/终态结果。出站覆盖范围会将可重放安全的队列和平台启动记录写入延迟的所有者原生伴随存储，并为每个到达共享持久化投递的原始逻辑回复负载写入一条终态活动行；运行检查会合并这些来源。分块和适配器扇出会聚合到终态 resultCount 中。歧义发送只有在确认、死信或对账之后才会到达终态。绕过这些共享边界的插件本地和直接发送路径不在覆盖范围内。有界的进程拥有的异步队列是尽力而为的，在饱和、终态持久化失败或关闭超时时可能丢弃记录，因此该审计表面不是无损合规归档。

记录默认开启，并由 logging.audit.enabled 控制。消息记录由 logging.audit.messages 单独控制，默认值为 "off"。当记录被禁用时，audit.activity.list 会继续提供先前写入的记录，直到它们过期。

audit.run.inspect 还要求 operator.read。其封闭请求恰好选择一个 executionId 用于精确检查，或选择一个 runId 用于有界的执行发现。匹配到一个运行时直接解析；多个匹配会返回显式的 ambiguous 结果，最多包含 50 个候选项，并要求精确选择执行。决策页面最多包含 100 个回执。执行身份收集默认单独关闭，并且需要在 Gateway 重启后启用 logging.audit.executionIdentity: true 以及已启用的审计账本。缺失的尽力而为证据永远不能证明某个运行未发生。

对于所选运行，决策回执会合并终态出站活动与所有者原生的 queued 和 platform_started 进度。进度仅用于归因，存在于延迟伴随存储中，并且不属于 audit.activity.list 结果模式。

已发布的 audit.list 请求、结果和 AuditEvent 模式保持不变，并且仅返回代理运行和工具操作记录。新的操作员客户端应在 Gateway 通告该方法时调用 audit.activity.list。旧版 Gateway 可能会报告 unknown method: audit.activity.list，或者，由于在已发布版本中授权先于方法查找，对读取范围请求报告 missing scope: operator.admin。仅当该方法未被通告时，才将后者视为方法缺失。只有当客户端的过滤器不要求消息类型、方向或通道支持时，客户端才可以重试 audit.list。

使用 openclaw audit 进行文本查询和有界 JSON 导出。