Una pasarela para 3 CLI de programación (2026): Configuración y resolución de problemas — Gemini CLI, Codex CLI, Claude Code

Si utiliza CLI de programación a diario, la fricción de configuración se convierte en un coste real: múltiples claves de API, diferentes formatos de configuración, conflictos de autenticación y el clásico bucle de 401/429/stream bloqueado.

¿Busca el camino más corto? Utilice las guías de integración dedicadas (recomendado):

• Claude CLI / Claude Code
• Codex CLI
• Gemini CLI

Empiece aquí (configuración más rápida)

Elija su herramienta y siga la guía dedicada enlazada en la introducción anterior.

TL;DR: Lista de verificación de 5 minutos (elija su herramienta)

Nota: Algunas CLI requieren formas de endpoint ligeramente diferentes (por ejemplo, /v1 o barra final). Siga la guía de cada herramienta para el formato exacto que espera esa CLI.

¿Por qué enrutar las CLI de programación a través de un host de pasarela?

Utilice una pasarela/router cuando desee uno o más de estos beneficios:

1. Dejar de hacer malabares con las claves en múltiples herramientas.
2. Cambiar de modelos/proveedores sin reescribir las configuraciones de las herramientas.
3. Enrutar el tráfico a través de un solo lugar para controles operativos (reintentos/tiempos de espera/auditoría).
4. Mantener su flujo de trabajo estable a medida que las herramientas y los proveedores evolucionan.

Esta guía se centra en la configuración + la realidad operativa: qué se rompe y cómo solucionarlo.

Tabla de decisión: directo al proveedor vs. un único host de pasarela

Antes de comprometerse, aquí está el intercambio real en producción.

Camino A — Codex CLI (proveedor personalizado mediante config.toml)

Pasos mínimos

1. Instalar:

   npm install -g @openai/codex

2. Configure su clave de API:

   export OPENAI_API_KEY="SU_CLAVE_EVOLINK"

3. Crear / editar la configuración ~/.codex/config.toml

4. Verificar:

   codex "Who are you"

Fragmento mínimo de config.toml (ejemplo)

model = "gpt-5.2"
model_provider = "evolink"

[model_providers.evolink]
name = "EvoLink API"
base_url = "https://api.evolink.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Camino B — Claude Code / Claude CLI (settings.json + URL base de Anthropic)

Pasos mínimos

1. Instalar:

   npm install -g @anthropic-ai/claude-code

2. Editar ~/.claude/settings.json

3. Verificar:

   claude "Who are you"

Fragmento mínimo de settings.json (ejemplo)

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "SU_CLAVE_EVOLINK",
    "ANTHROPIC_BASE_URL": "https://api.evolink.ai",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": { "allow": [], "deny": [] }
}

Nota sobre conflictos de autenticación (error común)

Si inició sesión previamente mediante un flujo de suscripción y también configuró una clave de API/token, el comportamiento puede ser inconsistente. Si ve advertencias o un comportamiento de autenticación inesperado:

• Ejecute claude /logout y vuelva a autenticarse de forma limpia, y/o
• Elimine las variables de entorno de Anthropic en conflicto y reinicie su terminal.

Camino C — Gemini CLI (.env + URL base personalizada)

Prerrequisito

Comprobar:

node -v

Pasos mínimos

1. Instalar:

   npm install -g @google/gemini-cli

2. Crear / editar ~/.gemini/.env

3. Verificar:

   gemini "Who are you"

Fragmento mínimo de .env (ejemplo)

GOOGLE_GEMINI_BASE_URL="https://api.evolink.ai/"
GEMINI_API_KEY="SU_CLAVE_EVOLINK"
GEMINI_MODEL="gemini-2.5-pro"

Error conocido: la URL base no surte efecto

• Reinicie su sesión de terminal.
• Confirme que la ruta del archivo .env sea correcta.
• Compruebe el modo de autenticación de la CLI y las sesiones en caché.
• Vuelva a ejecutar con un prompt mínimo para aislar problemas de configuración frente a problemas de prompt/tiempo de ejecución.

¿Por qué los cambios de configuración no surten efecto? (lista de verificación de precedencia)

La mayoría de los problemas de "no cambió" provienen de uno de estos motivos:

1. Ubicación de archivo incorrecta — Codex: ~/.codex/config.toml / Claude: ~/.claude/settings.json / Gemini: ~/.gemini/.env
2. Editó el archivo pero no lo reinició — Reinicie la terminal o el proceso de la CLI.
3. Las variables de entorno anulan la configuración — Especialmente relevante para los conflictos de autenticación de Claude (token frente a inicio de sesión).

Comprobación rápida:

env | grep -E "OPENAI_API_KEY|ANTHROPIC_|GEMINI_|GOOGLE_GEMINI_BASE_URL"

Hoja de trucos para la resolución de problemas (401/403/429/stream/tool-calls/timeout)

401 / 403 (errores de autenticación)

• ¿Está su clave configurada en la variable que lee la herramienta?
  • Codex: OPENAI_API_KEY
  • Claude: ANTHROPIC_AUTH_TOKEN
  • Gemini: GEMINI_API_KEY
• ¿Coincide su URL base con el formato de endpoint utilizado por su guía de integración?

• Vuelva a exportar la variable de entorno y reinicie su shell.
• Vuelva a comprobar la ubicación y la ortografía del archivo de configuración.
• Para Claude: /logout, luego vuelva a autenticarse de forma limpia.

¿Necesita una nueva clave para resolver 401/403? Crear / gestionar clave de API →

429 (límite de frecuencia / cuota / estrangulamiento)

• Reduzca la concurrencia (evite muchas ejecuciones en paralelo).
• Añada pequeños retrasos entre tareas grandes.
• Reintente con backoff exponencial (mejor gestionado por una pasarela/router, cuando esté disponible).

Si el 429 persiste, trátelo como un problema operativo: los patrones de ráfaga, las sesiones de streaming largas o las llamadas a herramientas pesadas pueden amplificar el problema.

Stream bloqueado / salidas largas colgadas

• Pruebe con un prompt corto para validar la conectividad.
• Desactive VPN/proxy temporalmente para aislar problemas de red.
• Vuelva a ejecutar en un directorio limpio (evite contextos de repositorio enormes).

Fallo en tool-calls (el agente intenta ejecutar comandos/archivos)

• La política de permisos bloquea la ejecución.
• Al entorno de la herramienta le faltan dependencias (git, ripgrep, herramientas de construcción).
• Restricciones de ruta/sandbox.

• Confirme la política de permisos de la herramienta y el directorio de trabajo.
• Reproduzca con una acción de herramienta mínima.

Tiempo de espera (Timeout)

• Divida las tareas en prompts más pequeños.
• Reduzca el tamaño del contexto del repositorio.
• Evite sesiones de streaming muy largas para una primera prueba.

Cambio de modelo (rápido)

• Codex CLI: Actualice model = "..." en ~/.codex/config.toml
• Claude Code: Use /model (si lo admite su versión)
• Gemini CLI: Use /model o actualice GEMINI_MODEL en .env

Siguientes pasos

Si utiliza múltiples CLI de programación, la forma más rápida de reducir la fricción es estandarizar en:

• Un único host de pasarela.
• Plantillas de configuración predecibles por herramienta.
• Un manual de resolución de problemas repetible.

Empiece con las guías de integración dedicadas (consulte la introducción anterior).

Preguntas frecuentes

¿Qué es un "endpoint LLM personalizado" para una CLI de programación?

Un endpoint personalizado es una URL base a la que su CLI envía solicitudes en lugar de un endpoint de proveedor predeterminado. En la práctica, puede ser una pasarela/router que expone una o más API de modelos tras un único host.

¿Por qué esta guía muestra diferentes formatos de endpoint (/v1, barra final) para diferentes herramientas?

¿Dónde se encuentra el archivo de configuración de Codex CLI?

¿Cómo configuro una base_url personalizada en Codex CLI?

¿Qué significa wire_api = "responses" en la configuración de Codex?

Indica qué forma de API utiliza la CLI al comunicarse con el endpoint. Manténgalo alineado con su guía de integración.

¿Dónde se encuentra settings.json de Claude Code?

¿Para qué se utiliza ANTHROPIC_BASE_URL?

Establece la URL base a la que Claude Code envía solicitudes, permitiendo el enrutamiento a través de un endpoint personalizado en lugar de un endpoint de proveedor predeterminado.

¿Por qué Claude Code advierte sobre conflictos de autenticación?

¿Desde dónde lee Gemini CLI el archivo .env?

¿Por qué GOOGLE_GEMINI_BASE_URL no surte efecto?

¿Qué versión de Node.js debo usar para Gemini CLI?

Utilice Node.js 20+.

¿Cómo soluciono rápidamente el error 401/403 cuando uso un endpoint personalizado?

Verifique que la variable de clave correcta esté configurada, confirme el formato del endpoint y reinicie la terminal. Para Claude, también elimine los conflictos de autenticación cerrando sesión o eliminando las variables.

¿Qué significa 429 en las CLI de programación?

Normalmente indica límite de frecuencia o estrangulamiento de cuota. Reduzca la concurrencia, añada retrasos y reintente con backoff exponencial.

Mi CLI transmite la salida y luego se cuelga. ¿Qué debería intentar primero?

Pruebe con un prompt corto, desactive VPN/proxy temporalmente y reduzca el tamaño del contexto del repositorio. Divida las tareas grandes en prompts más pequeños.