Al conectar modelos personalizados en Cline, la clave es a la vez el pase de entrada y el límite del costo y la seguridad. Crear claves sin criterio suele terminar en consumo anómalo, uso imposible de atribuir, claves antiguas que siguen activas después de una salida y, peor aún, claves que llegan a una copia de seguridad o a un repositorio junto con el archivo de configuración.

Este artículo presenta una lista de trabajo en el orden «creación, varios modelos, almacenamiento, rotación, permisos, equipo y diagnóstico». La interfaz y la forma de almacenamiento pueden cambiar según la versión; toma como referencia la versión actual y la documentación oficial.

Nota: Cline es una marca de Cline Bot Inc. Este artículo solo ofrece una explicación técnica y no implica afiliación, representación ni respaldo de Cline Bot Inc. Las funciones, la interfaz y las reglas de facturación del producto se rigen por la documentación oficial de Cline.

1. Aclara qué significa «clave de API de Cline»

La expresión se usa a menudo para tres cosas distintas:

  • Credencial de la plataforma Cline: sirve para el sistema de cuentas o la interfaz de la plataforma de Cline; la cuota la decide el lado de Cline.
  • Clave del proveedor de modelos: la emiten OpenAI, Anthropic, Google u otros proveedores y se ingresa en el campo del proveedor correspondiente en Cline.
  • Clave de gateway: la emite un servicio compatible como ZSQH AI Gateway; suele comenzar con sk- y permite llamar a varios modelos mediante el protocolo compatible con OpenAI.

Este artículo trata la tercera. No sirve para iniciar sesión en Cline ni para llamar a la interfaz de la plataforma Cline. La entrada correcta es OpenAI Compatible, no los campos específicos de OpenAI, Anthropic o Azure.

2. Crear una clave: define límites antes de copiar

Antes de crearla, decide para quién es, en qué proyecto se usará y cuánto consumo máximo se permite.

  1. Abre la página de registro de ZSQH AI Gateway e inicia sesión en la consola.
  2. Entra a «Claves de API» y crea una clave nueva.
  3. Incluye en el nombre el usuario, el dispositivo y el uso, por ejemplo cline-zhang-macbook-daily; no escribas solo test.
  4. Configura el límite de cuota y la fecha de expiración; si la consola permite limitar modelos, restringe los disponibles según el proyecto.
  5. Confirma el saldo y la cuota para no descubrir al terminar la configuración que no puedes llamar al modelo.
  6. Copia la clave al gestor de contraseñas; no la envíes primero por un chat o un ticket.

Conviene registrarla con este formato para facilitar la rotación y la entrega:

Uso: cline-zhang-macbook-daily
Base URL: https://ai.zhongshangqihang.com/v1
Key: sk-... (guardar solo en el gestor de contraseñas)
Modelo: el ID que muestre la página de precios de modelos
Cuota: según el presupuesto del proyecto
Expiración: 2027-01-31

La clave suele mostrarse completa una sola vez; si se pierde, crea una nueva y deshabilita la anterior. Los modelos y precios cambian; usa los precios de modelos como referencia.

3. Cómo configurar varios modelos

En la extensión de VS Code, API Provider, Base URL y modelo suelen formar una configuración vigente; para cambiar de modelo normalmente hay que hacerlo en los ajustes o en el selector de tareas. Que se puedan guardar varias configuraciones por proyecto depende de la versión actual y de la documentación oficial.

La forma más confiable de gestionar varios modelos es del lado del gateway: usa claves distintas para escenarios distintos y separa los usos mediante cuotas, alcance de modelos y registros. Así, incluso si alguien modifica la configuración de una máquina, el impacto queda acotado.

Escenario de uso Nivel de modelo Estrategia de clave Observaciones
Preguntas diarias y cambios pequeños Modelo ligero y rápido Clave personal exclusiva Bajo costo; capacidad limitada en tareas complejas
Edición principal y tareas de agente Modelo principal de código Clave personal exclusiva Debe admitir llamadas a herramientas
Diseño de arquitectura y diagnóstico difícil Modelo de alta capacidad Clave de proyecto, con aprobación según el caso Mayor costo; limita el alcance de uso
Automatización, CI y scripts Modelo de versión estable Clave de servicio independiente Cuota separada; no mezclar con claves personales
Pruebas temporales Modelo de bajo costo Clave de corta duración Configura la expiración más breve posible

En escenarios de línea de comandos puedes usar cline auth para configurar el proveedor, la clave, el modelo y la Base URL; los parámetros pueden cambiar según la versión, así que revisa primero la ayuda local:

export ZSQH_API_KEY="sk-... (inyectar desde el gestor de contraseñas, no escribir en el script)"
cline auth -p <provider-id> -k "$ZSQH_API_KEY" \
  -m <model-id> -b https://ai.zhongshangqihang.com/v1

Ten en cuenta que la clave pasada con -k puede guardarse como configuración persistente de ese proveedor. Úsala solo en máquinas de confianza y confirma que el historial del shell, la lista de procesos y los registros no dejen texto plano. La CLI permite aislar el directorio de configuración con --config, --data-dir o las variables CLINE_DIR y CLINE_DATA_DIR.

4. Dónde se guarda la clave

Las versiones recientes guardan la configuración global en ~/.cline/data/settings/:

  • providers.json: configuración de proveedores; la documentación oficial indica que incluye la clave de API.
  • global-settings.json: ajustes globales generales.
  • cline_mcp_settings.json: configuración de servidores MCP, que puede contener tokens de servicios de terceros.

La configuración por proyecto suele estar en .cline/, en la raíz del repositorio, e incluye reglas, flujos de trabajo, hooks, agentes y otros elementos. Distintas versiones pueden usar el almacén de secretos de VS Code o un directorio de datos unificado; no supongas que la clave siempre está cifrada.

Por eso hay que tratarla como un «archivo sensible local»:

  • Activa el cifrado del disco y el bloqueo de pantalla, y limita los permisos locales.
  • No pongas ~/.cline en un disco público, un repositorio de código ni una copia de seguridad compartida.
  • Antes de hacer commit, revisa .vscode/, .cline/, .clinerules y los scripts para confirmar que no haya claves.
  • Los tokens de la configuración MCP se gestionan igual que las claves.
  • Tapa la página de ajustes al tomar capturas, grabar pantalla o compartir el escritorio en asistencia remota.
  • Antes de sincronizar la configuración, confirma el alcance de la herramienta y el método de cifrado, y luego decide si incluyes archivos con claves.

5. Rotación y revocación

Se recomienda rotar cada 90 días, o de inmediato ante cambios de personal, cambio de dispositivo o sospecha de filtración. La rotación se hace primero en paralelo y luego se cambia; no consiste en borrar y recrear.

  1. Crea una clave nueva con los mismos permisos y agrega la fecha al nombre.
  2. Reemplaza la clave en los ajustes de Cline o actualiza la configuración del proveedor en la CLI.
  3. Envía una solicitud de prueba y confirma que el registro del gateway muestra la clave nueva.
  4. Observa durante un tiempo la tasa de errores y el consumo para confirmar que no quede ningún cliente sin actualizar.
  5. Deshabilita la clave anterior y elimínala después de conservarla un tiempo.

Si sospechas una filtración, el orden es el inverso: deshabilita o elimina primero la clave, luego revisa consumo anómalo, origen y periodo, y después avisa al equipo y revisa repositorios y registros. Ante una salida o un cambio de equipo, deshabilita la clave ese mismo día; no esperes la próxima auditoría.

Antes de rotar, inventaría los lugares donde se usa la clave: extensión de VS Code, CLI, CI, otros editores y scripts temporales. Si solo cambias la clave del IDE, la anterior puede seguir activa en tareas automatizadas.

6. Permisos mínimos y política de equipo

  • Una clave por persona: una clave compartida no permite distinguir el consumo y, si se filtra, es difícil localizarla. Los servicios compartidos llevan una clave aparte.
  • Una clave por uso: separa el desarrollo diario, la automatización y las pruebas temporales para facilitar el límite y la desactivación.
  • Configura límites: cuota, expiración y alcance de modelos siempre que sea posible; como mínimo, los dos primeros.
  • Entrada centralizada: conecta preferentemente mediante un gateway unificado que conserve registros de miembros, modelos y consumo para auditoría y atribución de costos.
  • Mantén un inventario: registra solo el nombre de la clave, el titular, el uso, la fecha de creación y la de expiración; nunca la clave completa.
  • Audita periódicamente: cada mes revisa claves sin uso prolongado, claves con exceso de consumo y aumentos anómalos de fallos de autenticación.
  • Proceso de ingreso y salida: incluye la creación, la entrega y la desactivación de claves en las listas de incorporación y salida.
  • Clasifica los datos: define qué repositorios pueden usar qué modelos y canales; evalúa primero los proyectos sensibles.
  • Controla los permisos del agente: la aprobación automática y el modo YOLO amplifican los errores y el riesgo de inyección de instrucciones; el equipo debe fijar permisos predeterminados y excepciones aprobadas.
  • Revisa extensiones y MCP: instala solo de fuentes confiables; los hooks, complementos y servidores MCP pueden ejecutar código o acceder a la red.

Para calcular costos, usa los precios de modelos como referencia. No juzgues si algo es caro por la impresión de una sola tarea; cuenta el volumen de solicitudes, la longitud del contexto y el nivel del modelo.

7. Lista de diagnóstico de fallas

  • 401 o Invalid API Key: la clave es incorrecta, está deshabilitada o se pegó con espacios o saltos de línea. Bórrala y vuelve a copiarla completa.
  • 403: se agotó la cuota, la clave no tiene permisos suficientes o el modelo no está permitido.
  • 404 o Model Not Found: la ruta de la Base URL es incorrecta o el ID del modelo no existe. Conserva la dirección hasta /v1 y no agregues /chat/completions.
  • 429: se activó el límite de frecuencia o se alcanzó la cuota de la clave. Revisa el consumo y los límites en la consola.
  • Tiempo de espera agotado: el endpoint no es accesible, hay un problema en la ruta de red o un proxy bloquea la conexión. Confirma primero la conectividad con una solicitud simple.
  • Contexto excedido: revisa si la ventana de contexto configurada en Cline coincide con las especificaciones reales del modelo y reduce el alcance de la tarea.
  • El chat normal funciona pero las operaciones del agente fallan: sospecha primero de un modelo sin soporte de llamadas a herramientas, no de una clave inválida.
  • La CLI funciona pero la extensión falla: pueden leer directorios de configuración distintos; revisa por separado ~/.cline y la configuración del proyecto actual.
  • Falla justo después de cambiar la clave: confirma que se guardó y verifica en el registro del gateway si la clave nueva recibe solicitudes.

8. Preguntas frecuentes

¿Dónde se guarda la clave de Cline y es segura?

En las versiones recientes está en ~/.cline/data/settings/providers.json, que contiene la configuración del proveedor y la clave de API; los ajustes MCP pueden contener tokens adicionales. La documentación oficial no promete cifrado, así que trátala como un archivo sensible, activa el cifrado del disco y evita sincronizarla con lugares públicos.

¿Una clave puede usarse con varios modelos?

Normalmente sí, siempre que el gateway permita que esa clave llame a esos modelos. La posibilidad de limitar el alcance depende de la consola; si no existe, controla el impacto con cuotas y registros, y crea claves separadas para los modelos de mayor costo.

¿Cómo puede el equipo compartir modelos sin exponer la clave?

No entregues la misma clave a todos. Lo más confiable es que cada persona cree su propia clave en el gateway, con una Base URL y una tabla de modelos comunes, y que un administrador gestione cuotas, registros y desactivaciones. Los servicios compartidos llevan una clave propia con cuota limitada.

¿La rotación afecta las tareas en ejecución?

Las solicitudes ya enviadas pueden no verse afectadas, pero las siguientes usarán la clave nueva. Conviene cambiar en horas de baja actividad, enviar de inmediato una solicitud de prueba y luego deshabilitar la clave anterior. En tareas largas, confirma antes si se pueden interrumpir.

¿Qué hacer primero si se filtra una clave?

Deshabilita o elimina la clave para limitar el daño y después investiga el consumo anómalo y el origen de las llamadas. No empieces confirmando cómo se filtró. Luego revisa repositorios, registros, historiales de chat y copias de seguridad, y rota otras credenciales si es necesario.

Resumen

Configurar la clave de Cline no es complicado; lo difícil es gestionarla a largo plazo: nombres rastreables, cuotas con límite, almacenamiento protegido y capacidad de limitar el daño ante una filtración. Primero regístrate en ZSQH AI Gateway y crea una clave exclusiva para Cline; cuando funcione, ajusta poco a poco los permisos según la política del equipo y revisa los costos periódicamente con los precios de modelos.

Lecturas relacionadas: