moltbot/docs/tools/trajectory.md

---
summary: "Export redacted trajectory bundles for debugging an OpenClaw agent session"
read_when:
  - 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
title: "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?

If you are filing a broad support report for a live Gateway issue, start with
[`/diagnostics`](/gateway/diagnostics#chat-command). Diagnostics collects the
sanitized Gateway bundle and, for OpenAI Codex harness sessions, can also send
Codex feedback to OpenAI servers after approval. Use `/export-trajectory` when
you specifically need the detailed per-session prompt, tool, and transcript
timeline.

## Quick start

Send this in the active session:

```text
/export-trajectory
```

Alias:

```text
/trajectory
```

OpenClaw writes the bundle under the workspace:

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

You can choose a relative output directory name:

```text
/export-trajectory bug-1234
```

The custom path is resolved 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. The chat slash command therefore runs
through exec approval every time. 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 the
trajectory details back to the shared room.

For local inspection or support workflows, you can also run the approved command
path directly:

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

## 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.fallback_step`, including the source model, next model, failure reason/detail, chain position, and whether fallback advanced, succeeded, or exhausted the chain
- `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:

```json
{
  "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, tool metadata, and SQLite tool-artifact 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.

`artifacts.json` may include `toolArtifacts` entries for run-scoped SQLite
artifacts such as runtime trajectory mirrors or tool media manifests. These
entries are metadata-only: the export omits artifact blobs and `blobBase64`
payloads so large generated media is not duplicated into the support bundle.

## Capture location

By default, runtime trajectory events are written to the owning agent database:

```text
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
trajectory_runtime_events
```

The export manifest reports this source as an agent-database reference, for
example:

```text
agent-db:<agentId>:trajectory_runtime_events:<sessionId>
```

For compatibility with older captures, `/export-trajectory` can still read a
legacy `<session>.trajectory.jsonl` sidecar or pointer file when no SQLite
runtime events exist for the session. New runtime captures do not create those
files. `OPENCLAW_TRAJECTORY_DIR` is therefore only useful for legacy/debug
captures and is not the normal durable store.

## Disable capture

Set `OPENCLAW_TRAJECTORY=0` before starting OpenClaw:

```bash
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: live capture stops at 10 MiB and records a truncation event when space remains; export accepts existing runtime sidecars up to 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.

## Related

- [Diffs](/tools/diffs)
- [Session management](/concepts/session)
- [Exec tool](/tools/exec)