Trajectory 轨迹导出

概述

Trajectory capture 是 OpenClaw 的 per-session 飞行记录器，记录每次 Agent 运行的结构化时间线。/export-trajectory 将当前会话打包成脱敏的支持 bundle。

适用场景：

模型收到了什么 prompt、system prompt 和工具？
哪些 transcript 消息和工具调用导致了这个回答？
运行是否超时、中止、压缩或遇到 provider 错误？
哪些模型、插件、skill 和运行时设置处于活跃状态？
provider 返回了什么用量和 prompt-cache 元数据？

若需要 Gateway 级别的诊断报告，用 /diagnostics；/export-trajectory 专注于 per-session 的 prompt/工具/transcript 时间线。

快速使用

/export-trajectory          # 导出当前会话
/trajectory                 # 别名
/export-trajectory bug-1234 # 自定义输出目录名（相对路径）

输出位置：

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

自定义路径在 .openclaw/trajectory-exports/ 内解析，不接受绝对路径和 ~ 路径。

CLI 路径：

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

此命令每次都走 exec 审批。群聊中，审批提示和导出结果私发给 owner，不发到共享房间。

Bundle 文件

文件	内容
`manifest.json`	Bundle schema、来源文件、事件计数、生成文件列表
`events.jsonl`	有序的运行时和 transcript 时间线
`session-branch.json`	脱敏的活跃 transcript 分支和会话头
`metadata.json`	OpenClaw 版本、OS/运行时、模型、配置快照、插件、skill、prompt 元数据
`artifacts.json`	最终状态、错误、用量、prompt cache、压缩次数、assistant 文本、工具元数据
`prompts.json`	提交的 prompt 和选定的 prompt 构建细节
`system-prompt.txt`	最新编译的 system prompt（如已捕获）
`tools.json`	发送给模型的工具定义（如已捕获）

manifest.json 列出 bundle 中存在的文件；未捕获对应数据的文件会被省略。

记录的事件

运行时事件

session.started
trace.metadata
context.compiled
prompt.submitted
model.fallback_step（含来源模型、下一模型、失败原因、链位置、是否推进/成功/耗尽）
model.completed
trace.artifacts
session.ended

Transcript 事件（从活跃会话分支重建）

用户消息、assistant 消息
工具调用、工具结果
压缩记录、模型变更
标签和自定义会话条目

事件以 JSON Lines 格式写入，schema 标记：

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

捕获位置与配置

默认写在 session 文件旁边：

<session>.trajectory.jsonl
<session>.trajectory-path.json   # 指针文件

# 自定义轨迹存储目录
export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories
 
# 禁用轨迹捕获（/export-trajectory 仍可导出 transcript 分支，但运行时文件缺失）
export OPENCLAW_TRAJECTORY=0

Session 维护时，若 session 条目被清理，对应的 trajectory sidecar 也会被移除。

隐私与大小限制

导出前自动脱敏：凭证、已知 secret 类字段、图片数据、本地状态路径、工作区路径（替换为 $WORKSPACE_DIR）、家目录路径。

项目	限制
运行时 sidecar（实时捕获）	10 MiB（超出记录截断事件）
运行时 sidecar（导出接受）	50 MiB
Session 文件	50 MiB
运行时事件数	200,000
总导出事件数	250,000
单条运行时事件行	256 KiB

脱敏是尽力而为，无法识别所有应用特定的 secret。分享前请人工审查。

故障排查

问题	排查方法
导出无运行时事件	确认未设置 `OPENCLAW_TRAJECTORY=0`；检查 `OPENCLAW_TRAJECTORY_DIR` 是否可写；再发一条消息后重新导出；查看 `manifest.json` 中的 `runtimeEventCount`
命令拒绝输出路径	使用相对名称如 `bug-1234`；不要用 `/tmp/...` 或 `~/...`
导出因大小失败	开新会话或导出更小的复现场景

Wiki AI

目录