Tool Integrations29 de junio de 2026Flatkey

Configuración del router de la API de Claude Code: URL base, modelos y registros de uso

La configuración de un router para la API de Claude Code no es lo mismo que cambiar la URL base de un SDK de OpenAI. Claude Code utiliza el formato del gateway de Mensajes de Anthropic, por lo que las comprobaciones importantes son la raíz del router, el encabezado de credenciales, el nombre del modelo que Claude Code enviará y los registros de uso que demuestran que las solicitudes están llegando.

La configuración de un router de la API de Claude Code no es lo mismo que cambiar una URL base del SDK de OpenAI. Claude Code utiliza el formato de la puerta de enlace de mensajes de Anthropic, por lo que las comprobaciones importantes son la raíz del router, el encabezado de las credenciales, el nombre del modelo que enviará Claude Code y los registros de uso que demuestran que las solicitudes están llegando a la cuenta correcta.

Esta guía ofrece una configuración de Flatkey orientada a la producción para desarrolladores, equipos de productos de IA, creadores de automatización, ingenieros de plataforma, operadores financieros y revisores de adquisiciones. Abarca la URL base, la comprobación previa de un solo token, los nombres de los modelos, el descubrimiento de modelos en la puerta de enlace, los registros de uso y los modos de fallo antes de que traslade el trabajo de codificación diario a un router de la API de Claude Code.

Nota sobre la fuente: esto se verificó el 29 de junio de 2026 con la documentación oficial de las puertas de enlace LLM de Claude Code, la guía de conexión de la puerta de enlace de Claude Code, la referencia del protocolo de la puerta de enlace, la documentación de configuración del modelo, la documentación de supervisión y las páginas públicas actuales de Flatkey. No se utilizó ninguna clave de Flatkey específica de una cuenta para una prueba de humo en vivo de Claude Code, por lo que los fragmentos siguientes son plantillas para ejecutar con su propia clave y modelo aprobado.

Respuesta rápida: configuración del router de la API de Claude Code

Para una configuración de un router de la API de Claude Code con Flatkey, configure Claude Code con la raíz del router de Claude Code de Flatkey, una clave de Flatkey y un nombre de modelo de Claude exacto al que su cuenta pueda llamar. A continuación, pruebe el punto de conexión de mensajes de Anthropic antes de abrir una sesión de codificación larga.

Campo de configuración	Valor o comprobación de Flatkey	Por qué es importante
URL base	`https://router.flatkey.ai` para el caso de uso de Claude Code, a menos que su cuenta de Flatkey muestre un valor más reciente específico de Claude Code	Claude Code anexa `/v1/messages`. No pegue una base del SDK de OpenAI que termine en `/v1` a menos que su prueba confirme que no crea `/v1/v1/messages`.
Credencial	`ANTHROPIC_AUTH_TOKEN` para el enrutamiento de token de portador, o `ANTHROPIC_API_KEY` cuando la puerta de enlace espera `x-api-key`	Los documentos oficiales de Claude Code asignan cada variable a un encabezado HTTP diferente. Una clave que funcione en la variable incorrecta seguirá devolviendo `401`.
Comprobación previa del punto de conexión	`$ANTHROPIC_BASE_URL/v1/messages`	La página de precios actual de Flatkey incluye `/v1/messages` en el mapa de puntos de conexión, que es la ruta que Claude Code necesita para el tráfico de mensajes de Anthropic.
Modelo	Utilice un ID de modelo de Claude exacto o un alias de Claude Code que se resuelva en una ruta de Flatkey habilitada	La selección del modelo es independiente del enrutamiento de la URL base. El router decide a dónde va el tráfico; Claude Code sigue enviando un nombre de modelo.
Prueba de uso	Compruebe el uso de Flatkey y la telemetría de Claude Code después de la primera instrucción	Un resultado exitoso no es suficiente. Los equipos necesitan pruebas de clave, modelo, marca de tiempo, sesión, coste y token.

Esa es la versión corta. El resto de esta guía del router de la API de Claude Code convierte esos campos en un manual de configuración repetible.

Lo que confirman los documentos oficiales de la puerta de enlace de Claude Code

La descripción general oficial de la puerta de enlace de Claude Code define una puerta de enlace LLM como un proxy entre Claude Code y un proveedor de modelos. Claude Code envía el tráfico de la API a la puerta de enlace, y la puerta de enlace lo reenvía con una credencial de proveedor controlada por la organización. La misma página enumera los beneficios de la puerta de enlace, como credenciales centralizadas, seguimiento del uso, controles de costes, registro de auditoría y cambio de proveedor.

La regla de la URL base es específica. Normalmente, Claude Code envía las solicitudes a la API de Anthropic, pero al establecer ANTHROPIC_BASE_URL se dirigen esas solicitudes a la puerta de enlace. A continuación, la guía de conexión verifica la ruta publicando en $ANTHROPIC_BASE_URL/v1/messages con anthropic-version: 2023-06-01.

La referencia del protocolo de la puerta de enlace añade los detalles del lado del operador. Para el formato de mensajes de Anthropic, una puerta de enlace seleccionada por ANTHROPIC_BASE_URL debe servir /v1/messages y, opcionalmente, /v1/messages/count_tokens. También dice que las respuestas de inferencia deben transmitirse porque Claude Code consume los eventos enviados por el servidor a medida que llegan.

Para un router de la API de Claude Code, eso significa que debe validar la ruta de mensajes de Anthropic, no solo una ruta de finalización de chat compatible con OpenAI. Una ruta de OpenAI puede funcionar para otras herramientas, mientras que Claude Code seguirá fallando si faltan /v1/messages, la transmisión o los encabezados de Anthropic necesarios.

Valores de Flatkey verificados para esta configuración

La página de inicio de Flatkey, comprobada el 29 de junio de 2026, tiene el título One API gateway for production AI teams y una metadescripción que dice que Flatkey unifica el acceso a los modelos, el enrutamiento, la facturación, el análisis de uso y los controles operativos. La misma página de inicio sigue mostrando ejemplos al estilo de OpenAI que utilizan https://console.flatkey.ai/v1 y /v1/chat/completions, que son útiles para las herramientas compatibles con OpenAI pero no son el patrón de URL base de Claude Code.

La página actual del caso de uso de Claude Code de Flatkey dice que Claude Code se configura con https://router.flatkey.ai y una clave de API de Flatkey. También indica a los usuarios que creen o copien la clave en https://console.flatkey.ai/keys antes de ejecutar el instalador. Utilice esa raíz de router específica de Claude Code para la configuración manual a continuación, a menos que su cuenta de Flatkey le proporcione un valor más reciente.

La página de precios de Flatkey, consultada el 29 de junio de 2026, publica precios renderizados en el servidor para 635 modelos de IA de 23 proveedores. Su mapa de endpoints incluye /v1/messages, /v1/chat/completions, /v1/responses, /v1/images/generations, /v1/video/generations y /v1beta/models/{model}:generateContent. Este artículo considera eso como una evidencia pública anticuada de la cobertura de endpoints, no como una garantía de que cada cuenta pueda llamar a cada modelo.

Configuración paso a paso con Flatkey

Cree o elija una clave de Flatkey. Use una clave que pertenezca a la persona, equipo o entorno correcto. Manténgala fuera de capturas de pantalla, prompts, repositorios y comentarios de incidencias.
Comience con exportaciones de shell. No guarde la configuración de forma persistente hasta que la comprobación previa (preflight) de un solo token funcione.
Use la raíz del router de Claude Code. Para la página actual de Claude Code de Flatkey, ese valor es https://router.flatkey.ai.
Elija la variable de credencial. Use ANTHROPIC_AUTH_TOKEN cuando la clave deba enviarse como Authorization: Bearer. Use ANTHROPIC_API_KEY solo cuando el gateway espere x-api-key.
Establezca un modelo para la primera prueba. Use un ID de modelo de Claude actual que esté habilitado para su cuenta de Flatkey. Si el modelo no es visible en el selector de Claude Code, use el descubrimiento del gateway o agregue una opción de modelo personalizado después de que la comprobación previa funcione.
Ejecute la comprobación previa (preflight) con curl. Una solicitud de un solo token separa el enrutamiento de Flatkey del estado de la interfaz de usuario de Claude Code.
Inicie Claude Code desde el mismo shell. Esto hace que la CLI herede las variables que acaba de probar.
Ejecute /status. Confirme que la línea de la URL base de Anthropic muestre el router de Flatkey y que la línea de la credencial nombre la variable que estableció.
Envíe un prompt pequeño. Luego, verifique el uso de Flatkey y cualquier telemetría de Claude Code que haya habilitado.

Configuración del shell

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_AUTH_TOKEN="fk_replace_with_your_flatkey_key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"

Si las instrucciones de su gateway dicen explícitamente x-api-key, cambie ANTHROPIC_AUTH_TOKEN por ANTHROPIC_API_KEY y actualice el encabezado de la comprobación previa. No establezca ambas para la primera prueba; las fuentes de credenciales mixtas hacen que los fallos sean más difíciles de aislar.

Configuración persistente después de que la prueba sea exitosa

Después de que la prueba del shell funcione, puede colocar las mismas variables en el bloque env de ~/.claude/settings.json. No ponga credenciales en un archivo .claude/settings.json de un proyecto versionado.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
    "ANTHROPIC_AUTH_TOKEN": "fk_replace_with_your_flatkey_key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

Realice una comprobación previa (preflight) de la ruta Messages antes de iniciar Claude Code

La comprobación más rápida del router de la API de Claude Code es una solicitud de Messages de un solo token. Si esto falla, corrija la clave de Flatkey, la URL base, la ruta de red o el modelo antes de cambiar la configuración de Claude Code.

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1,
    "messages": [
      {"role": "user", "content": "."}
    ]
  }'

Una respuesta JSON que comience con un ID de mensaje e incluya un campo de contenido significa que la ruta y la credencial están funcionando. La documentación oficial también señala que un error de modelo desconocido demuestra que el gateway autenticó la solicitud antes de rechazar el nombre del modelo. Un 401 significa que la credencial fue rechazada o enviada en el encabezado incorrecto.

Observe atentamente la URL resuelta. Con ANTHROPIC_BASE_URL=https://router.flatkey.ai, la prueba llega a https://router.flatkey.ai/v1/messages. Si su comando crea /v1/v1/messages, ha copiado una URL base del SDK de cliente en un campo de gateway de Claude Code.

Nombres de modelos: alias, descubrimiento y entradas personalizadas

Los nombres de los modelos son la segunda fuente común de fallos del router de la API de Claude Code. La URL base envía el tráfico a Flatkey, pero Claude Code aún necesita un valor de modelo para enviar en la solicitud.

La documentación de configuración de modelos dice que Claude Code admite configuraciones de modelos integradas como default, best, sonnet, opus, haiku y variantes de contexto largo como sonnet[1m] y opus[1m]. La misma documentación dice que ANTHROPIC_MODEL se aplica solo a la sesión que se inicia con él, mientras que /model puede guardar una elección interactiva para sesiones posteriores.

Para una ruta de Flatkey, la regla segura es comenzar con un ID de modelo de Claude completo que Flatkey haya habilitado para su clave, y luego decidir si exponerlo en el selector. No asuma que un nombre de familia genérico, una etiqueta de marketing o el título de una fila de proveedor se aceptan como el ID del modelo en la solicitud.

Necesidad de configuración del modelo	Mecanismo de Claude Code	Verificación de Flatkey
Prueba de una sola sesión	`ANTHROPIC_MODEL` o `claude --model`	Usa un ID de modelo de Claude habilitado para Flatkey y mantén la prueba pequeña.
Selección interactiva	`/model`	Confirma que el nombre seleccionado es el ID real que Flatkey espera.
Lista de modelos proporcionada por la puerta de enlace	`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`	La puerta de enlace debe servir `/v1/models` rápidamente en la URL base configurada.
Entrada manual en el selector	`ANTHROPIC_CUSTOM_MODEL_OPTION`	Usa esto cuando el descubrimiento esté deshabilitado o no devuelva el modelo que necesitas.
Respaldo de disponibilidad	`--fallback-model` o `fallbackModel`	El respaldo no soluciona errores de autenticación, facturación, límite de velocidad, tamaño de solicitud o transporte.

Descubrimiento de modelos de la puerta de enlace

Claude Code puede consultar el punto de conexión /v1/models de una puerta de enlace al inicio cuando ANTHROPIC_BASE_URL apunta a una puerta de enlace de Anthropic Messages y el descubrimiento está habilitado. Los documentos del protocolo dicen que la solicitud es GET /v1/models?limit=1000 con un tiempo de espera de 3 segundos, y Claude Code lee el id más el display_name opcional de la respuesta.

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude --debug

El descubrimiento está desactivado por defecto para que una clave compartida no exponga todos los modelos accesibles a todos los usuarios. Si el descubrimiento falla, Claude Code recurre al selector almacenado en caché o integrado. Si tu cuenta de Flatkey sirve un modelo bajo un alias que el descubrimiento no muestra, añade una opción personalizada en su lugar.

Opción de modelo personalizado

export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-sonnet-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet via Flatkey"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Claude model routed through the Flatkey API router"

La opción de modelo personalizado omite la validación del lado del cliente para ese ID de modelo, por lo que es útil para un piloto controlado. No sustituye a la solicitud de pre-vuelo (preflight). Si hay una lista de permitidos de la organización activa, incluye también el ID del modelo personalizado allí.

Registros de uso: qué verificar después de la primera instrucción

Una configuración fiable del enrutador de la API de Claude Code termina con una evidencia de uso, no solo con una respuesta exitosa. El posicionamiento público de Flatkey dice que unifica la facturación, el análisis de uso y los controles operativos; los documentos de la puerta de enlace de Claude Code también enmarcan el seguimiento del uso y los controles de costos como beneficios de la puerta de enlace. Usa ambas capas intencionadamente.

Fuente del registro	Qué inspeccionar	Por qué es importante
Uso de Flatkey	Propietario de la clave, marca de tiempo, modelo, familia de puntos de conexión, uso de tokens y registro de costos donde esté disponible	Confirma que la solicitud llegó a la cuenta de la puerta de enlace prevista y puede ser conciliada por operaciones o finanzas.
Claude Code `/status`	URL base de Anthropic y fuente de credenciales activa	Confirma que la sesión en ejecución está utilizando la ruta de Flatkey en lugar de un inicio de sesión guardado de claude.ai.
Métricas de OpenTelemetry	`claude_code.cost.usage`, `claude_code.token.usage`, recuento de sesiones, tiempo activo y punto de entrada	Crea observabilidad a nivel de equipo para las sesiones de Claude Code.
Registros/eventos de OpenTelemetry	Eventos de instrucción, resultados de herramientas, errores de la API y campos de costo cuando están configurados	Ayuda a depurar fallos a nivel de solicitud, pero debe ser controlado porque los registros detallados pueden exponer contenido sensible.
Encabezados de la puerta de enlace	`x-claude-code-session-id`, ID de agente y encabezados de enrutamiento personalizados	Permite agrupar solicitudes por sesión o subagente sin analizar los cuerpos completos de las solicitudes.

Para la telemetría de Claude Code, habilita OpenTelemetry solo con una configuración de privacidad deliberada. Los documentos de monitoreo dicen que el texto de la instrucción se redacta por defecto, mientras que configuraciones como OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 y OTEL_LOG_RAW_API_BODIES añaden detalles sensibles. Mantén el registro del cuerpo sin procesar fuera de la configuración de desarrollador predeterminada a menos que tu revisión de seguridad lo apruebe.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Usa OTEL_RESOURCE_ATTRIBUTES para campos de propiedad de baja cardinalidad como departamento, ID de equipo o centro de costos. Evita los nombres de proyecto o los ID de ticket introducidos por el usuario como etiquetas a menos que tu backend de observabilidad pueda manejar la cardinalidad y el impacto en la privacidad.

Modos de fallo que depurar primero

Síntoma	Causa probable	Primera solución
`401` o token no válido	La clave fue rechazada, expiró, se copió en la variable incorrecta o se envió en un encabezado que el gateway no lee.	Cambie entre `ANTHROPIC_AUTH_TOKEN` y `ANTHROPIC_API_KEY` solo después de confirmar qué encabezado espera Flatkey.
Conexión rechazada o tiempo de espera agotado	URL base incorrecta, ruta de red bloqueada, problema de VPN o un punto final del router que no es accesible desde la máquina del desarrollador.	Ejecute la comprobación previa de curl y verifique la URL con las instrucciones de su cuenta de Flatkey.
Respuesta malformada con HTTP 200	Un proxy o una página de inicio de sesión devolvió HTML en lugar de JSON de la API.	Inspeccione el cuerpo de la respuesta de la comprobación previa y corrija la ruta del gateway que devuelve algo que no es JSON.
`400` que nombra `context_management` o campos adicionales	El gateway reenvió campos de solicitud en formato Anthropic a un upstream que los rechaza.	Reenvíe el par de encabezado/cuerpo beta correctamente o establezca `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` como una mitigación temporal.
`400` que nombra `thinking` o `adaptive`	La compilación del modelo upstream no acepta el razonamiento adaptativo solicitado para los modelos más nuevos de Claude.	Actualice la ruta upstream o use el indicador de desactivación de pensamiento adaptativo documentado solo donde corresponda.
Falta el modelo en `/model`	El modelo no está en el selector integrado de Claude Code y el descubrimiento está deshabilitado o falla.	Habilite el descubrimiento de modelos del gateway o agregue `ANTHROPIC_CUSTOM_MODEL_OPTION`.
Claude Code solicita iniciar sesión después de que curl tenga éxito	La CLI no recibió una credencial donde la configuración de la primera ejecución pueda leerla.	Establezca la credencial en el shell, `~/.claude/settings.json`, o en la configuración administrada antes del inicio.
El uso no se puede conciliar	La configuración carece del propietario de la clave, el nombre del modelo, el entorno, el ID de sesión o las etiquetas de telemetría.	Agregue una fila al runbook antes de que más desarrolladores usen la ruta.

Lista de verificación de producción para equipos

Antes de estandarizar un router de la API de Claude Code en un equipo, registre los datos operativos que necesitará una futura revisión de incidentes o financiera.

Elemento de la lista de verificación	Registre esto
URL base	El valor exacto guardado en el shell, la configuración administrada, la configuración de VS Code, CI o la configuración del SDK del agente.
Fuente de la credencial	Propietario de la clave de Flatkey, entorno, propietario de la rotación y si es estática o proviene de un `apiKeyHelper`.
Nombres de los modelos	ID del modelo solicitado, etiqueta del selector, cadena de respaldo, regla de la lista de permitidos y fecha de prueba.
Prueba del punto final	Resultado de `/v1/messages` de un solo token, marca de tiempo de la solicitud y cualquier ID de solicitud devuelto por el gateway.
Revisión del uso	Vista de uso de Flatkey, backend de telemetría de Claude Code, etiquetas y propietario del panel de control.
Controles de privacidad	Si se permiten prompts, detalles de herramientas, cuerpos de API sin procesar o contenido de herramientas en la telemetría.
Reversión	Inicio de sesión anterior de Claude Code o ruta del proveedor, modelo anterior y quién puede desconfigurar las variables del gateway.

Ruta de migración interna

Si Flatkey se está convirtiendo en la ruta compartida para múltiples herramientas de desarrollador, mantenga la configuración de Claude Code alineada con el resto del clúster de integración. Utilice la guía de migración de la API compatible con OpenAI para los patrones de URL base del SDK, pero recuerde que Claude Code utiliza la ruta de mensajes de Anthropic en lugar de /v1/chat/completions.

Para la configuración del cliente de escritorio, compare la guía de configuración de la API de Cherry Studio. Para los patrones de enrutamiento de la máquina del desarrollador adyacentes a Claude Code, consulte la configuración de cc-switch para Claude Code. Después de que el primer prompt funcione, revise los precios de los modelos de Flatkey y, a continuación, obtenga una clave para cualquier entorno adicional que necesite un límite de credenciales independiente.

Preguntas frecuentes

¿Qué URL base debo usar para un router de la API de Claude Code con Flatkey?

Utilice la raíz del router de Flatkey específica para Claude Code que se muestra para su cuenta. El 29 de junio de 2026, la página del caso de uso de Claude Code de Flatkey indicaba que Claude Code se configura con https://router.flatkey.ai. La comprobación previa debe llegar exactamente a una ruta /v1/messages.

¿Debo usar `ANTHROPIC_AUTH_TOKEN` o `ANTHROPIC_API_KEY`?

Use ANTHROPIC_AUTH_TOKEN cuando el gateway espere un token de portador (bearer token) en el encabezado Authorization. Use ANTHROPIC_API_KEY cuando espere x-api-key. Si ha adivinado y obtiene un 401, cambie las variables y vuelva a probar.

¿Puedo usar una URL base de Flatkey compatible con OpenAI para Claude Code?

No directamente como un campo copiado. Las herramientas compatibles con OpenAI a menudo usan una URL base que termina en /v1, mientras que Claude Code anexa /v1/messages a ANTHROPIC_BASE_URL. Utilice el valor del router de Claude Code de Flatkey y verifique la URL final.

¿Cómo agrego modelos de Flatkey al selector de modelos de Claude Code?

Habilite CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 cuando la puerta de enlace sirva /v1/models, o agregue una fila de selector manual con ANTHROPIC_CUSTOM_MODEL_OPTION. En ambos casos, confirme que el ID de modelo exacto esté habilitado para su clave de Flatkey.

¿Qué registros de uso debo verificar después de la configuración?

Verifique el uso de Flatkey para la clave, el modelo, la familia de puntos de conexión, la marca de tiempo, los tokens y el costo donde esté disponible. Utilice también /status de Claude Code y las métricas de OpenTelemetry como claude_code.cost.usage y claude_code.token.usage cuando la telemetría de la organización esté habilitada.

Conclusión

Una configuración fiable del router de la API de Claude Code tiene cuatro puntos de prueba: la URL base de Claude Code de Flatkey, el encabezado de credenciales correcto, un nombre de modelo probado y un rastro de uso que los equipos de finanzas y plataforma puedan revisar. Comience con una comprobación previa de /v1/messages de un solo token, confirme /status y, a continuación, escale la ruta solo después de que se documenten los registros y la reversión. Cuando esté listo para enrutar Claude Code a través de una puerta de enlace compartida, obtenga una clave y pruebe primero con la indicación más pequeña.