Saltar al contenido principal

Requisitos previos

Antes de configurar Claude Code con Microsoft Foundry, asegúrese de que tiene:
  • Una suscripción de Azure con acceso a Microsoft Foundry
  • Permisos RBAC para crear recursos e implementaciones de Microsoft Foundry
  • Azure CLI instalado y configurado (opcional - solo necesario si no tiene otro mecanismo para obtener credenciales)
Si está implementando Claude Code para múltiples usuarios, fije las versiones de su modelo antes de implementar.

Configuración

  1. Aprovisionar recurso de Microsoft Foundry

Primero, crea un recurso de Claude en Azure:
  1. Ve al portal de Microsoft Foundry
  2. Crea un nuevo recurso y anota el nombre de tu recurso
  3. Crea despliegues para los modelos de Claude y anota el nombre de despliegue que asignes a cada uno; establecerás estos nombres como las variables de modelo en el paso 4:
    • Claude Opus
    • Claude Sonnet
    • Claude Haiku
    Cuando configuras un despliegue, también eliges su opción de alojamiento, que determina si la inferencia se ejecuta en Azure o en la infraestructura de Anthropic.

  1. Configurar credenciales de Azure

Claude Code admite tres métodos de autenticación para Microsoft Foundry. Elige el método que mejor se ajuste a tus requisitos de seguridad:
  • Clave de API: copias una clave del portal de Microsoft Foundry y la estableces como ANTHROPIC_FOUNDRY_API_KEY
  • Microsoft Entra ID: Claude Code obtiene tokens a través de la cadena de credenciales predeterminada del SDK de Azure, por ejemplo, desde una sesión de az login, por lo que no hay ninguna clave de API que almacenar
  • Token portador: otro proceso obtiene un token de acceso de Microsoft Entra ID y tú lo pasas en ANTHROPIC_FOUNDRY_AUTH_TOKEN
Cuando se usa Microsoft Foundry, el comando /logout no está disponible ya que la autenticación se maneja a través de credenciales de Azure.

Usar una clave de API

Copia una clave del portal de Microsoft Foundry y luego establécela como variable de entorno:
  1. Ve a tu recurso en el portal de Microsoft Foundry
  2. Abre la sección Endpoints and keys
  3. Copia API Key
  4. Establece la variable de entorno, reemplazando your-azure-api-key con la clave que copiaste:

Usar Microsoft Entra ID

Deja ANTHROPIC_FOUNDRY_API_KEY y ANTHROPIC_FOUNDRY_AUTH_TOKEN sin configurar. Así, Claude Code utiliza la cadena de credenciales predeterminada del SDK de Azure. Esto admite una variedad de métodos para autenticar cargas de trabajo locales y remotas. En una máquina local, inicia sesión con Azure CLI:
Para conocer los roles que necesita tu identidad, consulta Configuración de Azure RBAC.

Usar un token portador

Claude Code envía el valor de ANTHROPIC_FOUNDRY_AUTH_TOKEN en cada solicitud como el encabezado Authorization: Bearer. Usa esta opción cuando otro proceso, como una aplicación host o un script de inicio de sesión, ya haya obtenido un token de acceso para ti. Establece la variable en un token portador que Microsoft Entra ID emitió para tu recurso:
ANTHROPIC_FOUNDRY_AUTH_TOKEN tiene prioridad sobre ANTHROPIC_FOUNDRY_API_KEY y sobre la cadena de credenciales predeterminada.

  1. Configurar Claude Code

Establece las siguientes variables de entorno para habilitar Microsoft Foundry:
Establece ANTHROPIC_FOUNDRY_RESOURCE solo con el nombre del recurso, como my-resource. Claude Code rechaza una URL o un nombre de host cuando envías un mensaje.

  1. Fijar versiones de modelo

Fija versiones de modelo específicas para cada despliegue. Sin fijar, los alias de modelo como sonnet y opus se resuelven al valor predeterminado integrado de Claude Code para Microsoft Foundry, que puede estar rezagado con respecto a la versión más reciente y es posible que aún no esté disponible en tu cuenta. Microsoft Foundry no tiene verificación de modelo de inicio, por lo que las solicitudes fallan cuando el valor predeterminado no está disponible. Cuando crees despliegues de Azure, selecciona una versión de modelo específica en lugar de “actualizar automáticamente a la última”.
Establece las variables de modelo para que coincidan con los nombres de despliegue que creaste en el paso 1. Sin ANTHROPIC_DEFAULT_OPUS_MODEL, el alias opus en Microsoft Foundry se resuelve a Opus 4.6. Establécelo en el ID de un modelo Opus más reciente, como Opus 4.8:
Las tareas en segundo plano, como la generación de títulos de sesión, utilizan el modelo pequeño/rápido, normalmente un modelo de clase Haiku. En Microsoft Foundry, Claude Code establece por defecto esto al modelo principal porque no todas las cuentas tienen un despliegue de Haiku. Para usar Haiku para tareas en segundo plano, establece ANTHROPIC_DEFAULT_HAIKU_MODEL en un despliegue de Haiku que esté disponible en tu cuenta, como se muestra arriba. Para los ID de modelos actuales y heredados, consulta Descripción general de modelos. Consulta Configuración de modelo para la lista completa de variables de entorno. La caché de prompts está habilitada automáticamente. Para solicitar un TTL de caché de 1 hora en lugar del predeterminado de 5 minutos, establece la siguiente variable; las escrituras de caché con un TTL de 1 hora se facturan a una tasa más alta:
Para establecer diferentes TTL para tu conversación principal y para las solicitudes que Claude Code realiza fuera de ella, elige el TTL tú mismo.

  1. Ejecutar Claude Code

Con las variables de entorno configuradas, inicia Claude Code desde tu directorio de proyecto:
Claude Code lee CLAUDE_CODE_USE_FOUNDRY y las otras variables de Microsoft Foundry del entorno y se conecta a tu recurso de Azure en el primer prompt. A diferencia de Amazon Bedrock y Google Cloud’s Agent Platform, Microsoft Foundry no tiene un asistente de configuración interactivo, por lo que las variables de entorno en los pasos 3 y 4 son la única ruta de configuración. Para verificar tu configuración, ejecuta /status dentro de Claude Code. La línea del proveedor de API muestra Microsoft Foundry, junto con el nombre del recurso o la URL base que configuraste.

Configuración de RBAC de Azure

Si te autenticas con Microsoft Entra ID o con un token de portador emitido por este, asigna a tu identidad el rol Foundry User o Cognitive Services User en tu recurso de Foundry. Es posible que todavía veas Foundry User con su nombre anterior, Azure AI User. Si estos roles no satisfacen tus necesidades, consulta la documentación de RBAC de Microsoft Foundry para conocer los roles personalizados.

Ventana de contexto de 1M tokens

En Microsoft Foundry, cuando Claude Code puede identificar qué modelo sirve tu despliegue, los modelos Fable, Sonnet 5 y posteriores, y Opus 4.7 y posteriores se ejecutan con la ventana de contexto de 1M tokens de forma predeterminada, sin necesidad del sufijo [1m]. Claude Code lee el modelo a partir del nombre del despliegue en tus variables de modelo. Nombra cada despliegue con su ID de modelo, como claude-opus-4-8, o asigna el modelo al nombre de tu despliegue con modelOverrides. Para un nombre de despliegue que no puede asociar a un modelo, Claude Code asume una ventana de 200K a menos que declares una diferente. Esta entrada de settings.json le indica a Claude Code que un despliegue llamado team-opus-prod sirve Opus 4.8:
Para mantener en su lugar una ventana de 200K, establece CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Opus 4.6 y Sonnet 4.6 alcanzan la ventana de 1M cuando agregas [1m] al nombre del despliegue en ANTHROPIC_DEFAULT_OPUS_MODEL o ANTHROPIC_DEFAULT_SONNET_MODEL, como se describe en Fijar modelos para despliegues de terceros. Antes de la v2.1.287, los modelos Fable y Opus 4.7 y posteriores también necesitaban ese sufijo en Microsoft Foundry y, sin él, se ejecutaban con una ventana de 200K de forma predeterminada.

Solución de problemas

Si recibe un error “Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed”:
  • Configure Entra ID en el entorno, o establezca ANTHROPIC_FOUNDRY_API_KEY.
Si las solicitudes fallan con errores de conexión repetidos en el primer mensaje:
  • Verifique que ANTHROPIC_FOUNDRY_RESOURCE esté configurado con el nombre de recurso real en lugar de un marcador de posición. Claude Code construye la URL del punto de conexión a partir de este valor, por lo que un nombre incorrecto apunta a un host que no existe.

Recursos adicionales