Clave de API de Claude Code — dónde obtenerla, dónde colocarla y por qué la variable incorrecta falla silenciosamente

Claude Code puede autenticarse de dos maneras distintas, y la que necesites determina todo lo demás. Un inicio de sesión mediante una suscripción de claude.ai cubre el uso dentro de tu plan Pro o Max. Una clave de API factura por token sin límites del plan. Esta guía explica dónde obtener una clave, exactamente dónde introducirla, las dos variables de credenciales y por qué elegir la incorrecta produce un fallo silencioso, además de cómo controlar la factura una vez que funciona.

¿Necesitas una clave?

Conviene saberlo antes de empezar: establecer una clave pone en pausa tu suscripción. Mientras una variable de credenciales esté activa, Claude Code la utiliza en lugar del inicio de sesión guardado de claude.ai, los límites del plan dejan de aplicarse y el uso se factura al propietario de la clave. Elimínala y Claude Code vuelve a la suscripción.

Opción 1: una clave propia de Anthropic

1. Inicia sesión en console.anthropic.com (una cuenta separada de claude.ai).
2. Añade crédito en Billing. La API es prepago y está separada de cualquier suscripción; un plan Pro no la financia.
3. Crea una clave en API Keys. Comienza por sk-ant- y se muestra una sola vez.

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

Observa el segundo paso de ese fragmento. ANTHROPIC_API_KEY se envía en el encabezado x-api-key y necesita una aprobación interactiva única antes de que Claude Code la use. Si ese aviso se rechazó alguna vez, la clave se ignora posteriormente sin mostrar ningún aviso, lo que parece exactamente que no se está leyendo la variable. Vuelve a habilitarla en /config → Use custom API key.

Opción 2: una clave que cuesta menos por token

Claude Code lee ANTHROPIC_BASE_URL de forma nativa, por lo que funciona contra cualquier endpoint que sirva la API Anthropic Messages: sin plugin, proxy ni binario modificado. Esa es la vía compatible para los gateways y así puedes ejecutar los mismos modelos Claude a una tarifa menor:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URL es solo el origen; Claude Code añade /v1/messages por su cuenta. Conserva las líneas de modelo: el valor predeterminado integrado de Claude Code y su alias opus apuntan ambos al Opus más reciente, y si Kunavo todavía no ofrece ese modelo, la primera solicitud devuelve 404. La línea opus lo fija en Claude Opus 5.5, que requiere Claude Code v2.1.280 o posterior (ejecuta claude update en una versión anterior). El alias sonnet solicita Sonnet 5.5, que Kunavo no ofrece, por lo que, sin ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase de ejecución de opusplan y los subagentes configurados en sonnet devuelven 404. Crea la clave sk-kn- en el panel después de registrarte y recargar $10. No hay cuota mensual y el saldo no caduca.

Eso supone aproximadamente un 30% por debajo del precio de lista en el modelo principal. Las tarifas completas están en la guía de precios de la API de Claude, y precios de Claude Code compara esta vía con las cuotas de los planes Pro y Max; la configuración completa, incluido el enrutamiento de modelos por tarea y lo que cambia detrás de un gateway, está en la guía del enrutador de Claude Code. Si aún no has instalado la CLI, empieza por instalar Claude Code.

Dónde va realmente la clave

Dos variables, dos encabezados HTTP distintos. Una clave en el encabezado que el servidor no lee falla con 401:

Si no te dijeron qué tipo tienes, empieza con ANTHROPIC_AUTH_TOKEN, que no requiere aprobación. En Kunavo, cualquiera de las dos variables también permite que Claude Code descubra la lista de modelos, ya que /v1/models lee la clave desde cualquiera de los dos encabezados.

Exportación del shell frente al archivo de configuración

Una exportación del shell se aplica solo a ese terminal y sus procesos hijos. Un editor iniciado desde el dock no la verá, y tampoco los agentes en segundo plano. Para cualquier configuración permanente, usa en su lugar el bloque env de ~/.claude/settings.json: las mismas claves, aplicadas en todos los lugares donde se ejecute Claude Code. No pongas una clave en el .claude/settings.json de un proyecto; ese archivo se confirma y se comparte con todos los que clonen el repositorio.

Ejecuta /status para confirmar qué credencial está activa. Una línea Auth token o API key que nombre tu variable significa que la clave está activa; una línea Login method que nombre una cuenta de claude.ai significa que no lo está.

Rotar claves sin editar archivos

Si la credencial caduca según un calendario o procede de un vault, apunta apiKeyHelper a un comando que muestre la actual:

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

Haz referencia a ella como "apiKeyHelper": "~/bin/get-key.sh" en tu archivo de configuración. Claude Code almacena la salida en caché durante cinco minutos y vuelve a ejecutarla en un 401; ajusta esto con CLAUDE_CODE_API_KEY_HELPER_TTL_MS. El valor se envía en ambos encabezados, así que funciona de cualquiera de las dos formas.

Cómo mantener predecible la factura

La programación agéntica consume muchos tokens: cada paso vuelve a enviar el prompt del sistema, el historial de la tarea y el contexto actualizado de los archivos. Cuatro cosas importan más que cualquier otra:

1. Dirige el trabajo en segundo plano a Haiku. ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 cubre los resúmenes y títulos que Claude Code genera por su cuenta. Es una línea y supone un ahorro puro; importa sobre todo cuando el trabajo se divide en varias ramas, cuyo coste se explica en cuánto cuesta un flujo de trabajo de Claude Code.
2. Las mismas dos variables dirigen el Agent SDK. No tiene una opción de URL base propia: inicia esta CLI y pasa directamente tu entorno, así que un programa del Agent SDK se dirige exactamente mediante la configuración anterior.
3. Inicia tareas nuevas en lugar de prolongar una indefinidamente. El contexto se reenvía en cada paso, por lo que una sesión larga resulta costosa de forma cuadrática. La elección del nivel para el modelo principal se analiza en Opus frente a Sonnet frente a Haiku, según el coste por tarea terminada y no el coste por token.
4. Deja que funcione la caché de prompts. La entrada almacenada en caché se factura al 10% de la tarifa de entrada, y la ruta nativa de la API Messages pasa cache_control sin traducir (detalles).
5. Asigna al editor su propia clave con un límite de gasto en el panel y comprueba el uso después de una semana. Los límites por clave convierten un bucle descontrolado en uno limitado.

Solución de problemas

Preguntas frecuentes