跳转至

轨迹包

轨迹捕获是 OpenClaw 的按会话飞行记录器。它为每次代理运行记录结构化时间线,然后 /export-trajectory 将当前会话打包成脱敏的支持包,涵盖:

  • 发送给模型的提示、系统提示和工具
  • 哪些转录消息和工具调用导致了答案
  • 运行是否超时、中止、压缩或遇到提供商错误
  • 哪些模型、插件、技能和运行时设置处于活动状态
  • 提供商返回的使用量和提示缓存元数据

如需广泛的 Gateway 支持报告,请改用 /diagnostics;它会收集脱敏的 Gateway 支持包,并且对于 OpenAI Codex harness 会话,可以在批准后向 OpenAI 发送 Codex 反馈。当你需要详细的按会话提示、工具和转录时间线时,请使用 /export-trajectory。

快速开始

在活跃会话中发送(别名 /trajectory):

/export-trajectory

OpenClaw 将支持包写入工作区下:

.openclaw/trajectory-exports/openclaw-trajectory-<session>-<timestamp>/

传入相对输出目录名以覆盖默认值:

/export-trajectory bug-1234

该名称在 .openclaw/trajectory-exports/ 内解析。绝对路径和 ~ 路径会被拒绝。

轨迹支持包可能包含提示、模型消息、工具架构、工具结果、运行时事件和本地路径,因此聊天命令始终通过 exec 审批运行。当你打算创建支持包时,请一次性批准导出;不要使用 allow-all。在群聊中,OpenClaw 会私下将审批提示和导出结果发送给所有者,而不是将轨迹详情发布回共享房间。房间只会收到一条状态通知,用于区分已确认、待处理和已抑制的私密投递。

用于本地检查或支持工作流时,直接运行底层 CLI 命令:

openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .

其他标志:--output <path>(.openclaw/trajectory-exports 内的目录名)、--store <path>(会话存储覆盖)、--agent <id>(用于存储解析的代理 id)、--json(结构化输出)。

访问

轨迹导出是所有者命令。发送者必须通过常规命令授权检查,以及该频道的所有者检查。

记录内容

对于 OpenClaw 代理运行,轨迹捕获默认开启。

运行时事件包括:

  • session.started
  • trace.metadata
  • context.compiled
  • prompt.submitted
  • tool.call,包含工具标识和脱敏参数
  • tool.result,包含脱敏结果和执行结果
  • model.fallback_step,包括源模型、下一模型、失败原因/详情、链位置,以及链是否推进、成功或耗尽
  • model.completed
  • trace.artifacts
  • session.ended

转录事件从活跃会话分支重建:用户消息、助手消息、工具调用、工具结果、压缩、模型变更、标签和自定义会话条目。

事件以 JSON Lines 写入,并带有此架构标记:

{
  "traceSchema": "openclaw-trajectory",
  "schemaVersion": 1
}

支持包文件

文件 内容
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 边车文件不再被读取或跟踪。保留任何所需诊断数据后,可以删除现有文件。

禁用捕获

export OPENCLAW_TRAJECTORY=0

这会在启动 OpenClaw 之前禁用运行时轨迹捕获。 /export-trajectory 仍然可以导出转录分支,但仅运行时数据(例如编译上下文、提供商工件和提示元数据)可能缺失。

调整刷新超时

OpenClaw 会在代理清理期间排空任何待处理的运行时轨迹行。默认清理超时为 10,000 ms。在慢速磁盘或大型存储上,请在启动 OpenClaw 前设置 OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS:

export OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=30000

这控制 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