From 04a14e5dfc6239327f2a6e406ee670f2a5fb5669 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Thu, 23 Apr 2026 06:40:47 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@d8db122a23b600ff0f32ee5d1ccc6c505be308a5 --- .openclaw-sync/source.json | 4 +- docs/docs.json | 14 +++ docs/tools/slash-commands.md | 2 +- docs/tools/trajectory.md | 184 +++++++++++++++++++++++++++++++++++ 4 files changed, 201 insertions(+), 3 deletions(-) create mode 100644 docs/tools/trajectory.md diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 752598c4f..f8ee8bb04 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "30a5c441f32109bc8d4e424903e70564bba71ed3", - "syncedAt": "2026-04-23T06:40:36.740Z" + "sha": "d8db122a23b600ff0f32ee5d1ccc6c505be308a5", + "syncedAt": "2026-04-23T06:40:47.326Z" } diff --git a/docs/docs.json b/docs/docs.json index f1675382e..cdc7217b1 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1227,6 +1227,7 @@ "tools/btw", "tools/code-execution", "tools/diffs", + "tools/trajectory", "tools/elevated", "tools/exec", "tools/exec-approvals", @@ -2614,6 +2615,7 @@ "ja-JP/tools/btw", "ja-JP/tools/code-execution", "ja-JP/tools/diffs", + "ja-JP/tools/trajectory", "ja-JP/tools/elevated", "ja-JP/tools/exec", "ja-JP/tools/exec-approvals", @@ -3386,6 +3388,7 @@ "es/tools/btw", "es/tools/code-execution", "es/tools/diffs", + "es/tools/trajectory", "es/tools/elevated", "es/tools/exec", "es/tools/exec-approvals", @@ -4158,6 +4161,7 @@ "pt-BR/tools/btw", "pt-BR/tools/code-execution", "pt-BR/tools/diffs", + "pt-BR/tools/trajectory", "pt-BR/tools/elevated", "pt-BR/tools/exec", "pt-BR/tools/exec-approvals", @@ -4930,6 +4934,7 @@ "ko/tools/btw", "ko/tools/code-execution", "ko/tools/diffs", + "ko/tools/trajectory", "ko/tools/elevated", "ko/tools/exec", "ko/tools/exec-approvals", @@ -5702,6 +5707,7 @@ "de/tools/btw", "de/tools/code-execution", "de/tools/diffs", + "de/tools/trajectory", "de/tools/elevated", "de/tools/exec", "de/tools/exec-approvals", @@ -6474,6 +6480,7 @@ "fr/tools/btw", "fr/tools/code-execution", "fr/tools/diffs", + "fr/tools/trajectory", "fr/tools/elevated", "fr/tools/exec", "fr/tools/exec-approvals", @@ -7246,6 +7253,7 @@ "ar/tools/btw", "ar/tools/code-execution", "ar/tools/diffs", + "ar/tools/trajectory", "ar/tools/elevated", "ar/tools/exec", "ar/tools/exec-approvals", @@ -8018,6 +8026,7 @@ "it/tools/btw", "it/tools/code-execution", "it/tools/diffs", + "it/tools/trajectory", "it/tools/elevated", "it/tools/exec", "it/tools/exec-approvals", @@ -8790,6 +8799,7 @@ "tr/tools/btw", "tr/tools/code-execution", "tr/tools/diffs", + "tr/tools/trajectory", "tr/tools/elevated", "tr/tools/exec", "tr/tools/exec-approvals", @@ -9562,6 +9572,7 @@ "uk/tools/btw", "uk/tools/code-execution", "uk/tools/diffs", + "uk/tools/trajectory", "uk/tools/elevated", "uk/tools/exec", "uk/tools/exec-approvals", @@ -10334,6 +10345,7 @@ "id/tools/btw", "id/tools/code-execution", "id/tools/diffs", + "id/tools/trajectory", "id/tools/elevated", "id/tools/exec", "id/tools/exec-approvals", @@ -11106,6 +11118,7 @@ "pl/tools/btw", "pl/tools/code-execution", "pl/tools/diffs", + "pl/tools/trajectory", "pl/tools/elevated", "pl/tools/exec", "pl/tools/exec-approvals", @@ -11878,6 +11891,7 @@ "th/tools/btw", "th/tools/code-execution", "th/tools/diffs", + "th/tools/trajectory", "th/tools/elevated", "th/tools/exec", "th/tools/exec-approvals", diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md index 8a6ed6aff..0b9bd0e92 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 000000000..4870cce96 --- /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.