mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-28 17:39:24 +00:00
235 lines
8.2 KiB
Markdown
235 lines
8.2 KiB
Markdown
---
|
|
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` | Exported 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 structured database provenance, for
|
|
example:
|
|
|
|
```json
|
|
{
|
|
"sourceDatabases": {
|
|
"runtime": {
|
|
"role": "agent",
|
|
"agentId": "<agentId>",
|
|
"table": "trajectory_runtime_events",
|
|
"sessionId": "<sessionId>"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
`/export-trajectory` reads runtime events from SQLite and materializes
|
|
`events.jsonl` only inside the explicit support bundle. New runtime captures do
|
|
not create legacy `<session>.trajectory.jsonl` sidecars or pointer files.
|
|
|
|
## 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.
|
|
|
|
## 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
|
|
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 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 capture: live capture stops at 10 MiB and records a truncation event when space remains
|
|
- transcript branch export: 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`
|
|
- 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 transcript branch or runtime capture
|
|
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)
|