Al configurar modelos personalizados en Cursor, la clave es a la vez un pase de acceso y el límite del coste y la seguridad. Si creas claves sin criterio, las consecuencias habituales son consumos anómalos, imposibilidad de atribuir el uso por miembro y claves antiguas que siguen activas después de que alguien deja la empresa.

Este artículo ofrece una lista de control ejecutable en el orden "crear, vincular, mapear, verificar, rotar, prevenir fugas y política de equipo". Los nombres de la interfaz cambian según la versión; usa como referencia la pantalla Cursor Settings de la versión instalada.

Aviso: Cursor es una marca registrada de Anysphere, Inc. Este artículo tiene fines exclusivamente técnicos y no implica afiliación ni representación con Cursor o Anysphere. Las funciones del producto y las reglas de facturación se rigen por las páginas oficiales de Cursor.

1. Confirma qué tipo de clave vas a configurar

La expresión "Cursor API Key" se usa a menudo para tres cosas distintas:

  • API Key de la plataforma Cursor: sirve para Cloud Agents, interfaces de administración y otros servicios propios de Cursor; se crea en la cuenta de Cursor.
  • Clave de proveedor de modelos: la que emiten OpenAI, Anthropic, Google, Azure o AWS Bedrock, entre otros, y que se introduce en la sección API Keys de Cursor.
  • Clave de gateway: la emite un servicio compatible como ZSQH AI Gateway, suele empezar por sk- y permite llamar a varios modelos mediante el protocolo compatible con OpenAI.

Este artículo trata de la configuración de la tercera en Cursor. No sirve para iniciar sesión en Cursor ni para llamar a las interfaces de la plataforma Cursor. La clave del gateway debe introducirse en OpenAI API Key y sobrescribir la Base URL; si la pones en los campos específicos de Anthropic o Google, normalmente no funcionará.

2. Crea la clave: define primero los límites y luego copia

Antes de crear una clave, aclara tres cosas: para quién es, en qué proyecto se usará y cuánto consumo máximo se permite. Si lo decides de antemano, la gestión posterior será mucho más sencilla.

  1. Abre la página de registro de ZSQH AI Gateway e inicia sesión en la consola.
  2. Entra en "API Keys" y crea una clave nueva.
  3. Incluye en el nombre el usuario y el dispositivo, por ejemplo cursor-zhang-macbook; no escribas solo test.
  4. Define un límite de gasto y una fecha de caducidad; si la consola permite limitar modelos, restringe los disponibles según el proyecto.
  5. Recarga saldo y confirma el importe disponible para no descubrir al final que no puedes llamar a la API.
  6. Copia la clave en el gestor de contraseñas; no la envíes primero por herramientas de chat ni por tickets.

Guarda el registro en el gestor de contraseñas con un formato como este, que facilita la rotación y el traspaso:

Uso: cursor-equipo-trabajo
Base URL: https://ai.zhongshangqihang.com/v1
Clave: sk-... (solo se guarda en el gestor de contraseñas)
Modelo: el ID de modelo que muestre la página de precios en ese momento

Por lo general, la clave solo se muestra completa una vez. Si la pierdes, crea una nueva y elimina la anterior; no intentes recuperarla. Los modelos y los precios cambian; consulta Precios de modelos.

3. Vincula la clave en Cursor

La ruta habitual es Cursor Settings → Models → API Keys. Presta atención al estado de guardado en cada paso.

  1. Abre Cursor Settings; el atajo suele ser Cmd/Ctrl + ,.
  2. Entra en Models y despliega API Keys.
  3. Activa OpenAI API Key, pega la clave y pulsa Save.
  4. Activa Override OpenAI Base URL e introduce https://ai.zhongshangqihang.com/v1.
  5. Pulsa + Add Custom Model (en algunas versiones aparece como + Add model), introduce el ID de modelo exacto y habilítalo.
  6. Selecciona ese modelo en el chat y envía una solicitud corta de prueba.

Tres errores frecuentes:

  • Escribir la Base URL como la dirección del sitio web https://ai.zhongshangqihang.com, sin /v1.
  • Escribir la Base URL hasta /chat/completions, lo que duplica la ruta y devuelve 404.
  • Poner la clave del gateway en los campos de Azure OpenAI o Bedrock. Esos campos corresponden a la autenticación de cada servicio en la nube y no sirven para un gateway compatible normal.

Si tu versión no tiene Override OpenAI Base URL, significa que no admite direcciones compatibles personalizadas. No intentes evitarlo modificando otros campos: actualiza la versión o cambia a una que incluya esa opción.

4. Mapa de modelos: convierte el "nombre" en una tabla mantenible

El nombre del modelo no es un texto de presentación, sino un identificador de enrutamiento. Conviene que el equipo mantenga una tabla de mapeo que incluya, como mínimo, el uso previsto, el ID que se introduce en Cursor, el modelo correspondiente en el gateway, los límites de capacidad y la fecha de retirada.

Uso En Cursor se introduce Referencia en el gateway Punto clave de verificación
Preguntas diarias ID de modelo ligero Modelo con el mismo nombre en la página de precios Nombre exactamente igual
Trabajo principal de código ID del modelo principal Modelo con el mismo nombre en la página de precios Admite llamadas a herramientas
Tareas de contexto largo Modelo de contexto largo Modelo con el mismo nombre en la página de precios Límite de contexto
Reserva ante fallos ID de modelo de reserva Modelo con el mismo nombre en la página de precios Se puede cambiar manualmente

No uses el nombre comercial en lugar del ID ni adivines el sufijo de versión. Si te equivocas, lo habitual es ver un error de modelo inexistente, un 404 o una solicitud rechazada. Cuando el gateway cambie un modelo, actualiza también Cursor y la documentación interna.

5. Verificación: configuración, solicitud y facturación

No verifiques solo si "hay respuesta", porque la respuesta puede venir del canal integrado. Revisar en tres niveles es más fiable.

  1. Nivel de configuración: confirma que la clave está guardada, que la Base URL termina en /v1 y que el modelo personalizado está habilitado.
  2. Nivel de solicitud: crea una conversación vacía, selecciona explícitamente el modelo personalizado y envía una solicitud corta.
  3. Nivel de facturación: abre el registro de uso o de solicitudes de la consola del gateway y confirma que aparece un registro con la hora, el modelo y la clave correspondientes. Si no hay registro, la solicitud no llegó al gateway.

Comparación de errores habituales:

  • 401 o 403: clave incorrecta, deshabilitada o cuota agotada.
  • 404: ruta de Base URL incorrecta o nombre de modelo inexistente.
  • 429: límite de velocidad alcanzado o tope de cuota.
  • Tiempo de espera agotado: endpoint inaccesible o problema en la ruta de red.
  • Chat normal funciona y Agent falla: puede ser una incompatibilidad de capacidades de la interfaz, no necesariamente un problema de la clave.

Durante las pruebas, puedes crear una clave aparte con cuota baja y sustituirla por la clave definitiva cuando la verificación funcione, para no pegar la clave real una y otra vez en distintas ventanas.

6. Rotación, revocación y gestión de incidentes

Conviene rotar las claves con una periodicidad fija, por ejemplo cada 90 días, o de inmediato cuando cambie un miembro o un dispositivo. Rotar no es borrar y recrear, sino ejecutar primero en paralelo y después cambiar.

  1. Crea una clave nueva con los mismos permisos y un sufijo de fecha en el nombre.
  2. Sustituye la clave en Cursor y guarda.
  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 asegurarte de que no queda ningún cliente sin migrar.
  5. Deshabilita la clave antigua y elimínala después de un tiempo prudencial.

Si sospechas una fuga, invierte el orden: deshabilita o elimina primero la clave; después investiga el consumo anómalo, el origen y el intervalo de tiempo; luego avisa al equipo, revisa repositorios y registros y, si es necesario, rota otras credenciales relacionadas. Cuando alguien deja la empresa o cambia de equipo, deshabilita su clave ese mismo día, sin esperar a la próxima auditoría.

7. Prevención de fugas: por dónde se escapa una clave

  • Código y archivos de configuración: .env, configuraciones de contenedores y notebooks pueden acabar en un commit. Usa herramientas de gestión de secretos y escanea antes de confirmar cambios.
  • Capturas y grabaciones de pantalla: la página de configuración muestra la clave completa. Tápala antes de capturar y no abras el campo de la clave durante una demostración.
  • Chats y tickets: no envíes la clave completa a compañeros ni al soporte. Cuando necesites identificarla, indica solo el nombre o los últimos cuatro caracteres.
  • Sincronización de ajustes del IDE y extensiones: revisa el alcance de la sincronización y los permisos de las extensiones; los equipos corporativos deberían tener una lista blanca clara.
  • Equipos compartidos: usa cuentas de sistema independientes, no marques la opción de guardado permanente y cierra la sesión al terminar.
  • Registros y reportes de errores: los registros de depuración pueden incluir cabeceras de solicitud. Elimina la información de autenticación antes de enviarlos.
  • Ruta de transmisión: según la página de ayuda de Cursor, la clave se envía cifrada con la solicitud a los servidores de Cursor y no se conserva; sin embargo, una clave propia no necesariamente se beneficia de la política de retención cero de datos. Usa una clave dedicada con cuota limitada.

8. Política de equipo: claves gestionables

  • Una clave por persona; los servicios compartidos deben tener su propia clave, sin mezclarse con las personales.
  • Define de forma uniforme límites de gasto, fechas de caducidad y listas blancas de modelos.
  • Canaliza el acceso por un gateway unificado siempre que sea posible y conserva registros de usuario, modelo y consumo.
  • Revisa cada mes: claves sin uso prolongado, claves por encima de la cuota y aumentos anómalos de autenticaciones fallidas.
  • Define niveles de datos: los repositorios sensibles solo deben usar modelos y canales previamente evaluados.
  • Incluye la creación, el traspaso y la deshabilitación de claves en las listas de incorporación y salida.
  • Los planes de equipo pueden cobrar además una tarifa de plataforma aunque uses tu propia clave; calcula el coste según la página de facturación de Cursor y Precios de modelos.

9. Lista de diagnóstico

  • La clave se pegó con espacios o saltos de línea: bórrala y vuelve a copiarla completa.
  • La Base URL incluye /chat/completions de más: déjala solo hasta /v1.
  • Al nombre del modelo le falta el sufijo de versión: cópialo tal cual de la página de precios.
  • Cuota de la clave agotada: revisa el saldo y el límite en la consola y ajústalos si es necesario.
  • Restricción del plan: confirma si el plan actual de Cursor permite claves propias y las funciones relacionadas.
  • Endpoint inaccesible: confirma que la Base URL es pública y prueba con una solicitud simple fuera del navegador.
  • Agent falla pero el chat normal funciona: sospecha primero de una incompatibilidad de capacidades, no de una clave inválida.
  • El autocompletado Tab no usa la clave: según Cursor, el autocompletado usa los modelos integrados; es el comportamiento esperado.

10. Preguntas frecuentes

¿Cuál es la diferencia entre una API Key de Cursor y una clave de API de modelo?

La primera suele ser la clave emitida por la plataforma Cursor para sus propias interfaces; la segunda la emite un proveedor de modelos o un gateway para llamar a los modelos. Este artículo configura la segunda; no se pueden mezclar.

¿Puedo limitar una clave a un solo modelo?

Depende de si la consola del gateway ofrece configuración de alcance o permisos de modelos. Si no la ofrece, al menos usa una clave independiente con límite de gasto para acotar el impacto y comprueba en los registros qué modelo se llama realmente.

¿Rotar la clave interrumpe las conversaciones en curso?

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 después deshabilitar la clave antigua.

¿Qué hago primero si se filtra una clave?

Deshabilita o elimina la clave y luego investiga el consumo anómalo y el origen de las llamadas. No dediques primero tiempo a confirmar cómo se filtró: contener el daño es prioritario. Después revisa repositorios, registros e historiales de chat y, si procede, rota otras credenciales.

¿La cuota gratuita alcanza para probar?

Depende de las promociones vigentes en la consola y de Precios de modelos. Para probar, usa una clave con cuota baja y limita la prueba a la conectividad y al nombre del modelo; no uses tráfico real de negocio como experimento.

Resumen

Configurar la clave de Cursor no es complicado; lo difícil es gestionarla a largo plazo: nombres trazables, cuotas con límite, modelos con mapa y capacidad de contener una fuga. Primero regístrate en ZSQH AI Gateway y crea una clave exclusiva para Cursor; cuando funcione, ve ajustando los permisos según la política del equipo.

Lecturas relacionadas: