Claude Code es una herramienta de programación por línea de comandos de Anthropic. Está diseñada para leer código, editarlo, ejecutar pruebas y refactorizar en la terminal. Llama a la API de Anthropic por defecto, por lo que los desarrolladores en China suelen enfrentarse a tres problemas: acceso inestable al endpoint oficial, métodos de pago restringidos y cuotas y costes de equipo difíciles de gestionar.

ZSQH AI Gateway ofrece un punto de entrada de API unificado: solo necesitas una API Key para llamar a Claude y otros modelos principales a través de una interfaz compatible. Este artículo recorre el proceso completo, desde el registro y la creación de la clave hasta la configuración de la Base URL y la primera ejecución.

Nota: Claude Code se actualiza con frecuencia y las variables de entorno y los nombres de menú pueden cambiar entre versiones. Este artículo usa las versiones habituales a octubre de 2026; consulta claude --help y la documentación oficial para los detalles.

1. Primero, entiende qué interfaz usa Claude Code

Claude Code usa por defecto la API Anthropic Messages, no la API Chat Completions de OpenAI. Al conectar con un gateway de terceros, prepara tres cosas:

  1. Base URL: la dirección del endpoint, por ejemplo https://ai.zhongshangqihang.com.
  2. API Key: un token creado en la consola de ZSQH, que suele empezar por sk-.
  3. Nombre del modelo: por ejemplo claude-sonnet-4-5 o claude-opus-4-1; usa los nombres de modelo que muestre actualmente la página de precios del sitio.

Si usas el SDK de OpenAI u otra herramienta compatible con OpenAI, la Base URL suele necesitar https://ai.zhongshangqihang.com/v1. Cuando Claude Code usa el protocolo Anthropic, introduce la dirección raíz y deja que el cliente añada /v1/messages por sí mismo.

2. Prepara una cuenta y una API Key

1. Regístrate e inicia sesión

Abre ZSQH AI Gateway, registra una cuenta e inicia sesión en la consola.

2. Crea una API Key

Ve a la página "API Keys" de la consola y crea una clave nueva. Recomendaciones:

  • Dale un nombre claro, por ejemplo claude-code-work-laptop.
  • Fija un límite de gasto para que una clave filtrada no pueda usarse de forma abusiva.
  • Fija una fecha de caducidad para que deje de funcionar si no se usa durante un periodo largo.
  • Cópiala y guárdala inmediatamente después de crearla; la clave suele mostrarse completa solo una vez.

3. Confirma tu saldo

Consulta el saldo en la página "Wallet" o "Recarga". Los distintos modelos se facturan de forma distinta; consulta precios de modelos para las tarifas concretas.

3. Configura Claude Code

Opción A: variables de entorno en macOS / Linux

Ejecuta en la terminal:

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_API_KEY="sk-your-key"
claude

Para que se aplique cada vez que abras una terminal, añade las dos líneas a ~/.zshrc o ~/.bashrc y luego ejecuta source ~/.zshrc.

Opción B: Windows PowerShell

$env:ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
$env:ANTHROPIC_API_KEY="sk-your-key"
claude

Opción C: cuando el cliente requiere AUTH_TOKEN

Algunos clientes de terceros o configuraciones de proxy usan ANTHROPIC_AUTH_TOKEN en lugar de ANTHROPIC_API_KEY:

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-key"

Si existen ambas variables, conserva solo la que requiera la documentación del cliente para evitar conflictos en las cabeceras de autenticación. Las distintas versiones de Claude Code admiten estos nombres de variable de forma ligeramente distinta; si ves un 401, comprueba esto primero.

Opción D: configuración a nivel de proyecto

Si no quieres cambiar el entorno global, inyecta las variables de entorno con un archivo .env o un script de arranque en el directorio del proyecto. No subas .env a Git:

# .env.local (do not commit)
ANTHROPIC_BASE_URL=https://ai.zhongshangqihang.com
ANTHROPIC_API_KEY=sk-your-key

Luego carga el archivo antes de iniciar Claude Code. Los métodos de carga varían según el shell; sigue las convenciones de tu proyecto.

4. Elige un modelo

La familia Claude suele tener tres niveles: Opus, Sonnet y Haiku.

Nivel Mejor para Características
Opus Refactorización compleja, agentes de cadena larga, razonamiento difícil Máxima capacidad, normalmente el precio unitario más alto
Sonnet Programación diaria, corrección de errores, revisión de código Un equilibrio entre capacidad y coste
Haiku Autocompletado simple, trabajos por lotes, llamadas de bajo coste Rápido, normalmente un precio unitario inferior

En Claude Code puedes especificar el modelo mediante un parámetro de modelo o una variable de entorno. Para conocer los nombres de modelo realmente disponibles, consulta la página de precios de modelos; un nombre de modelo inexistente suele devolver model not found.

5. Primera llamada y resolución de problemas

Después de configurar, ejecuta esto en el directorio de tu proyecto:

claude

Luego introduce una tarea sencilla, como "explica la estructura de directorios de este proyecto". Si obtienes una respuesta normal, la Base URL, la clave y el modelo funcionan.

Errores comunes:

Error Causa probable Qué hacer
401 Unauthorized Clave incorrecta o caducada, o nombre de variable incorrecto Copia la clave de nuevo; revisa ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN
404 Not Found /v1 sobra o falta en la Base URL Claude Code usa la dirección raíz; el SDK de OpenAI usa /v1
model not found El nombre de modelo no existe o no está habilitado Copia el nombre de modelo actual de la página de precios
429 Too Many Requests Concurrencia o límite de peticiones superado Reduce la concurrencia y reintenta más tarde; revisa la cuota de la clave
insufficient quota Saldo insuficiente Recarga y reintenta
Bloqueado o tiempo de espera agotado Problema de red o proxy Revisa la red, el DNS y la configuración del proxy

6. Cómo controlar el coste y la cuota

Los costes de Claude Code provienen principalmente de los tokens de entrada, los tokens de salida, el contexto largo y la caché. Para controlar el coste:

  1. Crea una clave separada para cada proyecto, con cuota y fecha de caducidad.
  2. Usa Sonnet/Haiku para tareas sencillas y cambia a Opus solo para trabajos complejos.
  3. Evita meter un repositorio grande entero en el contexto de una vez; deja que Claude Code lea primero los archivos relevantes.
  4. Revisa los registros de uso con regularidad para encontrar los proyectos y modelos que más consumen.
  5. Usa un gateway unificado para los equipos para gestionar miembros, claves, cuotas y facturas por separado.

Para tarifas y normas de facturación concretas, consulta precios de modelos. Los precios cambian con las versiones de modelo y las políticas upstream; este artículo no fija cifras para evitar quedar desactualizado.

7. Recomendaciones de seguridad

  • No pongas claves de API en código, capturas de pantalla, repositorios Git ni documentación pública.
  • Fija límites de gasto y fechas de caducidad en las claves.
  • Si sospechas que hay una fuga, elimina la clave antigua de inmediato y crea una nueva.
  • Una clave por persona en un equipo facilita la auditoría y la desactivación.
  • Usa claves separadas para producción y entornos de prueba.

Preguntas frecuentes

¿Son lo mismo Claude Code y la API de Claude?

No. Claude Code es una herramienta de programación; la API de Claude es una interfaz de modelos. Claude Code llama a los modelos a través de la API, y también puedes usar la API de Claude para construir tu propia aplicación.

¿Se puede usar una clave de ZSQH directamente en Claude Code?

Sí, siempre que el cliente use el protocolo compatible con Anthropic y la Base URL, la clave y el nombre de modelo estén configurados correctamente. Consulta las notas de integración del sitio y tu versión actual del cliente para los detalles.

¿Por qué usar un gateway en lugar de una conexión oficial directa?

El valor de un gateway es principalmente un punto de entrada unificado, facturación unificada, gestión de cuotas, uso auditable y cambio multimodelo. Para equipos y acceso desde China, suele ser más fácil de gestionar que hacer que cada miembro solicite una cuenta oficial por separado.

¿Necesito Node.js?

Claude Code suele instalarse mediante npm y requiere un entorno Node.js. Consulta la documentación oficial para las instrucciones de instalación.

Próximos pasos

Si aún no tienes cuenta, regístrate en ZSQH AI Gateway, crea una clave de prueba y configúrala como se describe arriba para ejecutar tu primera tarea. Si tienes problemas con nombres de modelo o facturación, consulta primero precios de modelos y luego usa los registros de uso de la consola para resolver el problema.

Lecturas relacionadas: