openclaw audit¶
查询 Gateway 的仅元数据活动账本,发现共享运行关联的执行,或检查单个精确 agent 执行的不可变身份上下文。
运行和工具活动记录默认开启。执行身份在全新安装和升级时默认单独关闭。请显式启用:
身份收集要求 logging.audit.enabled 保持启用。消息记录同样默认单独禁用;将 logging.audit.messages 设置为 direct 或 all,然后重启 Gateway 即可记录它们。现有记录在过期(30 天)前仍可查询。
直接本地命令使用与 Gateway 相同的有界写入器生命周期。openclaw agent exec 默认删除其临时状态目录,因此其审计证据会与隔离运行的其余部分一起被有意丢弃。当运行状态必须保持可用时,请使用 agent exec --state-dir <dir>,并通过使用同一状态目录的 Gateway 检查它。
该账本与对话记录分离:它记录身份、排序、来源、动作、状态和标准化结果代码,但从不存储内容;消息标识符仅以安装本地的键控假名形式出现。审计历史 描述了完整的数据模型、隐私语义、存储/保留边界和覆盖范围限制;本页介绍命令接口。
openclaw audit
openclaw audit --agent main --status failed
openclaw audit --session "agent:main:main" --after 2026-07-01T00:00:00Z
openclaw audit --run 8c69f72e-8b11-4c54-98d5-1a3dd67450c3
openclaw audit --run 8c69f72e-8b11-4c54-98d5-1a3dd67450c3 --explain
openclaw audit --execution 5da4c4c3-e1c9-4c95-a17d-6e5c10fd45cf --explain
openclaw audit --execution 5da4c4c3-e1c9-4c95-a17d-6e5c10fd45cf --explain --json
openclaw audit --run 8c69f72e-8b11-4c54-98d5-1a3dd67450c3 --explain --json
openclaw audit --kind tool_action --limit 50 --json
openclaw audit --kind message --direction outbound --channel telegram --json
过滤器¶
--agent <id>:精确的 agent id--session <key>:精确的 session key--run <id>:精确的 run id;除非同时设置了--explain,否则过滤活动--execution <id>:精确的 execution id;需要--explain--kind <kind>:agent_run、tool_action或message--status <status>:started、succeeded、failed、cancelled、timed_out、blocked或unknown--direction <direction>:消息方向,inbound或outbound--channel <channel>:精确的消息通道--after <timestamp>/--before <timestamp>:包含所给端点的 ISO 时间戳或 Unix 毫秒--limit <count>:活动页大小 1 到 500(默认100),决策页大小 1 到 100,或使用--explain时有歧义的执行候选页大小 1 到 50(默认50)--cursor <sequence>:继续活动、决策或有歧义的执行候选页--explain:检查不可变的执行身份和运行准入推理;要求--run和--execution中恰好提供一项,且仅接受--limit、--cursor、--json--json:以 JSON 形式打印有界页
CLI 查询版本化的活动 RPC,因此一条命令即可显示完整配置的账本。文本输出显示时间、类型、方向、通道、状态、agent、run 和操作。缺失的消息来源渲染为 -;OpenClaw 不会编造 agent 或 run id。工具操作还会显示工具名称。当存在下一页时,JSON 输出包含 nextCursor。将该值传给 --cursor 即可继续,而不会重新排列分页期间到达的记录。
即使没有消息正文和原始消息身份字段,这些导出仍属于敏感的操作元数据。Agent、session 和 run id、时间、通道、结果以及稳定的 HMAC 引用都可能关联活动。请像保护其他操作员记录一样,使用相同的访问控制和保留策略来保护它们。
Gateway 有意将保留的执行身份诊断暴露给其 operator 域中每个拥有 operator.read 的客户端。该范围是受信任的只读边界,而非敌对的多租户隔离。如果操作员之间不应共享审计身份数据,请使用独立的 Gateway 信任域。
发现并解释执行¶
每个被准入的外层轮次都会收到一个不透明的 executionId。contextId 标识其不可变的证据记录;现有的 runId 仍然是可能共享的会话、路由或恢复关联。使用 --run <id> --explain 来发现保留的执行,而不是查询尽力而为的活动列表。单个匹配会直接解析。多个匹配返回 ambiguous,列出最多 50 个候选者,并提示你明确选择一个:
OpenClaw 绝不会静默选择第一个或最新的执行。精确的文本视图呈现以下部分:
- 身份:信任域、调用者、入口、agent 主体、agent 定义、运行时实例、被代表主体和发起方。
- 权限:适用的授权与保证证据。
- 谱系:父上下文或显式的 absent、unknown 或 unsupported 状态。
- 决策:有界的运行准入与权威的动作决策回执,包括最终 operator 批准和精确边界的 cron 生命周期行。独立的审计事件和决策事实在其现有保留策略下仍然可用;任务/流程生命周期联接已退役。
- 缺失证据和后续步骤。
每个字段的值可以是 present、absent、unknown 或 unsupported;CLI 不会根据 session key、设备 id、显示名称或共享凭据推断用户。直接本地运行显示权威的 local-cli 入口、缺失的调用者和 unattributed 覆盖。其准入回执显示 not-applicable,因为没有证明任何身份感知的策略或授权评估。
来自 cron_run_receipts 的 cron 生命周期行,当其键控生命周期元数据携带确切的被检查上下文和执行 ID 时,会呈现为 owner-native、attribution-only 的收据。它们包含状态和有界记录引用,不包含提示词、任务目标、钩子载荷、路径或原始错误。它们的决策是 not-applicable,因为生命周期归因并不证明授权。任务与流程检查关联已被停用,但其现有存储布局保持不变。没有新的迁移会删除或复制独立的审计事件或决策事实。
将所有决策游标视为不透明:数字值以及 a:、m: 和 g: 值保持兼容。Cron 页面可能返回 c:。格式正确的历史 t: 或 f: 游标会报告 decision cursor is no longer retained; restart inspection without --cursor。它不会别名指向已保留的来源,也不会静默开始另一页。
对于 Gateway 运行,已解析的经过身份验证的配置文件可以让调用者(invoker)为 present,覆盖范围为 attribution-only。配对设备和共享凭据并不能确立一个人:没有持久配置文件时,调用者保持 absent;当经过身份验证的用户证据承诺了一个无法解析的配置文件时,则为 unknown。会话创建会保留实时的规范化持久配置文件 ID,因此配置文件链接不会使所有权孤立,而运行检查则使用不可变的连接时审计事实。普通会话来源不存储显示标签。只有在显式启用该审计存储后,才能在执行身份中保留一个可选的、有界且经过机密编辑的标签。
已接纳的频道运行也可以显示一个假名化的人员调用者。受信任的、处于活动状态且已注册的原生插件会产生远程参与者事实;核心会验证其确切记录、注册表纪元、作用域和一次性交接。由此产生的 boundary-verified 保证描述的是该进程内边界,而非核心对远程服务的独立查询。身份永远不会来自会话、房间、路由、账户、线程、消息、传输、会话密钥或显示名称。仅当所有排队输入都为同一参与者携带有效证据时,收集到的运行才会显示该人员;混合或缺失证据则显示 unknown 调用者。只有在该参与者影响了每一个促成访问决策时,其 channel/admission 收据才被强制执行;否则仅为 attribution-only。
对于频道入口(ingress),unknown 意味着受支持的集成无法提供有效的主机绑定证据;它绝不表示允许。unsupported 保留给没有权威入口集成的命名路径。插件提供的发送者或结构上复制的解析器结果不能升级这两种状态中的任何一种。
终端审批显示会展示 allowed 或 denied、其稳定的原因代码、强制执行状态、已验证的生产者类别、策略和授权(grant)计数、使用的上下文字段以及补救措施。已过期和已取消的审批是带不同原因代码的拒绝非操作。仅当审批所有者记录了该终态时,no-route 才是被强制执行的拒绝。损坏的审批为 unknown。文本视图将已验证的操作员审批生产者标记为权威的 owner-native SQLite 记录,保留 30 天。文本和 JSON 都不会暴露原始来源所有者、记录引用、策略引用或授权引用。enforced 要求审批的不可变所有者本地绑定与所选的上下文、执行和运行完全匹配。缺失、格式错误或不匹配的绑定会报告 operator_approval_execution_link_missing、operator_approval_execution_link_malformed 或 operator_approval_execution_link_mismatch,且覆盖范围为 unknown,没有授权引用。检查器绝不会根据 runId、会话元数据、时间戳或保留执行的数量重建该绑定。
出站消息收据区分持久生命周期,而不会将传输进度视为授权:
message_queued:共享投递队列已接受保管。message_platform_started:频道适配器已开始平台发送。message_delivered:适配器返回了收件人可见的投递身份。message_delivery_failed_<stage>或message_delivery_unknown_<stage>:投递未产生已证明的成功;后缀标识重试前的queue、platform_send或unknown阶段。message_suppressed_<reason>:所属钩子或载荷规范化器有意不产生可见消息。
这些 owner-native 记录始终为 attribution-only。队列和平台启动进度来自惰性 outbound_message_progress 伴随表;终态结果保留在 audit_events 中。两者仅在已接纳回合提供了一个经主机验证的上下文/执行/运行绑定时,才保留该绑定。检查要求该确切绑定,并且绝不会将仅运行时的投递证据从 runId 分配给某个执行。该绑定是诊断性来源,并非身份或授权已批准投递的证明。目标验证、消息策略和活动回合能力拒绝仅当其确切元组被记录且该门禁改变了结果时,才为 enforced。没有持久投递记录的可移植操作和早期抑制使用通用决策事实所有者,而不是复制投递状态。
插件、节点和工作进程收据使用相同的覆盖词汇:
- 已注册插件的
before_tool_call钩子允许/阻止、节点配对或能力决策,以及精确的工作进程凭据/构建/所有者纪元准入,都是enforced门禁。 - 成功的节点结果或已完成的插件所属运行是
attribution-only;成功绝不会将先前的门禁升级为授权证明。 - 插件节点策略在未调用其提供的节点回调的情况下返回,则为
unknown,并缺少node.action_callback。 - 在 ACP 或其他外部原生运行时中完全执行、且没有 OpenClaw 预操作回调的动作,在已接纳的提示提交后会产生一个 ACP 所有者的
unsupported收据,并缺少native.action_callback。它不会声称产生副作用。向适配器添加权威的原生操作回调以提供更强证据;转录文本或任务文本无法修复这一证据缺口。
这些通用回执不保留插件 ID、节点 ID、worker 环境或会话 ID、凭据或构建哈希、token、命令、参数,或原始错误文本。Owner 原生审批、配对、放置和 worker 操作行不会被重复。
JSON 输出是 Gateway 的仅安全结果,不进行有损重排。精确结果包含一个有界 V1 上下文(最大 16 KiB)、最多 100 个 decisionDisplays、覆盖范围和缺失证据代码,以及可选的 nextDecisionCursor。模糊的运行结果则最多包含 50 个执行候选项和可选的 nextExecutionCursor。敏感域、运行时、调用者、保障、入口来源和授权引用是安装本地 HMAC 投影。已配置的 agent ID 和精确运行 ID 仍然可见,上下文 ID 和执行 ID 也仍然可见,因此重定向输出仍然是私有操作员数据。
较旧的 Gateway 会产生显式 unsupported 结果,并带有 gateway_upgrade_required 以及升级并重试的下一步。CLI 从不从旧版审计行重建身份。当前 Gateway 会区分未知运行、不可用的 pre-feature、已禁用或写入失败的上下文、已过期的上下文以及损坏的上下文,而不会声称缺失的最佳努力活动证明没有执行。新准入的运行也可能暂时不可用,因为其有界身份信封正在审计写入器队列中等待;请在运行结束后或正常进程关闭后重试检查。准入从不等待写入器就绪、schema 或 HMAC 密钥初始化、SQLite 或持久化。
一旦上下文超过 30 天,CLI 不再返回其中的任何字段或关联决策。在有界清理待处理期间,结果为 unsupported,并带有过期并重试的下一步。清理后,如果没有单独保留的活动,它可能变为 unknown;这种缺失并不证明该运行未发生。启动和每小时维护每个 tick 最多修剪 1,024 个身份上下文,并在收集被禁用时继续。队列饱和、存储故障、清理失败、关闭超时或进程突然终止可能丢失最佳努力证据,但绝不会阻塞或中止 agent 运行。当写入器生命周期允许时,正常 Gateway 和 direct-local CLI 关闭会刷新已接受的工作。
记录事件¶
Gateway 为八个操作收集可信生命周期流:
agent.run.startedagent.run.finishedtool.action.startedtool.action.finishedmessage.inbound.processedmessage.outbound.queuedmessage.outbound.platform-startedmessage.outbound.finished
活动账本返回运行、工具、入站消息和终态出站记录。非终态出站操作使用独立的进度所有者,并由 --run ... --explain 投影为决策回执;它们不会被放入兼容已发布读取器的活动账本。每个返回的活动记录都有稳定的事件 ID、单调递增的账本序列、生命周期时间戳、actor、action、status、schemaVersion: 1 标记、源序列,以及 redaction: "metadata_only"。
Agent/session/run 来源信息和事件特定字段仅在可信源提供时存在。消息记录有意省略 sessionKey 和 sessionId,因此 --session 仅过滤运行和工具记录。
终态运行和工具记录使用封闭的状态和错误代码区分成功、失败、取消、超时以及策略阻止。当上游运行时未暴露权威终态结果时,unknown 是显式的非成功结果。工具调用 ID 仅作为稳定指纹导出。工具名称必须匹配紧凑的面向模型名称契约;其他值变为 unknown。
消息记录添加 direction、channel、conversation kind、outcome,以及可选的 delivery kind、failure stage、duration、result count、normalized reason code,以及带密钥的 account/conversation/message/target 伪名。当前入站边界覆盖到达核心分发的已接受消息,包括核心重复和终态处理结果。出站边界向其惰性 companion 写入可重放安全的 queued 和 platform_started 进度记录,并为每个到达共享持久投递的原始逻辑回复载荷写入一行终态活动记录。分块和适配器扇出聚合在终态 resultCount 中。
在确认、死信或对账使该结果可知后,终态为 sent、suppressed、failed 或 unknown。
绕过这些共享边界的插件本地和 direct-send 路径尚未覆盖;缺少某行并不证明不存在消息。
审计账本不替代会话转录、Cron 运行历史或日志。它为操作员问题提供小型跨运行索引,而无需将对话内容复制到另一个存储中。
对于入站行,durationMs 衡量核心分发,resultCount 统计已最终确定的排队 tool、block 和 reply 载荷。对于出站行,durationMs 包含直到其终态的投递所有权(因此包括排队等待时间),而 resultCount 统计已识别的物理平台发送。deliveryKind 存在时,描述有效的 post-hook、post-render 载荷;suppressed 和崩溃歧义行省略它。
Gateway RPC¶
audit.activity.list 需要 operator.read,并接受相同的过滤器。它返回命名的 V1 活动事件联合,包括运行、工具、入站消息和终态出站消息记录。
结果是 { "events": AuditActivityEventV1[], "nextCursor"?: string }。
结果按最新优先排序,每次请求限制为 500 条记录。
audit.run.inspect 也需要 operator.read:
openclaw gateway call audit.run.inspect \
--params '{"runId":"8c69f72e-8b11-4c54-98d5-1a3dd67450c3","decisionLimit":50}'
openclaw gateway call audit.run.inspect \
--params '{"executionId":"5da4c4c3-e1c9-4c95-a17d-6e5c10fd45cf","decisionLimit":50}'
其结果为 { "schemaVersion": 1, "run": ..., "identity": ...,
"decisionDisplays": ..., "coverage": ..., "nextDecisionCursor"?: ...,
"nextExecutionCursor"?: ... }。必需的 decisionDisplays 数组是唯一回执展示字段。原始所有者回执和 decisions 键从不跨越 Gateway 边界。
封闭请求恰好接受 executionId 或 runId 之一。
decisionLimit 为 1–100,decisionCursor 可选。运行发现也接受 1–50 的 executionLimit 和可选的 executionCursor。具有多个保留执行的运行会返回带类型的 ambiguous 身份状态,且不返回身份上下文;其必需的 decisionDisplays 数组在调用方选择执行 id 之前为空。
对于某个已选上下文,回执分页从 admission 开始,然后读取所有者原生的终态批准,合并出站进度和终态记录,然后读取 generic 事实和 cron 生命周期所有者。完整顺序为 admission、approval、message、generic,然后 cron。
该合并在重启之间是确定性的,并拒绝其精确所有者行已过期的游标。approval 和 message 选择器使用从同一所有者查询快照铸造的不透明 approval-decision: 和 message-decision: 命名空间;原始回执、resolution 和 event 标识符永远不会成为选择器。
approval 和 delivery 检查从不写入 generic 重复项。generic 事实写入和投影也要求完整的 context、execution 和 run 元组与不可变的 execution context 匹配。
活动账本仍为尽力而为。相比之下,返回的 approval 回执来自权威的 first-answer-wins approval 行,返回的 generic 回执来自可附加的不可变 decision-fact 表。这三个接口均使用 30 天保留期,但活动账本中缺失不能证明某个 approval 或 action 未发生。generic 事实 delivery 也是尽力而为,直到其有界队列写入持久化该行;所有者原生 approval 持久化不使用该队列。
已发布的 audit.list RPC 对较旧的 run/tool 客户端保持不变。当较旧 Gateway 上 audit.activity.list 不可用时,CLI 仅当每个请求的过滤器都受该遗留方法支持时才重试 audit.list。在较旧 Gateway 上,--kind message、--direction 和 --channel 会因升级消息而失败,而不是被静默丢弃。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw