Transcript hygiene

기준일: 2026-07-26
공식 기준: Transcript hygiene

Transcript hygiene 문서는 OpenClaw 공식 문서(reference/transcript-hygiene)를 한국어로 정리한 가이드입니다. Reference: provider-specific transcript sanitization and repair rules 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Reference: provider-specific transcript sanitization and repair rules

한국어 가이드 범위: reference/transcript-hygiene 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Global rule: runtime context is not user transcript
• Where this runs
• Global rule: image sanitization
• Global rule: malformed tool calls
• Global rule: tool result pairing
• Global rule: incomplete or silent reasoning-only turns
• Global rule: inter-session input provenance
• Provider matrix (current behavior)
• Historical behavior (pre-2026.1.22)
• 관련 문서

상세 내용

본문

OpenClaw applies provider-specific fixes to transcripts before a run (building model context). Most of these are in-memory adjustments used to satisfy strict provider requirements. A separate session-file repair pass may also rewrite stored JSONL before the session is loaded, but only for malformed lines or persisted turns that are invalid durable records. Delivered assistant replies are preserved on disk; provider-specific assistant-prefill stripping happens only while constructing outbound payloads.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Runtime-only prompt context staying out of user-visible transcript turns
• Tool call id sanitization
• Tool call input validation
• Tool result pairing repair
• Turn validation / ordering
• Thought signature cleanup
• Thinking signature cleanup
• Image payload sanitization
• Blank text-block cleanup before provider replay
• Incomplete reasoning-only length-turn cleanup before provider replay
• User-input provenance tagging (for inter-session routed prompts)
• Empty assistant error-turn repair for Bedrock Converse replay

Global rule: runtime context is not user transcript

Runtime/system context can be added to the model prompt for a turn, but it is not end-user-authored content. OpenClaw keeps a separate transcript-facing prompt body for Gateway replies, queued followups, ACP, CLI, and embedded OpenClaw runs. Stored visible user turns use that transcript body instead of the runtime-enriched prompt.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Where this runs

All transcript hygiene is centralized in the embedded runner:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Policy selection: src/agents/transcript-policy.ts
• Sanitization/repair application: sanitizeSessionHistory in
• repairSessionFileIfNeeded in src/agents/session-file-repair.ts
• Called from src/agents/embedded-agent-runner/run/attempt.ts and

Global rule: image sanitization

Image payloads are always sanitized to prevent provider-side rejection due to size limits (downscale/recompress oversized base64 images). This also helps control image-driven token pressure for vision-capable models: lower max dimensions reduce token usage, higher dimensions preserve detail.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• sanitizeSessionMessagesImages in
• sanitizeContentBlocksImages in src/agents/tool-images.ts
• Max image side is configurable via agents.defaults.imageMaxDimensionPx
• Blank text blocks are removed while this pass walks replay content.

Global rule: malformed tool calls

Assistant tool-call blocks missing both input and arguments are dropped before model context is built. This prevents provider rejections from partially persisted tool calls (예를 들어, after a rate limit failure).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• sanitizeToolCallInputs in src/agents/session-transcript-repair.ts
• Applied in sanitizeSessionHistory

Global rule: tool result pairing

Tool results are paired to tool-call occurrences within each assistant turn before provider-specific call IDs are rewritten. Provider-generated IDs may repeat on later turns, so a result adjacent to a repeated call stays with that occurrence. A displaced result is moved only when exactly one unresolved occurrence can own it; ambiguous extras are dropped and missing occurrences receive synthetic error results.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Global rule: incomplete or silent reasoning-only turns

Assistant turns are omitted from the in-memory replay copy when they contain only thinking or redacted-thinking content after either of these events:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• The provider output limit ends the turn with incomplete reasoning state.
• Silent-reply cleanup removes the turn's only visible NO_REPLY text.

Global rule: inter-session input provenance

When an agent sends a prompt into another session via sessions_send (including agent-to-agent reply/announce steps), OpenClaw persists the created user turn with message.provenance.kind = "inter_session".

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Provider matrix (current behavior)

following content block) for OpenAI Responses/Codex transcripts, and drop replayable OpenAI reasoning after a model route switch.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Image sanitization only.
• Drop orphaned reasoning signatures (standalone reasoning items without a
• Preserve replayable OpenAI Responses reasoning item payloads, including
• Native ChatGPT Codex Responses follows Codex wire parity by replaying
• OpenAI Responses-family replay preserves canonical call_*|fc_*
• Tool result pairing repair may move real matched outputs and synthesize
• No turn validation or reordering; no thought signature stripping.
• Historical assistant thinking/reasoning blocks are stripped before replay
• Current same-turn tool-call continuations keep the assistant reasoning
• Custom/self-hosted model entries with reasoning: true preserve replayed
• Provider-owned exceptions can opt out when their wire protocol requires
• Tool call id sanitization: strict alphanumeric.
• Tool result pairing repair and synthetic tool results.
• Turn validation (Gemini-style turn alternation).
• Google turn ordering fixup (prepend a tiny user bootstrap if history
• Antigravity Claude: normalize thinking signatures; drop unsigned thinking
• Tool result pairing repair and synthetic tool results.
• Turn validation (merge consecutive user turns to satisfy strict
• Trailing assistant prefill turns are stripped from outgoing Anthropic
• Pre-compaction assistant thinking signatures are stripped before provider
• Thinking blocks with missing, empty, or blank replay signatures are
• Older thinking-only assistant turns that must be stripped are replaced
• Empty assistant stream-error turns are repaired to a non-empty fallback
• Assistant stream-error turns with only blank text blocks are dropped from
• Pre-compaction assistant thinking signatures are stripped before Converse

Historical behavior (pre-2026.1.22)

Before the 2026.1.22 release, OpenClaw applied multiple layers of transcript hygiene:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• A transcript-sanitize extension ran on every context build and could:
• Repair tool use/result pairing.
• Sanitize tool call ids (including a non-strict mode that preserved
• The runner also performed provider-specific sanitization, which
• Additional mutations occurred outside the provider policy, including

관련 문서

주요 항목:

• Session management
• Session pruning

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/transcript-hygiene
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

관련 링크

• 공식 원문: reference/transcript-hygiene
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.