Dirigir el tráfico de Claude Code por encabezados en lugar de leer la solicitud
Aprenda cómo los encabezados de indicación del portal de opt-in de Claude Code permiten a un portal de LLM dar prioridad, presupuestar y gestionar cachés a partir de los metadatos de la solicitud, sin necesidad de analizar el contenido del prompt.
Cuando una empresa envía tráfico de Claude Code a través de una pasarela LLM, dicha pasarela debe tomar decisiones sobre cada solicitud antes de reenviarla: qué conexión ascendente utilizar, a qué cola unirse, en qué bucket de límite de velocidad aplicar la carga y qué prioridad asignar. Hasta hace poco, el único lugar donde se encontraban los datos que sustentaban esas decisiones era en el cuerpo de la solicitud, es decir, tus instrucciones, el contenido de los archivos, los resultados de las herramientas y CLAUDE.md. Un conjunto de encabezados de solicitud opcionales añadidos en una reciente versión de Claude Code traslada esos datos al sobre de la solicitud. A continuación verás qué puede decidirse con cada encabezado, cómo cambia el proxy cuando puede utilizarlos y en qué casos aún no debes confiar en ellos.
Por qué las pasarelas terminan leyendo tus instrucciones
La inspección del cuerpo de la solicitud no es un problema teórico; así funcionan muchos routers en la actualidad. Los routers semánticos como el vLLM Semantic Router extraen la instrucción del usuario, la incrustan en un modelo de tipo BERT y comparan el vector resultante con los vectores de tareas de referencia para clasificar la solicitud. Los routers optimizados para reducir la latencia pueden detectar el nombre del modelo aproximadamente a partir del primer kilobyte y transmitir el resto, pero cualquier router que necesite clasificar la solicitud debe almacenar en búfer e inspeccionar todo el contenido.
Esa inspección constituye la característica distintiva del producto, y también hace que la pasarela sea un límite de confianza mucho más sensible de lo que sugiere su nombre sencillo. Puede ver, e incluso almacenar, todo lo que envía el agente de un desarrollador.
Claude Code 2.1.273, con fecha del 15 de septiembre de 2026 según el changelog, añadió cinco encabezados dirigidos a los operadores de gateway. En conjunto, funcionan más bien como el mínimo metadato necesario para que un gateway actúe como programador sin funcionar también como lector, en lugar de ser una característica de observabilidad.
Los límites de los encabezados de identificador originales
Antes de 2.1.273, la guía de compatibilidad para gateways documentaba tres encabezados de Claude Code, todos ellos identificadores:
+--------------------------------+---------------------------------+
| HEADER | WHAT IT IS |
+--------------------------------+---------------------------------+
| x-claude-code-session-id | which session |
| x-claude-code-agent-id | which subagent (if any) |
| x-claude-code-parent-agent-id | which agent spawned it |
+--------------------------------+---------------------------------+
|
v
good for GROUPING after the fact
useless for DECIDING before forwarding
abc y del agente def no dice nada sobre cuán costosa será, cuánto tiempo tomará ni si puede permitirse esperar. Por lo tanto, cualquier pasarela que quisiera ser más inteligente que un simple contador tenía que acceder al contenido del cuerpo de la solicitud.
Los cinco nuevos encabezados de indicación
Según el registro de cambios, la versión 2.1.273 introdujo cinco encabezados, todos activados al mismo tiempo con CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. Dos describen al llamante (x-claude-code-agent-type y x-claude-code-request-class), uno describe los tiempos recientes (x-claude-code-prev-tool-durations), y una pareja describe las reescrituras de contexto (x-claude-code-context-compacted junto con x-claude-code-compaction).
Una advertencia importante: en el momento de redactar este texto, la tabla de encabezados de solicitud en la guía de compatibilidad del gateway todavía muestra solo los tres encabezados identificadores, y la variable falta en la referencia de variables de entorno. Los nombres de los encabezados provienen del registro de cambios, pero sus formatos de valor aún no están documentados. Todo lo que se describe a continuación indica qué puede decidir un gateway con cada encabezado, no un formato de transmisión garantizado. Revise su propio tráfico antes de confiar en valores específicos y consulte la documentación actual, que podría haberse actualizado.
Clasificados según la decisión que cada uno permite tomar:
+---------------------------+------------------------------------------+
| HEADER | DECISION IT UNBLOCKS AT THE EDGE |
+---------------------------+------------------------------------------+
| request-class | is this a real turn, or a small |
| | internal call? -> priority, cheap pool |
+---------------------------+------------------------------------------+
| agent-type | which kind of subagent is asking |
| | -> per-agent-type budgets and quotas |
+---------------------------+------------------------------------------+
| prev-tool-durations | how long the last tools took |
| | -> timeout and retry window sizing |
+---------------------------+------------------------------------------+
| compaction | this turn IS the summarization call |
| | -> never count it as user latency |
+---------------------------+------------------------------------------+
| context-compacted | the prefix just changed under you |
| | -> do not expect a cache hit this turn |
+---------------------------+------------------------------------------+
En resumen:
- request-class separa las interacciones reales de la conversación de las llamadas internas menores, lo que permite dar prioridad a las primeras y enviar las segundas a un grupo más económico.
- agent-type identifica qué tipo de subagente está realizando la llamada, lo que facilita establecer presupuestos y cuotas por tipo de agente.
- prev-tool-durations indica cuánto tiempo duraron las ejecuciones recientes de herramientas, lo cual ayuda a definir los tiempos de espera y los períodos de intento nuevamente.
- compaction marca la solicitud que realiza la propia resumen, por lo que nunca debe influir en la latencia percibida por el usuario.
- context-compacted indica que el prefijo de la conversación acaba de ser reescrito, por lo que no se espera un acceso desde el caché.
Nada de esto constituye información nueva. Una pasarela ya podría deducir la clase de la solicitud al distinguir entre el prompt completo del sistema Claude Code y uno simplificado, inferir el tipo de agente a partir de la sección correspondiente en el prompt del sistema, y detectar la compresión por la estructura del array de mensajes. Los encabezados no revelan nada adicional sobre usted. Lo que cambia es el precio del conocimiento: en lugar de analizar hasta un megabyte de código fuente, la pasarela lee una cadena corta de los encabezados.
La misma regla de enrutamiento, antes y después
Tomemos un objetivo concreto: enrutar la resumen de contexto a un grupo menos costoso. Sin indicaciones, el proxy debe almacenar temporalmente y analizar la conversación, para luego adivinar su contenido:
// BEFORE: the router has to read the conversation to classify it
const body = await readEntireBody(req); // buffers the whole prompt
const parsed = JSON.parse(body); // your files are now in gateway memory
const sys = flattenSystemBlocks(parsed.system);
const isBackground =
sys.includes("summarize the conversation") ||
parsed.messages.length > COMPACT_THRESHOLD;
y solo entonces enviar el cuerpo almacenado temporalmente:
route(isBackground ? "cheap-pool" : "interactive-pool", body);
Este enfoque presenta tres problemas, del menos grave al más serio. Al almacenar todo el contenido en búfer se destruye la latencia de transmisión en tiempo real. La comparación basada en las palabras del comando es frágil, ya que dichas palabras cambian entre las diferentes versiones de Claude Code. Lo peor es que todo el texto de tu repositorio ahora se encuentra en la memoria del proceso de la capa de enrutamiento, en sus volcados de heap y muy probablemente en sus registros, un lugar que no aparece en ningún diagrama de arquitectura y del cual nadie pensó en protegerlo.
Con los encabezados de indicación, el router lee dos valores del sobre:
// AFTER: the router decides on the envelope and never touches the body
const cls = req.headers["x-claude-code-request-class"];
const comp = req.headers["x-claude-code-compaction"];
y enruta la secuencia de solicitudes sin modificarla. Como señala el comentario en el fragmento, las cadenas de texto literales son meramente ilustrativas, ya que el formato aún no está documentado:
// value strings below are illustrative: confirm them against your own
// traffic, since the wire format is not documented yet
const isBackground = Boolean(comp) || cls === "background";route(isBackground ? "cheap-pool" : "interactive-pool", req); // streams through
No hay buffering, ni análisis de JSON ni mensaje almacenado en memoria. La guía de compatibilidad ya permite este patrón: aparte de anthropic-workspace-id, anthropic-beta y anthropic-version, los encabezados se describen como entradas que la pasarela puede utilizar para el rastreo, la atribución o el enrutamiento y no es necesario que las transmita. Estas indicaciones están diseñadas para quedar en la pasarela; como el modelo nunca las ve, pueden ser simples y económicas.
La pareja de compactación es una señal de caché
Dos de los encabezados parecen redundantes, pero responden a preguntas diferentes. El primero, x-claude-code-compaction, se establece en la misma llamada que genera el resumen. El segundo, x-claude-code-context-compacted, aparece en llamadas posteriores, una vez que ya se ha realizado la compactación.
La distinción es importante cuando se utiliza un caché. Las claves del caché para los comandos son prefijos formados a partir de las herramientas, seguidos del comando del sistema y luego de los mensajes; por lo tanto, reescribir cualquier elemento al principio invalida todo lo que sigue. Las escrituras en el caché también tienen un costo mayor que las lecturas, por lo que las escrituras innecesarias representan un gasto puramente inútil. La compactación es el factor que más invalida datos en una sesión normal: sustituye el historial acumulado por un resumen, generando así, por definición, un nuevo prefijo.
turn N turn N+1 (compaction) turn N+2
+---------+ +------------------+ +------------------+
| prefix | | compaction: 1 | | context- |
| stable | --> | rewrites history | --> | compacted: 1 |
| cache | | EXPECT A MISS | | new prefix is |
| hits | | bill it as | | now the stable |
+---------+ | background | | one, re-warm it |
+------------------+ +------------------+
Una pasarela que mantiene su propio caché pero no sabe nada sobre la compactación se comporta de la peor manera posible durante el proceso de compactación: realiza una búsqueda completa, falla, almacena una entrada para un prefijo que quedará obsoleto en el turno siguiente, y luego informa de una tasa de aciertos en descenso que se investiga como un defecto. Con los encabezados adecuados, puede omitir la búsqueda en la solicitud de compactación, considerar esa llamada como trabajo en segundo plano y calentar intencionadamente el nuevo prefijo en el turno siguiente, cuando se convierta en el estable.
Los indicadores son afirmaciones del cliente, no credenciales
Tanto el registro de cambios como el nombre de la variable utilizan estos encabezados indicadores, y la elección de las palabras es importante. Un indicador es una afirmación no verificada hecha por el cliente. El valor de x-claude-code-request-class es lo que Claude Code decida enviar; ningún componente superior lo verifica.
Supongamos que su gateway recompensa las solicitudes etiquetadas como de fondo con tarifas reducidas, cuotas mayores o límites de tasa más flexibles. Entonces, una cadena proporcionada por el cliente toma silenciosamente la decisión de autorización. Un desarrollador que modifica su entorno de shell, o cualquier persona que ejecute un pequeño proxy local delante del gateway, puede elegir la etiqueta que reciba el trato más generoso. Las indicaciones son entradas adecuadas para la gestión de colas, las decisiones relacionadas con el caché y la medición de la latencia, pero nunca para decidir qué derechos tiene quien realiza la solicitud.
El segundo problema práctico es la adopción. Los encabezados están deshabilitados a menos que se active explícitamente, lo cual es la opción adecuada para metadatos que exponen la estructura de la sesión a un middlebox. Sumado a su ausencia en la referencia de variables de entorno en el momento de redactar este texto, es poco probable que muchas instalaciones los tengan habilitados. En una organización, generalmente será necesario implementarlos a través de configuraciones gestionadas por un administrador que haya notado una sola línea en el registro de cambios.
Un plan de implementación para operadores de gateway
Si su equipo gestiona un gateway para el tráfico de Claude Code, una ruta de adopción cautelosa sería la siguiente:
- Habilitar
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1para un pequeño grupo piloto. - Registrar los cinco encabezados durante aproximadamente una semana sin tomar ninguna acción al respecto.
- Comparar sus valores con las decisiones que toma actualmente el clasificador de análisis de contenido.
La ventaja es un radio de impacto significativamente menor: el código fuente de sus desarrolladores ya no necesita pasar por la memoria de la capa de enrutamiento, y solo requiere una variable de entorno.
Conclusión
Los encabezados en sí son específicos de Claude Code, pero la lección de diseño es aplicable a cualquier plataforma de agentes. Cualquier capa colocada delante de un agente necesita clasificar las solicitudes antes de pasarlas, y solo hay dos formas de hacerlo: deducir la respuesta a partir del contenido de la solicitud o recibirla como metadatos explícitos. La deducción siempre funciona, pero deja siempre una copia de contenido sensible en un componente que no tenía motivos para conservarlo. Un canal de metadatos explícitos requiere más trabajo de diseño inicial, pero es el único arreglo en el que el intermediario puede enrutar correctamente sin llegar a tener nunca los datos en sí. Para una visión más amplia de lo que ofrece una pasarela, consulte la visión general de la pasarela LLM en los documentos de Claude Code.
Lecturas relacionadas
- Cursor, Claude Code y Codex: Elegir una herramienta de programación con IA para JS — Esta comparación explica cómo Cursor, Claude Code y Codex se adaptan a diferentes flujos de trabajo en JavaScript, desde la programación basada en editores hasta tareas con agentes autónomos.
- Un playbook práctico para escribir un archivo CLAUDE.md efectivo — Aprenda 21 reglas concretas y verificables para reducir el tamaño de un archivo CLAUDE.md excesivo, de modo que Claude Code siga siendo fiable, predecible y fácil de confiar en sesiones prolongadas.