La API Key de Claude Code no es solo una cadena de texto: determina a nombre de quién se factura cada petición, qué modelos se pueden invocar y cuánto impacto tiene una filtración. La mayoría de los errores 401 no se deben a que la clave esté invalidada, sino al nombre de la variable, al encabezado de autenticación o al nivel de configuración.

Este artículo sigue este orden: cadena de autenticación, creación de la clave, variables de entorno y archivos de configuración, varios conjuntos de configuración, rotación, prevención de fugas, uso en CI y equipos, y diagnóstico de errores 401. Los nombres de variables y las opciones concretas dependen de la versión actual de Claude Code y de la documentación del gateway.

Nota: Claude y Anthropic son marcas de sus respectivos titulares; este artículo solo tiene fines técnicos y no implica relación de afiliación con esos fabricantes. La interfaz, los permisos y los precios se rigen por la documentación oficial de cada plataforma y por las páginas del sitio.

1. Entiende primero la cadena de autenticación de Claude Code

Cuando Claude Code arranca, envía las peticiones a ANTHROPIC_BASE_URL con información de autenticación. Esa información suele provenir de una de dos variables:

  • ANTHROPIC_AUTH_TOKEN: se envía como Authorization: Bearer, frecuente en accesos a través de un gateway.
  • ANTHROPIC_API_KEY: se envía como x-api-key, más cercano al método nativo de Anthropic.

Cuando el gateway recibe la petición, usa la clave para localizar la cuenta correspondiente y después comprueba saldo, cuota, permisos de modelo y vigencia. Si falla cualquiera de esos eslabones, el resultado puede aparecer como 401, 403 o 429. Por eso, al diagnosticar no conviene fijarse solo en la cadena de la clave.

Otro malentendido frecuente es vincular la clave al modelo. La clave es la identidad; el modelo es un parámetro de la petición. Una misma clave suele poder invocar varios modelos, según los permisos de la cuenta y la política del gateway.

2. Crear la clave: cinco pasos

  1. Abre ZSQH AI Gateway o la plataforma que utilices, regístrate e inicia sesión en la consola.
  2. Entra en la página de claves de API y pulsa crear. Escribe un nombre que indique entorno y uso, por ejemplo claude-code-work-mac.
  3. Define un límite de cuota y una fecha de expiración. Para una clave de prueba, empieza con una cuota baja y ajústala cuando conozcas el consumo real.
  4. Si la plataforma admite listas de modelos permitidos o ámbitos de proyecto, marca solo los modelos que necesita Claude Code.
  5. Copia la clave completa y guárdala de inmediato en un gestor de contraseñas o de secretos. La mayoría de las consolas solo muestra el valor completo una vez.

Las claves suelen empezar por sk-, pero el prefijo no demuestra autenticidad ni indica permisos. Al copiar, revisa los espacios y saltos de línea al principio y al final; es una causa muy frecuente de 401.

Después de crearla, valídala con una petición curl mínima antes de distribuirla entre los miembros del equipo. El método de validación se explica más adelante, en la sección de diagnóstico de 401.

3. Variables de entorno y archivos de configuración: cómo elegir

Método Cuándo conviene Ventajas Atención
Variables de shell Máquina personal, cambios temporales No se guardan en el proyecto; cambiar es rápido Una terminal o IDE nuevos pueden no leerlas
settings.json de usuario Uso personal prolongado Se configura una vez y aplica a todo La clave queda en texto plano
settings.local.json de proyecto Anulación en un solo proyecto No afecta a otros proyectos; se puede excluir de git Hay que reconfigurar al cambiar de máquina
apiKeyHelper o gestor de secretos Equipos, máquinas compartidas, cumplimiento La clave no aparece directamente en el archivo Requiere scripts y gestión de permisos adicionales
Variables secretas de CI Canalizaciones automatizadas Separadas del código; auditables Cuidado con el enmascarado de logs y los permisos de rama

Las variables de entorno sirven para “probarlo ahora mismo”; settings.json, para “usar esta máquina así de forma permanente”; el gestor de secretos, para “la clave no puede estar en texto plano en el disco”. Se pueden combinar, pero hay que saber cuál anula a cuál. La prioridad de configuración de Claude Code va, a grandes rasgos, de la configuración empresarial a los argumentos de línea de comandos, el proyecto local, el proyecto y el usuario, con posibles ajustes entre versiones; consulta la documentación oficial.

Un error fácil de cometer: exportar la variable en ~/.zshrc y luego lanzar Claude Code desde el Dock o desde el IDE, donde no se lee. Los programas con interfaz gráfica heredan el entorno de inicio de sesión y no siempre cargan la configuración de tu shell. En ese caso, modifica settings.json o inyecta la variable explícitamente en el script de arranque.

4. Varios conjuntos de configuración: separa personal, proyecto y equipo

Se recomienda tener al menos tres claves: uso personal diario, uso exclusivo del proyecto y automatización. Tienen cuotas, permisos y ciclos de rotación distintos; mezclarlas dificulta tanto el análisis del consumo como la localización de fallos.

Si no quieres mantener varios archivos de configuración, puedes inyectar la configuración por escenario con funciones de shell:

# ~/.zshrc
claude_work() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_WORK_KEY" \
  claude "$@"
}

claude_test() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_TEST_KEY" \
  claude "$@"
}

Las claves reales van en ~/.zshrc.local o en un gestor de secretos; el archivo principal solo referencia variables. Así, para cambiar de entorno basta con cambiar el nombre de la función, sin tocar el código del proyecto.

Para aislar un proyecto, usa .claude/settings.local.json y confirma que esté incluido en .gitignore. El .claude/settings.json compartido por el equipo solo debe contener elementos no sensibles, como la Base URL, el nombre del modelo y los permisos; nunca la clave.

5. Rotación de claves: cuándo y cómo

El objetivo de la rotación no es cumplir un trámite, sino reducir la ventana de exposición tras una filtración. Conviene rotar en estas situaciones: salida o cambio de puesto de un empleado, pérdida de un dispositivo, sospecha de filtración, exigencia de un proveedor y un ciclo fijo. El ciclo puede fijarse según los requisitos de cumplimiento del equipo, por ejemplo cada 90 días.

  1. Crea una clave nueva en la consola con la fecha en el nombre, por ejemplo claude-code-prod-2026-10.
  2. Guarda primero la clave nueva en el gestor de secretos o en las variables de entorno; no borres todavía la antigua.
  3. Valida una vez con curl y otra con Claude Code para confirmar modelo, cuota y permisos.
  4. Revisa los registros de consumo de la clave antigua y comprueba que no queden scripts ni miembros usándola.
  5. Desactiva la clave antigua y observa la tasa de errores durante uno o dos días.
  6. Registra la fecha de rotación, el responsable y el alcance del cambio para facilitar el siguiente traspaso.

No hagas la rotación en horas de máxima carga de producción. Mantener dos claves en paralelo durante un tiempo es mucho más seguro que “borrar y volver a crear”.

6. Prevención de fugas: de la máquina de desarrollo al repositorio

La ruta habitual de una fuga de claves no es un ataque informático, sino una confirmación propia, una captura, una grabación de pantalla, un mensaje de grupo o un registro mal escrito. Puedes seguir estas pautas:

  • Que .gitignore cubra .env, .env.*, .claude/settings.local.json, *.pem y similares.
  • Antes de confirmar cambios, usar secret scanning o un hook de pre-commit para detectar patrones como sk-.
  • No escribir claves por defecto en el código ni depurar con echo $ANTHROPIC_AUTH_TOKEN.
  • Enmascarar encabezados como Authorization y x-api-key en los registros.
  • Cerrar el historial de la terminal o limpiar la pantalla antes de compartir pantalla o hacer capturas.
  • Restringir permisos de archivos en la máquina de desarrollo, por ejemplo chmod 600 ~/.claude/settings.json.
  • Usar claves con expiración y límite de cuota para reducir el daño de una filtración puntual.

Si confirmas una filtración, el orden es: desactivar o eliminar primero la clave, crear después una nueva y, por último, revisar los registros de consumo y el historial del repositorio. Cambiar solo la contraseña o borrar solo el archivo no basta, porque la clave antigua puede haberse copiado en otro lugar.

7. Uso en CI y en equipo

El principio en CI es que “la clave no entra en el código, ni en la imagen, ni en los registros”. En la práctica:

  • Usa la función de secretos o de variables de entorno de la plataforma; no escribas la clave en texto plano dentro del YAML.
  • Limita el secreto a ramas protegidas o flujos de trabajo de confianza.
  • Antes de registrar, confirma que no se imprimen encabezados; la mayoría de las bibliotecas HTTP no lo hacen por defecto, pero un registro personalizado podría hacerlo.
  • Usa una clave separada para tareas automatizadas, con su propia cuota, para localizar anomalías con facilidad.
  • Una clave por miembro del equipo, desactivada el mismo día de la salida; no uses una clave compartida para ahorrar esfuerzo.
  • Exporta el consumo con regularidad y revísalo por miembro, proyecto y modelo.

Si la plataforma admite credenciales de corta duración u OIDC, dales prioridad para reducir el almacenamiento de claves permanentes. La disponibilidad depende de las capacidades de cada plataforma; consulta la documentación antes de integrar.

8. Diagnóstico de 401: revisa en este orden

Un 401 indica un fallo de autenticación, no necesariamente una clave incorrecta. Sigue este orden; normalmente el problema se localiza en pocos minutos:

  1. Confirma a qué Base URL se envían las peticiones con echo $ANTHROPIC_BASE_URL. Un valor vacío o una dirección antigua provocará fallos.
  2. Comprueba que la clave no tenga espacios, saltos de línea ni comillas sobrantes; cópiala de nuevo desde la consola.
  3. Verifica el nombre de la variable: ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY, sin definir ambas a la vez.
  4. Confirma que el encabezado coincide con lo que exige el gateway: Bearer o x-api-key.
  5. Comprueba que la clave no esté expirada ni desactivada y que la cuenta tenga saldo.
  6. Verifica que el nombre del modelo exista en el catálogo del gateway; algunas plataformas devuelven 401 o 403 para modelos sin permiso.
  7. Si hay un proxy de por medio, revisa si elimina o reescribe el encabezado Authorization.
  8. Reproduce con un curl mínimo para descartar interferencias de la versión de Claude Code o del nivel de configuración.

Correspondencia de errores habituales:

Error Causa frecuente Qué hacer
401 (autenticación fallida) Clave incorrecta, nombre de variable erróneo, encabezado inadecuado Copiar de nuevo; dejar una sola variable de autenticación
403 Forbidden La clave no tiene permiso de modelo o hay restricción por IP Revisar listas de permitidos y permisos de modelo
404 Not Found Base URL o ruta incorrecta Validar la dirección raíz y /v1 por separado
429 Too Many Requests Concurrencia o cuota superada Reducir concurrencia; revisar el límite de la clave
insufficient quota Saldo insuficiente Recargar o cambiar de clave

Si curl funciona y Claude Code sigue devolviendo 401, revisa el entorno de arranque: la terminal integrada del IDE, Docker, systemd o launchd pueden no heredar las variables de tu shell. Escribir la configuración en settings.json o en el script de arranque suele resolverlo.

Preguntas frecuentes

¿La clave de Claude Code es la misma que la membresía web de Claude?

No. La membresía web es una suscripción al producto de chat; la API Key es una credencial de identidad para la interfaz. Claude Code usa llamadas a la API, así que la membresía web no sustituye a la clave.

¿Puedo usar la misma clave en Claude Code y en Cursor?

Técnicamente suele ser posible, siempre que ambas herramientas admitan el mismo protocolo de gateway y los mismos nombres de modelo. Aun así, se recomienda separar las claves por herramienta para poder limitar cuotas, diagnosticar y desactivar por separado.

¿Es seguro guardar la clave en settings.json?

En un equipo personal es aceptable, porque el archivo solo está en la máquina. En máquinas compartidas, repositorios y CI no pongas claves en texto plano; usa variables de entorno, apiKeyHelper o un servicio de gestión de secretos.

¿Hay que detener el servicio para rotar la clave?

No. Crea y valida primero la clave nueva, cambia después la configuración y desactiva por último la antigua. Mantener ambas en paralelo durante un tiempo evita interrupciones en las peticiones.

¿Por qué funcionaba ayer y hoy devuelve 401?

Las causas habituales son expiración de la clave, saldo insuficiente, cuota agotada, desactivación por un administrador, un cambio en el método de autenticación del gateway o un entorno de arranque que no carga las variables más recientes. Revisa cada punto en el orden de diagnóstico de 401.

Próximos pasos

Si todavía no tienes una clave, crea una de prueba con cuota baja desde el registro y configúrala y valídala en el orden de este artículo. Los modelos, las cuotas y la facturación están en precios de modelos; los precios cambian según la versión del modelo y las políticas del proveedor, así que toma como referencia la información en tiempo real de la página.

Lecturas relacionadas: