---
read_when:
    - Estás depurando rechazos de solicitudes del proveedor relacionados con la estructura de la transcripción
    - Estás cambiando la lógica de saneamiento de transcripciones o de reparación de llamadas a herramientas
    - Estás investigando discrepancias de ID de llamadas a herramientas entre proveedores
summary: 'Referencia: reglas de saneamiento y reparación de transcripciones específicas del proveedor'
title: Higiene de transcripciones
x-i18n:
    generated_at: "2026-04-26T11:38:01Z"
    model: gpt-5.4
    provider: openai
    source_hash: e380be2b011afca5fedf89579e702c6d221d42e777c23bd766c8df07ff05ed18
    source_path: reference/transcript-hygiene.md
    workflow: 15
---

Este documento describe las **correcciones específicas del proveedor** aplicadas a las transcripciones antes de una ejecución
(construcción del contexto del modelo). La mayoría de estos son ajustes **en memoria** usados para satisfacer
requisitos estrictos del proveedor. Una pasada separada de reparación de archivos de sesión también puede reescribir
el JSONL almacenado antes de que se cargue la sesión, ya sea eliminando líneas JSONL malformadas o
reparando turnos persistidos que son sintácticamente válidos pero se sabe que un
proveedor rechaza durante la reproducción. Cuando ocurre una reparación, se crea una copia de seguridad del archivo original junto al
archivo de sesión.

El alcance incluye:

- Contexto del prompt solo en tiempo de ejecución que permanece fuera de los turnos visibles de la transcripción para el usuario
- Saneamiento de ID de llamadas a herramientas
- Validación de entradas de llamadas a herramientas
- Reparación de emparejamiento de resultados de herramientas
- Validación / ordenación de turnos
- Limpieza de firmas de pensamiento
- Limpieza de firmas de thinking
- Saneamiento de cargas útiles de imágenes
- Etiquetado de procedencia de entrada del usuario (para prompts enrutados entre sesiones)
- Reparación de turnos de error de assistant vacíos para la reproducción de Bedrock Converse

Si necesitas detalles sobre el almacenamiento de transcripciones, consulta:

- [Análisis detallado de la gestión de sesiones y Compaction](/es/reference/session-management-compaction)

---

## Regla global: el contexto de tiempo de ejecución no es la transcripción del usuario

El contexto de tiempo de ejecución/sistema puede añadirse al prompt del modelo para un turno, pero
no es contenido creado por el usuario final. OpenClaw mantiene un cuerpo del
prompt independiente orientado a la transcripción para respuestas de Gateway, seguimientos en cola, ACP, CLI y ejecuciones
integradas de Pi. Los turnos visibles de usuario almacenados usan ese cuerpo de transcripción en lugar del
prompt enriquecido en tiempo de ejecución.

Para sesiones heredadas que ya persistieron envoltorios de tiempo de ejecución, las
superficies del historial de Gateway aplican una proyección de visualización antes de devolver mensajes a WebChat,
TUI, clientes REST o SSE.

---

## Dónde se ejecuta esto

Toda la higiene de transcripciones está centralizada en el ejecutor integrado:

- Selección de políticas: `src/agents/transcript-policy.ts`
- Aplicación de saneamiento/reparación: `sanitizeSessionHistory` en `src/agents/pi-embedded-runner/replay-history.ts`

La política usa `provider`, `modelApi` y `modelId` para decidir qué aplicar.

Por separado de la higiene de transcripciones, los archivos de sesión se reparan (si es necesario) antes de cargarse:

- `repairSessionFileIfNeeded` en `src/agents/session-file-repair.ts`
- Llamado desde `run/attempt.ts` y `compact.ts` (ejecutor integrado)

---

## Regla global: saneamiento de imágenes

Las cargas útiles de imágenes siempre se sanean para evitar rechazos del lado del proveedor debido a límites de tamaño
(reducir escala/recomprimir imágenes base64 sobredimensionadas).

Esto también ayuda a controlar la presión de tokens impulsada por imágenes para modelos con capacidad de visión.
Dimensiones máximas más pequeñas generalmente reducen el uso de tokens; dimensiones más grandes preservan el detalle.

Implementación:

- `sanitizeSessionMessagesImages` en `src/agents/pi-embedded-helpers/images.ts`
- `sanitizeContentBlocksImages` en `src/agents/tool-images.ts`
- El lado máximo de la imagen es configurable mediante `agents.defaults.imageMaxDimensionPx` (predeterminado: `1200`).

---

## Regla global: llamadas a herramientas malformadas

Los bloques de llamadas a herramientas de assistant a los que les faltan tanto `input` como `arguments` se eliminan
antes de que se construya el contexto del modelo. Esto evita rechazos del proveedor por llamadas a herramientas
parcialmente persistidas (por ejemplo, después de un fallo por límite de tasa).

Implementación:

- `sanitizeToolCallInputs` en `src/agents/session-transcript-repair.ts`
- Aplicado en `sanitizeSessionHistory` en `src/agents/pi-embedded-runner/replay-history.ts`

---

## Regla global: procedencia de entrada entre sesiones

Cuando un agente envía un prompt a otra sesión mediante `sessions_send` (incluidos
los pasos agent-to-agent de reply/announce), OpenClaw persiste el turno de usuario creado con:

- `message.provenance.kind = "inter_session"`

Estos metadatos se escriben al anexar la transcripción y no cambian el rol
(`role: "user"` se mantiene por compatibilidad con el proveedor). Los lectores de transcripciones pueden usar
esto para evitar tratar prompts internos enrutados como instrucciones creadas por el usuario final.

Durante la reconstrucción del contexto, OpenClaw también antepone un breve marcador
`[Inter-session message]` a esos turnos de usuario en memoria para que el modelo pueda distinguirlos de
las instrucciones externas del usuario final.

---

## Matriz de proveedores (comportamiento actual)

**OpenAI / OpenAI Codex**

- Solo saneamiento de imágenes.
- Elimina firmas reasoning huérfanas (elementos reasoning independientes sin un bloque de contenido posterior) para transcripciones de OpenAI Responses/Codex, y elimina reasoning reproducible de OpenAI después de un cambio de ruta del modelo.
- Sin saneamiento de ID de llamadas a herramientas.
- La reparación de emparejamiento de resultados de herramientas puede mover salidas reales emparejadas y sintetizar salidas `aborted` de estilo Codex para llamadas a herramientas faltantes.
- Sin validación ni reordenación de turnos.
- Las salidas de herramientas faltantes de la familia OpenAI Responses se sintetizan como `aborted` para coincidir con la normalización de reproducción de Codex.
- Sin eliminación de firmas de pensamiento.

**Google (Generative AI / Gemini CLI / Antigravity)**

- Saneamiento de ID de llamadas a herramientas: alfanumérico estricto.
- Reparación de emparejamiento de resultados de herramientas y resultados de herramientas sintéticos.
- Validación de turnos (alternancia de turnos estilo Gemini).
- Corrección del orden de turnos de Google (antepone un pequeño bootstrap de usuario si el historial comienza con assistant).
- Antigravity Claude: normaliza firmas de thinking; elimina bloques de thinking sin firma.

**Anthropic / Minimax (compatible con Anthropic)**

- Reparación de emparejamiento de resultados de herramientas y resultados de herramientas sintéticos.
- Validación de turnos (fusiona turnos consecutivos de user para satisfacer la alternancia estricta).
- Los bloques de thinking con firmas de reproducción faltantes, vacías o en blanco se eliminan
  antes de la conversión del proveedor. Si eso vacía un turno de assistant, OpenClaw conserva
  la forma del turno con texto no vacío de reasoning omitido.
- Los turnos más antiguos de assistant que solo contienen thinking y que deben eliminarse se sustituyen por
  texto no vacío de reasoning omitido para que los adaptadores del proveedor no eliminen el
  turno de reproducción.

**Amazon Bedrock (Converse API)**

- Los turnos vacíos de error de flujo de assistant se reparan con un bloque de texto alternativo no vacío
  antes de la reproducción. Bedrock Converse rechaza mensajes de assistant con `content: []`, por lo que
  los turnos persistidos de assistant con `stopReason: "error"` y contenido vacío también se
  reparan en disco antes de la carga.
- Los bloques de thinking de Claude con firmas de reproducción faltantes, vacías o en blanco se
  eliminan antes de la reproducción de Converse. Si eso vacía un turno de assistant, OpenClaw
  conserva la forma del turno con texto no vacío de reasoning omitido.
- Los turnos más antiguos de assistant que solo contienen thinking y que deben eliminarse se sustituyen por
  texto no vacío de reasoning omitido para que la reproducción de Converse mantenga una forma estricta del turno.
- La reproducción filtra los turnos de assistant de espejo de entrega de OpenClaw e inyectados por gateway.
- El saneamiento de imágenes se aplica mediante la regla global.

**Mistral (incluida la detección basada en model-id)**

- Saneamiento de ID de llamadas a herramientas: strict9 (alfanumérico de longitud 9).

**OpenRouter Gemini**

- Limpieza de firmas de pensamiento: elimina valores `thought_signature` que no sean base64 (conserva base64).

**Todo lo demás**

- Solo saneamiento de imágenes.

---

## Comportamiento histórico (anterior a 2026.1.22)

Antes del lanzamiento 2026.1.22, OpenClaw aplicaba múltiples capas de higiene de transcripciones:

- Una **extensión transcript-sanitize** se ejecutaba en cada construcción de contexto y podía:
  - Reparar el emparejamiento de uso/resultado de herramientas.
  - Sanear ID de llamadas a herramientas (incluido un modo no estricto que preservaba `_`/`-`).
- El ejecutor también realizaba saneamiento específico del proveedor, lo que duplicaba trabajo.
- Se producían mutaciones adicionales fuera de la política del proveedor, incluidas:
  - Eliminar etiquetas `<final>` del texto de assistant antes de la persistencia.
  - Eliminar turnos vacíos de error de assistant.
  - Recortar contenido de assistant después de llamadas a herramientas.

Esta complejidad causó regresiones entre proveedores (especialmente en el emparejamiento
`call_id|fc_id` de `openai-responses`). La limpieza de 2026.1.22 eliminó la extensión, centralizó
la lógica en el ejecutor e hizo que OpenAI fuera **sin intervención** más allá del saneamiento de imágenes.

## Relacionado

- [Gestión de sesiones](/es/concepts/session)
- [Poda de sesiones](/es/concepts/session-pruning)
