Documentación

ANTHROPIC_BASE_URL

La variable de entorno que dirige Claude Code y los SDK de Anthropic a un endpoint distinto de api.anthropic.com. Incluye la referencia completa de variables, la configuración por cliente y los dos errores que causan casi todos los fallos.

ANTHROPIC_BASE_URL indica a los SDK de Anthropic y a Claude Code a qué host enviar las solicitudes a la API, en sustitución del predeterminado https://api.anthropic.com. Configúrala con un origen sin ruta: el cliente añade /v1/messages por sí mismo. Combínala con ANTHROPIC_AUTH_TOKEN, que se convierte en el encabezado Authorization: Bearer.

~/.zshrc

# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

Después, abre un terminal nuevo: Claude Code y los SDK leen estas variables al iniciarse el proceso, por lo que una sesión que ya estaba en ejecución conserva el endpoint anterior.

No incluyas /v1 en ANTHROPIC_BASE_URL. Los clientes de Anthropic añaden la ruta por sí mismos, así que https://api.kunavo.com/v1 envía solicitudes a /v1/v1/messages y todas las llamadas devuelven 404. El SDK de OpenAI sigue la convención opuesta y sí requiere /v1 en su base_url. Esa diferencia es el error de configuración más común en este caso.

Todas las variables y su función

La referencia de variables de entorno de Anthropic contiene la lista completa de variables que lee Claude Code. Estas son las importantes cuando rediriges el endpoint.

Variable	Valor	Qué controla
`ANTHROPIC_BASE_URL`	`https://api.kunavo.com`	El origen al que se envían todas las solicitudes. Sin ruta ni barra final.
`ANTHROPIC_AUTH_TOKEN`	`sk-kn-…`	La credencial enviada como Authorization: Bearer. Es la que necesita una pasarela.
`ANTHROPIC_API_KEY`	`sk-ant-…`	La credencial enviada en el encabezado x-api-key, que es el formato que espera api.anthropic.com. Configura esta variable O el token anterior, pero no ambas.
`ANTHROPIC_MODEL`	`claude-sonnet-5`	El modelo principal que usa Claude Code para la conversación.
`ANTHROPIC_DEFAULT_OPUS_MODEL`	`claude-opus-5-5`	El modelo detrás del alias opus (/model opus). El valor predeterminado propio de Claude Code es el Opus más reciente, así que fíjalo a uno que ofrezca el endpoint. Opus 5.5 requiere Claude Code v2.1.280 o posterior.
`ANTHROPIC_DEFAULT_SONNET_MODEL`	`claude-sonnet-5`	El modelo detrás del alias sonnet (/model sonnet). El alias solicita Sonnet 5.5 de forma predeterminada, así que fíjalo a un Sonnet que ofrezca el endpoint.
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`claude-haiku-4-5`	El modelo económico que Claude Code usa para sus llamadas en segundo plano; es el principal factor para reducir costes después del almacenamiento en caché.

Los nombres de modelo deben corresponder a modelos que el endpoint realmente ofrezca. Apuntar a una pasarela y dejar un ID de modelo que no incluye es el segundo fallo más común, y se manifiesta como un 404 model_not_found, no como un error de autenticación. Los ID de modelo de Kunavo se indican en la página de modelos y se devuelven en tiempo real mediante GET /v1/models.

Configuración por cliente

Claude Code

Añade las exportaciones al perfil de shell desde el que se inicia Claude Code y abre un terminal nuevo. La instalación y el flujo de trabajo no cambian.

~/.zshrc

# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
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

Ejecuta /status dentro de Claude Code para confirmar qué endpoint está usando la sesión actual. Consulta la guía paso a paso, incluido cómo generar la clave: configurar una clave de API en Claude Code.

SDK de Anthropic (Python / TypeScript)

Los SDK leen las mismas variables de entorno; también puedes pasar ambas opciones al constructor, lo que resulta útil cuando un proceso se comunica con más de un endpoint.

anthropic_sdk.py

from anthropic import Anthropic

# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
    base_url="https://api.kunavo.com",
    auth_token="sk-kn-...",          # sets the Authorization: Bearer header
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)

SDK de OpenAI: la otra convención

Si tu código ya usa OpenAI, no necesitas ANTHROPIC_BASE_URL. Configura base_url con la ruta compatible con OpenAI, esta vez con /v1, y llama a los mismos modelos Claude mediante /v1/chat/completions.

openai_sdk.py

from openai import OpenAI

# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)

Cline, Roo Code, Kilo Code, Cursor

Los agentes de editor suelen mostrar estas dos opciones en su propia interfaz, en lugar de usar variables de entorno: un campo «URL base» o «endpoint personalizado» y un campo para la clave de API. Las reglas no cambian: para un proveedor de estilo Anthropic, usa el origen sin /v1 y coloca la clave en el campo de clave de API. Guías para cada cliente: Cline, Roo Code, Kilo Code.

Comprueba que funciona

Una sola llamada curl permite comprobar a la vez la URL base y la credencial. Una respuesta 200 con un cuerpo JSON indica que ambas son correctas.

# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

# In Claude Code, /status shows the endpoint the session is actually using.

Cuando no funciona

Síntoma	Causa	Solución
404 en todas las solicitudes	`/v1` al final de `ANTHROPIC_BASE_URL`	Configura solo el origen. El cliente añade /v1/messages.
401 / x-api-key no válida	La credencial está configurada como `ANTHROPIC_API_KEY`, pero el endpoint autentica con tokens bearer	Usa `ANTHROPIC_AUTH_TOKEN` en su lugar; consulta la explicación completa de la diferencia
Sigue usando api.anthropic.com	Las variables se exportaron después de iniciar la sesión o se configuraron en un perfil que el shell no lee	Abre un terminal nuevo; confirma con echo $ANTHROPIC_BASE_URL en el mismo shell que inicia el cliente.
404 model_not_found	El endpoint no ofrece ese ID de modelo	Configura `ANTHROPIC_MODEL` con un ID de `GET /v1/models`
Claude Code indica que el saldo de crédito es demasiado bajo	Las solicitudes llegan al endpoint y se facturan a la clave, no a la suscripción	Es lo esperado: recarga el saldo o elimina el token para volver al plan. Consulta crédito insuficiente

Qué ocurre con una suscripción Pro o Max

Mientras haya una variable de credenciales configurada, Claude Code factura a la clave en lugar de a la suscripción con la que iniciaste sesión: dejan de aplicarse los límites del plan y el uso se cobra a quien sea titular de la clave. La suscripción no se modifica: elimina la variable, abre un terminal nuevo y Claude Code volverá al plan. No se combinan; el cálculo de costes de cada opción se explica en precios de Claude Code.

Preguntas frecuentes

¿Qué es ANTHROPIC_BASE_URL?

ANTHROPIC_BASE_URL es la variable de entorno que indica a los SDK de Anthropic y a Claude Code a qué host enviar las solicitudes a la API, en lugar de usar el predeterminado https://api.anthropic.com. Configúrala con un origen sin ruta —el cliente añade /v1/messages— y combínala con ANTHROPIC_AUTH_TOKEN, que se convierte en el encabezado Authorization: Bearer. Funciona con cualquier endpoint compatible con Anthropic; en Kunavo, el valor es https://api.kunavo.com.

¿ANTHROPIC_BASE_URL debe incluir /v1?

No. ANTHROPIC_BASE_URL solo lleva el origen: https://api.kunavo.com, no https://api.kunavo.com/v1, porque los SDK de Anthropic y Claude Code añaden por sí mismos la ruta /v1/messages. Si incluyes /v1, las solicitudes se envían a /v1/v1/messages y devuelven 404. El SDK de OpenAI sigue la convención opuesta y sí requiere /v1 en su base_url; por eso, la misma pasarela se escribe de dos formas distintas según el cliente que la use.

¿Cuál es la diferencia entre ANTHROPIC_AUTH_TOKEN y ANTHROPIC_API_KEY?

ANTHROPIC_AUTH_TOKEN envía la credencial en un encabezado Authorization: Bearer, mientras que ANTHROPIC_API_KEY la envía en el encabezado x-api-key que espera api.anthropic.com. Una pasarela que autentica con tokens bearer requiere ANTHROPIC_AUTH_TOKEN; configurar ANTHROPIC_API_KEY en su lugar es la causa más común de un 401 después de cambiar ANTHROPIC_BASE_URL. Configura una sola variable, no ambas: si están presentes las dos, el comportamiento depende de la versión del cliente.

¿Cómo configuro una URL base personalizada en Claude Code?

Exporta ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN en el perfil de shell desde el que se inicia Claude Code (~/.zshrc o ~/.bashrc) y abre un terminal nuevo para que herede las variables. Claude Code las lee al iniciarse, por lo que una sesión que ya estaba en ejecución conserva el endpoint anterior. Ejecuta /status dentro de Claude Code para confirmar qué endpoint está usando la sesión actual.

¿Configurar ANTHROPIC_BASE_URL desactiva mi suscripción a Claude Pro o Max?

Mientras esté configurada una variable de credenciales como ANTHROPIC_AUTH_TOKEN, Claude Code factura a la clave en lugar de a la suscripción con la que iniciaste sesión, por lo que dejan de aplicarse los límites de los planes Pro y Max y el uso se cobra a quien sea titular de la clave. La suscripción no se modifica ni se cancela: elimina la variable y abre un terminal nuevo para que Claude Code vuelva al plan.