Пакеты траекторий

Захват траектории — это посеансовый бортовой самописец OpenClaw. Он записывает структурированную временную шкалу для каждого запуска агента, затем /export-trajectory упаковывает текущий сеанс в отредактированный пакет для поддержки.

Используйте его, когда нужно ответить на такие вопросы:

• Какой промпт, системный промпт и инструменты были отправлены модели?
• Какие сообщения транскрипта и вызовы инструментов привели к этому ответу?
• Завершился ли запуск по тайм-ауту, был ли прерван, прошел ли Compaction или столкнулся с ошибкой провайдера?
• Какая модель, Plugin, Skills и настройки среды выполнения были активны?
• Какие метаданные использования и кэша промптов вернул провайдер?

Если вы отправляете широкий отчет в поддержку о проблеме живого Gateway, начните с /diagnostics. Диагностика собирает санитизированный пакет Gateway и для сеансов harness OpenAI Codex также может отправлять отзыв Codex на серверы OpenAI после подтверждения. Используйте /export-trajectory, когда вам нужна именно подробная посеансовая временная шкала промптов, инструментов и транскрипта.

Быстрый старт

Отправьте это в активном сеансе:

/export-trajectory

Псевдоним:

/trajectory

OpenClaw записывает пакет в рабочей области:

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

Можно выбрать имя относительного выходного каталога:

/export-trajectory bug-1234

Пользовательский путь разрешается внутри .openclaw/trajectory-exports/. Абсолютные пути и пути с ~ отклоняются.

Пакеты траектории могут содержать промпты, сообщения модели, схемы инструментов, результаты инструментов, события среды выполнения и локальные пути. Поэтому slash-команда в чате каждый раз проходит через подтверждение exec. Подтвердите экспорт один раз, когда намерены создать пакет; не используйте allow-all. В групповых чатах OpenClaw отправляет запрос подтверждения и результат экспорта владельцу приватно, а не публикует детали траектории обратно в общую комнату.

Для локальной проверки или рабочих процессов поддержки также можно напрямую выполнить подтвержденный путь команды:

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

Доступ

Экспорт траектории — команда владельца. Отправитель должен пройти обычные проверки авторизации команд и проверки владельца для канала.

Что записывается

Захват траектории по умолчанию включен для запусков агентов OpenClaw.

События среды выполнения включают:

• session.started
• trace.metadata
• context.compiled
• prompt.submitted
• model.fallback_step, включая исходную модель, следующую модель, причину/подробности сбоя, позицию в цепочке и то, продвинулся ли fallback, завершился ли успешно или исчерпал цепочку
• model.completed
• trace.artifacts
• session.ended

События транскрипта также реконструируются из активной ветки сеанса:

• сообщения пользователя
• сообщения ассистента
• вызовы инструментов
• результаты инструментов
• Compaction
• изменения модели
• метки и пользовательские записи сеанса

События записываются как JSON Lines с этим маркером схемы:

{  "traceSchema": "openclaw-trajectory",  "schemaVersion": 1}

Файлы пакета

Экспортированный пакет может содержать:

manifest.json перечисляет файлы, присутствующие в этом пакете. Некоторые файлы опускаются, когда в сеансе не были захвачены соответствующие данные среды выполнения.

Место захвата

По умолчанию события траектории среды выполнения записываются рядом с файлом сеанса:

<session>.trajectory.jsonl

OpenClaw также записывает best-effort файл-указатель рядом с сеансом:

<session>.trajectory-path.json

Задайте OPENCLAW_TRAJECTORY_DIR, чтобы хранить sidecar-файлы траектории среды выполнения в выделенном каталоге:

export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories

Когда эта переменная задана, OpenClaw записывает один файл JSONL на каждый идентификатор сеанса в этом каталоге.

Обслуживание сеансов удаляет sidecar-файлы траектории, когда принадлежащая им запись сеанса обрезается, ограничивается лимитом или вытесняется из-за дискового бюджета сеансов. Файлы среды выполнения вне каталога сеансов удаляются только тогда, когда целевой указатель все еще доказывает, что принадлежит этому сеансу.

Отключение захвата

Задайте OPENCLAW_TRAJECTORY=0 перед запуском OpenClaw:

export OPENCLAW_TRAJECTORY=0

Это отключает захват траектории среды выполнения. /export-trajectory все еще может экспортировать ветку транскрипта, но файлы, существующие только в среде выполнения, такие как скомпилированный контекст, артефакты провайдера и метаданные промптов, могут отсутствовать.

Настройка тайм-аута сброса

OpenClaw сбрасывает sidecar-файлы траектории среды выполнения во время очистки агента. Тайм-аут очистки по умолчанию составляет 10 000 мс. На медленных дисках или больших хранилищах задайте OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS перед запуском OpenClaw:

export OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=30000

Это управляет тем, когда OpenClaw логирует тайм-аут openclaw-trajectory-flush и продолжает работу. Это не меняет ограничения размера траектории. Чтобы настроить все шаги очистки агента, которые не передают явный тайм-аут, задайте OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS.

Конфиденциальность и ограничения

Пакеты траектории предназначены для поддержки и отладки, а не для публичной публикации. OpenClaw редактирует чувствительные значения перед записью файлов экспорта:

• учетные данные и известные поля полезной нагрузки, похожие на секреты
• данные изображений
• локальные пути состояния
• пути рабочей области, заменяемые на $WORKSPACE_DIR
• пути домашнего каталога, где они обнаружены

Экспортер также ограничивает размер входных данных:

• sidecar-файлы среды выполнения: живой захват останавливается на 10 MiB и записывает событие усечения, когда остается место; экспорт принимает существующие sidecar-файлы среды выполнения размером до 50 MiB
• файлы сеансов: 50 MiB
• события среды выполнения: 200 000
• всего экспортированных событий: 250 000
• отдельные строки событий среды выполнения усекаются выше 256 KiB

Проверяйте пакеты перед тем, как делиться ими за пределами вашей команды. Редактирование выполняется best-effort и не может знать каждый секрет, специфичный для приложения.

Устранение неполадок

Если в экспорте нет событий среды выполнения:

• убедитесь, что OpenClaw был запущен без OPENCLAW_TRAJECTORY=0
• проверьте, указывает ли OPENCLAW_TRAJECTORY_DIR на доступный для записи каталог
• отправьте еще одно сообщение в сеансе, затем экспортируйте снова
• проверьте manifest.json на наличие runtimeEventCount

Если команда отклоняет выходной путь:

• используйте относительное имя, например bug-1234
• не передавайте /tmp/... или ~/...
• держите экспорт внутри .openclaw/trajectory-exports/

Если экспорт завершается ошибкой размера, сеанс или sidecar-файл превысил ограничения безопасности экспорта. Начните новый сеанс или экспортируйте меньшую репродукцию.

Связанные материалы

• Diffs
• Управление сеансами
• Инструмент Exec