apiKeyHelper script is failing en Claude Code: causas y 5 soluciones probadas

Claude Code muestra apiKeyHelper script is failing cuando el comando de tu ajuste apiKeyHelper no devuelve una clave válida. Sin clave, la petición sale con una credencial vacía y la API responde 401. Ejecuta tú mismo el comando, corrige lo que reporte (casi siempre una sesión caducada de vault o SSO) y comprueba que imprime solo la clave en stdout y termina con código 0. Reprodujimos el error en Claude Code 2.1.318 el 5 de noviembre de 2026; la salida está más abajo. Las causas y soluciones siguen la referencia oficial de errores de Claude Code.

El mensaje completo es:

Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

Qué significa apiKeyHelper script is failing

apiKeyHelper es un ajuste que contiene un comando de shell. Claude Code lo ejecuta (/bin/sh en macOS y Linux, cmd en Windows) y envía lo que imprime en las cabeceras X-Api-Key y Authorization: Bearer. El error aparece en uno de estos casos:

• el comando terminó con error o agotó el tiempo;
• el comando no imprimió nada en stdout;
• el comando imprimió algo además de la clave, como un banner o una línea de log. Claude Code indica entonces returned output that cannot be used as an API key y explica el problema sin repetir la salida. Antes de la v2.1.227 enviaba lo impreso tras quitar los espacios.

Claude Code vuelve a ejecutar el script y reintenta hasta dos veces más, así que el aviso aparece en tres intentos como mucho. Antes de la v2.1.208 agotaba todos los reintentos y mostraba un 401 genérico. Si no sabes en qué archivo está el helper, nuestra guía de settings.json de Claude Code explica cada ruta y su prioridad.

Nuestra prueba en Claude Code 2.1.318

Conectamos un Claude Code 2.1.318 aislado a una API simulada local, con un helper que escribe un error en stderr y sale con código 1. Este fue el resultado:

$ claude -p "say ok"        # helper script exits 1
Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

# stderr (printed 3 times)
apiKeyHelper failed: exited 1: vault: session expired, run vault login

# what our mock API received (3 requests)
POST /v1/messages  Authorization: "Bearer"  x-api-key: ""  -> 401

El mensaje de stdout coincide palabra por palabra con la documentación. El motivo concreto va a stderr con el prefijo apiKeyHelper failed:, y solo se imprime ahí en modo -p; en una sesión interactiva se lee en /status o en el panel Authentication. Las peticiones fallidas llevaban una cabecera Authorization: Bearer vacía, el comportamiento descrito en el issue #100514 de GitHub (abierto cuando escribimos esto).

Un segundo helper que imprimía una línea de log antes de la clave falló así:

# helper prints "Fetching key from relay..." and then the key
apiKeyHelper failed: returned output that cannot be used as an API key: it contains a line break at character 27 (41 characters on 2 lines). The script must print only the key to stdout.

Cómo solucionar apiKeyHelper script is failing

1. Ejecuta el helper a mano. Copia el comando de apiKeyHelper y lánzalo en la misma terminal. Mira el código de salida y busca texto de más:
2. Vuelve a autenticarte con tu proveedor si el comando dice que la sesión caducó: inicia sesión en tu SSO, ejecuta vault login o renueva la fuente de la que lee el script.
3. Imprime solo la clave. La salida debe ser un único token de ASCII imprimible, de hasta 16.384 caracteres, con código de salida 0. Manda logs y banners a stderr con >&2.
4. Revisa /status. Desde la v2.1.274 la fila apiKeyHelper muestra Failing con el código de salida y el error del script, y desaparece tras la siguiente ejecución correcta.
5. Abre una sesión nueva después del cambio y envía un prompt corto para confirmar.

~/bin/get-gateway-key.sh; echo "exit=$?"
~/bin/get-gateway-key.sh 2>/dev/null | od -c | tail -3

La segunda línea muestra los bytes que salen por stdout. Un \n en medio o texto antes de la clave hará fallar el helper. Los saltos de línea finales no molestan: en nuestra prueba con 2.1.318, una clave seguida de una línea en blanco o de \r\n de Windows funcionó. Un helper que funciona, basado en la guía oficial de gateways:

#!/bin/sh
# send every log line to stderr; stdout carries only the key
echo "fetching key..." >&2
vault kv get -field=api_key secret/llm-gateway/claude-code

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

En Windows, llama a PowerShell de forma explícita y escapa las barras invertidas en el JSON:

{
  "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}

Si el helper está en el .claude/settings.json o settings.local.json de un proyecto, una sesión interactiva no lo ejecuta hasta que aceptas el aviso de confianza del espacio de trabajo.

Por qué /login no lo arregla

La salida del helper tiene prioridad sobre un inicio de sesión de claude.ai mientras el ajuste exista, así que /login no cambia nada. Para volver a la suscripción, borra apiKeyHelper de todos los archivos de configuración. El orden oficial de autenticación es: credenciales del proveedor cloud, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, perfil de Anthropic y /login. Los errores de sesión que sí se arreglan con /login están en nuestra solución al 401 OAuth token has expired.

apiKeyHelper script is failing con un gateway o proxy

Revisa esta sección si el error empezó después de apuntar ANTHROPIC_BASE_URL a un gateway o a un endpoint de terceros, por ejemplo para usar Claude Code con DeepSeek. Si tu clave es fija, no necesitas helper. Ponla en ANTHROPIC_AUTH_TOKEN (Bearer) o ANTHROPIC_API_KEY (x-api-key) y elimina apiKeyHelper:

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

En nuestra prueba, con ANTHROPIC_AUTH_TOKEN definido y un helper roto todavía configurado, la petición funcionó con el token, pero stderr imprimió una vez apiKeyHelper failed:. Borra el helper sobrante para quitar ese ruido. Si tu gateway es LiteLLM, el issue #100514 indica que la cabecera Bearer vacía de un helper fallido vuelve como 401 con Malformed API Key passed in, y eso hace sospechar del gateway cuando el fallo está en el helper.

Preguntas frecuentes

¿Cada cuánto ejecuta Claude Code el helper?

Guarda la salida cinco minutos; puedes cambiarlo con CLAUDE_CODE_API_KEY_HELPER_TTL_MS en milisegundos. También lo vuelve a ejecutar tras un 401 o 403 y, desde la v2.1.246, antes de una petición si el valor guardado es un JWT caducado. Estos dos casos solo aplican si ANTHROPIC_AUTH_TOKEN no está definido (referencia de ajustes).

Mi helper es lento. ¿Puede ser la causa?

Puede. Un comando que agota el tiempo cuenta como fallo. Desde la v2.1.77 Claude Code muestra un aviso si el helper tarda más de 10 segundos. La documentación no indica el tiempo límite exacto, así que no damos una cifra.

¿Dónde veo otros errores de Claude Code?

En nuestra guía de errores de Claude Code. Un mensaje relacionado, Could not resolve authentication method, indica que ninguna credencial llegó al cliente de la API.

Fuentes: referencia de errores de Claude Code, referencia de apiKeyHelper, guía de LLM gateway, issue #100514 de GitHub, changelog de Claude Code (2.1.77, 2.1.208, 2.1.227, 2.1.274). Revisado el 5 de noviembre de 2026 con Claude Code 2.1.318.