Cursor es un editor de código con IA ampliamente utilizado. Además de la cuota de modelos incluida, permite introducir tu propia API Key y una Base URL. Para los equipos, conectar Cursor a un gateway compatible con OpenAI aporta tres ventajas: una ruta de acceso estable, facturación centralizada y la posibilidad de cambiar de modelo sin reconfigurar el editor.

Este artículo sigue el orden real de una implementación: preparación, configuración, verificación, límites y despliegue en equipo. Los nombres de los menús pueden variar entre versiones; usa como referencia la pantalla Cursor Settings de la versión que tengas 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. La interfaz, los planes y las reglas de facturación se rigen por las páginas oficiales de Cursor.

1. Distingue primero los dos tipos de "Cursor API"

El primero es la API que ofrece la propia plataforma Cursor, por ejemplo Cloud Agents y las interfaces de administración. La clave se crea en la cuenta de Cursor y sirve para llamar a los servicios de Cursor. El segundo es el modelo "trae tu propia clave" (BYOK): introduces en Cursor la clave de un proveedor de modelos para que el editor use tu cuenta al llamar al modelo. Este artículo trata del segundo caso.

Hay una condición previa que suele pasarse por alto: Cursor reenvía las solicitudes a los modelos desde sus propios servidores, no las conecta directamente desde tu equipo local. Por eso la Base URL debe ser una dirección accesible desde Internet. Un gateway que solo responde dentro de la red corporativa suele agotar el tiempo de espera en el lado de Cursor. ZSQH AI Gateway es un servicio público, por lo que en general no tiene esta limitación.

2. Prepara la clave, la Base URL y el nombre del modelo

Antes de empezar necesitas tres elementos: una API Key, una dirección compatible y un ID de modelo exacto.

  1. Abre la página de registro de ZSQH AI Gateway, regístrate e inicia sesión en la consola.
  2. Entra en "API Keys", crea una clave nueva y asígnale un nombre que indique su uso, por ejemplo cursor-equipo-trabajo.
  3. Define un límite de gasto y una fecha de caducidad. También conviene hacerlo en cuentas personales para evitar consumos anómalos.
  4. Copia la clave y guárdala en un gestor de contraseñas. Por lo general, la consola solo la muestra completa una vez.
  5. Abre Precios de modelos y anota el ID del modelo que vas a usar. Los precios y los modelos cambian; toma como referencia lo que muestre la página en ese momento.

La configuración de los tres valores queda así:

Base URL: https://ai.zhongshangqihang.com/v1
API Key:  sk-... (se crea en la consola y solo se guarda en el gestor de contraseñas)
Modelo:   el ID de modelo que muestre la página de precios en ese momento

La Base URL usa la dirección compatible con OpenAI y termina en /v1. No introduzcas la dirección raíz de Anthropic ni añadas /chat/completions por tu cuenta; de lo contrario es fácil duplicar la ruta.

3. Introduce la configuración en Cursor

La ruta habitual es Cursor Settings → Models → API Keys. Las distintas versiones añaden o quitan opciones, pero los pasos esenciales son similares.

  1. Abre Cursor Settings; el atajo suele ser Cmd/Ctrl + ,.
  2. Entra en Models y despliega la sección API Keys.
  3. Activa OpenAI API Key, pega la clave que acabas de crear 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 de la página de precios y habilita ese modelo.
  6. En el selector de modelos del chat, elige ese modelo y envía una solicitud sencilla.

Si no encuentras Override OpenAI Base URL, significa que la versión o el plan actual no admite dirigir tráfico compatible con OpenAI a una dirección personalizada. En ese caso no insistas: actualiza la versión o cambia a una instalación que incluya esa opción.

El nombre del modelo es un identificador de enrutamiento, no una nota descriptiva. Mayúsculas, guiones y sufijos de versión deben coincidir exactamente con los del gateway. Si lo escribes mal, lo habitual es ver un error de modelo inexistente, un 404 o una solicitud rechazada.

4. Cómo elegir el modelo

Puedes añadir varios modelos personalizados en Cursor, pero el éxito de la solicitud depende de que el gateway ofrezca un modelo con el mismo nombre y admita la forma de llamada correspondiente.

Caso de uso Nivel recomendado Cómo rellenarlo Puntos a tener en cuenta
Preguntas diarias, cambios pequeños Modelo ligero y rápido Copiar el ID de la página de precios Baja latencia; capacidad limitada para refactorizaciones complejas
Cambios en varios archivos, Agent Modelo principal de código Copiar el ID de la página de precios Debe admitir llamadas a herramientas
Diseño de arquitectura, diagnóstico difícil Modelo de mayor capacidad Copiar el ID de la página de precios Mayor coste; úsalo cuando sea necesario
Autocompletado Tab Modelo integrado de Cursor No pasa por la clave personalizada BYOK no cubre el autocompletado

El modo Agent puede depender de la API de Responses o de llamadas a herramientas. Si el gateway solo es compatible con Chat Completions, algunas funciones de Agent fallarán. En ese caso, verifica primero en un chat normal y después determina si el problema es del modelo o de una incompatibilidad de funciones.

Además, Auto, Composer y el autocompletado Tab no necesariamente usan tu clave. Según la página de ayuda de Cursor, el autocompletado Tab siempre utiliza los modelos integrados, y el modo Auto también puede enrutarse por decisión de Cursor. Lo más realista es tratar los modelos personalizados como un canal que solo entra en juego cuando los seleccionas de forma explícita.

5. Verifica que la configuración funciona

No basta con comprobar que Cursor responde, porque la respuesta puede venir del canal integrado. Conviene verificar en el siguiente orden.

  1. Crea una conversación vacía para evitar interferencias del contexto anterior.
  2. Selecciona explícitamente el modelo personalizado en el selector; no uses Auto.
  3. Envía una solicitud corta, por ejemplo, pide que explique un fragmento de código de menos de diez líneas.
  4. Abre el registro de uso o de solicitudes de la consola del gateway y confirma que aparece un registro con la misma hora, el mismo modelo y la misma clave.
  5. Anota el resultado de la verificación. Si el registro no aparece, la solicitud no llegó al gateway y debes revisar la Base URL y el interruptor correspondiente.

Puedes comparar los errores habituales así:

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

6. Límites que debes conocer

  • BYOK cubre principalmente modelos de chat; el autocompletado Tab sigue usando los modelos integrados de Cursor.
  • El alcance de compatibilidad con claves de OpenAI varía según la versión. La página de ayuda de Cursor indica que una clave propia de OpenAI solo cubre modelos de chat estándar sin razonamiento; los modelos de razonamiento y algunas funciones nuevas pueden no estar disponibles.
  • Las solicitudes se reenvían a través de los servidores de Cursor, por lo que el endpoint personalizado debe ser accesible desde Internet.
  • Las solicitudes con clave propia no necesariamente se benefician de la política de retención cero de datos de Cursor; el tratamiento de datos depende del proveedor del modelo y del gateway. Los equipos con requisitos estrictos de retención deben evaluarlo antes.
  • Los planes Team y Enterprise pueden seguir cobrando una tarifa de plataforma de Cursor aunque uses tu propia clave; consulta la página de facturación de Cursor.
  • Cursor se actualiza con rapidez, y los nombres de menú, los modelos compatibles y las reglas de facturación pueden cambiar.

7. Pasos para implementarlo en equipo

  • Haz primero una prueba piloto: elige de tres a cinco desarrolladores, unifiquen un modelo principal y trabajen así durante una semana.
  • Registra tres tipos de datos: tasa de éxito de las solicitudes, latencia media y consumo diario por persona.
  • Crea una clave independiente para cada persona en el gateway, con cuotas por usuario; no uses una clave compartida.
  • Mantén una tabla de mapeo de modelos: qué se introduce en Cursor, qué corresponde en el gateway y a qué modelo cambiar si falla.
  • Documenta la configuración en la documentación interna, incluidos la Base URL, los ID de modelo y el tratamiento de errores comunes.
  • Después de observar los costes, decide qué miembros usan clave propia y cuáles siguen con la cuota del plan. Los precios se rigen por Precios de modelos.
  • Cuando alguien deje la empresa, cambie de equipo o termine un proyecto, deshabilita su clave ese mismo día.

8. Lista de seguridad

  • Una clave por uso; no la reutilices entre dispositivos.
  • Define un límite de gasto y una fecha de caducidad.
  • No escribas la clave en el código, en archivos .env, en capturas de pantalla ni en tickets.
  • No guardes claves de forma permanente en equipos compartidos.
  • Rota las claves con regularidad; si sospechas una fuga, deshabilita primero y luego investiga.
  • En equipo, canaliza todo por el gateway y conserva los registros de solicitudes para auditoría.
  • Para repositorios sensibles, confirma antes si los datos salen del equipo local y a qué servicios se dirigen.

9. Preguntas frecuentes

¿Cursor admite cualquier interfaz compatible con OpenAI?

No necesariamente. Depende de si la versión de Cursor ofrece Override OpenAI Base URL y de si la interfaz es compatible con la ruta y los parámetros que realmente utiliza. Verifica primero en un chat normal y después prueba las funciones de Agent.

Si introduje mi propia clave, ¿por qué sigue pidiendo una suscripción?

Tener tu propia clave no desbloquea todas las funciones. Algunas funciones del editor, la gestión de equipos y los modelos integrados siguen sujetos al plan; consulta las reglas vigentes de Cursor.

¿Por qué el autocompletado Tab no consume mi clave?

Según la página de ayuda de Cursor, el autocompletado Tab siempre usa los modelos integrados de Cursor y no pasa por la clave propia. Es una decisión de diseño del producto, no un error de configuración.

¿La Base URL debe ser la dirección raíz o terminar en /v1?

Con el protocolo compatible con OpenAI, introduce la dirección hasta /v1. No incluyas /chat/completions, o es fácil que se duplique la ruta y aparezca un 404.

¿Puede un equipo compartir una sola clave?

Técnicamente sí, pero no es recomendable. Una clave compartida no permite distinguir el consumo de cada miembro y, si se filtra, es difícil localizar el origen. Una clave por persona, con cuotas y registros, es más seguro.

Siguiente paso

Primero regístrate en ZSQH AI Gateway y crea una clave exclusiva para Cursor; después introduce la Base URL y el modelo según este artículo. Cuando el chat normal funcione, revisa Precios de modelos para ajustar el modelo principal y las cuotas.

Lecturas relacionadas: