OpenClaw trajectory bundles

When an agent answered strangely, failed, or called a tool you did not expect, the question is always the same: what did the model actually see? OpenClaw’s trajectory capture is the per-session flight recorder that answers it. It records a structured timeline for each run, and one command 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, and the usage and prompt-cache metadata the provider returned. Here is how to export one, what it records, what is in the bundle, how it is stored, and the limits.

Exporting

• Send the export-trajectory command, alias trajectory, in the active session; the bundle lands under the workspace in a trajectory-exports directory named by session and timestamp, and a relative name argument overrides the directory, while absolute and home-relative paths are rejected.
• Because a bundle can contain prompts, model messages, tool schemas, tool results, runtime events and local paths, the chat command always runs through exec approval: approve the export once when you mean to create it, and never with allow-all. In group chats the approval prompt and the result go to the owner privately, and the room sees only a status notice that distinguishes confirmed, pending and suppressed delivery.
• It is an owner command: the sender must pass the normal command authorisation plus the channel’s owner check.
• For local inspection or support workflows the underlying sessions export-trajectory CLI takes a session key and workspace, plus flags for the output name, a store override, an agent id and JSON output. For a broad Gateway support report the docs point to the diagnostics command instead; the trajectory export is for the detailed per-session timeline.

Trajectory capture is OpenClaw’s per-session flight recorder.

What is recorded

Capture is on by default for agent runs. Runtime events include session started, trace metadata, context compiled, prompt submitted, tool call with the tool identity and sanitised arguments, tool result with the sanitised result and execution outcome, model fallback step with the source and next model, the failure reason, the chain position and whether the chain advanced, succeeded or was exhausted, model completed, trace artifacts and session ended. Transcript events are reconstructed from the active session branch: user and assistant messages, tool calls and results, compactions, model changes, labels and custom entries. Events are written as JSON Lines with a schema marker naming the trajectory schema and version. The bundle holds eight files: a manifest with the schema, source files, event counts and generated file list; the ordered events; the redacted active transcript branch and session header; metadata with the OpenClaw version, OS and runtime, model, config snapshot, plugins, skills and prompt metadata; artifacts with the final status, errors, usage, prompt cache, compaction count, assistant text and tool metadata; the submitted prompts; the latest compiled system prompt when captured; and the tool definitions sent to the model when captured. The manifest lists which files a given bundle actually contains, since some are omitted when the session did not capture that data.

Storage, disabling, limits

• Runtime events are stored with the session in the per-agent SQLite database; exporting materialises the redacted JSONL bundle, and the live capture is not a session-adjacent sidecar file. Legacy sidecar files from older releases are treated as cleanup targets by session maintenance.
• An environment variable set to zero before start disables runtime capture; the export command still works on the transcript branch, but runtime-only data such as compiled context, provider artifacts and prompt metadata may be missing. Rows are flushed during agent cleanup with a ten-second default timeout that another variable raises on slow disks, without changing the size caps.
• Redaction covers credentials and known secret-like fields, image data, local state paths, workspace paths replaced by a placeholder, and detected home directory paths; the live capture is a rolling window capped at ten mebibytes, legacy sidecars are accepted up to fifty, session files up to fifty, runtime events per export at two hundred thousand, total exported events at two hundred and fifty thousand, and individual event lines are truncated above 256 kibibytes. Redaction is best-effort, so review bundles before sharing them outside your team.

OpenClaw exec approvals is the gate the chat command passes through, and OpenClaw model failover the mechanism behind the fallback-step events the timeline records.

Troubleshooting

An export with no runtime events usually means OpenClaw was started with capture disabled, or nothing ran since; send another message and export again, and check the manifest’s runtime event count. A rejected output path is an absolute or home-relative one; use a relative name that stays inside the exports directory. A size error means the session or sidecar exceeded the bounds above, so start a new session or export a smaller reproduction. OpenClaw sessions explains the branch the transcript events come from, and OpenClaw context window and compaction the compaction events you will see in a long one.

On Diali

On Diali capture runs at the upstream default, on, and an export lands under the assistant’s workspace on its volume; the exec approval it asks for is the same approval you see for any command. Hosted OpenClaw on Diali is the assistant and Diali security describes who can reach it.

• One command, one redacted bundle, eight files.
• Owner-only, exec-approved, private in groups.
• Rolling ten mebibytes; review before sharing.