Clave API de Claude Code — ANTHROPIC_API_KEY: cómo obtenerla, configurarla y cuándo usar claude setup-token en su lugar

Claude Code necesita una clave API para funcionar. Tanto si configuras Claude Code por primera vez como si migras de una cuenta directa de Anthropic a una pasarela con tarifa plana, el proceso consiste en generar una clave, configurar dos variables de entorno y verificar la conexión.

Clave API de Claude Code: versión breve

Una clave API de Claude Code es una clave normal con formato de Anthropic (sk-...) que Claude Code lee de ANTHROPIC_API_KEY. Obtén una en Claude Console (Configuración → Claves API, se muestra una sola vez) o en el panel de esta pasarela (visible en cualquier momento), expórtala y Claude Code se iniciará sin necesidad de iniciar sesión en el navegador. Con una clave de pasarela también debes configurar ANTHROPIC_BASE_URL con el host de la pasarela. Esa es toda la configuración; el resto de esta página explica los detalles: la diferencia entre una clave API, el token OAuth de /login y una clave de sesión de claude.ai, los pasos para cada sistema operativo y los errores que suelen surgir.

Qué es una clave API de Claude Code

Una clave API de Claude Code es la credencial de autenticación que permite a la CLI de Claude Code enviar solicitudes a un proveedor de modelos de Claude. Sin ella, cada comando que ejecutes en Claude Code devuelve un error de autenticación. La clave es una cadena que almacenas en una variable de entorno: ANTHROPIC_API_KEY (enviada como encabezado x-api-key) o ANTHROPIC_AUTH_TOKEN (enviada como token Bearer). Ambas funcionan con AI Prime Tech.

Cuando usas una pasarela como AI Prime Tech en lugar de Anthropic directamente, la clave procede del panel de la pasarela en vez de Anthropic Console. El formato de la clave puede variar, pero el proceso de configuración en Claude Code es idéntico: establece la clave en tu entorno, apunta la URL base a la pasarela y Claude Code se encarga del resto. Tu clave está vinculada al saldo o a la suscripción de tu cuenta de la pasarela, no a la facturación de Anthropic.

Una misma clave se puede usar simultáneamente en varios equipos y sesiones de Claude Code. Sin embargo, si compartes una clave con un equipo, todo el uso cuenta para los límites de solicitudes y el saldo de la misma cuenta. Para configurar equipos, genera una clave independiente por desarrollador desde el panel, de modo que el seguimiento del uso y la limitación de solicitudes funcionen correctamente para cada persona.

Clave API frente a token OAuth: y qué es una «clave de sesión»

Claude Code acepta dos tipos de credenciales. Una clave API (ANTHROPIC_API_KEY, o ANTHROPIC_AUTH_TOKEN enviada como token Bearer) se factura por token con cargo a un saldo de API; es lo que usas con una pasarela. Un token OAuth procede de una suscripción a Claude Pro o Max: /login dentro de Claude Code inicia tu sesión, y claude setup-token genera un token de larga duración que puedes usar en CI o en un equipo sin interfaz gráfica para que consuma la suscripción en lugar de un saldo de API.

Una «clave de sesión de Claude» no es ninguna de las dos: es la cookie de sesión del navegador de claude.ai, que algunos clientes no oficiales extraen para interactuar con la interfaz de chat. No es una credencial de API, infringe las condiciones de uso para consumidores, caduca y puede provocar la suspensión de la cuenta. Si quieres acceso programático, usa una clave API de la consola de Anthropic o de una pasarela como esta.

Paso 1 — Obtén la clave: Claude Console o el panel de la pasarela

Hay dos lugares que emiten claves aceptadas por Claude Code. En Claude Console (la plataforma de Claude en platform.claude.com), abre Configuración → Claves API, haz clic en Crear clave, asígnale un nombre y copia el valor secreto de la clave. La consola lo muestra una sola vez y después solo enumera el nombre y el prefijo, por lo que gestionar las claves allí implica crear una nueva en lugar de recuperar una antigua.

Claude Code necesita una clave normal; una clave API de administrador es una credencial distinta para gestionar una organización y no sirve para autenticar solicitudes. Después export ANTHROPIC_API_KEY=sk-ant-... en tu shell y Claude Code la usará sin /login. Anthropic factura por token y requiere que primero añadas un método de pago a la cuenta.

La vía más rápida es una clave de pasarela: regístrate en aiprimetech.io, abre Claves API en el panel, haz clic en Crear y la clave estará visible en el panel en cualquier momento; puedes volver a copiarla, cambiarle el nombre o revocarla cuando quieras. Tiene el mismo formato sk- y funciona con la misma variable; el único paso adicional es ANTHROPIC_BASE_URL, que se explica en el paso 2.

En este punto tienes una clave, pero no tienes saldo. Haz una pequeña recarga antes de probarla —la página de modelos muestra cuánto puedes obtener por un dólar con cada modelo— o elige un plan ilimitado en /plans/ si ya sabes que vas a usar Claude Code todo el día.

Paso 2 — Configura las variables de entorno

Claude Code lee dos variables de entorno para configurar la pasarela: ANTHROPIC_BASE_URL y ANTHROPIC_API_KEY. Establece ANTHROPIC_BASE_URL en el host raíz de la pasarela, sin ningún sufijo de ruta. El SDK de Anthropic añade /v1/messages automáticamente; si incluyes /v1 en la URL base, las solicitudes llegarán a /v1/v1/messages y devolverán errores 404.

En Linux o macOS, añade estas líneas al archivo de perfil de tu shell (~/.bashrc, ~/.zshrc o ~/.profile): export ANTHROPIC_BASE_URL="https://aiprimetech.io" y export ANTHROPIC_API_KEY="tu-clave-aquí". En Windows, configúralas como variables de entorno del sistema desde Configuración > Sistema > Configuración avanzada del sistema > Variables de entorno, o añádelas a tu $PROFILE de PowerShell.

Para configurar cada proyecto por separado, crea un archivo .env en la raíz del proyecto con las mismas variables. Claude Code carga los archivos .env del directorio de trabajo, y estos tienen prioridad sobre las variables del sistema. Esto resulta útil si usas distintos proveedores de API para distintos proyectos. Asegúrate de añadir .env a tu .gitignore para evitar incluir accidentalmente tu clave en el control de versiones.

Paso 3 — Verifica la conexión

Después de configurar las variables de entorno, abre una nueva sesión de terminal (para que se carguen las variables) y ejecuta Claude Code. Escribe un mensaje sencillo como «Hola, confirma que puedes responder». Si recibes una respuesta de Claude, la configuración funciona de extremo a extremo. La clave es válida, la URL base es correcta y la pasarela está dirigiendo tu solicitud a Claude correctamente.

Si la verificación falla, el mensaje de error te indica qué ha ocurrido. Un error 401 o 403 significa que la clave API no es válida o ha caducado; vuelve a copiarla desde el panel. Un error 404 casi siempre significa que la URL base es incorrecta; comprueba si has añadido por accidente el sufijo /v1 o barras al final. Un error de conexión rechazada significa que no se puede acceder a la pasarela; revisa la configuración de tu red, VPN o cortafuegos.

También puedes verificarlo de forma programática accediendo al endpoint de estado de la pasarela con curl: curl -H 'Authorization: Bearer YOUR_KEY' https://aiprimetech.io/v1/models — esto devuelve la lista de modelos disponibles si tu clave es válida. Si esto funciona pero Claude Code no, el problema está en la carga de las variables de entorno, no en la clave ni en la propia pasarela.

Paso 4 — Configura las preferencias de modelos

De forma predeterminada, Claude Code usa sus selecciones de modelos integradas para cada nivel (Sonnet, Opus, Haiku). Puedes sustituirlas mediante variables de entorno adicionales: ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL y ANTHROPIC_DEFAULT_FABLE_MODEL. Establécelas en los identificadores exactos de los modelos que admite la pasarela.

Para la mayoría de los desarrolladores, basta con configurar ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5 y ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6. Claude Code usa Sonnet de forma predeterminada para la mayoría de las interacciones y usa Opus cuando lo seleccionas mediante el comando /model o cuando el modo de planificación recurre a un modelo más potente. La pasarela admite todas las versiones actuales de los modelos de Claude.

Activa el descubrimiento de modelos de la pasarela configurando CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Esto indica a Claude Code que consulte a la pasarela qué modelos están disponibles en lugar de usar una lista fija en el código. Configura también CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 para impedir que las solicitudes de telemetría se envíen a la pasarela; esto reduce el ruido y mejora ligeramente la latencia de las solicitudes.

Solución de errores de autenticación habituales

El problema más frecuente es que las variables de entorno no se cargan. Después de configurarlas en tu archivo de perfil, debes abrir un nuevo terminal; los terminales existentes usan el entorno anterior. En Windows, puede que tengas que reiniciar por completo la aplicación de terminal, no solo abrir una nueva pestaña. Compruébalo con echo $ANTHROPIC_BASE_URL (bash/zsh) o echo $env:ANTHROPIC_BASE_URL (PowerShell).

Si recibes errores de «modelo no encontrado» pese a tener una conexión válida, el identificador del modelo no coincide con lo que ofrece la pasarela. Los identificadores de modelo distinguen entre mayúsculas y minúsculas y son específicos de cada versión. Consulta el panel o el endpoint /v1/models para obtener los identificadores exactos admitidos. Entre los errores habituales están usar 'claude-3-opus' en lugar de 'claude-opus-4-6' o añadir espacios en blanco adicionales al valor de la variable de entorno.

Consulta el saldo en tu panel. Para continuar sin interrupciones, añade saldo de pago por uso o cambia a un plan ilimitado de 1 día ($9) o 1 semana ($39) para acceder a todos los modelos con una tarifa fija y sin facturación por token.

# Add to ~/.bashrc or ~/.zshrc:
export ANTHROPIC_BASE_URL="https://aiprimetech.io"
export ANTHROPIC_API_KEY="your-key-from-dashboard"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# Verify connection:
# $ source ~/.bashrc && claude
# Or test the gateway directly:
# $ curl -H "x-api-key: $ANTHROPIC_API_KEY" https://aiprimetech.io/v1/models

Preguntas frecuentes

AI Prime Tech es una pasarela de API independiente. No está afiliada a Anthropic, no cuenta con su respaldo ni es un distribuidor de Anthropic. Claude y los nombres de los modelos relacionados son marcas comerciales de sus respectivos propietarios.