From d8db122a23b600ff0f32ee5d1ccc6c505be308a5 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 23 Apr 2026 07:39:45 +0100 Subject: [PATCH] docs: document trajectory bundles --- docs/docs.json | 1 + docs/tools/slash-commands.md | 2 +- docs/tools/trajectory.md | 184 +++++++++++++++++++++++++++++++++++ 3 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 docs/tools/trajectory.md diff --git a/docs/docs.json b/docs/docs.json index 9e502593e97..369037d2c60 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1215,6 +1215,7 @@ "tools/btw", "tools/code-execution", "tools/diffs", + "tools/trajectory", "tools/elevated", "tools/exec", "tools/exec-approvals", diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md index 8a6ed6aff2b..0b9bd0e921e 100644 --- a/docs/tools/slash-commands.md +++ b/docs/tools/slash-commands.md @@ -112,7 +112,7 @@ Built-in commands available today: - `/tasks` lists active/recent background tasks for the current session. - `/context [list|detail|json]` explains how context is assembled. - `/export-session [path]` exports the current session to HTML. Alias: `/export`. -- `/export-trajectory [path]` exports a JSONL trajectory bundle for the current session. Alias: `/trajectory`. +- `/export-trajectory [path]` exports a JSONL [trajectory bundle](/tools/trajectory) for the current session. Alias: `/trajectory`. - `/whoami` shows your sender id. Alias: `/id`. - `/skill [input]` runs a skill by name. - `/allowlist [list|add|remove] ...` manages allowlist entries. Text-only. diff --git a/docs/tools/trajectory.md b/docs/tools/trajectory.md new file mode 100644 index 00000000000..4870cce96df --- /dev/null +++ b/docs/tools/trajectory.md @@ -0,0 +1,184 @@ +--- +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 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: + +```text +/export-trajectory +``` + +Alias: + +```text +/trajectory +``` + +OpenClaw writes the bundle under the workspace: + +```text +.openclaw/trajectory-exports/openclaw-trajectory--/ +``` + +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. + +## 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: + +```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, 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: + +```text +.trajectory.jsonl +``` + +OpenClaw also writes a best-effort pointer file beside the session: + +```text +.trajectory-path.json +``` + +Set `OPENCLAW_TRAJECTORY_DIR` to store runtime trajectory sidecars in a +dedicated directory: + +```bash +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: + +```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: 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.