ANTHROPIC_BASE_URL no funciona en Claude Code: síntomas y arreglos

Si Claude Code no hace caso a ANTHROPIC_BASE_URL, abre /status antes de cambiar nada. Si falta la línea Anthropic base URL, la variable no ha llegado a la sesión. Si aparece la URL pero en lugar de Auth token o API key ves Login method con tu cuenta de claude.ai, la sesión va al gateway con tu suscripción y no con la credencial del gateway. Cuando esas dos líneas están bien y aun así hay errores, el fallo está entre Claude Code y el gateway, y una petición curl de un solo token a $ANTHROPIC_BASE_URL/v1/messages separa la dirección, la credencial y los campos que envía Claude Code.

Mira también la versión. Claude Code 2.1.299, publicada en npm el 14 de octubre de 2026, corrigió cuatro fallos que solo aparecen con una URL base personalizada: entre ellos, streams cortados tras 180 segundos sin datos y sesiones con nombres de modelo propios del gateway que terminaban con «Prompt is too long · automatic compaction failed» cerca de 200K tokens. A 15 de octubre de 2026, el canal stable todavía sirve la 2.1.292, así que si lo usas no tienes esos arreglos (registro de npm, CHANGELOG).

/status en Claude Code: comprueba qué URL y qué credencial usa la sesión

/status abre la pestaña Status, y dos líneas bastan para saber en qué capa estás (documentación de Claude Code):

• Anthropic base URL solo aparece cuando hay una dirección de gateway configurada. Si no está, Claude Code no apunta al gateway, por mucho que hayas escrito la variable en algún sitio.
• Auth token o API key aparece cuando una credencial del gateway está activa y nombra su origen: ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY o un apiKeyHelper. Si en su lugar ves Login method con una cuenta de claude.ai, la credencial no ha llegado a la sesión.

Con las dos líneas correctas, envía cualquier mensaje. Si Claude responde sin error, la conexión funciona y el problema que tenías era de otra parte (por ejemplo, de VS Code o de la app de escritorio, más abajo). Si el mensaje falla, pasa al curl.

Prueba el gateway con curl en /v1/messages

La prueba manda una petición de un token directamente al gateway, sin Claude Code de por medio. Lee las variables de la shell, así que necesita los export aunque también tengas los valores en un archivo de ajustes (Verify the connection):

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

En PowerShell:

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Si tu credencial va en ANTHROPIC_API_KEY, cambia la cabecera Authorization por x-api-key: $ANTHROPIC_API_KEY. Cómo leer el resultado:

• JSON que empieza por {"id":"msg_: el gateway responde y acepta la credencial. Si Claude Code sigue fallando, el problema está en cómo le llegan las variables o en los campos que envía.
• Error de modelo desconocido: también prueba que la URL y la credencial funcionan, porque el gateway autenticó la petición antes de rechazar el nombre. No necesitas encontrar un modelo que sirva tu gateway para esta prueba.
• 401: credencial rechazada. Si elegiste la variable a ojo, cambia a la otra y vuelve a exportar.
• Fallo inmediato de conexión o de DNS: la dirección o la red; mira la sección de la URL base.
• HTML con código 200: el gateway, o un proxy intermedio, responde con una página que no es de la API.

Claude Code pide iniciar sesión en claude.ai aunque pusiste ANTHROPIC_BASE_URL

ANTHROPIC_BASE_URL sola no sustituye a tu suscripción. Si solo pones la dirección, las peticiones pasan por el gateway, pero la credencial activa sigue siendo tu sesión guardada de claude.ai, con sus límites de uso y su facturación (LLM gateways). Una variable de credencial del gateway tiene prioridad sobre el login guardado, y /logout borra ese login.

Los casos que provocan la pantalla de inicio de sesión aunque el curl funcione:

• No hay credencial en ningún sitio. Una URL accesible no es una credencial. Añade ANTHROPIC_AUTH_TOKEN junto a la URL.
• La credencial está en los ajustes del proyecto. En una sesión interactiva, el bloque env de .claude/settings.json o .claude/settings.local.json de un proyecto solo se aplica después del asistente inicial y de la confirmación de confianza en la carpeta. Pon ANTHROPIC_AUTH_TOKEN donde Claude Code lo lea antes: un export en la shell, el bloque env de ~/.claude/settings.json o los ajustes gestionados de tu empresa. No metas la credencial en el .claude/settings.json del proyecto, que se sube al repositorio.
• ANTHROPIC_API_KEY está puesta pero se ignora sin preguntar. En modo interactivo esa variable necesita una aprobación única, y si alguna vez la rechazaste se ignora sin volver a preguntar. Actívala en /config con la opción Use custom API key.
• Aviso al arrancar que nombra dos orígenes de credencial y termina en auth may not work as expected (en versiones antiguas, Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set). Conviven la credencial del gateway y el login guardado. Ejecuta /logout para quedarte solo con el gateway, o quita la variable para volver a claude.ai.
• This machine's managed settings require a first-party login. Los ajustes gestionados incluyen forceLoginMethod o forceLoginOrgUUID, que no pueden convivir con una credencial de gateway. Solo tu administrador puede quitarlos.

Todos vienen de la tabla de errores de gateway de la documentación oficial. Si al volver a iniciar sesión con claude.ai aparecen Invalid code, 403 o 500, sigue con Claude Code no inicia sesión: cómo resolver Invalid code, 403 y 500.

Exportaste la variable, pero /status muestra otra URL o ninguna

Cuando una variable está a la vez en un export de la shell y en el bloque env de un archivo de ajustes, gana el archivo de ajustes (Set in a settings file). La documentación de Ollama lo dice igual: los ajustes de Claude pueden pisar las variables de la shell. Si /status enseña una URL vieja, busca un bloque env en ~/.claude/settings.json, en el .claude/settings.local.json del proyecto o en los ajustes gestionados, y corrígelo allí.

Si no aparece ninguna URL, la variable no está en el entorno del proceso:

• Un export solo vale en esa terminal y en lo que arranques desde ella. Un editor abierto desde el Dock o el menú Inicio no lo ve. Para que dure, añade las líneas a ~/.zshrc, ~/.bashrc o tu $PROFILE de PowerShell, o pásalas al bloque env de ~/.claude/settings.json.
• Los agentes en segundo plano no reciben de forma fiable lo que solo exportas en la shell. Si deben pasar siempre por el gateway, usa el bloque env de un archivo de ajustes.
• El instalador nativo no lee el .env del proyecto, según la documentación de OpenRouter. Un .env con la URL no basta.
• El orden en tu perfil de la shell importa. ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" se expande en el momento de cargar el archivo: si la clave se define más abajo, la variable queda vacía y todas las peticiones fallan al autenticar.

El bloque env tiene esta forma, igual en ~/.claude/settings.json que en .claude/settings.local.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

Error 401: ¿la credencial va en ANTHROPIC_AUTH_TOKEN o en ANTHROPIC_API_KEY?

Cada variable manda la credencial en una cabecera HTTP distinta. Si la pones en la que no toca, llega al gateway en una cabecera que no lee y la respuesta es 401 (documentación de Claude Code):

Si no sabes cuál usa tu gateway, empieza por ANTHROPIC_AUTH_TOKEN y, si el curl devuelve 401, cambia a la otra. Si el 401 sigue con las dos, la clave no es una que haya emitido el gateway o está revocada: genera otra.

OpenRouter y Ollama usan ANTHROPIC_AUTH_TOKEN y piden dejar ANTHROPIC_API_KEY="" vacía de forma explícita. Con OpenRouter, si antes iniciaste sesión con claude.ai, ejecuta /logout una vez; el login guardado puede chocar y mostrarse como errores de modelo no encontrado. Una ANTHROPIC_API_KEY real que se haya quedado en tu perfil de la shell no se arregla con /logout: hay que borrarla de ahí.

ConnectionRefused, ENOTFOUND o una página HTML: revisa la URL base

ANTHROPIC_BASE_URL es la raíz del gateway. Claude Code añade /v1/messages por su cuenta, y por eso la prueba oficial apunta a $ANTHROPIC_BASE_URL/v1/messages. Los proveedores documentan la raíz sin /v1:

Fuentes: OpenRouter y Ollama. Son valores para comparar con los tuyos, no una configuración completa de cada proveedor.

Si tu URL termina en /v1, la petición acaba en /v1/v1/messages. Es una deducción a partir de cómo forma Claude Code la ruta, no un mensaje documentado; qué devuelve el gateway en ese caso depende de él. Quita el /v1 y repite el curl.

Los errores de conexión, según la tabla oficial:

• Connection refused — a firewall or proxy may be blocking it (ConnectionRefused) o Can't reach the API server — check your internet or DNS (ENOTFOUND), a menudo tras una pausa en silencio mientras Claude Code reintenta. Nadie responde en esa dirección o el nombre no se resuelve: la URL está mal o una VPN o un cortafuegos cortan el camino. El curl falla al instante con la misma causa.
• API returned an empty or malformed response (HTTP 200). El gateway o un proxy intermedio devolvió algo que no es una respuesta de la API, a menudo una página HTML de error o de inicio de sesión. Arregla la ruta que contesta eso.
• 403 con cuerpo HTML (403 Forbidden) y nada en los registros del gateway. Un cortafuegos de aplicaciones web delante del gateway bloqueó el cuerpo de la petición. Los prompts de Claude Code llevan etiquetas de estilo XML y código fuente que disparan reglas contra cross-site scripting, así que un curl corto pasa y una sesión real no. Exime la ruta /v1/messages de la inspección del cuerpo; en AWS WAF es la regla gestionada CrossSiteScripting_Body.
• SSL certificate verification failed o Self-signed certificate detected con el curl funcionando. El runtime de Claude Code no confía en la misma autoridad de certificación que curl, algo habitual detrás de un proxy corporativo que inspecciona TLS. Apunta NODE_EXTRA_CA_CERTS al paquete de certificados.

Si el error es un 529 overloaded_error y el mensaje termina en check your inference gateway, ya ha pasado por tu gateway; lo explica Claude 529 overloaded_error: qué significa y cómo solucionarlo en 2026.

Error 400 del gateway: campos beta, adaptive thinking y límite de contexto

Un 400 con el curl funcionando significa que el gateway acepta la conexión pero rechaza algo de lo que Claude Code envía. El texto del error indica qué.

400 con Extra inputs are not permitted o context_management

El gateway reenvía a un modelo de destino que no acepta campos que Claude Code manda a los endpoints con formato de Anthropic. Pon CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, que suprime la mayoría de campos de versiones preliminares. Algunas betas no dependen de esa variable; para ellas, la documentación indica la variable CLAUDE_CODE_USE_* del proveedor correspondiente, con la que Claude Code solo envía lo que ese proveedor acepta.

Dos cambios recientes van en la misma línea (CHANGELOG): la 2.1.288 añadió CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS para gateways que rechazan las salidas estructuradas (fallan los títulos de sesión, la recuperación de memoria o los hooks de prompt), y la 2.1.290 corrigió peticiones que fallaban cuando el gateway rechazaba una cabecera beta con un código distinto de 400.

Hay además un informe abierto de la comunidad, sin confirmar por Anthropic: en el issue #95087, la primera petición con una URL base personalizada lleva bloques tool_addition (beta mid-conversation-tool-changes) que los endpoints estrictos rechazan con 400; Claude Code reintenta en silencio sin ellos. Un comentario del 13 de octubre de 2026 sobre la 2.1.296 describe un gateway donde ese reintento no llegó a producirse y la conversación quedó inservible.

400 con thinking o adaptive

Un error como Input tag 'adaptive' found indica que el modelo detrás del gateway no acepta el razonamiento adaptativo, que Claude Code pide para Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 5.5, Claude Fable 5 y posteriores. La solución es actualizar el modelo de destino del gateway. Con Opus 4.6 y Sonnet 4.6 también sirve CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1.

400 de contexto o «Prompt is too long · automatic compaction failed»

Cuando el gateway impone un contexto menor que el del modelo y reescribe el error con sus propias palabras (ContextWindowExceededError, prompt token count of N exceeds the limit of M), Claude Code no lo reconoce como «prompt demasiado largo» y no compacta ni reintenta. Ejecuta /compact para recuperar la sesión. Para prevenirlo, pon CLAUDE_CODE_AUTO_COMPACT_WINDOW en el límite del gateway y CLAUDE_CODE_MAX_OUTPUT_TOKENS por debajo del límite de salida del modelo. Claude Code ajusta el primero a un mínimo de 100.000 tokens y a un máximo igual a la ventana del modelo: si tu gateway corta por debajo de 100.000, /compact es la única salida.

Según la versión, hay tres situaciones más:

• Desde la 2.1.285, las sesiones con una URL base personalizada usan la ventana de 1M de los modelos que la tienen (Opus 4.7 y posteriores, Sonnet 5 y posteriores, Fable). Si tu gateway corta en 200K, ejecuta /autocompact 200k.
• Antes de la 2.1.299, las sesiones con un nombre de modelo propio del gateway podían terminar con «Prompt is too long · automatic compaction failed» cerca de 200K tokens en lugar de enviar la petición. Actualizar lo corrige.
• Informe abierto #101897 (13 de octubre de 2026): tras pasar de la 2.1.269 a la 2.1.296, un modelo autoalojado falla con un 400 de contexto redactado al estilo de OpenAI («maximum context length») y la compactación no lo evita ni lo recupera. Quien lo informó volvió a la 2.1.269. Es un único caso sin confirmar; el arreglo oficial de arriba (/compact y CLAUDE_CODE_AUTO_COMPACT_WINDOW) es lo primero que hay que probar. Para volver a una versión concreta, mira Claude Code changelog: qué cambió y cuándo volver atrás.

Modelos locales lentos: el stream se corta a los 180 o 300 segundos sin datos

Con Ollama, LM Studio o cualquier modelo local que tarda en empezar a responder, si la respuesta se corta tras un silencio largo, la causa está en los tiempos de espera del stream y no en la URL. Hasta la 2.1.299, los streams que pasaban por una ANTHROPIC_BASE_URL personalizada se abortaban tras 180 segundos sin recibir datos; desde esa versión esperan 300 segundos, con o sin feature flags cargados. Un modelo que calla más de 300 segundos sigue cortándose.

Dos variables controlan los tiempos (variables de entorno):

• API_FORCE_IDLE_TIMEOUT sustituye el tiempo de inactividad de 5 minutos que aborta una respuesta en streaming cuando no llegan bytes. 0 lo desactiva. Sin definir, está activo en todos los proveedores salvo la API directa de Anthropic. Los watchdogs del stream, un control independiente, pueden cortar una pausa larga aunque pongas 0; la documentación no explica cómo se combina esto con los 300 segundos de la 2.1.299.
• API_TIMEOUT_MS es el tiempo máximo por petición: 600000 (10 minutos) por defecto. La documentación usa 1200000 como ejemplo para subirlo.

export API_FORCE_IDLE_TIMEOUT=0
export API_TIMEOUT_MS=1200000

Con Ollama hay dos condiciones más de su documentación: elige un modelo que admita herramientas y, para repositorios grandes, configura un contexto de 64k o más.

Funciona en la terminal pero no en VS Code ni en Claude Desktop

VS Code. La extensión comprueba la credencial antes de arrancar y la lee de claudeCode.environmentVariables, en los ajustes de usuario de VS Code (comando Preferences: Open User Settings (JSON)). Los valores de ~/.claude/settings.json llegan al proceso que lanza la extensión, pero no a esa comprobación de login; por eso la extensión puede pedir iniciar sesión aunque la terminal funcione (VS Code extension):

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

Claude Desktop. La app de escritorio no lee ANTHROPIC_BASE_URL ni settings.json. Usa su propia configuración de inferencia de terceros: o la distribuye tu administrador, o la introduces en Help → Troubleshooting → Enable Developer Mode y después Developer → Configure Third-Party Inference, con la URL base del gateway. Si tu empresa ya distribuyó una configuración, esa manda y el formulario queda en solo lectura. El mensaje Gateway was unreachable significa que la app no pudo llegar a esa URL al arrancar (Desktop app).

Qué corrige Claude Code 2.1.299 y si te llega por el canal stable

La 2.1.299 salió en npm el 14 de octubre de 2026 a las 00:23 UTC (02:23 en Madrid) y la 2.1.300, el mismo día. Para quien usa ANTHROPIC_BASE_URL, el CHANGELOG recoge cuatro arreglos:

1. Las peticiones a Anthropic de feature flags, arranque, fast mode, perfil y comentarios llevaban la clave API configurada para el gateway externo. Las claves de la API de Anthropic se siguen enviando.
2. Lo mismo en la petición de ajustes gestionados por el servidor, cuando un archivo de ajustes gestionados define ANTHROPIC_BASE_URL.
3. Los streams por una URL base personalizada se abortaban tras 180 segundos sin datos; ahora esperan 300.
4. Las sesiones con un nombre de modelo propio del gateway terminaban con «Prompt is too long · automatic compaction failed» cerca de 200K tokens.

En los dos primeros, el changelog no describe qué error veías; el hecho es que tu clave del gateway viajaba a Anthropic. Antes de la 2.1.246, la telemetría y las métricas de uso también podían llevar la credencial del gateway. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 corta ese tráfico fuera del gateway (comprobaciones de versión, telemetría, notas de versión), pero también desactiva las actualizaciones automáticas, y entonces los arreglos como estos solo te llegan si actualizas a mano (Turn off traffic outside the gateway path).

Otros cambios para gateways de las últimas semanas, por si tu versión es anterior:

Canal latest o stable: cómo actualizar desde la terminal

A 15 de octubre de 2026, las etiquetas de npm son latest = 2.1.300 y stable = 2.1.292. latest es el canal por defecto y recibe cada versión al salir; stable sirve una versión de aproximadamente una semana de antigüedad y se salta las que tienen regresiones graves (Set up Claude Code). De ahí se deduce que, en stable, no tienes los arreglos de la 2.1.299 hasta que el canal llegue a esa versión o una posterior, y no hay fecha publicada para eso.

• Instalador nativo: claude update sigue el canal configurado (autoUpdatesChannel). Para fijar una versión: curl -fsSL https://claude.ai/install.sh | bash -s 2.1.299; con bash -s latest instalas la última y pasas a ese canal.
• Homebrew: el cask claude-code sigue stable y claude-code@latest sigue latest. Ninguno se actualiza solo: brew upgrade claude-code@latest.
• WinGet y apt: tampoco se actualizan solos (winget upgrade Anthropic.ClaudeCode; en apt, la actualización normal del sistema).

Si tu gateway usa una clave API propia, ten en cuenta los dos primeros arreglos: en versiones anteriores, esa clave sigue saliendo hacia Anthropic en esas peticiones. Si te afecta el corte a los 180 segundos o el error de compactación, pasa a la 2.1.299 o posterior. Si nada de esto te afecta y prefieres stable, puedes esperar a que el canal avance. Ten en cuenta que el informe #101897 describe una regresión desde la 2.1.296, así que actualizar no garantiza que desaparezca un 400 de contexto con un modelo autoalojado.

Cuándo parar: modelos que no son Claude y funciones que se apagan con un gateway

Anthropic no admite conectar Claude Code a modelos que no son Claude a través de ningún gateway, y no avala, mantiene ni audita gateways de terceros (LLM gateways). Usar DeepSeek, GLM, Qwen, Kimi o un modelo local con Claude Code es posible, pero queda fuera de lo que Anthropic sostiene. Los proveedores ponen sus propios límites: OpenRouter solo garantiza que Claude Code funcione con Anthropic como proveedor directo, y Ollama advierte de que WebSearch alojado y los controles avanzados de herramientas no tienen soporte completo.

Una prueba útil: si /status está bien, el curl responde y un modelo Claude a través del mismo gateway funciona, pero otro modelo falla, lo más probable es que hayas llegado al límite de esa ruta y no a un error de tu configuración.

Hay funciones que se apagan por diseño y que no debes intentar arreglar:

• Búsqueda de herramientas MCP: desactivada por defecto cuando ANTHROPIC_BASE_URL apunta a un host que no es de Anthropic. Se puede activar con ENABLE_TOOL_SEARCH=true si el gateway reenvía los bloques tool_reference.
• Remote Control: desactivado cuando la URL apunta a un host distinto de api.anthropic.com (desde la 2.1.196) y mientras haya una credencial de gateway activa.
• Dictado por voz: no disponible mientras haya una credencial de gateway activa.
• Fast mode: su comprobación de disponibilidad va directa a api.anthropic.com y no sigue ANTHROPIC_BASE_URL; si esa salida está bloqueada, /fast dice que no está disponible aunque las respuestas funcionen.

Si lo que falta son modelos en /model, prueba CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 para que Claude Code pida la lista al gateway. Para un modelo concreto que no aparece, sigue con Fable 5.1 no aparece en Claude Code: cómo saber qué lo bloquea.

Preguntas frecuentes sobre ANTHROPIC_BASE_URL en Claude Code

¿ANTHROPIC_BASE_URL tiene que terminar en /v1?

No. Es la raíz del gateway, porque Claude Code añade /v1/messages. OpenRouter documenta https://openrouter.ai/api y Ollama http://localhost:11434, ambos sin /v1.

¿Necesito ANTHROPIC_API_KEY si uso un gateway o un modelo local?

Solo si tu gateway lee la cabecera x-api-key. Para un bearer token se usa ANTHROPIC_AUTH_TOKEN. OpenRouter y Ollama piden ANTHROPIC_AUTH_TOKEN y, además, dejar ANTHROPIC_API_KEY="" vacía de forma explícita.

¿Dónde pongo ANTHROPIC_BASE_URL para que no se pierda al cerrar la terminal?

En tu perfil de la shell (~/.zshrc, ~/.bashrc, $PROFILE) o en el bloque env de ~/.claude/settings.json. Si está en los dos sitios con valores distintos, manda el archivo de ajustes. Para VS Code, además, en claudeCode.environmentVariables.

¿Cómo actualizar Claude Code desde la terminal para tener la 2.1.299?

Con el instalador nativo, claude update, que respeta tu canal; en stable a 15 de octubre de 2026 te quedas en la 2.1.292. Para fijar la versión: curl -fsSL https://claude.ai/install.sh | bash -s 2.1.299. En Homebrew, brew upgrade claude-code@latest si usas ese cask.