궤적 번들

Trajectory 캡처는 OpenClaw의 세션별 비행 기록 장치입니다. 각 에이전트 실행의 구조화된 타임라인을 기록한 다음, /export-trajectory가 현재 세션을 수정된 지원 번들로 패키징합니다.

다음과 같은 질문에 답해야 할 때 사용하세요.

• 모델에 어떤 프롬프트, 시스템 프롬프트, 도구가 전송되었나요?
• 어떤 트랜스크립트 메시지와 도구 호출이 이 답변으로 이어졌나요?
• 실행이 시간 초과, 중단, Compaction 처리되었거나 공급자 오류가 발생했나요?
• 어떤 모델, Plugin, Skills, 런타임 설정이 활성화되어 있었나요?
• 공급자가 어떤 사용량 및 프롬프트 캐시 메타데이터를 반환했나요?

라이브 Gateway 문제에 대한 광범위한 지원 보고서를 제출하는 경우 /diagnostics로 시작하세요. 진단은 정리된 Gateway 번들을 수집하고, OpenAI Codex 하네스 세션의 경우 승인 후 Codex 피드백을 OpenAI 서버로 보낼 수도 있습니다. 세션별 프롬프트, 도구, 트랜스크립트 타임라인이 자세히 필요한 경우 /export-trajectory를 사용하세요.

# 빠른 시작

활성 세션에서 다음을 보내세요.

/export-trajectory

별칭:

/trajectory

OpenClaw는 작업 영역 아래에 번들을 작성합니다.

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

상대 출력 디렉터리 이름을 선택할 수 있습니다.

/export-trajectory bug-1234

사용자 지정 경로는 .openclaw/trajectory-exports/ 내부에서 해석됩니다. 절대 경로와 ~ 경로는 거부됩니다.

Trajectory 번들에는 프롬프트, 모델 메시지, 도구 스키마, 도구 결과, 런타임 이벤트, 로컬 경로가 포함될 수 있습니다. 따라서 채팅 슬래시 명령은 매번 exec 승인을 거쳐 실행됩니다. 번들을 만들 의도가 있을 때 내보내기를 한 번 승인하세요. allow-all은 사용하지 마세요. 그룹 채팅에서는 OpenClaw가 공유 방에 trajectory 세부 정보를 다시 게시하는 대신 승인 프롬프트와 내보내기 결과를 소유자에게 비공개로 보냅니다.

로컬 검사 또는 지원 워크플로의 경우 승인된 명령 경로를 직접 실행할 수도 있습니다.

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

# 액세스

Trajectory 내보내기는 소유자 명령입니다. 발신자는 채널의 일반 명령 권한 검사와 소유자 검사를 통과해야 합니다.

# 기록되는 내용

Trajectory 캡처는 OpenClaw 에이전트 실행에서 기본적으로 켜져 있습니다.

런타임 이벤트에는 다음이 포함됩니다.

• session.started
• trace.metadata
• context.compiled
• prompt.submitted
• model.fallback_step: 원본 모델, 다음 모델, 실패 이유/세부 정보, 체인 위치, 폴백이 진행되었는지, 성공했는지, 또는 체인을 모두 소진했는지 포함
• model.completed
• trace.artifacts
• session.ended

트랜스크립트 이벤트도 활성 세션 브랜치에서 재구성됩니다.

• 사용자 메시지
• 어시스턴트 메시지
• 도구 호출
• 도구 결과
• Compaction
• 모델 변경
• 레이블 및 사용자 지정 세션 항목

이벤트는 이 스키마 마커가 포함된 JSON Lines로 작성됩니다.

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

# 번들 파일

내보낸 번들에는 다음이 포함될 수 있습니다.

파일	내용
manifest.json	번들 스키마, 원본 파일, 이벤트 수, 생성된 파일 목록
events.jsonl	정렬된 런타임 및 트랜스크립트 타임라인
session-branch.json	수정된 활성 트랜스크립트 브랜치와 세션 헤더
metadata.json	OpenClaw 버전, OS/런타임, 모델, 구성 스냅샷, Plugin, Skills, 프롬프트 메타데이터
artifacts.json	최종 상태, 오류, 사용량, 프롬프트 캐시, Compaction 수, 어시스턴트 텍스트, 도구 메타데이터
prompts.json	제출된 프롬프트와 선택된 프롬프트 구성 세부 정보
system-prompt.txt	캡처된 경우, 최신 컴파일된 시스템 프롬프트
tools.json	캡처된 경우, 모델에 전송된 도구 정의

manifest.json은 해당 번들에 있는 파일을 나열합니다. 세션이 해당 런타임 데이터를 캡처하지 않은 경우 일부 파일은 생략됩니다.

# 캡처 위치

기본적으로 런타임 trajectory 이벤트는 세션 파일 옆에 작성됩니다.

<session>.trajectory.jsonl

OpenClaw는 세션 옆에 최선 노력 방식의 포인터 파일도 작성합니다.

<session>.trajectory-path.json

런타임 trajectory 사이드카를 전용 디렉터리에 저장하려면 OPENCLAW_TRAJECTORY_DIR을 설정하세요.

export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories

이 변수가 설정되면 OpenClaw는 해당 디렉터리에 세션 ID별로 하나의 JSONL 파일을 작성합니다.

세션 유지 관리는 소유 세션 항목이 세션 디스크 예산에 의해 정리, 제한 또는 축출될 때 trajectory 사이드카를 제거합니다. 세션 디렉터리 외부의 런타임 파일은 포인터 대상이 여전히 해당 세션에 속한다는 것을 증명하는 경우에만 제거됩니다.

# 캡처 비활성화

OpenClaw를 시작하기 전에 OPENCLAW_TRAJECTORY=0을 설정하세요.

export OPENCLAW_TRAJECTORY=0

이렇게 하면 런타임 trajectory 캡처가 비활성화됩니다. /export-trajectory는 여전히 트랜스크립트 브랜치를 내보낼 수 있지만, 컴파일된 컨텍스트, 공급자 아티팩트, 프롬프트 메타데이터 같은 런타임 전용 파일이 누락될 수 있습니다.

# 개인정보 보호 및 제한

Trajectory 번들은 지원 및 디버깅용으로 설계되었으며, 공개 게시용이 아닙니다. OpenClaw는 내보내기 파일을 작성하기 전에 민감한 값을 수정합니다.

• 자격 증명 및 알려진 비밀과 유사한 페이로드 필드
• 이미지 데이터
• 로컬 상태 경로
• 작업 영역 경로, $WORKSPACE_DIR로 대체됨
• 감지된 경우 홈 디렉터리 경로

내보내기는 입력 크기도 제한합니다.

• 런타임 사이드카 파일: 라이브 캡처는 10 MiB에서 중지되고 공간이 남아 있으면 잘림 이벤트를 기록합니다. 내보내기는 기존 런타임 사이드카를 최대 50 MiB까지 허용합니다
• 세션 파일: 50 MiB
• 런타임 이벤트: 200,000
• 내보낸 전체 이벤트: 250,000
• 개별 런타임 이벤트 줄은 256 KiB를 초과하면 잘립니다

팀 외부에 번들을 공유하기 전에 검토하세요. 수정은 최선 노력 방식이며 모든 애플리케이션별 비밀을 알 수는 없습니다.

# 문제 해결

내보내기에 런타임 이벤트가 없는 경우:

• OpenClaw가 OPENCLAW_TRAJECTORY=0 없이 시작되었는지 확인하세요
• OPENCLAW_TRAJECTORY_DIR이 쓰기 가능한 디렉터리를 가리키는지 확인하세요
• 세션에서 다른 메시지를 실행한 다음 다시 내보내세요
• runtimeEventCount를 확인하려면 manifest.json을 검사하세요

명령이 출력 경로를 거부하는 경우:

• bug-1234 같은 상대 이름을 사용하세요
• /tmp/... 또는 ~/...를 전달하지 마세요
• 내보내기를 .openclaw/trajectory-exports/ 내부에 유지하세요

내보내기가 크기 오류로 실패하는 경우 세션 또는 사이드카가 내보내기 안전 제한을 초과한 것입니다. 새 세션을 시작하거나 더 작은 재현 사례를 내보내세요.

# 관련 항목

• Diffs
• 세션 관리
• Exec 도구