Configuración de Claude Code API: claves, settings.json, modelos y gateways

Para configurar Claude Code con una clave de la API de Anthropic, define ANTHROPIC_API_KEY en el entorno desde el que vas a iniciarlo, ejecuta claude y aprueba el uso de esa clave cuando te lo pregunte. Comprueba después /status. Si usas un gateway, necesitas su URL, una credencial con el esquema que acepte y un modelo disponible allí; cambiar solo ANTHROPIC_BASE_URL no cambia automáticamente la autenticación ni la facturación. Estas condiciones están en la documentación de autenticación y la guía de gateways.

La guía parte de que tienes Claude Code instalado y acceso autorizado al servicio elegido. Los ejemplos de terminal son para Bash en macOS o Linux; los archivos JSON ilustran la configuración, sin claves reales. Los comandos de Claude Code y las solicitudes descritas proceden de su documentación: no se han ejecutado llamadas de pago para esta actualización.

Qué acceso debes configurar

Elige primero dónde debe ir la petición y con qué credencial. Tener una suscripción, una clave API y credenciales de AWS en el mismo equipo no convierte esos accesos en uno solo.

Las opciones de Console y del gateway corporativo merecen atención. Desde Claude Code v2.1.242, Console puede autenticar mediante un perfil OAuth sin que crees una clave API; esa vía requiere que ANTHROPIC_API_KEY no esté definida y sustituye el inicio de sesión de claude.ai guardado. En entornos administrados se aplican requisitos adicionales, incluido el soporte desde v2.1.257. No cambies de cuenta siguiendo un ejemplo de clave si tu organización te ha asignado este perfil. El gateway de Claude apps con SSO tiene su propio flujo y puede imponerse incluso sobre un proveedor cloud seleccionado. Consulta las condiciones de autenticación.

Configurar una clave API en el terminal

Con una clave ya emitida y autorizada para la API directa de Anthropic, puedes probar primero una sesión temporal de Bash. Antes, confirma que no estás dentro de un entorno administrado que exija otro acceso y que no hay un token o proveedor seleccionado que deba tener prioridad.

Introduce la clave sin mostrarla en pantalla ni escribirla como texto literal en el historial:

IFS= read -r -s -p 'Clave API de Anthropic: ' ANTHROPIC_API_KEY
printf '\n'
export ANTHROPIC_API_KEY
claude

Cuando Claude Code detecta la clave por primera vez en modo interactivo, solicita aprobación. Aceptar activa la clave; rechazar permite conservar el inicio de sesión que corresponda. La decisión queda recordada y se puede cambiar en /config, con la opción Use custom API key. En modo no interactivo claude -p, una ANTHROPIC_API_KEY presente se utiliza sin esa aprobación interactiva, siempre dentro de las condiciones de prioridad y política. Por eso no conviene copiar una prueba interactiva a un trabajo automatizado dando por hecho que conservará la suscripción. Reglas de la clave y aprobación.

Dentro de la sesión, ejecuta:

/status

El método activo debe coincidir con la clave o acceso que has elegido. Que una variable exista no demuestra que haya ganado: puede haber un bearer token, un proveedor seleccionado o una configuración corporativa por delante. Una vez confirmado el acceso, envía una petición breve que hayas autorizado, por ejemplo «Responde únicamente OK, sin usar herramientas». Una respuesta confirma que esa sesión ha podido obtener una inferencia; para identificar quién la cobra, comprueba también el proyecto y el registro de uso correspondiente en Console.

La variable exportada se transmite a los procesos que arrancas desde esa terminal. Para mantener la configuración entre sesiones, utiliza el mecanismo de secretos de tu entorno o un helper aprobado; no pongas la clave en un archivo compartido del repositorio. Tampoco presupongas que una aplicación abierta desde el Dock recibe lo que acabas de exportar en Bash. La ayuda en español sobre variables de entorno explica el alcance temporal y persistente; la documentación actual de autenticación añade las condiciones de aprobación y perfiles.

Qué credencial gana si tienes varias

En el flujo ordinario del CLI, las credenciales de Bedrock, Google Cloud o Foundry participan cuando está activado su selector. Después están ANTHROPIC_AUTH_TOKEN, la clave ANTHROPIC_API_KEY aplicable, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, los perfiles y el inicio de sesión de suscripción. Los perfiles tienen sus propias condiciones de selección, y el gateway de Claude apps con SSO queda fuera de esta secuencia. Una política administrada también puede restringir proveedores o métodos de inicio de sesión. Orden y excepciones actuales.

Para revisar solo la presencia de las dos variables más habituales en Bash, sin mostrar valores:

for nombre in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN; do
  if [ -n "${!nombre}" ]; then
    printf '%s: definida\n' "$nombre"
  else
    printf '%s: no definida\n' "$nombre"
  fi
done

Esta comprobación describe la shell, no los valores que aportará un archivo de configuración al proceso. Si quieres volver a tu inicio de sesión y has identificado una clave temporal que sobra, unset ANTHROPIC_API_KEY la retira de esa shell; si vuelve al abrir otra terminal, revisa el lugar concreto que la define. Evita borrar perfiles enteros o cerrar sesión antes de saber qué credencial está interviniendo.

Dónde va settings.json y qué alcance tiene

Los archivos de configuración sirven para separar preferencias personales, ajustes del proyecto y política de la organización. Usa JSON estricto: sin comentarios ni comas finales. Un archivo no aparece necesariamente al instalar Claude Code; créalo solo en el alcance que necesitas. Archivos y precedencia de settings.

Para un mismo ajuste, el orden habitual es administrado → línea de comandos → proyecto local → proyecto compartido → usuario. Las listas pueden combinarse y hay excepciones para restricciones y ciertos campos de modelo: no interpretes la tabla como «el archivo superior sustituye todo el inferior». Las variables de entorno tampoco son un sexto alcance; cada una tiene su comportamiento documentado.

Por ejemplo, si quieres un modelo predeterminado para tus proyectos, este es un archivo de usuario completo y válido:

{
  "model": "sonnet"
}

El alias debe estar disponible en tu acceso. El ajuste local o compartido del proyecto puede establecer otro valor, y ANTHROPIC_MODEL o --model pueden cambiar el modelo al arrancar. Para un gateway, env permite aportar variables al proceso:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com"
  }
}

Esta URL es de ejemplo: sustituye el valor por el endpoint autorizado. Si la misma variable aparece en la shell y en env de settings, se aplica el valor del archivo. Para resolver un destino equivocado, revisa ambos lugares. Un export nuevo no corrige un ANTHROPIC_BASE_URL distinto que el archivo siga imponiendo. Configuración del entorno para gateways.

Claude Code ignora en Git un settings.local.json que él crea; si lo creas tú, debes asegurarte de excluirlo. Estar excluido de Git evita una incorporación accidental, pero no convierte el archivo en un almacén seguro de secretos. En un proyecto Git, los ajustes locales pueden resolverse desde la raíz o el worktree principal según las reglas documentadas, no necesariamente desde cada subdirectorio. Los ajustes compartidos que permiten acciones o aportan env también dependen de la confianza concedida al proyecto. Alcance, confianza y worktrees.

Cómo usar apiKeyHelper

apiKeyHelper configura un comando que obtiene la credencial desde el mecanismo autorizado por tu equipo. Un ejemplo de configuración, si ese ejecutable ya existe, es:

{
  "apiKeyHelper": "/ruta/absoluta/helper-aprobado"
}

La ruta es ilustrativa: necesitas un helper real que devuelva la credencial esperada. Claude Code envía su resultado como X-Api-Key y como bearer, por lo que debes comprobar que el gateway admite ese comportamiento. No es intercambiable con cualquier script que imprima diagnósticos. Un ANTHROPIC_AUTH_TOKEN o una clave API aplicable tienen prioridad sobre el helper; si acabas de cambiarlo y no parece usarse, revisa esas variables antes de modificar el programa. Helper y encabezados.

Elegir un modelo y saber si se guarda

Usa /model para elegir el modelo desde la sesión. En el comportamiento actual, seleccionar con Intro o escribir /model seguido del nombre guarda el modelo predeterminado de usuario. Si solo quieres probarlo durante esa sesión, utiliza la tecla s del selector. Esto evita que una elección de prueba cambie el siguiente arranque. Selección y persistencia del modelo.

Para arrancar con un modelo sin guardar ese cambio como preferencia de usuario:

claude --model sonnet

La prioridad documentada es la elección actual con /model, seguida de --model, ANTHROPIC_MODEL, el campo model de settings y, como respaldo inferior, ANTHROPIC_DEFAULT_MODEL. El model administrado puede establecer el valor inicial; la restricción de selección se configura con availableModels. No confundir un modelo inicial con una lista de modelos permitidos.

Un alias como sonnet se resuelve según el proveedor y la versión, y no garantiza que tu cuenta tenga acceso. Para fijar el destino exacto, usa el identificador admitido por ese servicio: ID de la API de Anthropic, identificador o ARN de perfil de inferencia en Bedrock, nombre de modelo de Google o nombre de despliegue en Foundry. ANTHROPIC_BASE_URL cambia el servidor, no traduce el nombre del modelo. Evita mantener IDs históricos copiados de otra plataforma. Nombres de modelo por proveedor.

Configurar un gateway compatible

Pide al administrador o proveedor tres datos: URL base, esquema de autenticación y nombre de modelo. Que un servicio anuncie compatibilidad con una API de chat no prueba que soporte Claude Code: debe aceptar uno de los formatos documentados, como Anthropic Messages, y conservar las capacidades y encabezados que necesita el cliente. Requisitos de protocolo.

Para un gateway que acepte bearer tokens, este ejemplo de Bash configura una sesión temporal. Antes de ejecutarlo, asegúrate de que el env de settings no impone otra URL y de que no hay un proveedor cloud o gateway corporativo que deba prevalecer:

export ANTHROPIC_BASE_URL='https://gateway.example.com'
IFS= read -r -s -p 'Token del gateway: ' ANTHROPIC_AUTH_TOKEN
printf '\n'
export ANTHROPIC_AUTH_TOKEN
claude --model 'modelo-habilitado-en-el-gateway'

Sustituye la URL y el modelo por los datos reales. Si el servicio exige x-api-key, define ANTHROPIC_API_KEY con su credencial en lugar del bearer y comprueba que no queda un ANTHROPIC_AUTH_TOKEN que gane por prioridad. No mezcles los dos esquemas esperando que el servidor elija el correcto. Conectar un gateway.

Cambiar solo la URL conserva la autenticación de inicio de sesión cuando esa sigue activa; no convierte una suscripción en una clave API. En ese caso el gateway necesita poder reenviar las capacidades OAuth correspondientes. Cuando se usa una credencial del gateway, el inicio de sesión guardado puede conservarse, pero no es la credencial enviada para esas peticiones. El responsable de la clave upstream y su servicio determinan la facturación: la URL por sí sola no la demuestra. Acceso y facturación a través de gateways.

Si administras el gateway, comprueba /v1/messages y el reenvío de los encabezados anthropic-version y anthropic-beta que correspondan, sin reducir las betas a una lista antigua. La ruta de conteo de tokens es opcional según el protocolo. Una respuesta a la petición de calentamiento HEAD /api/hello no prueba que funcione la inferencia. Tampoco cualquier 404 con un modelo inventado demuestra que la credencial sea válida: el servidor puede comprobar el modelo antes de autenticar. La prueba útil utiliza una credencial y un modelo autorizados y obtiene una respuesta real. Compatibilidad y comprobación.

Si recibes un 400 por un rol no admitido, revisa cómo corregir el formato de los mensajes sin perder las instrucciones del sistema.

Bedrock, Google Cloud y Foundry: sus propios campos

Estos accesos necesitan recursos y permisos del proveedor antes de configurar Claude Code. Una clave de Anthropic no sustituye la autenticación cloud. Los siguientes valores son ejemplos de arranque, no instrucciones para crear cuentas o conceder permisos.

Ejemplo de arranque para un perfil AWS ya configurado y con el modelo habilitado:

CLAUDE_CODE_USE_BEDROCK=1 AWS_PROFILE='perfil-autorizado' \
  AWS_REGION='region-del-modelo' claude --model 'id-o-arn-del-modelo'

La región usada para el inicio de sesión SSO no tiene por qué ser la región del modelo. Configuración de Bedrock.

Para un proyecto Google ya preparado y con credenciales compatibles disponibles:

CLAUDE_CODE_USE_VERTEX=1 CLOUD_ML_REGION='region-compatible' \
  ANTHROPIC_VERTEX_PROJECT_ID='proyecto-autorizado' \
  claude --model 'nombre-del-modelo-en-google'

El proyecto de la petición es el de ANTHROPIC_VERTEX_PROJECT_ID; no se deduce del proyecto que emitió la credencial. Usa una región admitida por ese modelo, no global por costumbre. Configuración de Google Cloud.

Para un recurso Foundry existente accesible con la cadena de credenciales de Azure:

CLAUDE_CODE_USE_FOUNDRY=1 ANTHROPIC_FOUNDRY_RESOURCE='nombre-del-recurso' \
  claude --model 'nombre-del-despliegue'

También se puede configurar la URL completa del recurso. En Foundry, el token configurado tiene prioridad sobre la clave y esta sobre la cadena de credenciales predeterminada. No hay una comprobación del modelo al iniciar que garantice su existencia: un despliegue equivocado puede fallar en la primera petición. Configuración de Foundry.

Por qué funciona en el terminal pero no en VS Code o Desktop

Comprueba el cliente que va a enviar la petición. Un terminal integrado con la variable correcta no demuestra que la extensión haya superado su propia comprobación de credenciales.

• Extensión de VS Code: para gateways, la comprobación previa de la extensión lee claudeCode.environmentVariables en la configuración de usuario de VS Code. El bloque env de ~/.claude/settings.json llega al proceso que inicia, pero no basta para esa comprobación previa de la extensión.
• Claude Desktop con inferencia de terceros: requiere su configuración ThirdPartyInference; no se configura trasladando sin más ANTHROPIC_BASE_URL o el archivo de settings del CLI. La configuración administrada tiene prioridad. El gateway local no se aplica a sesiones SSH, cloud o Remote Control.
• Sesiones cloud: usan el acceso previsto para ese entorno; las variables de API key o bearer del CLI local no sustituyen su autenticación de suscripción.

Son diferencias documentadas de conexión desde cada cliente y autenticación, no señales de que debas borrar la sesión guardada. Consulta el apartado específico del cliente antes de mover secretos a otro archivo.

Comprobar la configuración y resolver ajustes que no se aplican

La comprobación tiene tres resultados distintos: el archivo se carga, la petición obtiene respuesta y el uso aparece en el registro correcto. Ninguno sustituye al siguiente.

1. Revisa el formato y el origen. JSON debe ser válido; abre /status en la sesión afectada para ver la configuración cargada, cuenta y modelo. Ver un archivo en esa pantalla no identifica el valor ganador de cada campo. Comprueba el mismo campo en los alcances superiores y las variables relacionadas.
2. Revisa el cambio que esperabas. En el terminal, /config abre el menú de opciones, no todos los campos JSON, y no es un comando equivalente en el chat de VS Code o Desktop. Muchos ajustes se recargan al editar, pero model se lee al iniciar: usa /model para cambiarlo durante la sesión o abre una nueva. Comportamiento de settings.
3. Confirma el destino y envía una petición autorizada. Revisa el host, la credencial y el modelo en el cliente concreto. Un 401 exige revisar la credencial que ese servicio recibió; un error de modelo requiere contrastar el ID y su disponibilidad allí. Si aparece una prohibición administrada, pide el acceso al administrador en lugar de intentar saltarla.
4. Contrasta el registro de uso. Tras la respuesta, comprueba Console o el registro del proveedor para la cuenta y el proyecto previstos. /status no es una factura ni una garantía de que todas las funciones de herramientas sean compatibles con el gateway.

Si el problema es Login expired, Failed to authenticate o «Temporarily unable to authenticate», continúa con el diagnóstico de errores de autenticación en Claude. Allí se distingue el texto del cliente de un incidente del servicio; reinstalar o cerrar sesión indiscriminadamente no resuelve esas diferencias.

Preguntas frecuentes

¿Necesito una clave API para usar Claude Code?

No siempre. Puedes usar un inicio de sesión de claude.ai con acceso a Code, un perfil de Console compatible o un proveedor autorizado por tu organización. Console admite el perfil OAuth sin crear una clave desde v2.1.242, con requisitos de entorno y política. Usa una clave cuando esa sea la modalidad que has elegido y aprobado. Opciones de autenticación.

¿Por qué sigue pidiendo login aunque haya configurado una clave?

Comprueba si la clave llega al proceso correcto, si rechazaste su uso interactivo o si la organización restringe ese método. En un gateway desde VS Code, revisa también claudeCode.environmentVariables, que participa en la comprobación previa de la extensión. No deduzcas el entorno de la extensión a partir de una terminal externa. Autenticación y entrada de VS Code.

¿Puedo usar cualquier API compatible con OpenAI cambiando la base URL?

No basta con eso. El gateway debe implementar un formato que Claude Code admita, el esquema de credenciales y las capacidades que necesite la sesión. Un endpoint de chat compatible con OpenAI por sí solo no demuestra compatibilidad con Claude Code. Formatos admitidos.

¿Cambiar /model afecta a la próxima sesión?

Normalmente sí: Intro en el selector o un nombre con /model guarda el valor predeterminado de usuario. La tecla s lo limita a la sesión actual. --model y ANTHROPIC_MODEL seleccionan el modelo al arrancar; las sesiones reanudadas y las políticas tienen condiciones propias. Persistencia de la selección.