轨迹包
轨迹捕获是 OpenClaw 的按会话飞行记录器。它为每次代理运行记录结构化时间线,然后 /export-trajectory 将当前会话打包成脱敏的支持包,涵盖:
- 发送给模型的提示、系统提示和工具
- 哪些转录消息和工具调用导致了答案
- 运行是否超时、中止、压缩或遇到提供商错误
- 哪些模型、插件、技能和运行时设置处于活动状态
- 提供商返回的使用量和提示缓存元数据
如需广泛的 Gateway 支持报告,请改用
/diagnostics;它会收集脱敏的 Gateway 支持包,并且对于 OpenAI Codex harness 会话,可以在批准后向 OpenAI 发送 Codex 反馈。当你需要详细的按会话提示、工具和转录时间线时,请使用 /export-trajectory。
快速开始¶
在活跃会话中发送(别名 /trajectory):
OpenClaw 将支持包写入工作区下:
传入相对输出目录名以覆盖默认值:
该名称在 .openclaw/trajectory-exports/ 内解析。绝对路径和
~ 路径会被拒绝。
轨迹支持包可能包含提示、模型消息、工具架构、工具结果、运行时事件和本地路径,因此聊天命令始终通过 exec 审批运行。当你打算创建支持包时,请一次性批准导出;不要使用 allow-all。在群聊中,OpenClaw 会私下将审批提示和导出结果发送给所有者,而不是将轨迹详情发布回共享房间。房间只会收到一条状态通知,用于区分已确认、待处理和已抑制的私密投递。
用于本地检查或支持工作流时,直接运行底层 CLI 命令:
其他标志:--output <path>(.openclaw/trajectory-exports 内的目录名)、--store <path>(会话存储覆盖)、--agent <id>(用于存储解析的代理 id)、--json(结构化输出)。
访问¶
轨迹导出是所有者命令。发送者必须通过常规命令授权检查,以及该频道的所有者检查。
记录内容¶
对于 OpenClaw 代理运行,轨迹捕获默认开启。
运行时事件包括:
session.startedtrace.metadatacontext.compiledprompt.submittedtool.call,包含工具标识和脱敏参数tool.result,包含脱敏结果和执行结果model.fallback_step,包括源模型、下一模型、失败原因/详情、链位置,以及链是否推进、成功或耗尽model.completedtrace.artifactssession.ended
转录事件从活跃会话分支重建:用户消息、助手消息、工具调用、工具结果、压缩、模型变更、标签和自定义会话条目。
事件以 JSON Lines 写入,并带有此架构标记:
支持包文件¶
| 文件 | 内容 |
|---|---|
manifest.json |
支持包架构、源文件、事件计数和生成的文件列表 |
events.jsonl |
有序的运行时和转录时间线 |
session-branch.json |
脱敏的活跃转录分支和会话头 |
metadata.json |
OpenClaw 版本、操作系统/运行时、模型、配置快照、插件、技能和提示元数据 |
artifacts.json |
最终状态、错误、使用量、提示缓存、压缩计数、助手文本和工具元数据 |
prompts.json |
已提交的提示和选定的提示构建详情 |
system-prompt.txt |
捕获时最新编译的系统提示,如已捕获 |
tools.json |
发送给模型的工具定义,如已捕获 |
manifest.json 列出给定支持包中存在的文件;如果会话未捕获相应的运行时数据,则某些文件会被省略。
捕获存储¶
运行时轨迹事件与会话一起存储在按代理划分的 SQLite 数据库中。活跃运行以批次持久化事件;清理会排空最终批次。当数据库写入器繁忙时,排队事件遵循相同的滚动字节限制。导出轨迹会生成脱敏的 JSONL 支持包;实时运行时捕获不是会话相邻的 JSONL 边车文件。
每个会话保留一个滚动 10 MiB 运行时窗口。全局保留策略会删除 14 天前的完整运行,然后删除最旧的剩余运行,以将总量控制在 512 MiB。触发清理的会话由其自身的滚动窗口保护。全局清理在首次使用时开始,之后每小时执行一次,独立于追加操作。它选择有界批次而不持有数据库写入器,并在每次删除前重新检查选择。清理通过有界批次继续;并发更改会将过时的选择推迟到稍后的追加。
运行时导出读取 SQLite 捕获。2026 年 7 月之前的 .trajectory.jsonl 和
.trajectory-path.json 边车文件不再被读取或跟踪。保留任何所需诊断数据后,可以删除现有文件。
禁用捕获¶
这会在启动 OpenClaw 之前禁用运行时轨迹捕获。
/export-trajectory 仍然可以导出转录分支,但仅运行时数据(例如编译上下文、提供商工件和提示元数据)可能缺失。
调整刷新超时¶
OpenClaw 会在代理清理期间排空任何待处理的运行时轨迹行。默认清理超时为 10,000 ms。在慢速磁盘或大型存储上,请在启动 OpenClaw 前设置 OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS:
这控制 OpenClaw 何时记录 openclaw-trajectory-flush 超时并继续;它不会改变轨迹大小上限。若要调整所有未显式传入超时的代理清理步骤,请设置 OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS。
隐私与限制¶
轨迹包用于支持和调试,而非公开发布。OpenClaw 在写入导出文件前会脱敏敏感值:
- 凭据和已知的类似密钥的负载字段
- 图像数据
- 本地状态路径
- 工作区路径,替换为
$WORKSPACE_DIR - 主目录路径(如检测到)
导出器还会限制输入大小:
- 运行时捕获:实时捕获是一个上限为 10 MiB 的滚动窗口,会丢弃最旧的事件以为新事件腾出空间;导出接受最多 50 MiB 的 SQLite 运行时存储
- 会话(转录)源:50 MiB,无论读取自 SQLite 转录存储还是会话文件
- 每次导出的运行时事件数:200,000
- 导出的总事件数:250,000
- 单个运行时事件行超过 256 KiB 时会被截断
源字节限制在解析事件之前检查。SQLite 源使用 UTF-8 JSONL 大小,包括行之间的分隔符,无论数据库编码如何。SQLite 运行时事件计数也会在加载行之前检查。超大的源会在创建导出包之前以大小错误失败。
这些是逐源限制,不是进程总内存的上限。解析、投影、脱敏和输出序列化可能保留额外副本;大型导出仍可能需要比源大小更多的内存。
在将包分享给团队外部之前,请审查这些包。脱敏是尽力而为的,无法知晓每个应用程序特定的密钥。
故障排除¶
如果导出没有运行时事件:
- 确认 OpenClaw 启动时未设置
OPENCLAW_TRAJECTORY=0 - 在会话中再运行一条消息,然后再次导出
- 检查
manifest.json中的runtimeEventCount
如果命令拒绝输出路径:
- 使用类似
bug-1234的相对名称 - 不要传入
/tmp/...或~/... - 将导出保留在
.openclaw/trajectory-exports/内
如果导出因大小错误失败,则某个转录或运行时源(SQLite 存储或文件)超过了上述导出安全限制。请开始新会话或导出更小的复现。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw