트랜스크립트 위생(제공자 수정)

이 문서는 실행 전(모델 컨텍스트 구축 시) 트랜스크립트에 적용되는 제공자별 수정을 설명합니다. 이는 엄격한 제공자 요구 사항을 충족하는 데 사용되는 메모리 내 조정입니다. 이러한 위생 단계는 디스크에 저장된 JSONL 트랜스크립트를 다시 작성하지 않습니다. 그러나 별도의 세션 파일 수리 패스는 세션이 로드되기 전에 잘못된 행을 삭제하여 형식이 잘못된 JSONL 파일을 다시 작성할 수 있습니다. 수리가 발생하면 원본 파일은 세션 파일 옆에 백업됩니다.

범위는 다음을 포함합니다:

  • Tool call id 정제
  • Tool call 입력 검증
  • Tool 결과 페어링 수리
  • 턴 검증/순서 지정
  • 사고 서명 정리
  • 이미지 payload 정제

트랜스크립트 저장소 세부 정보가 필요한 경우 다음을 참조하세요:

실행 위치

모든 트랜스크립트 위생은 임베디드 러너에 집중되어 있습니다:

  • 정책 선택: src/agents/transcript-policy.ts
  • 정제/수리 적용: src/agents/pi-embedded-runner/google.ts의 sanitizeSessionHistory

정책은 provider, modelApi, modelId를 사용하여 무엇을 적용할지 결정합니다.

트랜스크립트 위생과는 별도로 세션 파일은 로드 전에 수리됩니다(필요한 경우):

  • src/agents/session-file-repair.ts의 repairSessionFileIfNeeded
  • run/attempt.ts 및 compact.ts(임베디드 러너)에서 호출됨

전역 규칙: 이미지 정제

이미지 payload는 항상 정제되어 크기 제한으로 인한 제공자 측 거부를 방지합니다(너무 큰 base64 이미지 다운스케일/재압축).

구현:

  • src/agents/pi-embedded-helpers/images.ts의 sanitizeSessionMessagesImages
  • src/agents/tool-images.ts의 sanitizeContentBlocksImages

전역 규칙: 잘못된 형식의 tool call

input과 arguments가 모두 누락된 Assistant tool-call 블록은 모델 컨텍스트가 구축되기 전에 삭제됩니다. 이는 부분적으로 지속된 tool call로부터의 제공자 거부를 방지합니다(예: 속도 제한 실패 후).

구현:

  • src/agents/session-transcript-repair.ts의 sanitizeToolCallInputs
  • src/agents/pi-embedded-runner/google.ts의 sanitizeSessionHistory에서 적용

제공자 매트릭스(현재 동작)

OpenAI / OpenAI Codex

  • 이미지 정제만
  • OpenAI Responses/Codex 모델로 전환 시 고립된 추론 서명(후속 콘텐츠 블록이 없는 독립 추론 항목) 삭제
  • tool call id 정제 없음
  • tool 결과 페어링 수리 없음
  • 턴 검증 또는 재정렬 없음
  • 합성 tool 결과 없음
  • 사고 서명 제거 없음

Google(Generative AI / Gemini CLI / Antigravity)

  • Tool call id 정제: 엄격한 영숫자
  • Tool 결과 페어링 수리 및 합성 tool 결과
  • 턴 검증(Gemini 스타일 턴 교대)
  • Google 턴 순서 수정(히스토리가 assistant로 시작하는 경우 작은 사용자 부트스트랩을 앞에 추가)
  • Antigravity Claude: 사고 서명 정규화; 서명되지 않은 사고 블록 삭제

Anthropic / Minimax(Anthropic 호환)

  • Tool 결과 페어링 수리 및 합성 tool 결과
  • 턴 검증(엄격한 교대를 충족하기 위해 연속된 사용자 턴 병합)

Mistral(model-id 기반 감지 포함)

  • Tool call id 정제: strict9(영숫자 길이 9)

OpenRouter Gemini

  • 사고 서명 정리: 비 base64 thought_signature 값 제거(base64 유지)

기타 모든 것

  • 이미지 정제만

과거 동작(2026.1.22 이전)

2026.1.22 릴리스 이전에 OpenClaw는 여러 계층의 트랜스크립트 위생을 적용했습니다:

  • transcript-sanitize 확장이 모든 컨텍스트 구축 시 실행되어 다음을 수행할 수 있었습니다:

    • tool use/result 페어링 수리
    • tool call id 정제(_/-를 보존하는 비엄격 모드 포함)

  • 러너도 제공자별 정제를 수행하여 작업이 중복되었습니다

  • 제공자 정책 외부에서 추가 변경이 발생했습니다:

    • 지속 전 assistant 텍스트에서 태그 제거
    • 빈 assistant 오류 턴 삭제
    • tool call 후 assistant 콘텐츠 트리밍

이러한 복잡성은 교차 제공자 회귀를 일으켰습니다(특히 openai-responses의 call_id|fc_id 페어링). 2026.1.22 정리는 확장을 제거하고 로직을 러너에 집중시켰으며 OpenAI는 이미지 정제 외에는 아무것도 건드리지 않도록 했습니다.

← 문서로 돌아가기