> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 covering: * The prompt, system prompt, and tools sent to the model * Which transcript messages and tool calls led to an answer * Whether the run timed out, aborted, compacted, or hit a provider error * Which model, plugins, skills, and runtime settings were active * Usage and prompt-cache metadata the provider returned For a broad Gateway support report, start with [`/diagnostics`](/gateway/diagnostics#chat-command) instead; it collects the sanitized Gateway bundle and, for OpenAI Codex harness sessions, can send Codex feedback to OpenAI after approval. Use `/export-trajectory` when you need the detailed per-session prompt, tool, and transcript timeline. ## Quick start Send in the active session (alias `/trajectory`): ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /export-trajectory ``` OpenClaw writes the bundle under the workspace: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} .openclaw/trajectory-exports/openclaw-trajectory--/ ``` Pass a relative output directory name to override it: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /export-trajectory bug-1234 ``` The name resolves inside `.openclaw/trajectory-exports/`. Absolute paths and `~` paths are rejected. Trajectory bundles can contain prompts, model messages, tool schemas, tool results, runtime events, and local paths, so the chat command always runs through exec approval. Approve the export once when you intend to create the bundle; do not use allow-all. In group chats, OpenClaw sends the approval prompt and export result to the owner privately instead of posting trajectory details back to the shared room. For local inspection or support workflows, run the underlying CLI command directly: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . ``` Other flags: `--output ` (directory name inside `.openclaw/trajectory-exports`), `--store ` (session store override), `--agent ` (agent id for store resolution), `--json` (structured output). ## Access Trajectory export is an owner command. The sender must pass the normal command authorization checks plus the owner check 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.fallback_step`, including the source model, next model, failure reason/detail, chain position, and whether the chain advanced, succeeded, or was exhausted * `model.completed` * `trace.artifacts` * `session.ended` Transcript events are 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: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "traceSchema": "openclaw-trajectory", "schemaVersion": 1 } ``` ## Bundle files | 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 a given 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: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} .trajectory.jsonl ``` OpenClaw also writes a best-effort pointer file beside the session: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} .trajectory-path.json ``` Set `OPENCLAW_TRAJECTORY_DIR` to store runtime trajectory sidecars in a dedicated directory instead, one JSONL file per session id: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories ``` Session maintenance removes trajectory sidecars when their owning session entry is pruned, capped, or evicted by the sessions disk budget. Runtime files outside the sessions directory are removed only when the pointer target still proves it belongs to that session. ## Disable capture ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_TRAJECTORY=0 ``` This disables runtime trajectory capture before starting OpenClaw. `/export-trajectory` can still export the transcript branch, but runtime-only files such as compiled context, provider artifacts, and prompt metadata may be missing. ## Tune flush timeout OpenClaw flushes runtime trajectory sidecars during agent cleanup. The default cleanup timeout is 10,000 ms. On slow disks or large stores, set `OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS` before starting OpenClaw: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=30000 ``` This controls when OpenClaw logs an `openclaw-trajectory-flush` timeout and continues; it does not change the trajectory size caps. To tune all agent cleanup steps that do not pass an explicit timeout, set `OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS`. ## Privacy and limits Trajectory bundles are 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: the live capture file is a rolling window capped at 10 MiB, dropping the oldest events to make room for new ones; export accepts existing runtime sidecar files up to 50 MiB * session files: 50 MiB * runtime events per export: 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 above. Start a new session or export a smaller reproduction. ## Related * [Diffs](/tools/diffs) * [Session management](/concepts/session) * [Exec tool](/tools/exec)