Guía de compatibilidad de la puerta de enlace Claude Code

Mantener una puerta de enlace LLM compatible con Claude Code: los puntos finales que llama, los encabezados y campos de cuerpo a reenviar, y qué se rompe cuando se eliminan.

Esta página documenta las solicitudes que Claude Code envía a una puerta de enlace, incluidos los puntos finales que llama, los encabezados y campos de cuerpo que la puerta de enlace debe reenviar, y qué características dejan de funcionar cuando no lo hace. Está escrita para operadores que configuran un producto de puerta de enlace para trabajar con Claude Code.

La puerta de enlace de aplicaciones Claude, la puerta de enlace autohospedada de Anthropic, sirve su propia referencia de puntos finales en GET /protocol, cubriendo los puntos finales de inicio de sesión, inferencia, configuración administrada, descubrimiento de modelos y telemetría de esa puerta de enlace. Es un documento separado de esta guía.

Esta página cubre:

• Formatos de API y los puntos finales a servir para cada uno
• Encabezados de solicitud: cuáles deben llegar al proveedor ascendente y cuáles su puerta de enlace puede consumir
• El bloque de atribución del mensaje del sistema y cómo interactúa con el almacenamiento en caché de solicitudes
• Paso de características: qué se rompe cuando se eliminan encabezados o campos de cuerpo
• Descubrimiento de modelos

Esta página utiliza dos términos para lo que su puerta de enlace hace con cada encabezado y campo de cuerpo:

• Reenviar sin cambios: pasarlo al proveedor ascendente byte por byte
• Consumir: la puerta de enlace puede leerlo para enrutamiento, atribución o seguimiento y no necesita reenviarlo

Cualquier cosa no marcada como reenviar sin cambios es suya para consumir o ignorar.

Formatos de API

Una puerta de enlace debe exponer al menos uno de los siguientes formatos de API a los clientes de Claude Code. Un cliente elige un formato y apunta Claude Code a su puerta de enlace con las variables en la columna Seleccionado por de la tabla a continuación.

Google Cloud's Agent Platform es el punto de conexión de Claude de Google Cloud, anteriormente Vertex AI; sus nombres de variables mantienen la ortografía VERTEX.

Foundry y Claude Platform en AWS

Microsoft Foundry y la Claude Platform en AWS implementan el formato Anthropic Messages. Claude Code se enruta a ellos a través de sus propias variables, ANTHROPIC_FOUNDRY_BASE_URL y ANTHROPIC_AWS_BASE_URL, pero una puerta de enlace que está frente a cualquiera de ellos implementa la fila Anthropic Messages anterior. Una puerta de enlace que está frente a Claude Platform en AWS también debe reenviar el encabezado anthropic-workspace-id, que esa plataforma requiere en cada solicitud.

Puntos finales opcionales y tráfico de inicio

Los puntos finales de conteo de tokens son los únicos opcionales: cuando están ausentes, Claude Code recurre a una estimación basada en caracteres del uso de contexto.

Coincida con la ruta, no con la URL completa:

• Las solicitudes de inferencia se publican en /v1/messages?beta=true
• Los sufijos del método Google Cloud's Agent Platform se adjuntan a la ruta del modelo del editor, como en /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

Una puerta de enlace también ve tráfico de inicio de mejor esfuerzo que puede rechazar sin romper nada. Una puerta de enlace con formato Anthropic Messages recibe una sonda de calentamiento de conexión HEAD /api/hello, que Claude Code omite cuando se configura un proxy HTTP o certificado de cliente. Una puerta de enlace con formato Amazon Bedrock recibe una solicitud GET /inference-profiles?type=SYSTEM_DEFINED y, cuando el modelo configurado es un perfil de inferencia, búsquedas GET /inference-profiles/{profile}.

La verificación de disponibilidad de modo rápido nunca aparece en los registros de la puerta de enlace: llama a api.anthropic.com directamente en lugar de seguir ANTHROPIC_BASE_URL, por lo que en una red que bloquea la salida directa a api.anthropic.com, el modo rápido puede reportar un error de conectividad mientras que la inferencia a través de la puerta de enlace sigue funcionando. La verificación de seguridad del dominio WebFetch también llama a api.anthropic.com directamente. Usar modo rápido detrás de proxies y puertas de enlace LLM cubre las variables que lo restauran.

Transmisión

Transmita las respuestas de inferencia. Claude Code lee la transmisión a medida que llega, por lo que si su puerta de enlace almacena en búfer respuestas completas antes de retransmitirlas, Claude Code se detiene.

Cuando el cliente habla el formato Amazon Bedrock, retransmita el cuerpo de respuesta InvokeModelWithResponseStream y su encabezado Content-Type: application/vnd.amazon.eventstream sin modificar, y no convierta la transmisión a eventos enviados por el servidor. Consulte Errores de transmisión detrás de una puerta de enlace o proxy.

Reenvíe también los pings de mantenimiento de conexión. En conexiones a través de ANTHROPIC_BASE_URL o ANTHROPIC_AWS_BASE_URL, Claude Code cuenta cada byte que su puerta de enlace retransmite, incluidos los eventos SSE ping y líneas de comentario, y aborta una transmisión que se queda en silencio durante 300 segundos de forma predeterminada. Los pings del proveedor ascendente son el único tráfico durante pausas de pensamiento prolongado, por lo que si su puerta de enlace los elimina o los almacena en búfer, Claude Code aborta la transmisión durante esas pausas; Reintentos automáticos cubre lo que una transmisión abortada reporta según cuán lejos haya progresado la respuesta. Un proveedor ascendente que no envía pings en absoluto, como el flujo de eventos binario de Amazon Bedrock, deja esas pausas sin nada que reenviar. Al traducir desde tal proveedor ascendente, emita sus propios eventos ping durante brechas silenciosas. Las puertas de enlace alcanzadas a través de ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, o ANTHROPIC_FOUNDRY_BASE_URL no están envueltas por este vigilante de nivel de byte, incluso cuando retransmiten el formato Anthropic Messages; allí, un tiempo de espera de inactividad de 5 minutos aborta una transmisión silenciosa en su lugar, y en conexiones ANTHROPIC_BEDROCK_BASE_URL puede agregar el vigilante de byte con CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK.

Desajuste de formato con el proveedor ascendente

Qué formato habla el cliente determina lo que su puerta de enlace recibe. El modo de fallo común es un desajuste entre el formato que el cliente envía a su puerta de enlace y el formato que el proveedor ascendente detrás de él acepta.

• Cuando el cliente habla el formato Amazon Bedrock o Google Cloud's Agent Platform, Claude Code envía solo el subconjunto de su conjunto de capacidades completo que esos proveedores aceptan
• Cuando el cliente habla el formato Anthropic Messages, Claude Code envía el conjunto completo, incluso si su puerta de enlace se reenvía a un proveedor ascendente Amazon Bedrock o Google Cloud's Agent Platform

Cerrar esa diferencia es el trabajo de su puerta de enlace. Paso de características describe qué se rompe cuando no lo hace.

Encabezados de solicitud

Claude Code incluye estos encabezados en solicitudes de API. Los nombres de encabezados no distinguen mayúsculas de minúsculas en la red. Reenvíe anthropic-version y anthropic-beta sin cambios, más anthropic-workspace-id cuando el proveedor ascendente es la Claude Platform en AWS; el resto la puerta de enlace puede consumir para enrutamiento, atribución y seguimiento, y no necesita reenviar.

Los ID de subagente se generan nuevos para cada generación. Los agentes compañeros, los miembros nombrados de un equipo de agentes, reutilizan un ID estable basado en nombres en reconexiones. En ambos casos, el ID identifica un agente, no una persona o un dispositivo, así que no trate el encabezado de ID de agente como un identificador de usuario.

Si sus desarrolladores establecen ANTHROPIC_CUSTOM_HEADERS, esos encabezados también aparecen en las solicitudes.

Reenviar como listas abiertas

Trate los encabezados y campos de cuerpo como listas abiertas, no cerradas. Claude Code gana capacidades en las versiones, y llegan como nuevos valores anthropic-beta, nuevos campos de cuerpo de solicitud y ocasionalmente nuevos encabezados anthropic-* o x-claude-code-*.

Al reenviar a un proveedor ascendente con formato Anthropic, pase encabezados de solicitud anthropic-* y campos de cuerpo de solicitud sin cambios en lugar de permitir los que ve hoy. Una puerta de enlace fijada a una lista observada elimina el encabezado o campo de la siguiente capacidad y lo rompe en la versión que la introduce.

La excepción es un proveedor ascendente que no es Anthropic, como Amazon Bedrock o Agent Platform de Google Cloud, donde cerrar la diferencia de esquema es el trabajo de la puerta de enlace; consulte paso de características.

Bloque de atribución del mensaje del sistema

Claude Code antepone un bloque de atribución corto al mensaje del sistema que contiene la versión del cliente y una huella digital derivada de la conversación. El punto final api.anthropic.com elimina el bloque antes de procesar cuando llega sin cambios como el primer bloque del sistema, por lo que no afecta el almacenamiento en caché de solicitudes de primera parte. Cualquier otro proveedor ascendente lo recibe como parte del mensaje.

La eliminación es posicional, por lo que solo funciona cuando la puerta de enlace reenvía la matriz system sin cambios. Para mantener el bloque fuera del mensaje sin perder otro contenido del sistema:

• Reenvíe la matriz system exactamente como se recibió, manteniendo el bloque primero: anteponer otro bloque del sistema, reordenar la matriz o convertirla en una sola cadena anula la eliminación, y el bloque luego llega al modelo y a la clave de caché de solicitud.
• Mantenga el bloque en su propia entrada de matriz: el punto final trata un bloque fusionado que comienza con el encabezado de atribución como atribución en su totalidad y descarta todo lo fusionado en él, incluido el resto del mensaje del sistema.
• Si su puerta de enlace debe remodelar el contenido del sistema, establezca CLAUDE_CODE_ATTRIBUTION_HEADER=0 para que Claude Code omita el bloque. Anthropic y los puntos finales de Claude de los proveedores de nube leen el bloque para atribución, así que omítalo en el cliente en lugar de eliminarlo o moverlo en la puerta de enlace.

La variable existe para compatibilidad con almacenamiento en caché de puertas de enlace y terceros, no como control de privacidad: en una conexión directa la solicitud completa ya va a la API de Anthropic de cualquier forma. Cuando se cumplen ambas condiciones, Claude Code mantiene el bloque en solicitudes del clasificador de modo automático incluso cuando establece la variable en 0:

• Las solicitudes van a api.anthropic.com, con ANTHROPIC_BASE_URL sin establecer o nombrando ese host y sin proveedor de terceros seleccionado.
• La credencial activa no es una credencial de perfil de Anthropic o federación.

Las solicitudes del clasificador omiten el resto del mensaje del sistema de Claude Code, por lo que en esas solicitudes el bloque es el único marcador en el cuerpo de la solicitud que las identifica como tráfico de Claude Code. Cuando falla cualquiera de las condiciones, a través de una puerta de enlace LLM, en un proveedor de terceros, o con una credencial de perfil o federación activa, establecer 0 elimina el bloque de las solicitudes del clasificador también. Antes de v2.1.229, esta excepción no existía: establecer 0 eliminaba el bloque de esas solicitudes del clasificador, y cuando la API rechazaba las solicitudes no identificadas, el modo automático fallaba en cada acción que enviaba al clasificador.

Desde Claude Code v2.1.181, el bloque es estable para la vida útil de una conversación cuando las solicitudes se enrutan a través de una URL base personalizada, por lo que una caché de solicitud de puerta de enlace con clave en el cuerpo de solicitud completo funciona sin deshabilitarlo, y cualquier proveedor al que su puerta de enlace reenvíe recibe un prefijo de solicitud estable. Antes de v2.1.181, el bloque incluía un token por solicitud que cambiaba el inicio del mensaje del sistema en cada solicitud. En esas versiones, establezca CLAUDE_CODE_ATTRIBUTION_HEADER=0 cuando su puerta de enlace haga cualquiera de estas cosas:

• Implementa una caché de solicitud con clave en el cuerpo de la solicitud.
• Reenvía solicitudes a un proveedor de terceros como Amazon Bedrock, Microsoft Foundry o la Plataforma de Agentes de Google Cloud, en el formato de Mensajes de Anthropic o el del proveedor, donde el prefijo cambiante reduce la reutilización de caché de solicitud en ese proveedor.

Paso de características

Claude Code trata una puerta de enlace ANTHROPIC_BASE_URL como un punto final con formato Anthropic y le envía los encabezados beta y campos de cuerpo de solicitud que envía a api.anthropic.com, excepto un pequeño conjunto de diagnósticos y valores predeterminados reservados para conexiones directas, como el valor predeterminado de transmisión de herramientas de grano fino cubierto a continuación. Ese conjunto varía según la versión, así que no dependa de su contenido.

Las capacidades que agregan campos de cuerpo los emparejan con un encabezado beta, y el par viaja junto. Una puerta de enlace que elimina el encabezado mientras pasa el cuerpo, o reenvía un cuerpo con formato Anthropic a un proveedor ascendente con un esquema diferente, produce errores 400 duros; solo cuando ambas mitades están ausentes juntas la característica se apaga silenciosamente. Una puerta de enlace que reescribe o redacta cuerpos de solicitud para inspección de contenido rompe el emparejamiento de la misma manera que la eliminación, así que inspeccione sin modificar. La tabla señala dónde una característica se desvía del emparejamiento.

La transmisión de herramientas de grano fino es uno de los valores predeterminados de conexión directa: está desactivada de forma predeterminada siempre que las solicitudes se enruten a través de una URL base personalizada, y una puerta de enlace la recibe cuando los desarrolladores establecen CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1.

Las variables ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES declaran capacidades de modelo solo en las configuraciones del proveedor: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, y CLAUDE_CODE_USE_MANTLE. No tienen efecto detrás de una puerta de enlace ANTHROPIC_BASE_URL.

Reintento automático y reenvío de errores

Lo que Claude Code hace después de un rechazo ascendente depende de lo que fue rechazado:

• Cuando el proveedor ascendente rechaza el campo thinking, un mensaje del sistema a mitad de conversación, o el marcador cache_control en tal mensaje, Claude Code reintenta la solicitud y deshabilita la capacidad rechazada para el resto de la conversación
• Cuando el proveedor ascendente rechaza una firma de pensamiento, Claude Code reintenta la solicitud sin los bloques de pensamiento anteriores de la conversación y los mantiene fuera de cada solicitud posterior. Las nuevas respuestas aún incluyen pensamiento
• Claude Code no reintenta rechazos de gestión de contexto o campos de esquema de herramienta, así que esos errores 400 llegan al desarrollador

La lógica de reintento coincide con la redacción del error del proveedor ascendente, así que reenvíe cuerpos de respuesta de error sin modificar. Una puerta de enlace que envuelve errores ascendentes en su propio sobre rompe la ruta de recuperación, incluso cuando preserva el código de estado, a menos que el mensaje del sobre lleve un token capability_rejected: estable. La puerta de enlace de aplicaciones Claude sustituye esos tokens por la redacción de error de los proveedores de nube, por ejemplo capability_rejected: prompt_too_long.

Deshabilitar capacidades de pre-lanzamiento

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 detiene Claude Code de enviar capacidades de pre-lanzamiento y sus campos de cuerpo en cada proveedor, incluida la gestión de contexto y los campos de herramienta beta. La variable no afecta el razonamiento adaptativo, que se selecciona por modelo en lugar de por beta. Nunca suprime la capacidad OAuth que la autenticación de suscripción requiere.

En Claude Code v2.1.227 o posterior, su organización puede mantener búsqueda de herramientas MCP activada bajo esta variable a través de configuración administrada. Lo que Claude Code envía con esa anulación en su lugar depende de cómo se conecte:

• En una conexión directa, o a través de una puerta de enlace configurada con ANTHROPIC_BASE_URL, Claude Code sigue enviando el encabezado beta de búsqueda de herramientas, campos de herramienta defer_loading, y bloques tool_reference, y elimina el resto
• En un proveedor de nube, o iniciando sesión a través de una puerta de enlace de aplicaciones Claude, la anulación no tiene efecto

El conjunto de capacidades que Claude Code envía crece en las versiones. Para cadenas de encabezado beta actuales, consulte la referencia de encabezados beta; pruebe su puerta de enlace contra nuevas versiones de Claude Code en lugar de fijar a una lista observada.

Descubrimiento de modelos

Cuando ANTHROPIC_BASE_URL apunta a una puerta de enlace que expone el formato Anthropic Messages, Claude Code puede consultar el punto final /v1/models de la puerta de enlace al inicio y agregar los modelos devueltos al selector /model. Si usted o su administrador establecen replaceBuiltInOptions en una alineación modelPicker, Claude Code oculta los modelos descubiertos del selector.

Los desarrolladores lo habilitan estableciendo CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, en su propio entorno o a través de configuración administrada. El descubrimiento está desactivado de forma predeterminada para que las puertas de enlace respaldadas por una clave API compartida no expongan cada modelo que la clave puede acceder a cada usuario.

Cuándo se ejecuta el descubrimiento

El descubrimiento se aplica solo al formato Anthropic Messages. No se ejecuta cuando:

• Se establece cualquier variable de proveedor CLAUDE_CODE_USE_*, incluso si ANTHROPIC_BASE_URL también se establece
• ANTHROPIC_BASE_URL no se establece o apunta a api.anthropic.com

El descubrimiento aún se ejecuta cuando el tráfico no esencial está desactivado, porque la solicitud va solo a su puerta de enlace. Antes de v2.1.257, el descubrimiento no se ejecutaba mientras el tráfico no esencial estaba desactivado.

Solicitud y respuesta

La solicitud es GET /v1/models?limit=1000 con un tiempo de espera de 3 segundos, y cualquier redirección se trata como fallo para que la credencial no pueda filtrarse a un destino de redirección. Una puerta de enlace que responde lentamente o redirige /v1/models, incluso http a https, falla el descubrimiento silenciosamente; sirva el punto final directamente en la URL base configurada.

Claude Code envía la solicitud de descubrimiento con ambos encabezados de credencial a continuación y omite un encabezado cuyo valor no se resuelve. Enviar ambos encabezados requiere Claude Code v2.1.248 o posterior. Las versiones anteriores envían solo Authorization cuando ANTHROPIC_AUTH_TOKEN se establece y solo x-api-key de lo contrario.

• Authorization: ANTHROPIC_AUTH_TOKEN como un token portador, de lo contrario el valor apiKeyHelper como un token portador. En ese caso, Claude Code espera a que el asistente regrese antes de enviar la solicitud.
• x-api-key: la clave API que Claude Code resolvió, como ANTHROPIC_API_KEY. Cuando un valor de asistente es la única credencial, este encabezado también la lleva, por lo que el valor llega en ambos encabezados.

Claude Code también envía cualquier encabezado de ANTHROPIC_CUSTOM_HEADERS. Cuando un encabezado personalizado tiene un valor no vacío, Claude Code lo envía en lugar de un encabezado integrado del mismo nombre, haciendo coincidir los nombres sin distinción de mayúsculas y minúsculas.

Cuando ningún valor del encabezado de credencial se resuelve, Claude Code omite el descubrimiento y escribe una línea [gatewayDiscovery] skipped en el registro de depuración de una sesión claude --debug. Si proporciona una credencial solo a través de ANTHROPIC_CUSTOM_HEADERS, Claude Code aún omite el descubrimiento.

Claude Code lee id, el display_name opcional y la description opcional de cada entrada en la matriz data de la respuesta:

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Code mantiene una entrada cuando su id contiene claude o anthropic en cualquier lugar de la cadena, coincidiendo sin distinción de mayúsculas y minúsculas, e ignora el resto. Los ID con prefijo de proveedor como vertex_ai/claude-sonnet-4-6 o bedrock/anthropic.claude-sonnet-4-5 pasan el filtro; un ID que no contiene ninguna subcadena no lo hace. Antes de v2.1.223, Claude Code mantenía una entrada solo cuando su id comenzaba con claude o anthropic, lo que ocultaba los ID con prefijo de proveedor.

Entradas del selector y almacenamiento en caché

El selector es la lista de modelos interactiva que se abre cuando un desarrollador ejecuta /model en Claude Code. Cada entrada descubierta utiliza display_name como su nombre cuando la puerta de enlace envía uno que difiere del id. De lo contrario, la entrada muestra el nombre del modelo cuando Claude Code reconoce el id, y el id cuando no lo hace. Por ejemplo, una entrada con el id my-gateway-claude-sonnet-4-6 y sin display_name aparece como Sonnet 4.6.

El descubrimiento agrega solo modelos que la configuración administrada availableModels permite.

Cada entrada también muestra la description del modelo, contraída a una línea. Una entrada sin una description lee "From gateway" en su lugar. Antes de v2.1.257, cada entrada descubierta leía "From gateway".

Una ID descubierta no obtiene su propia fila cuando coincide con una fila ya en el selector:

• ID igual: la ID descubierta coincide exactamente con el ID de una fila existente, o los dos ID son ortografías de la misma versión de Fable.
• Mismo modelo que un alias integrado: cuando una ID explícita descubierta nombra el modelo al que un alias integrado se resuelve actualmente, el selector muestra solo la fila de alias. Por ejemplo, mientras sonnet se resuelve a claude-sonnet-5, un claude-sonnet-5 descubierto se colapsa en la fila sonnet, y un claude-sonnet-4-6 descubierto aún obtiene su propia fila. Antes de v2.1.197, Claude Code no plegaba estos ID en filas integradas, por lo que claude-sonnet-5 también obtenía su propia fila "From gateway".

Los resultados se almacenan en caché en ~/.claude/cache/gateway-models.json, o %USERPROFILE%\.claude\cache\gateway-models.json en Windows, y se actualizan en cada inicio. Si establece CLAUDE_CONFIG_DIR, el caché se encuentra bajo ese directorio en su lugar. Si la solicitud falla o la puerta de enlace no implementa /v1/models, el selector vuelve a la lista en caché del inicio anterior o a la lista de modelos integrada. Si su puerta de enlace sirve modelos de Claude bajo alias que no coinciden con el filtro de descubrimiento, los desarrolladores pueden agregar esos alias manualmente con las variables de configuración de modelo.

Recursos relacionados

Para el resto del conjunto de documentación de puerta de enlace y las referencias de API subyacentes:

• Descripción general de puertas de enlace: qué es una puerta de enlace y cómo elegir entre la puerta de enlace de aplicaciones Claude y otro producto
• Otras puertas de enlace LLM: cómo implementar una puerta de enlace que su organización ejecuta y cómo interactúa con suscripciones de claude.ai
• Implementar una puerta de enlace LLM para su organización: la lista de verificación de administrador que utiliza esta guía
• Conectar Claude Code a una puerta de enlace LLM: configuración por desarrollador y la tabla de solución de problemas
• Referencia de encabezados beta: el conjunto actual de valores anthropic-beta
• API de mensajes: el formato de API que implementa una puerta de enlace con formato Anthropic