OpenClaw Trajectory Bundles Explained

Trajectory bundles are OpenClaw's flight recorder for a single session. The docs describe trajectory capture as a structured timeline for each agent run, then /export-trajectory packages that timeline into a redacted support bundle you can inspect or share carefully.

30-second answer

Use trajectory export when you need to understand why an agent answered a certain way, called a tool, timed out, compacted, changed model, or hit a provider error. The command is /export-trajectory, with /trajectory as an alias. It writes under .openclaw/trajectory-exports/ and rejects absolute or home-directory output paths.

What gets recorded

The docs list events such as session start and end, compiled context, submitted prompts, model fallback steps, model completion, trace artifacts, user and assistant messages, tool calls, tool results, compactions, model changes, labels, and custom session entries. That gives you a timeline instead of a vague memory of what the agent seemed to do.

A bundle can also include model, plugin, skill, runtime setting, usage, and prompt-cache metadata. That matters when a failure only appears under one model, one channel, or one tool policy. Instead of guessing, you can inspect the actual run inputs and runtime events.

Privacy model

Trajectory export is powerful enough to be sensitive. The docs say the chat slash command runs through exec approval every time because bundles can contain prompts, model messages, tool schemas, tool results, runtime events, and local paths. In group chats, approval prompts and results go to the owner privately instead of being posted back into the group.

Redaction covers credentials and known secret-like fields, image data, local state paths, workspace paths, and home directory paths where detected. Redaction reduces risk, but it does not turn a trajectory bundle into casual public content. Treat it like a support artifact, not a blog post.

Command examples

/export-trajectory
/trajectory
/export-trajectory bug-1234

For scripted support work, the docs also show openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .. The safer day-to-day habit is to export from the active session only when you know why you need the bundle.

Operator checklist

Before exporting, write down the symptom: bad answer, wrong tool, timeout, abort, compaction, provider error, or unexpected fallback. After exporting, inspect the manifest first, then the run timeline. If the bundle is empty, confirm trajectory capture was not disabled with OPENCLAW_TRAJECTORY=0 and that the trajectory directory is writable.

The OpenClaw Playbook uses trajectory review as a debugging discipline: stop arguing with vague logs, preserve the run, read the actual evidence, then fix the prompt, policy, tool schema, or provider route that caused the failure.

Rollout plan

Treat OpenClaw Trajectory Bundles Explained as a workflow you roll out in stages, not a switch you flip once. Start with the smallest harmless proof: a status check, dry run, local-only call, private session, or read-only inspection. Confirm the documented behavior matches your installed OpenClaw version, then write the exact commands and expected output into the workspace so the next agent does not rely on memory or vibes.

For a production runbook, document decision owner, source document, acceptance check, upgrade risk, and where future agents should look before changing the behavior. Also write down what the agent may do alone, what requires approval, and what must stop immediately. That boundary is the difference between useful autonomy and a workflow that surprises the operator at the worst possible time.

Keep one rollback note beside the guide. It can be as simple as the command to disable a plugin, the channel to pause, the config key to revert, or the owner who must approve the next run. Include the proof that tells you rollback worked, and keep it visible near the production checklist for future maintainers. Agents are most useful when recovery is obvious.

After the first live run, review the transcript or logs while the details are fresh. Look for missing prerequisites, stale assumptions, broad prompts, confusing errors, and any external side effect that should have been gated. Tighten the guide, then repeat with one wider scope. The OpenClaw Playbook is built around this operating rhythm: cautious first proof, written runbook, verified automation, then gradual autonomy once the evidence is boring.