메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw는 실행 전(모델 컨텍스트를 빌드할 때) 트랜스크립트에 프로바이더별 수정을 적용합니다. 이들 대부분은 엄격한 프로바이더 요구사항을 충족하기 위해 사용하는 인메모리 조정입니다. 별도의 세션 파일 복구 패스가 세션이 로드되기 전에 저장된 JSONL을 다시 쓸 수도 있지만, 형식이 잘못된 줄이나 유효한 지속 레코드가 아닌 저장된 턴에만 적용됩니다. 전달된 어시스턴트 응답은 디스크에 보존되며, 프로바이더별 어시스턴트 프리필 제거는 아웃바운드 페이로드를 구성하는 동안에만 발생합니다. 복구가 발생하면 원본 파일은 세션 파일 옆에 백업됩니다. 범위에는 다음이 포함됩니다.
  • 사용자에게 보이는 트랜스크립트 턴에 런타임 전용 프롬프트 컨텍스트가 들어가지 않도록 유지
  • 도구 호출 id 정리
  • 도구 호출 입력 검증
  • 도구 결과 페어링 복구
  • 턴 검증 / 순서 지정
  • 사고 서명 정리
  • Thinking 서명 정리
  • 이미지 페이로드 정리
  • 프로바이더 리플레이 전 빈 텍스트 블록 정리
  • 사용자 입력 출처 태깅(세션 간 라우팅된 프롬프트용)
  • Bedrock Converse 리플레이용 빈 어시스턴트 오류 턴 복구
트랜스크립트 저장소 세부 정보가 필요하면 다음을 참조하세요.

​
전역 규칙: 런타임 컨텍스트는 사용자 트랜스크립트가 아닙니다

런타임/시스템 컨텍스트는 한 턴의 모델 프롬프트에 추가될 수 있지만, 최종 사용자가 작성한 콘텐츠는 아닙니다. OpenClaw는 Gateway 응답, 대기 중인 후속 작업, ACP, CLI, 임베디드 Pi 실행을 위해 트랜스크립트에 표시되는 별도의 프롬프트 본문을 유지합니다. 저장된 가시적 사용자 턴은 런타임이 보강된 프롬프트 대신 해당 트랜스크립트 본문을 사용합니다. 런타임 래퍼가 이미 저장된 레거시 세션의 경우, Gateway 기록 표면은 WebChat, TUI, REST 또는 SSE 클라이언트에 메시지를 반환하기 전에 표시 투영을 적용합니다.

​
실행 위치

모든 트랜스크립트 위생 처리는 임베디드 러너에 중앙화되어 있습니다.
  • 정책 선택: src/agents/transcript-policy.ts
  • 정리/복구 적용: src/agents/pi-embedded-runner/replay-history.ts의 sanitizeSessionHistory
정책은 provider, modelApi, modelId를 사용해 적용할 항목을 결정합니다. 트랜스크립트 위생 처리와 별도로, 세션 파일은 로드 전에 필요하면 복구됩니다.
  • src/agents/session-file-repair.ts의 repairSessionFileIfNeeded
  • run/attempt.ts 및 compact.ts(임베디드 러너)에서 호출됨

​
전역 규칙: 이미지 정리

크기 제한 때문에 프로바이더 측 거부가 발생하지 않도록 이미지 페이로드는 항상 정리됩니다 (너무 큰 base64 이미지는 다운스케일/재압축). 이는 비전 지원 모델의 이미지 기반 토큰 압력 제어에도 도움이 됩니다. 최대 치수가 낮을수록 일반적으로 토큰 사용량이 줄어들고, 치수가 높을수록 디테일이 보존됩니다. 구현:
  • src/agents/pi-embedded-helpers/images.ts의 sanitizeSessionMessagesImages
  • src/agents/tool-images.ts의 sanitizeContentBlocksImages
  • 최대 이미지 한 변은 agents.defaults.imageMaxDimensionPx로 구성할 수 있습니다(기본값: 1200).
  • 이 패스가 리플레이 콘텐츠를 순회하는 동안 빈 텍스트 블록은 제거됩니다. 비워지는 어시스턴트 턴은 리플레이 복사본에서 삭제되며, 비워지는 사용자 및 도구 결과 턴에는 비어 있지 않은 생략 콘텐츠 플레이스홀더가 들어갑니다.

​
전역 규칙: 형식이 잘못된 도구 호출

input과 arguments가 모두 없는 어시스턴트 도구 호출 블록은 모델 컨텍스트가 빌드되기 전에 삭제됩니다. 이는 부분적으로 저장된 도구 호출로 인한 프로바이더 거부를 방지합니다(예: rate limit 실패 후). 구현:
  • src/agents/session-transcript-repair.ts의 sanitizeToolCallInputs
  • src/agents/pi-embedded-runner/replay-history.ts의 sanitizeSessionHistory에 적용됨

​
전역 규칙: 세션 간 입력 출처

에이전트가 sessions_send를 통해 다른 세션으로 프롬프트를 보낼 때(에이전트 간 reply/announce 단계 포함), OpenClaw는 생성된 사용자 턴을 다음과 함께 저장합니다.
  • message.provenance.kind = "inter_session"
OpenClaw는 또한 라우팅된 프롬프트 텍스트 앞의 같은 턴에 [Inter-session message ... isUser=false] 마커를 붙여 활성 모델 호출이 외부 세션 출력과 외부 최종 사용자 지침을 구분할 수 있게 합니다. 이 마커에는 사용 가능한 경우 원본 세션, 채널, 도구가 포함됩니다. 트랜스크립트는 프로바이더 호환성을 위해 여전히 role: "user"를 사용하지만, 표시 텍스트와 출처 메타데이터가 모두 해당 턴을 세션 간 데이터로 표시합니다. 컨텍스트 재빌드 중 OpenClaw는 출처 메타데이터만 있는 오래된 저장 세션 간 사용자 턴에도 동일한 마커를 적용합니다.

​
프로바이더 매트릭스(현재 동작)

OpenAI / OpenAI Codex
  • 이미지 정리만 적용.
  • OpenAI Responses/Codex 트랜스크립트에서 고아 reasoning 서명(뒤따르는 콘텐츠 블록이 없는 독립 reasoning 항목)을 삭제하고, 모델 라우트 전환 후 리플레이 가능한 OpenAI reasoning을 삭제합니다.
  • 암호화된 빈 요약 항목을 포함해 리플레이 가능한 OpenAI Responses reasoning 항목 페이로드를 보존하여, 수동/WebSocket 리플레이가 필요한 rs_* 상태를 어시스턴트 출력 항목과 페어링된 상태로 유지합니다.
  • 네이티브 ChatGPT Codex Responses는 세션 prompt_cache_key를 보존하면서 이전 항목 ID 없이 이전 Responses reasoning/message/function 페이로드를 리플레이하여 Codex 와이어 패리티를 따릅니다.
  • 도구 호출 id 정리 없음.
  • 도구 결과 페어링 복구는 실제로 매칭된 출력을 이동하고 누락된 도구 호출에 대해 Codex 스타일의 aborted 출력을 합성할 수 있습니다.
  • 턴 검증 또는 재정렬 없음.
  • 누락된 OpenAI Responses 계열 도구 출력은 Codex 리플레이 정규화와 맞추기 위해 aborted로 합성됩니다.
  • 사고 서명 제거 없음.
OpenAI 호환 Chat Completions
  • 과거 어시스턴트 thinking/reasoning 블록은 리플레이 전에 제거되어 로컬 및 프록시 스타일 OpenAI 호환 서버가 reasoning 또는 reasoning_content 같은 이전 턴 reasoning 필드를 받지 않도록 합니다.
  • 현재 같은 턴의 도구 호출 연속은 도구 결과가 리플레이될 때까지 어시스턴트 reasoning 블록을 도구 호출에 붙여 둡니다.
  • 프로바이더가 소유한 예외는 와이어 프로토콜에서 리플레이된 reasoning 메타데이터가 필요할 때 이를 적용하지 않도록 선택할 수 있습니다.
Google(Generative AI / Gemini CLI / Antigravity)
  • 도구 호출 id 정리: 엄격한 영숫자.
  • 도구 결과 페어링 복구 및 합성 도구 결과.
  • 턴 검증(Gemini 스타일 턴 교대).
  • Google 턴 순서 수정(기록이 어시스턴트로 시작하면 작은 사용자 부트스트랩을 앞에 붙임).
  • Antigravity Claude: thinking 서명 정규화, 서명 없는 thinking 블록 삭제.
Anthropic / Minimax(Anthropic 호환)
  • 도구 결과 페어링 복구 및 합성 도구 결과.
  • 턴 검증(엄격한 교대를 충족하도록 연속 사용자 턴 병합).
  • thinking이 활성화되면 Cloudflare AI Gateway 라우트를 포함해 아웃바운드 Anthropic Messages 페이로드에서 뒤따르는 어시스턴트 프리필 턴이 제거됩니다.
  • 누락되었거나 비어 있거나 공백인 리플레이 서명이 있는 Thinking 블록은 프로바이더 변환 전에 제거됩니다. 이로 인해 어시스턴트 턴이 비워지면 OpenClaw는 비어 있지 않은 생략 reasoning 텍스트로 턴 형태를 유지합니다.
  • 제거해야 하는 오래된 thinking 전용 어시스턴트 턴은 비어 있지 않은 생략 reasoning 텍스트로 대체되어 프로바이더 어댑터가 리플레이 턴을 삭제하지 않도록 합니다.
Amazon Bedrock(Converse API)
  • 빈 어시스턴트 스트림 오류 턴은 리플레이 전에 비어 있지 않은 대체 텍스트 블록으로 복구됩니다. Bedrock Converse는 content: []인 어시스턴트 메시지를 거부하므로, stopReason: "error"와 빈 콘텐츠가 있는 저장된 어시스턴트 턴도 로드 전에 디스크에서 복구됩니다.
  • 공백 텍스트 블록만 포함하는 어시스턴트 스트림 오류 턴은 유효하지 않은 공백 블록을 리플레이하는 대신 인메모리 리플레이 복사본에서 삭제됩니다.
  • 누락되었거나 비어 있거나 공백인 리플레이 서명이 있는 Claude thinking 블록은 Converse 리플레이 전에 제거됩니다. 이로 인해 어시스턴트 턴이 비워지면 OpenClaw는 비어 있지 않은 생략 reasoning 텍스트로 턴 형태를 유지합니다.
  • 제거해야 하는 오래된 thinking 전용 어시스턴트 턴은 비어 있지 않은 생략 reasoning 텍스트로 대체되어 Converse 리플레이가 엄격한 턴 형태를 유지하도록 합니다.
  • 리플레이는 OpenClaw 전달 미러 및 Gateway 주입 어시스턴트 턴을 필터링합니다.
  • 이미지 정리는 전역 규칙을 통해 적용됩니다.
Mistral(모델 id 기반 감지 포함)
  • 도구 호출 id 정리: strict9(영숫자 길이 9).
OpenRouter Gemini
  • 사고 서명 정리: base64가 아닌 thought_signature 값 제거(base64는 유지).
OpenRouter Anthropic
  • reasoning이 활성화되면 검증된 OpenRouter OpenAI 호환 Anthropic 모델 페이로드에서 뒤따르는 어시스턴트 프리필 턴이 제거되며, 이는 직접 Anthropic 및 Cloudflare Anthropic 리플레이 동작과 일치합니다.
그 외 모든 항목
  • 이미지 정리만 적용.

​
과거 동작(2026.1.22 이전)

2026.1.22 릴리스 전에는 OpenClaw가 여러 계층의 트랜스크립트 위생 처리를 적용했습니다.
  • 트랜스크립트 정리 확장이 모든 컨텍스트 빌드에서 실행되었으며 다음을 수행할 수 있었습니다.
    • 도구 사용/결과 페어링 복구.
    • 도구 호출 id 정리(_/-를 보존하는 비엄격 모드 포함).
  • 러너도 프로바이더별 정리를 수행해 작업이 중복되었습니다.
  • 프로바이더 정책 외부에서도 다음을 포함한 추가 변이가 발생했습니다.
    • 저장 전에 어시스턴트 텍스트에서 <final> 태그 제거.
    • 빈 어시스턴트 오류 턴 삭제.
    • 도구 호출 뒤의 어시스턴트 콘텐츠 잘라내기.
이 복잡성은 교차 프로바이더 회귀(특히 openai-responses call_id|fc_id 페어링)를 일으켰습니다. 2026.1.22 정리는 확장을 제거하고, 러너에 로직을 중앙화했으며, OpenAI는 이미지 정리를 제외하고 건드리지 않음으로 만들었습니다.

​
관련 항목