轨迹包

轨迹捕获是 OpenClaw 的每会话飞行记录器。它为每次 agent 运行记录一条结构化时间线，然后 /export-trajectory 将当前会话打包为涵盖以下内容的脱敏支持包：

发送给模型的提示词、系统提示词和工具
哪些转录消息和工具调用最终产生了回答
运行是超时、中止、压缩，还是遇到 provider 错误
哪些模型、插件、技能和运行时设置处于活动状态
provider 返回的用量和提示词缓存元数据

如需生成覆盖面较广的 Gateway 支持报告，请改用 /diagnostics；它会收集脱敏后的 Gateway 包，并且对于 OpenAI Codex harness 会话，可以在批准后将 Codex 反馈发送给 OpenAI。当你需要详细的每会话提示词、工具和转录时间线时，请使用 /export-trajectory。

快速开始¶

在活动会话中发送（别名 /trajectory）：

/export-trajectory

OpenClaw 将包写入工作区下的目录：

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

传入相对输出目录名以覆盖默认位置：

/export-trajectory bug-1234

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

轨迹导出包可能包含提示词、模型消息、工具模式、工具结果、运行时事件和本地路径，因此该聊天命令始终需要经过 exec 批准。当你确实要创建导出包时，请批准这一次导出；不要使用 allow-all。在群聊中，OpenClaw 会将批准提示和导出结果私下发送给 owner，而不会将轨迹详情发布回共享房间。房间只会收到一条状态通知，用于区分已确认、待处理以及被抑制的私下投递。

如需在本地检查或用于支持工作流，可直接运行底层 CLI 命令：

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

其他标志：--output <path>（.openclaw/trajectory-exports 内的目录名）、--store <path>（session store 覆盖）、--agent <id>（用于 store 解析的 agent id）、--json（结构化输出）。

访问权限¶

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

记录内容¶

对于 OpenClaw agent 运行，轨迹捕获默认开启。

运行时事件包括：

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

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

事件以 JSON Lines 格式写入，并带有此 schema 标记：

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

导出包文件¶

文件	内容
`manifest.json`	包 schema、源文件、事件计数和生成的文件列表
`events.jsonl`	有序的运行时和转录时间线
`session-branch.json`	脱敏后的活动转录分支和会话头部
`metadata.json`	OpenClaw 版本、操作系统/运行时、模型、配置快照、插件、技能和提示词元数据
`artifacts.json`	最终状态、错误、用量、提示词缓存、压缩次数、助手文本和工具元数据
`prompts.json`	已提交的提示词和选定的提示词构建详情
`system-prompt.txt`	最新编译的系统提示词（如已捕获）
`tools.json`	发送给模型的工具定义（如已捕获）

manifest.json 列出给定包中存在的文件；当会话未捕获相应的运行时数据时，某些文件会被省略。

捕获存储¶

运行时轨迹事件与会话一起存储在每 agent 的 SQLite 数据库中。导出轨迹会生成一个脱敏后的 JSONL 支持包；实时运行时捕获并不是会话旁边的 JSONL sidecar 文件。

旧版发布或显式旧版文件导出仍可能产生 .trajectory.jsonl 和 .trajectory-path.json 文件。会话维护会将这些文件视为清理目标；活动捕获会写入数据库行。

禁用捕获¶

export OPENCLAW_TRAJECTORY=0

这会在启动 OpenClaw 之前禁用运行时轨迹捕获。/export-trajectory 仍可导出转录分支，但诸如编译后的上下文、provider 工件和提示词元数据等仅限运行时的数据可能会缺失。

调整刷新超时¶

OpenClaw 会在 agent 清理期间刷新运行时轨迹行。默认清理超时为 10,000 ms。在慢速磁盘或大型 store 上，请在启动 OpenClaw 前设置 OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS：

export OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=30000

这会控制 OpenClaw 在何时记录 openclaw-trajectory-flush 超时并继续执行；它不会改变轨迹大小上限。若要调整所有未传入显式超时的 agent 清理步骤，请设置 OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS。

隐私与限制¶

轨迹导出包用于支持与调试，而非公开发布。OpenClaw 在写入导出文件之前会对敏感值进行脱敏：

凭据和已知的类似密钥的 payload 字段
图像数据
本地状态路径
工作区路径，替换为 $WORKSPACE_DIR
主目录路径（若检测到）

导出器还会限制输入大小：

运行时捕获：实时捕获是一个上限为 10 MiB 的滚动窗口，会丢弃最旧的事件以为新事件腾出空间；导出接受现有的运行时源——SQLite 运行时存储或旧版运行时 sidecar 文件——最大 50 MiB
会话（转录）源：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

轨迹包