Errores de Claude Code ANTHROPIC_AUTH_TOKEN: soluciones completas de configuración

Cuando la consulta es Errores de Claude Code ANTHROPIC_AUTH_TOKEN: soluciones completas de configuración, la solución suele empezar con una pregunta: ¿Claude Code está enviando la credencial en el encabezado que realmente lee tu gateway?

Para el enrutamiento del gateway de Claude Code, ANTHROPIC_AUTH_TOKEN envía Authorization: Bearer .... ANTHROPIC_API_KEY envía x-api-key: .... Un token en la variable incorrecta puede parecer una clave inválida, un inicio de sesión obsoleto o un gateway roto incluso cuando el valor en sí es válido.

Usa esta guía de resolución cuando Claude Code falle después de configurar ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, un archivo de configuración de Claude Code, la extensión de VS Code o un flujo de trabajo de CI.

La solución rápida

Empieza con el diagnóstico más pequeño posible antes de editar todos los archivos de configuración de tu máquina.

1. Elige una sola variable de credencial.
2. Exporta la URL base del gateway y esa credencial en la misma shell.
3. Ejecuta una solicitud curl de un solo token contra $ANTHROPIC_BASE_URL/v1/messages.
4. Inicia Claude Code desde esa misma shell.
5. Ejecuta /status y confirma que aparecen tanto Anthropic base URL como la fuente de credenciales esperada.
6. Si curl funciona pero Claude Code sigue pidiéndote iniciar sesión, mueve la credencial a un lugar que Claude Code lea antes de la configuración inicial, como ~/.claude/settings.json, una exportación de shell o configuración administrada.

Para un gateway con token de portador:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"

curl -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": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

Para un gateway x-api-key:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_API_KEY="REPLACE_WITH_GATEWAY_KEY"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

Una respuesta JSON con un id de mensaje y content significa que la URL y la credencial funcionan. Un 401 significa que el gateway rechazó la credencial o la recibió en un encabezado que no lee.

Lista de verificación de errores de Claude Code ANTHROPIC_AUTH_TOKEN: soluciones completas de configuración

Usa esta tabla como diagnóstico de trabajo. No gires las claves hasta que se conozcan la variable activa, el encabezado y la precedencia de configuración.

Elija ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY

ANTHROPIC_AUTH_TOKEN es para un token bearer. Claude Code lo envía como:

Authorization: Bearer <token>

ANTHROPIC_API_KEY es para una clave de API. Claude Code la envía como:

x-api-key: <key>

Si tu equipo de gateway solo dice "token" o "Authorization header", empieza con ANTHROPIC_AUTH_TOKEN. Si dicen "API key" o "x-api-key", usa ANTHROPIC_API_KEY. Si adivinaste y recibiste 401, cambia de variable antes de rotar la clave.

No establezcas ambas durante la depuración. Así es como Claude Code ANTHROPIC_AUTH_TOKEN Errors: Complete Configuration Fixes pasa de ser un problema de autenticación a un problema de precedencia de autenticación.

Coloca las variables donde Claude Code realmente las lee

Las exportaciones de shell son buenas para la primera prueba porque son fáciles de deshacer:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"
claude

Solo se aplican a esa sesión de terminal y a los programas lanzados desde ella. Si abres VS Code, una app de escritorio o un agente en segundo plano desde otro lugar, la exportación puede no ser visible.

Para una configuración persistente a nivel de usuario para la CLI, usa ~/.claude/settings.json:

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

Para un solo proyecto, usa .claude/settings.local.json y asegúrate de que esté en gitignore antes de agregar una credencial. No pongas una credencial en .claude/settings.json, porque ese archivo está destinado a compartirse con el repositorio.

Cuando una exportación de shell y un bloque env en un archivo de configuración establecen la misma variable, Claude Code usa el valor del archivo de configuración. Por eso /status es una mejor fuente de verdad que echo $ANTHROPIC_AUTH_TOKEN.

Corrige la extensión de VS Code

La extensión de VS Code de Claude Code tiene sus propias comprobaciones de inicio. Configura las variables del gateway en la configuración de usuario de VS Code bajo claudeCode.environmentVariables:

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

Usa el comando de VS Code Preferences: Open User Settings (JSON). Luego reinicia la sesión de la extensión y ejecuta /status. Si la extensión todavía solicita iniciar sesión, no está viendo la credencial en su propia comprobación de inicio de sesión.

Corrige GitHub Actions

Claude Code GitHub Actions lee ANTHROPIC_BASE_URL del bloque env del flujo de trabajo. Para un gateway x-api-key, pasa la clave del gateway como entrada de la acción:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Para un gateway de token portador, la acción sigue necesitando anthropic_api_key para satisfacer su comprobación de inicio, mientras que ANTHROPIC_AUTH_TOKEN es el valor que Claude Code envía como Authorization: Bearer:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Mantén esos valores en GitHub Secrets. No pegues credenciales del gateway en registros de flujo de trabajo, comentarios de issues ni archivos comprometidos.

Usa /status como comprobación de verdad

Después de cualquier cambio de configuración, ejecuta:

/status

Para un gateway en formato Anthropic, la pestaña Status debería mostrar:

Anthropic base URL: https://llm-gateway.example.com
Auth token: ANTHROPIC_AUTH_TOKEN

o:

Anthropic base URL: https://llm-gateway.example.com
API key: ANTHROPIC_API_KEY

Si falta la fila de base URL, ANTHROPIC_BASE_URL no llegó a la sesión. Si la fuente de credenciales es un inicio de sesión guardado, Claude Code no está usando la credencial del gateway. Si ambos se ven correctos y el mensaje sigue fallando, es probable que el problema esté ahora en el enrutamiento del gateway, la compatibilidad con upstream, el comportamiento del proxy o la confianza en el certificado.

Nota de Flatkey para el enrutamiento del gateway de Claude Code

Flatkey es útil en dos flujos de trabajo distintos de Claude Code, y la distinción importa.

Para llamadas a modelos compatibles con OpenAI desde un proyecto o una skill de agente, la base URL de Flatkey es:

https://router.flatkey.ai/v1

Para la propia ruta de gateway de Claude Code, sigue la configuración del gateway en formato Messages de Anthropic y no añadas /v1 a ANTHROPIC_BASE_URL a menos que las instrucciones propias de Claude Code del gateway te indiquen explícitamente que lo hagas. Un patrón típico del proveedor es:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Luego ejecuta /status, envía un prompt breve y revisa el ledger o los registros del gateway. Mantén la configuración de Claude Code SKILL.md separada de esta ruta: una skill enseña a Claude Code cómo llamar a modelos y herramientas compatibles con Flatkey desde tu repositorio; el enrutamiento del gateway controla a dónde envía Claude Code su propio tráfico de la familia Claude.

Si estás estandarizando el tráfico de agentes entre proveedores, combina este artículo con las guías proxy de Claude API vs router multimodelo y inicio rápido de la API de Flatkey.

Comprobaciones del operador del gateway cuando el token no es el problema real

Algunas búsquedas de Errores de Claude Code ANTHROPIC_AUTH_TOKEN: soluciones completas de configuración comienzan como un problema de configuración local y terminan en el gateway. Si el curl de un solo token se autentica y /status se ve correcto, inspecciona estas condiciones del lado del gateway:

Si tu gateway se sitúa delante de un proveedor que no acepta la forma completa de la solicitud de Anthropic Messages, usa las variables específicas del proveedor en lugar de ANTHROPIC_BASE_URL, o adapta el esquema dentro del gateway. No elimines campos a ciegas; eso cambia un error visible por un fallo de capacidad más adelante.

Registro de depuración que se puede copiar

Usa este registro cuando le pases el problema a un compañero o al operador del gateway:

claude_code_auth_debug:
  date_checked: 2026-09-22
  surface: cli # cli | vscode | github_actions | agent_sdk | desktop
  claude_code_version: ""
  expected_gateway_base_url: "https://llm-gateway.example.com"
  variable_used: "ANTHROPIC_AUTH_TOKEN"
  expected_header: "Authorization: Bearer"
  status_tab_base_url_seen: false
  status_tab_credential_source: ""
  curl_status_code: ""
  curl_response_shape: "json_message | 401 | html_200 | dns_error | tls_error | other"
  settings_files_checked:
    - "~/.claude/settings.json"
    - ".claude/settings.local.json"
    - ".claude/settings.json"
  shell_started_claude: false
  saved_login_present: unknown
  gateway_logs_received_request: unknown
  suspected_fix: ""

Ese registro obliga a separar tres cosas en la investigación: dónde leyó Claude Code la configuración, qué encabezado envió y qué devolvió el gateway.

Preguntas frecuentes

¿Debo usar ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY?

Usa ANTHROPIC_AUTH_TOKEN cuando el gateway espere un token bearer o el encabezado Authorization. Usa ANTHROPIC_API_KEY cuando el gateway espere x-api-key. Si no lo sabes, empieza con ANTHROPIC_AUTH_TOKEN, verifica con la solicitud curl y cambia si recibes 401.

¿Por qué /status no muestra mi base URL?

ANTHROPIC_BASE_URL no llegó al proceso de Claude Code. Inicia claude desde la misma shell, mueve el valor al archivo de configuración correcto o configura la superficie que estás usando, como la configuración de VS Code o el env de GitHub Actions.

¿Por qué curl funciona pero Claude Code sigue pidiéndome que inicie sesión?

La URL base es accesible, pero Claude Code no dispone de una credencial en el momento en que la necesita. Coloque ANTHROPIC_AUTH_TOKEN o la variable de credencial correcta en un export de shell, en la configuración del usuario o en la configuración administrada que Claude Code lee antes de la configuración inicial.

¿Puedo poner el token en .claude/settings.json?

No coloque secretos en .claude/settings.json porque es un archivo compartido del proyecto. Use ~/.claude/settings.json, .claude/settings.local.json, configuración administrada, un gestor de secretos o secretos de CI.

¿ANTHROPIC_AUTH_TOKEN dirige Claude Code a modelos que no son Claude?

No. Solo cambia cómo Claude Code se autentica en la puerta de enlace con formato Anthropic configurada. La puerta de enlace puede enrutar o intermediar las solicitudes según su propia implementación, pero Claude Code sigue esperando la forma de la API de Claude en la ruta ANTHROPIC_BASE_URL.

¿Cuál es la verificación final más segura?

Ejecute la solicitud curl de un solo token, inicie Claude Code desde la superficie configurada, ejecute /status, envíe una breve instrucción y confirme que el registro o los logs de la puerta de enlace muestren la solicitud. Esa comprobación de cuatro pasos es la solución duradera detrás de Errores de Claude Code ANTHROPIC_AUTH_TOKEN: soluciones completas de configuración.

Fuentes consultadas

• Documentación de Anthropic Claude Code: conectar Claude Code a una puerta de enlace LLM, consultado el 2026-09-22.
• Documentación de Anthropic Claude Code: archivos de configuración y precedencia, consultado el 2026-09-22.
• Documentación de Anthropic Claude Code: guía de compatibilidad de la puerta de enlace de Claude Code, consultado el 2026-09-22.
• Centro de ayuda de Claude: administrar variables de entorno de claves de API en Claude Code, consultado el 2026-09-22.
• SKILL.md público de Flatkey, consultado el 2026-09-22.
• Base de conocimiento de Flatkey: descripción del producto, estrategia de marketing, voz de marca.