Claude Code es la herramienta de programación por línea de comandos de Anthropic y, por defecto, se conecta a la interfaz oficial de Anthropic. En la práctica, muchos equipos la apuntan a un gateway propio o de terceros para resolver la estabilidad del acceso, la facturación unificada y la gestión de cuotas. Eso que llamamos “conectar una API personalizada” consiste, en esencia, en cambiar solo tres cosas: a dónde se envían las peticiones (Base URL), con qué identidad se autentican (clave) y qué modelo se invoca (nombre del modelo).

Este artículo recorre un proceso reutilizable en este orden: instalación, variables de entorno, archivo de configuración, elección de modelo, verificación de la conexión, despliegue en equipo y seguridad. Los comandos están pensados para macOS y Linux; Windows se indica por separado.

Nota: Claude y Anthropic son marcas de sus respectivos titulares. Este artículo solo describe la integración técnica y no implica relación de afiliación con esos fabricantes. Claude Code se actualiza con frecuencia, y las variables de entorno, las opciones de configuración y los nombres de menú pueden cambiar entre versiones; toma como referencia claude --help, la documentación oficial y las instrucciones de acceso del sitio.

1. Confirma tres cosas antes de empezar

Claude Code utiliza el protocolo Anthropic Messages, no el protocolo Chat Completions de OpenAI. Por lo tanto, una API personalizada debe cumplir al menos dos condiciones: ofrecer un punto de entrada /v1/messages compatible con Anthropic y usar nombres de modelo que coincidan con los que realmente expone el gateway. Un gateway que solo tenga un punto de entrada compatible con OpenAI no sirve directamente para Claude Code, salvo que también ofrezca una ruta compatible con Anthropic.

Antes de comenzar, prepara tres elementos:

  • Base URL: la dirección raíz del gateway, por ejemplo https://ai.zhongshangqihang.com. Si incluye /v1 o no depende de la implementación del gateway; consulta las instrucciones de acceso del sitio.
  • Clave de API: se crea en la consola, con un límite de cuota y una fecha de expiración. No uses una clave permanente sin límite para las pruebas.
  • Nombre del modelo: cópialo de la consola o de la página de precios; no lo escribas de memoria. Un solo carácter mal puesto, mayúscula o guion incluido, puede devolver un error de modelo inexistente.

Si todavía no tienes cuenta, puedes empezar por el registro y crear primero una clave de prueba con cuota baja.

2. Instala Claude Code

Claude Code suele distribuirse mediante npm, aunque también ofrece otras formas de instalación. Este es el flujo más habitual:

  1. Verifica que Node.js esté instalado. Se recomienda una versión LTS que siga recibiendo mantenimiento; consulta la documentación oficial para la versión mínima exacta.
  2. Ejecuta npm install -g @anthropic-ai/claude-code para instalar de forma global.
  3. Ejecuta claude --version para confirmar que el comando funciona y anota el número de versión.
  4. Entra en un directorio de proyecto de prueba, ejecuta claude y completa la configuración inicial que se te pida, como el tema y la confianza en el directorio.
  5. Si el equipo exige control de versiones, fija una versión concreta y documéntala en la guía de inicio; antes de actualizar, valida la nueva versión en un proyecto de prueba.
node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

Cuando se usa una API personalizada, normalmente no hace falta iniciar sesión con una cuenta de Anthropic, pero si se omite el inicio de sesión depende de la versión y de la forma de configuración. Si al arrancar todavía te pide iniciar sesión, comprueba primero que las variables de entorno estén activas en la misma shell desde la que lanzas Claude Code.

3. Variables de entorno: BASE_URL y AUTH_TOKEN

Claude Code lee dos variables de autenticación habituales:

  • ANTHROPIC_BASE_URL: la dirección raíz de las peticiones.
  • ANTHROPIC_AUTH_TOKEN: se envía como Authorization: Bearer, lo habitual en accesos a través de un gateway.
  • ANTHROPIC_API_KEY: se envía como x-api-key, más cercano al método de autenticación nativo de Anthropic.

Basta con elegir una de las dos últimas. Si el gateway autentica con Bearer, usa ANTHROPIC_AUTH_TOKEN; si autentica de forma nativa, usa ANTHROPIC_API_KEY. Cuando ambas están definidas a la vez, la prioridad puede variar según la versión y aparece el clásico “lo configuré bien pero devuelve 401”; se recomienda dejar solo una.

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-tu-clave"
claude

Escribir estas líneas en ~/.zshrc o ~/.bashrc hace que la configuración persista; después ejecuta source ~/.zshrc. En Windows PowerShell se usa $env:ANTHROPIC_BASE_URL="...", que solo afecta a la ventana actual; para que sea permanente, usa la interfaz de variables de entorno del sistema o setx y vuelve a abrir la terminal.

No incluyas los export en un script del proyecto ni los confirmes en el repositorio. Una vez que una clave entra en el historial de Git, borrar el archivo no equivale a borrar el registro.

4. settings.json: fija la configuración en un archivo

Las variables de entorno son útiles para cambios temporales; para un uso prolongado conviene escribir la configuración en el archivo de ajustes de Claude Code. Hay tres niveles habituales:

  • Nivel de usuario: ~/.claude/settings.json, aplica a todos los proyectos de la máquina.
  • Nivel de proyecto: .claude/settings.json, se puede confirmar en el repositorio y sirve para compartir configuración no sensible con el equipo.
  • Nivel de proyecto local: .claude/settings.local.json, no se confirma y sirve para anulaciones personales.

Ejemplo:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-tu-clave"
  },
  "model": "claude-sonnet-4-5"
}

Atención: la clave dentro de settings.json queda en texto plano. Es aceptable en un equipo personal, pero no lo hagas en máquinas compartidas, CI ni repositorios de código. En los archivos de nivel de proyecto deja solo la Base URL y el nombre del modelo; la clave debe ir en variables de entorno o en un gestor de secretos. La prioridad de configuración, a grandes rasgos, va de la configuración empresarial a los argumentos de línea de comandos, el proyecto local, el proyecto y el usuario, en ese orden de anulación; consulta la documentación de la versión actual para el detalle exacto.

5. Elección de modelo: por niveles

Los modelos de Claude suelen dividirse en tres niveles, adecuados para tareas distintas:

Nivel Uso típico Compromiso
Opus Refactorizaciones complejas, análisis entre archivos, agentes de cadena larga Más capacidad, normalmente mayor costo y posiblemente más lentitud
Sonnet Programación diaria, corrección de errores, revisión de código Equilibrio entre capacidad y costo; buena opción por defecto
Haiku Autocompletado simple, formateo, tareas pequeñas en lote Rápido y económico, pero se queda corto en tareas complejas

En Claude Code puedes indicar el modelo principal con ANTHROPIC_MODEL, o sobrescribir la asignación de cada nivel con ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL y ANTHROPIC_DEFAULT_HAIKU_MODEL. No todas las versiones admiten las mismas variables; antes de configurar, revisa claude --help o la documentación oficial.

El nombre del modelo debe coincidir con el catálogo del gateway. Es posible que el gateway use su propia denominación para los modelos de origen, así que copiar el nombre de la documentación oficial no siempre acierta. Consulta los modelos disponibles y la facturación en precios de modelos; los precios cambian según la versión del modelo y las políticas del proveedor.

6. Verifica la conexión: primero curl, después Claude Code

Antes de involucrar a Claude Code, comprueba con curl si el gateway responde:

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Responde solo OK"}]
  }'

Si el gateway autentica con Bearer, cambia x-api-key por Authorization: Bearer $ANTHROPIC_AUTH_TOKEN. Si devuelve 200 y el contenido es correcto, significa que al menos una combinación de Base URL, clave y modelo funciona.

Después vuelve a Claude Code y revisa en orden:

  1. claude --version para confirmar que el cliente se puede ejecutar.
  2. En el directorio del proyecto, ejecuta claude doctor (si la versión actual ofrece ese comando) para revisar la instalación y la configuración.
  3. Inicia claude y usa /status para ver el modelo actual y la información de la cuenta.
  4. Envía una tarea de bajo riesgo, por ejemplo “explica la estructura de este directorio sin modificar archivos”.
  5. Observa si la respuesta llega con normalidad y si aparecen errores 401, 404 o de modelo inexistente.

Correspondencia de síntomas habituales:

Síntoma Qué revisar primero Qué hacer
401 Clave, nombre de variable, encabezados Copiar de nuevo la clave; dejar una sola variable de autenticación
404 Base URL con /v1 de más o de menos Ajustar a la dirección raíz o al punto de entrada compatible según la documentación del gateway
model not found Nombre del modelo distinto del catálogo Copiarlo de la consola o de la página de precios
Tiempo de espera agotado Red, DNS, proxy Probar otra red; comprobar si el proxy reescribe encabezados
429 Límite de concurrencia o de cuota Reducir la concurrencia; revisar el límite de la clave

7. Despliegue en equipo: una clave por persona, un punto de entrada

En un equipo no conviene compartir una sola clave. Lo más seguro es:

  • Una clave por persona, con un nombre que incluya el nombre o el uso, para poder desactivarla cuando alguien deje la empresa.
  • Límites de cuota por proyecto o entorno, separando producción de pruebas.
  • Un gateway unificado para consultar consumo, distribución de modelos y llamadas anómalas.
  • Configuración empresarial que distribuya la Base URL y los modelos permitidos, para reducir errores de configuración manual.
  • Una guía de inicio con los pasos de conexión, los comandos de verificación y los errores frecuentes.
  • Una revisión semanal o mensual del consumo, con acción inmediata ante claves anómalas.

Si la empresa tiene procesos de compras y cumplimiento, confirma primero el flujo de datos: los fragmentos de código se envían al gateway y a los servicios de modelos subyacentes. Si se conservan, durante cuánto tiempo y si se usan para entrenamiento son cuestiones que dependen de los términos del servicio; no lo des por sentado.

8. Límites de seguridad: claves, código y datos

Por último, algunas reglas básicas:

  • La clave no debe entrar en Git, imágenes, código de frontend, capturas de pantalla ni historiales de chat.
  • Añade un .gitignore al proyecto que cubra al menos .env, .env.* y .claude/settings.local.json.
  • Si sospechas una filtración, revoca primero la clave antigua y después revisa el consumo; no te limites a cambiar la contraseña.
  • Asigna una fecha de expiración a cada clave y rótalas cuando cambie el personal.
  • En máquinas compartidas, usa un gestor de secretos o apiKeyHelper; no escribas texto plano en settings.json.
  • Instala Claude Code solo desde fuentes confiables y revisa las notas de cambios antes de actualizar.

Preguntas frecuentes

¿Claude Code siempre requiere iniciar sesión con una cuenta de Anthropic?

No necesariamente. Con una Base URL y una variable de autenticación válidas, el cliente puede usar directamente la API personalizada; aun así, pueden aparecer asistentes iniciales como el tema y la confianza en el directorio. Si hace falta iniciar sesión depende de la versión y de la configuración; ante un problema, comprueba primero que las variables estén activas en la shell de arranque.

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

La primera suele enviarse en el encabezado x-api-key; la segunda, como Authorization: Bearer. Cuál usar depende del método de autenticación del gateway; se recomienda definir solo una para evitar conflictos de encabezados.

¿La Base URL debe ser la dirección raíz o incluir /v1?

Claude Code normalmente usa la dirección raíz y el cliente añade /v1/messages; algunos gateways piden el punto de entrada compatible directamente. La forma sencilla de saberlo es probar con curl la dirección raíz más /v1/messages: si funciona, usa la raíz; si no, ajusta según la documentación del gateway.

¿Por qué curl funciona pero Claude Code da error?

Las causas habituales son que las variables de la shell no llegan a la interfaz gráfica o a la terminal integrada del IDE, o que hay dos variables de autenticación definidas a la vez. Ejecuta echo $ANTHROPIC_BASE_URL en la misma terminal desde la que inicias Claude Code para confirmarlo.

¿Puede el equipo compartir una sola clave?

Técnicamente sí, pero no se recomienda. Una clave compartida no permite distinguir el consumo por persona y, si se filtra, es difícil identificar al responsable. Una clave por persona, con cuota y fecha de expiración, reduce el costo de gestión.

Próximos pasos

Si aún no tienes una cuenta de gateway, empieza por el registro, crea una clave de prueba con cuota baja y valida con los dos pasos de este artículo: curl y Claude Code. Los modelos y la facturación están en precios de modelos; los precios se ajustan con el tiempo, así que toma como referencia la información en tiempo real de la página.

Lecturas relacionadas: