Guía para Configurar Claude Code en Local con Modelos Alternativos

claude-code-modelos-alternativos.md

Guía para Configurar Claude Code en Local con Modelos Alternativos

⚠️ Nota Aclaratoria: Este documento ha sido creado con fines netamente educativos. Su objetivo es demostrar cómo gestionar configuraciones de línea de comandos, inyectar variables de entorno y comprender la flexibilidad e interoperabilidad de herramientas que utilizan APIs basadas en el estándar de Anthropic.

Introducción

Por defecto, el CLI de Claude Code está diseñado para conectarse a los servidores de Anthropic utilizando su familia de modelos Claude (Opus, Sonnet, Haiku). Sin embargo, su arquitectura permite inyectar variables de entorno para modificar este comportamiento y sobreescribir las rutas de las peticiones.

En este tutorial exploraremos cómo aprovechar esta característica para redirigir las solicitudes del agente hacia otros proveedores de Inteligencia Artificial que ofrecen APIs compatibles. Trabajaremos específicamente con dos proveedores y sus respectivos modelos:

• Z AI (Zhipu AI): Utilizando sus modelos glm-4.7 y glm-4.5-air.
• Minimax AI: Utilizando su modelo unificado MiniMax-M2.1.

El objetivo final de esta guía es estructurar la configuración necesaria y encapsularla en alias de terminal de ZSH. De esta manera, podremos iniciar sesiones de Claude Code con el proveedor que deseemos (Zhipu o Minimax) de forma rápida y sin tener que reescribir manualmente nuestras credenciales o parámetros en cada ejecución.

Requisitos Previos

Antes de comenzar, asegúrate de cumplir con lo siguiente:

1. Claude Code Instalado: Debes tener el CLI de Claude Code instalado en tu máquina.
2. Configuración Inicial: Haber ejecutado la configuración inicial del agente previamente.
3. Consola ZSH: Esta guía asume que utilizas zsh como tu shell principal (común en macOS y muchas distribuciones de Linux).

---

1. Configurar las Variables de Entorno

El primer paso es definir las variables de entorno que almacenarán la URL base, tu token de autenticación y los modelos específicos que deseas usar.

Abre tu archivo de variables de entorno (por lo general ~/.zshenv o directamente en ~/.zshrc) con tu editor de texto favorito:

nano ~/.zshrc

A continuación, añade la configuración del proveedor que desees utilizar (puedes agregar ambos si lo necesitas). Recuerda reemplazar los tokens con tus credenciales reales.

Configuración para Z AI (Zhipu AI)

Añade este bloque para usar Z AI:

# ==========================================
# Variables de Entorno - Z AI (Zhipu AI)
# ==========================================
export Z_AI_BASE_URL="https://api.z.ai/api/anthropic"
export Z_AI_AUTH_TOKEN="TU_TOKEN_DE_Z_AI_AQUI"
export Z_AI_MODEL="glm-4.7"
export Z_AI_MODEL_HAIKU="glm-4.5-air"
export Z_AI_API_TIMEOUT_MS="3000000"

Configuración para Minimax AI

Añade este bloque para usar Minimax AI:

# ==========================================
# Variables de Entorno - Minimax AI
# ==========================================
export MINIMAX_BASE_URL="https://api.minimax.io/anthropic"
export MINIMAX_AI_AUTH_TOKEN="TU_TOKEN_DE_MINIMAX_AQUI"
export MINIMAX_AI_MODEL="MiniMax-M2.1"
export MINIMAX_AI_API_TIMEOUT_MS="3000000"
export MINIMAX_AI_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export MINIMAX_AI_SMALL_FAST_MODEL="MiniMax-M2.1"
export MINIMAX_AI_DEFAULT_SONNET_MODEL="MiniMax-M2.1"
export MINIMAX_AI_DEFAULT_OPUS_MODEL="MiniMax-M2.1"
export MINIMAX_AI_DEFAULT_HAIKU_MODEL="MiniMax-M2.1"

---

2. Entendiendo las Variables de Entorno (Anthropic)

Claude Code está diseñado para conectarse a la API de Anthropic. Para poder usarlo con otros proveedores (como Z AI o Minimax), aprovechamos que sus APIs son compatibles con el estándar de Anthropic y sobrescribimos el comportamiento predeterminado inyectando las siguientes variables:

• ANTHROPIC_BASE_URL: Redirige todas las peticiones de Claude Code al endpoint de tu proveedor alternativo.
• ANTHROPIC_AUTH_TOKEN: La clave de API de tu servicio alternativo.
• ANTHROPIC_MODEL: Define el modelo principal que usará Claude Code.
• ANTHROPIC_DEFAULT_HAIKU_MODEL: Claude Code utiliza modelos diferentes según la tarea. Esta variable especifica qué modelo alternativo debe usar en lugar de Claude 3 Haiku para tareas rápidas y ligeras.
• ANTHROPIC_DEFAULT_SONNET_MODEL: Define el modelo que debe usar en lugar de Claude 3.5 Sonnet para tareas generales.
• ANTHROPIC_DEFAULT_OPUS_MODEL: Define el modelo a usar en lugar de Claude 3 Opus para razonamientos complejos.
• ANTHROPIC_SMALL_FAST_MODEL: Un modelo secundario rápido usado en algunas implementaciones para peticiones de muy baja latencia.
• API_TIMEOUT_MS: Fija el tiempo máximo de espera (en milisegundos) por una respuesta. Lo definimos con un valor alto para evitar desconexiones si el proveedor tarda más de lo habitual.
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Desactiva métricas y reportes telemétricos.

¿Por qué Minimax usa más variables que Z AI?
Para algunos proveedores como Minimax, configuramos explícitamente todas las variables de los modelos (Haiku, Sonnet, Opus, etc.) al mismo modelo (MiniMax-M2.1). Esto garantiza que Claude Code no intente realizar una petición pidiendo un modelo de Anthropic que el proveedor no va a reconocer. En Z AI configuramos dos variantes distintas para simular el comportamiento ligero (Haiku) y el principal.

---

3. Crear los Alias para Invocar Claude Code

Para no tener que pasar todas estas variables cada vez que ejecutes el comando, crearemos un par de alias en tu archivo ~/.zshrc.

Abre tu archivo ~/.zshrc:

nano ~/.zshrc

Y añade los alias correspondientes a las configuraciones que agregaste en el paso anterior. Estos alias inyectan dinámicamente las variables de entorno solo para la ejecución de claude, y utilizan la bandera --dangerously-skip-permissions para omitir confirmaciones de permisos.

Alias para Z AI (Comando zc)

# ==========================================
# Alias para ejecutar Claude Code con Z AI
# ==========================================
alias zc='\
ANTHROPIC_BASE_URL=${Z_AI_BASE_URL} \
ANTHROPIC_AUTH_TOKEN=${Z_AI_AUTH_TOKEN} \
ANTHROPIC_MODEL=${Z_AI_MODEL} \
ANTHROPIC_DEFAULT_HAIKU_MODEL=${Z_AI_MODEL_HAIKU} \
ANTHROPIC_DEFAULT_SONNET_MODEL=${Z_AI_MODEL} \
ANTHROPIC_DEFAULT_OPUS_MODEL=${Z_AI_MODEL} \
API_TIMEOUT_MS=${Z_AI_API_TIMEOUT_MS} \
claude --dangerously-skip-permissions'

Alias para Minimax AI (Comando mnc)

# ==========================================
# Alias para ejecutar Claude Code con Minimax AI
# ==========================================
alias mnc='\
ANTHROPIC_BASE_URL=${MINIMAX_BASE_URL} \
ANTHROPIC_AUTH_TOKEN=${MINIMAX_AI_AUTH_TOKEN} \
ANTHROPIC_MODEL=${MINIMAX_AI_MODEL} \
ANTHROPIC_DEFAULT_HAIKU_MODEL=${MINIMAX_AI_DEFAULT_HAIKU_MODEL} \
ANTHROPIC_DEFAULT_SONNET_MODEL=${MINIMAX_AI_DEFAULT_SONNET_MODEL} \
ANTHROPIC_DEFAULT_OPUS_MODEL=${MINIMAX_AI_DEFAULT_OPUS_MODEL} \
API_TIMEOUT_MS=${MINIMAX_AI_API_TIMEOUT_MS} \
ANTHROPIC_SMALL_FAST_MODEL=${MINIMAX_AI_SMALL_FAST_MODEL} \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=${MINIMAX_AI_CODE_DISABLE_NONESSENTIAL_TRAFFIC} \
claude --dangerously-skip-permissions'

---

4. Aplicar los Cambios

Una vez que hayas guardado y cerrado tu archivo ~/.zshrc, necesitas recargar la configuración de ZSH para que las nuevas variables y alias tengan efecto en tu terminal actual.

Ejecuta:

source ~/.zshrc

5. ¿Cómo utilizarlo?

¡Listo! Ahora tienes configurados comandos cortos para iniciar Claude Code con los distintos proveedores:

• Para iniciar el agente usando Z AI (Zhipu), simplemente escribe en tu terminal:

  zc

• Para iniciar el agente usando Minimax AI, escribe en tu terminal:

  mnc

Ambos comandos iniciarán el agente de Claude Code utilizando las credenciales y el modelo configurado, omitiendo la comprobación de permisos para un flujo de trabajo más rápido.