openclaw/docs/tools/trajectory.md

summary, read_when, title

summary	read_when	title
Export redacted trajectory bundles for debugging an OpenClaw agent session	Debugging why an agent answered, failed, or called tools a certain way Exporting a support bundle for an OpenClaw session Investigating prompt context, tool calls, runtime errors, or usage metadata Disabling or relocating trajectory capture	Trajectory Bundles

Trajectory bundles

Trajectory capture is OpenClaw's per-session flight recorder. It records a structured timeline for each agent run, then /export-trajectory packages the current session into a redacted support bundle.

Use it when you need to answer questions like:

• What prompt, system prompt, and tools were sent to the model?
• Which transcript messages and tool calls led to this answer?
• Did the run time out, abort, compact, or hit a provider error?
• Which model, plugins, skills, and runtime settings were active?
• What usage and prompt-cache metadata did the provider return?

Quick start

Send this in the active session:

/export-trajectory

Alias:

/trajectory

OpenClaw writes the bundle under the workspace:

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

You can choose a relative output directory name:

/export-trajectory bug-1234

The custom path is resolved inside .openclaw/trajectory-exports/. Absolute paths and ~ paths are rejected.

Access

Trajectory export is an owner command. The sender must pass the normal command authorization checks and owner checks for the channel.

What gets recorded

Trajectory capture is on by default for OpenClaw agent runs.

Runtime events include:

• session.started
• trace.metadata
• context.compiled
• prompt.submitted
• model.completed
• trace.artifacts
• session.ended

Transcript events are also reconstructed from the active session branch:

• user messages
• assistant messages
• tool calls
• tool results
• compactions
• model changes
• labels and custom session entries

Events are written as JSON Lines with this schema marker:

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

Bundle files

An exported bundle can contain:

File	Contents
manifest.json	Bundle schema, source files, event counts, and generated file list
events.jsonl	Ordered runtime and transcript timeline
session-branch.json	Redacted active transcript branch and session header
metadata.json	OpenClaw version, OS/runtime, model, config snapshot, plugins, skills, and prompt metadata
artifacts.json	Final status, errors, usage, prompt cache, compaction count, assistant text, and tool metadata
prompts.json	Submitted prompts and selected prompt-building details
system-prompt.txt	Latest compiled system prompt, when captured
tools.json	Tool definitions sent to the model, when captured

manifest.json lists the files present in that bundle. Some files are omitted when the session did not capture the corresponding runtime data.

Capture location

By default, runtime trajectory events are written beside the session file:

<session>.trajectory.jsonl

OpenClaw also writes a best-effort pointer file beside the session:

<session>.trajectory-path.json

Set OPENCLAW_TRAJECTORY_DIR to store runtime trajectory sidecars in a dedicated directory:

export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories

When this variable is set, OpenClaw writes one JSONL file per session id in that directory.

Disable capture

Set OPENCLAW_TRAJECTORY=0 before starting OpenClaw:

export OPENCLAW_TRAJECTORY=0

This disables runtime trajectory capture. /export-trajectory can still export the transcript branch, but runtime-only files such as compiled context, provider artifacts, and prompt metadata may be missing.

Privacy and limits

Trajectory bundles are designed for support and debugging, not public posting. OpenClaw redacts sensitive values before writing export files:

• credentials and known secret-like payload fields
• image data
• local state paths
• workspace paths, replaced with $WORKSPACE_DIR
• home directory paths, where detected

The exporter also bounds input size:

• runtime sidecar files: 50 MiB
• session files: 50 MiB
• runtime events: 200,000
• total exported events: 250,000
• individual runtime event lines are truncated above 256 KiB

Review bundles before sharing them outside your team. Redaction is best-effort and cannot know every application-specific secret.

Troubleshooting

If the export has no runtime events:

• confirm OpenClaw was started without OPENCLAW_TRAJECTORY=0
• check whether OPENCLAW_TRAJECTORY_DIR points to a writable directory
• run another message in the session, then export again
• inspect manifest.json for runtimeEventCount

If the command rejects the output path:

• use a relative name like bug-1234
• do not pass /tmp/... or ~/...
• keep the export inside .openclaw/trajectory-exports/

If the export fails with a size error, the session or sidecar exceeded the export safety limits. Start a new session or export a smaller reproduction.