Cline es un agente de programación de código abierto muy usado en VS Code. Al conectar una API personalizada, la mayoría de las personas elige OpenAI Compatible en los ajustes e ingresa la Base URL, la clave de API y el ID del modelo. Los errores suelen concentrarse en cuatro capas: credenciales, ruta, límite de frecuencia y red. Cambiar de modelo apenas aparece un aviso en rojo suele convertir un problema de configuración de diez minutos en medio día de trabajo.

Un orden más eficaz es: revisar primero el código de estado y el cuerpo del error, reproducir después con una solicitud mínima y solo al final cambiar el modelo, el contexto o el prompt. Este artículo desglosa uno por uno los errores 401, 404, 429, el contexto excedido, las llamadas a herramientas y los tiempos de espera, y ofrece la ubicación de los registros de Cline y una lista de verificación para soporte.

Nota: Cline es una marca de Cline Bot Inc.; VS Code es una marca de Microsoft Corporation; OpenAI es una marca de OpenAI, Inc. Este artículo solo ofrece una explicación técnica y no implica afiliación ni relación de colaboración con esas empresas. La interfaz, los menús y los mensajes de error pueden cambiar según la versión; toma como referencia la versión que tengas instalada.

1. Orden de diagnóstico: separa capas antes de cambiar la configuración

Síntoma o código de estado Significado habitual Qué revisar primero ¿Reintentar?
401 Clave ausente, incorrecta o vencida Clave, campo del proveedor, estado de la cuenta No
403 La clave no tiene permiso o una política la bloquea Permisos del modelo, ajustes del equipo, saldo No
404 Ruta incorrecta o modelo inexistente Base URL, ID del modelo No
429 Frecuencia, concurrencia o cuota excedidas Consumo, claves compartidas, política de reintentos Sí, con retroceso
400/413 Formato de solicitud incorrecto o contexto demasiado largo Contexto, parámetros, max_tokens Sí, después de corregir
Tiempo de espera o flujo interrumpido Proxy, TLS, tiempo de inactividad, sobrecarga del servidor Ruta de red, configuración de streaming Según el caso
Falla de llamada a herramientas El modelo o el gateway no admiten el protocolo de herramientas Capacidad del modelo, compatibilidad de la interfaz No

Al diagnosticar, fija las variables: la misma clave, la misma Base URL y el mismo ID de modelo, cambiando una sola cosa a la vez. Si cambias tres a la vez, aunque se recupere, no sabrás cuál funcionó.

2. 401 y 403: revisa la clave y después el campo del proveedor

La lista de proveedores de Cline incluye tanto OpenAI como OpenAI Compatible. Para conectar un gateway de terceros normalmente hay que elegir el segundo. Si eliges el primero, la solicitud puede enviarse a la dirección predeterminada de OpenAI y tu clave, naturalmente, no será reconocida.

Revisa en este orden:

  • Si la clave se copió completa y no tiene espacios, saltos de línea ni comillas delante o detrás. Copiar desde una ventana de chat es lo que más fácilmente arrastra caracteres invisibles.
  • Si la clave está en el formulario del proveedor correcto. Los campos de los distintos proveedores de Cline están separados; colocarla en el lugar equivocado produce un 401 directo.
  • Si la clave fue eliminada, deshabilitada o venció, según el estado en la consola del gateway.
  • Si la cuenta tiene saldo disponible. Cuando falta saldo, la respuesta puede ser 401, 402 o 403; guíate por el cuerpo del error.
  • Si la Base URL apunta al entorno al que pertenece la clave. Una clave de prueba configurada con la dirección de producción también suele dar 401.
  • Si la versión de equipo limita las claves personales o los endpoints de terceros. Cuando la política está activa, la configuración local puede ser correcta y aun así fallar.

Verifica primero la dirección y la clave con una solicitud mínima:

export API_KEY="sk-tu-clave"

curl -sS -o /tmp/cline_models.json -w "%{http_code}\n" \
  "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $API_KEY"

head -c 300 /tmp/cline_models.json

Un 200 indica que la dirección, la clave y el protocolo funcionan básicamente; si devuelve 401, prueba la misma clave en la entrada de pruebas de la consola del gateway para distinguir si el problema es de la clave o de los campos o la red de Cline.

3. 404: la Base URL y el ID del modelo se reparten la culpa

Un 404 no siempre significa que el modelo se retiró; la causa más común es una ruta mal escrita:

  • La Base URL omite /v1, la solicitud llega a una ruta web y devuelve HTML o 404.
  • La Base URL incluye /v1/chat/completions y el cliente lo agrega otra vez, duplicando la ruta.
  • Se ingresa /v1/messages de Anthropic en un campo compatible con OpenAI, o al revés.
  • El ID del modelo difiere del gateway en mayúsculas, guiones o sufijo de versión.
  • El modelo no está habilitado para la cuenta, el plan o la región actual.

El botón Verify de Cline sirve sobre todo para confirmar la conectividad de la dirección y la clave; no confirma que cada modelo esté disponible para la cuenta actual. Al final hay que enviar una conversación real para confirmarlo. Si /v1/models devuelve una lista pero la conversación real da 404, sospecha primero del ID del modelo y no de la clave. Lo más seguro es copiar el ID desde la lista de modelos o desde la página de precios de modelos, sin escribirlo a mano.

4. 429: límite de frecuencia, concurrencia y cuota no son lo mismo

El 429 indica que la solicitud superó la tasa, la concurrencia o la cuota de tokens. Escenarios habituales:

  • Se excede el número de solicitudes o de tokens por minuto.
  • Varias personas comparten una clave y se disputan la cuota.
  • El agente lee archivos y ejecuta comandos de forma continua y envía muchas solicitudes en poco tiempo.
  • Los reintentos no tienen retroceso: cuanto más falla, más reintenta, y se forma una tormenta de reintentos.
  • Las solicitudes con contexto largo consumen más cuota y dejan menos espacio para la concurrencia.

Revisa primero las cabeceras y el cuerpo de la respuesta. Si hay Retry-After, espera lo que indica; si no, aplica retroceso exponencial con jitter aleatorio. No reintentes los 401 ni los 404: reintentar solo amplifica el problema. A continuación, un ejemplo reutilizable de manejo de solicitudes:

import random
import time
import httpx

RETRYABLE = {429, 500, 502, 503, 504}

def chat(payload, key, url="https://ai.zhongshangqihang.com/v1/chat/completions"):
    for attempt in range(4):
        try:
            resp = httpx.post(
                url,
                json=payload,
                headers={"Authorization": f"Bearer {key}"},
                timeout=httpx.Timeout(120.0, connect=10.0),
            )
        except httpx.TimeoutException:
            if attempt == 3:
                raise
            time.sleep(min(30, 2 ** attempt) + random.random())
            continue

        if resp.status_code in (400, 401, 403, 404, 413):
            raise RuntimeError(f"{resp.status_code}: {resp.text[:300]}")

        if resp.status_code in RETRYABLE:
            retry_after = resp.headers.get("Retry-After", "")
            wait = float(retry_after) if retry_after.isdigit() else 2 ** attempt
            time.sleep(min(30, wait) + random.random())
            continue

        resp.raise_for_status()
        data = resp.json()
        choice = data["choices"][0]
        if choice.get("finish_reason") == "error":
            raise RuntimeError(f"stream error: {choice.get('error')}")
        return data

    raise RuntimeError("Se agotaron los reintentos")

Este código separa los «errores de autenticación y de ruta que no deben reintentarse» de los «errores de límite y del servidor que sí pueden reintentarse». En las respuestas en streaming, el error puede esconderse en finish_reason mientras el estado HTTP sigue siendo 200, así que hay que revisarlo por separado. El código de producción también debe admitir el formato de fecha HTTP de Retry-After para no fallar al convertirlo directamente a número.

5. Contexto excedido y fallas de llamadas a herramientas

El contexto excedido suele devolver 400 o 413, y el cuerpo del error incluye textos como context_length_exceeded o maximum context length. Cline envía juntos los archivos abiertos, la salida de la terminal, los fragmentos recuperados y el historial de la conversación; el contexto real suele ser más largo de lo que imaginas.

En Model Configuration de Cline, Context Window y Max Output Tokens normalmente deben confirmarse o completarse a mano. Si se configuran más grandes que la capacidad real, la solicitud puede rechazarse; si son demasiado pequeños, Cline puede comprimir el contexto antes de tiempo. Soluciones: crear una tarea nueva, excluir artefactos de compilación y registros, cerrar pestañas que no se usan, resumir primero los documentos largos y reiniciar las conversaciones largas.

Las fallas de llamadas a herramientas son otro tipo de problema. Un endpoint compatible con OpenAI no solo debe poder conversar: también debe admitir el protocolo nativo de tools/function calling. Algunos gateways o modelos solo implementan el chat básico; las preguntas normales funcionan, pero en cuanto el agente intenta leer un archivo puede devolver 400 u otro error. En ese caso, determina primero si «el chat funciona y solo fallan las llamadas a herramientas», y después revisa si el modelo admite llamadas a herramientas y si la capacidad Computer Use está bien configurada en Cline.

6. Tiempos de espera, interrupciones del streaming y fallas de conexión

Los tiempos de espera normalmente no devuelven un código de estado HTTP; se manifiestan como una solicitud sin respuesta durante mucho tiempo, ECONNRESET, errores de certificado o una respuesta que se detiene a la mitad. Causas comunes:

  • Un proxy corporativo o un firewall aplica un tiempo de inactividad a las conexiones largas.
  • El proxy almacena en búfer el SSE y los datos de streaming no se reenvían a tiempo.
  • Una VPN, un programa de seguridad o el DNS bloquea el dominio de la API.
  • La hora del sistema tiene una desviación grande y falla la validación del certificado TLS.
  • La tarea del agente es demasiado larga y una sola solicitud supera el límite de tiempo del cliente o del gateway.

Para diagnosticar, envía primero la misma solicitud con "stream": false. Si la versión sin streaming funciona, el problema está en la cadena de streaming o en el proxy; luego prueba directamente con curl -N para descartar factores del cliente Cline. Cuando un proxy corporativo hace inspección TLS, hay que instalar el certificado raíz de la empresa en la cadena de confianza y, si es necesario, configurar NODE_EXTRA_CA_CERTS. Desactivar http.proxyStrictSSL solo sirve como medida temporal y no se recomienda en producción. Tampoco concluyas que la API funciona porque ping responde: ping no valida TLS, certificados ni rutas.

7. Registros y diagnóstico: guarda evidencia antes de preguntar

En VS Code, abre View → Output y selecciona Cline en el menú de canales de salida para ver los registros en tiempo real de la extensión. En la CLI, los registros suelen estar en ~/.cline/data/logs/cline.log y también se pueden abrir con cline doctor log; en JetBrains, es habitual encontrarlos en ~/.cline/cline-core-service.log. La ruta exacta depende de la documentación de la versión actual.

Un registro útil para el diagnóstico debe incluir al menos: hora, código de estado, código de error, ID del modelo, nombre de host de la Base URL, ID de la solicitud, duración y número de reintentos. El ID de la solicitud suele estar en las cabeceras de respuesta, con nombres como request-id, x-request-id o un campo personalizado del gateway. Al pedir soporte, un registro con el ID de la solicitud es más útil que diez capturas de pantalla.

No registres la clave completa, el prompt completo ni el código del usuario. De la clave conserva solo los primeros y los últimos cuatro caracteres, y desidentifica el contenido sensible. Los propios registros pueden contener fragmentos de código; revísalos antes de compartirlos.

8. Lista de verificación para soporte

  1. Anota el texto original del error, el código de estado, la hora y el ID de la solicitud.
  2. Solicita /v1/models con curl para confirmar si la dirección y la clave funcionan.
  3. Revisa si la Base URL llega hasta /v1 y si hay una ruta duplicada.
  4. Copia el ID del modelo desde la lista y confirma mayúsculas y sufijo de versión.
  5. Prueba con una clave nueva para descartar clave vencida, cuota o políticas de equipo.
  6. Haz primero una solicitud sin streaming y con contexto corto; luego vuelve a agregar streaming y contexto largo.
  7. Cambia de red o de proxy para descartar DNS, TLS y proxy corporativo.
  8. Si todo lo anterior pasa, envía a soporte del gateway o de Cline los registros, los pasos de reproducción y el ID de la solicitud.

9. Preguntas frecuentes

La clave funciona en otro lugar, pero en Cline da 401. ¿Por qué?

Revisa primero si el proveedor está en OpenAI Compatible y después si la Base URL coincide con el entorno al que pertenece la clave. En la versión de equipo, confirma también que no haya una restricción sobre claves personales.

¿Un 404 siempre significa que el modelo se retiró?

No. La mayoría de las veces falta o sobra /v1 en la Base URL, o el ID del modelo está mal escrito. Consulta primero la lista de modelos y luego prueba copiando el ID.

¿Un 429 significa saldo insuficiente?

No necesariamente. El 429 indica que se excedió la tasa, la concurrencia o la cuota; la falta de saldo puede devolver 401, 402 o 403. Guíate por el cuerpo del error.

¿Por qué fallan solo las solicitudes en streaming?

Sospecha primero del búfer del proxy, del tiempo de inactividad y de la reutilización de conexiones. Compara primero con una solicitud sin streaming y luego prueba directamente con curl -N.

¿Dónde se ven los registros de Cline?

En VS Code, ve a View → Output → Cline; en la CLI, consulta ~/.cline/data/logs/cline.log o ábrelo con cline doctor log. Puede variar según la versión y la plataforma; toma como referencia la documentación actual.

Próximos pasos

Primero crea una clave de prueba en ZSQH AI Gateway, ejecuta con los comandos curl de este artículo la autenticación, el modelo y el streaming, y luego ingrésala en Cline. La disponibilidad y los precios de los modelos se rigen por los precios de modelos. Al diagnosticar, fija primero las variables y sustituye después un elemento a la vez.

Lecturas relacionadas:

Nota: Cline es una marca de Cline Bot Inc.; VS Code es una marca de Microsoft Corporation; OpenAI es una marca de OpenAI, Inc. Este artículo solo ofrece un análisis técnico de diagnóstico y no implica afiliación ni relación de colaboración con esas empresas. Los mensajes de error, los menús y el comportamiento de la interfaz pueden cambiar según la versión; toma como referencia la documentación del proyecto.