Cómo conectar Cursor a OpenRouter: configuración, límites de funciones y solución de errores
Guía para configurar Cursor con OpenRouter, demostrar la ruta mediante Activity, probar Chat, Agent, Tab y tools por separado y diagnosticar endpoint, modelo, saldo y límites.
Índice
La conclusión principal es esta: recibir una respuesta en Cursor no demuestra que todas sus funciones estén usando OpenRouter. A 4 de octubre de 2026, OpenRouter sigue marcando la integración con Cursor como Beta y exige el Base URL dedicado https://openrouter.ai/api/v1/cursor. Las solicitudes del modelo en Chat y Agent pueden pasar por esa ruta cuando eliges manualmente un modelo de OpenRouter. Tab Completion no usa tu API Key personalizada, y las llamadas a herramientas dependen tanto del endpoint como de la compatibilidad del modelo con tools.
La prueba correcta no es “pegar la clave y obtener texto”, sino una cadena de evidencias: ajustes correctos → modelo elegido manualmente → solicitud mínima → registro coincidente en OpenRouter Activity → pruebas separadas de Agent y tools. Esta guía se basa en la documentación oficial actual y no afirma haber probado una cuenta, clave o versión concreta de Cursor de extremo a extremo.
Qué funciones usan realmente la clave personalizada
| Función de Cursor | Ruta esperada | Límite importante | Cómo verificar |
|---|---|---|---|
| Modelo elegido manualmente en Chat o Ask | Normalmente OpenRouter | El modelo debe estar disponible por la ruta OpenAI-compatible de OpenRouter | Enviar un prompt mínimo y comparar hora y modelo en Activity |
| Modelo elegido manualmente en Agent | La llamada al modelo suele pasar; no se demuestra cada acción interna | La guía permite elegir el modelo en Agent, pero no documenta todas las solicitudes auxiliares | Observar el registro de Activity y las acciones visibles de herramientas |
| Tab Completion | No | Tab sigue usando modelos integrados de Cursor | No usar las sugerencias de Tab como prueba de OpenRouter |
| Tools dentro de Agent | Condicional | Se necesita /cursor y un modelo compatible con tools | Verificar Chat primero y luego ejecutar una tarea de solo lectura |
| Selección automática | Mala evidencia para aceptación | El cliente puede elegir otra ruta | Desactivar Auto y seleccionar el modelo añadido |
Hay que distinguir una solicitud al modelo de la ejecución de una herramienta. La documentación de tool calling de OpenRouter explica que el modelo propone la llamada y el cliente ejecuta la herramienta. Un registro en Activity prueba la solicitud al modelo, pero no demuestra por sí solo que leer un archivo o ejecutar un comando ocurriera en OpenRouter.
Requisitos previos
- Una versión actual de Cursor con
Cursor Settings→Models→API Keys. - Tu propia API Key de OpenRouter. No la pegues en chats, repositorios, capturas ni mensajes de soporte.
- El Model ID exacto copiado del catálogo actual de OpenRouter.
- Para tools de Agent, un modelo confirmado en el filtro de modelos con tools.
Los botones pueden cambiar entre versiones: activar, guardar, confirmar o verificar. La relación de campos es la misma: la clave va en OpenAI API Key, el endpoint en Override OpenAI Base URL y el modelo usa el ID completo de OpenRouter.
Configuración paso a paso
1. Abre los ajustes de API Keys
Ve a Cursor Settings → Models, expande API Keys y localiza OpenAI API Key y Override OpenAI Base URL.
2. Introduce la clave de OpenRouter
Pega en OpenAI API Key la clave creada en tu cuenta de OpenRouter. Hazlo solo en la interfaz de ajustes y completa la acción de guardar, activar o validar que muestre tu versión.
3. Usa el endpoint específico de Cursor
Activa Override OpenAI Base URL e introduce:
https://openrouter.ai/api/v1/cursor
No uses el genérico https://openrouter.ai/api/v1 ni añadas /chat/completions. El endpoint /cursor normaliza el formato de Cursor; con el endpoint genérico pueden fallar tools y otros formatos.
4. Añade el Model ID exacto
En Models, selecciona + Add model y copia el ID completo desde la página actual del modelo. Si utilizas un alias de router, copia su sintaxis completa. No uses un nombre comercial, abreviatura o ID de una guía antigua.
5. Selecciona el modelo manualmente
Vuelve a Chat o Agent y elige explícitamente el modelo añadido. No uses selección automática durante la primera prueba, porque una respuesta no revelaría qué ruta la atendió.
Cómo demostrar que funciona
Envía en Chat una solicitud mínima sin código ni secretos, por ejemplo pedir una frase fija. Abre enseguida OpenRouter Activity y comprueba:
- la hora coincide con la prueba;
- el modelo registrado coincide con el Model ID seleccionado;
- la solicitud terminó correctamente y tiene datos de uso;
- la evidencia interna no contiene la clave, el prompt completo ni código sensible.
La respuesta en Cursor es una evidencia débil; un registro coincidente en Activity es una evidencia de ruta más sólida. Si hay respuesta pero no registro, marca la ruta como no confirmada.
Para equipos, conserva solo hora, modelo, estado, identificador necesario, versión de Cursor y modo de prueba. Así podrás repetir la validación si cambia el comportamiento Beta.
Prueba Chat, Agent, Tab y tools por separado
Chat: crea primero una línea base
Elige manualmente el modelo y envía un prompt corto y determinista. Chat solo pasa la prueba cuando aparece el registro correspondiente en Activity. Si falla, no avances a Agent, porque añade variables de contexto, permisos y herramientas.
Agent: separa ruta del modelo y ejecución local
Usa un repositorio desechable o fácil de restaurar. Pide primero una tarea de bajo riesgo, como leer el README y proponer mejoras, sin autorizar escrituras ni comandos destructivos. Comprueba dos señales independientes:
- Activity contiene la solicitud al modelo.
- Cursor muestra la lectura de archivo u otra acción esperada.
La primera demuestra la ruta del modelo; la segunda demuestra la orquestación de Agent. La documentación no prueba que cada solicitud auxiliar de Agent use siempre la misma clave, por lo que un éxito no debe generalizarse a todo el tráfico interno.
Tab: que no aparezca en Activity es normal
Una sugerencia de Tab solo prueba Tab Completion. La documentación oficial indica que las claves personalizadas funcionan con modelos de chat y que Tab sigue usando modelos integrados. “Chat aparece en Activity y Tab no” es el resultado esperado.
Tools: valida endpoint y capacidad del modelo
Después de validar Chat, elige un modelo que incluya tools en sus capacidades. En un repositorio de prueba, solicita una acción de solo lectura, como listar archivos o leer un archivo pequeño. Si Chat funciona y tools no, revisa:
- Base URL exactamente
https://openrouter.ai/api/v1/cursor; - soporte explícito de
toolsen el modelo; - que Cursor no haya cambiado de modelo automáticamente;
- que el permiso de la herramienta no haya sido rechazado;
- si el fallo se repite con otro modelo compatible.
Solución de problemas por síntoma
| Síntoma | Causa probable | Primera comprobación | Cómo volver a probar |
|---|---|---|---|
| Clave rechazada | Clave inválida, revocada, con espacios o mezclada con otro endpoint | Copiar de nuevo la clave activa y confirmar el proveedor | Reiniciar la sesión, enviar el Chat mínimo y revisar Activity |
| Model not found / 404 | ID incorrecto, alias incompleto o modelo no disponible en la ruta compatible | Copiar el ID completo del catálogo | Elegirlo manualmente y repetir el mismo prompt |
| Chat funciona y tools de Agent fallan | Endpoint genérico /api/v1 o modelo sin tools | Revisar /cursor y supported_parameters=tools | Ejecutar una tarea de solo lectura y revisar Activity |
| Chat funciona y Tab no aparece | Tab no usa la clave personalizada | No cambiar clave ni endpoint | Aceptar Chat y Tab como funciones separadas |
| Respuesta 402 | Créditos, límite de clave o presupuesto en curso insuficiente | Revisar la página de créditos/clave y metadata del error | Esperar, reducir la solicitud o añadir crédito y repetir |
| Respuesta 429 | Límite de OpenRouter o del proveedor upstream | Revisar Retry-After y cabeceras; no reenviar inmediatamente | Esperar con exponential backoff o cambiar a una ruta disponible |
| Cursor responde pero Activity no registra | Modelo integrado, Auto o ajustes sin aplicar | Seleccionar el modelo añadido y revisar clave y Base URL | Reiniciar la sesión y repetir la solicitud mínima |
| Faltan campos en ajustes | Cambio de versión, plan o UI de Cursor | Actualizar Cursor y abrir la documentación BYOK actual | Reproducir la misma relación de campos y volver a probar |
Para 429, sigue la guía de límites de OpenRouter, respeta Retry-After y usa exponential backoff. Crear más claves no garantiza eludir límites globales. Para fallos de tools, corrige endpoint y capacidad del modelo antes de tocar ajustes avanzados de Agent.
BYOK no es una conexión directa del editor a OpenRouter
La documentación BYOK de Cursor indica que las solicitudes siguen pasando por el backend de Cursor para construir el prompt final. Los equipos con código sensible deben revisar las prácticas de Cursor y del proveedor elegido. No incluyas claves, datos de clientes ni código privado en capturas de diagnóstico; usa una reproducción mínima y anonimizada.
Planes, facturación y UI pueden cambiar. Antes de desplegar en producción, vuelve a abrir las páginas oficiales y confirma el comportamiento de ese día.
BetterToken es una ruta independiente
Si buscas otro gateway OpenAI-compatible y no OpenRouter específicamente, BetterToken tiene una guía propia para Cursor. Su Base URL es https://www.bettertoken.ai/v1 y debe usarse con una API Key y un Model ID de BetterToken.
No combines una clave de OpenRouter con el endpoint de BetterToken ni una clave de BetterToken con https://openrouter.ai/api/v1/cursor. Al cambiar de proveedor, repite el Chat mínimo y verifica el uso en el panel correspondiente.
Orden final de aceptación
Sigue esta secuencia: configura un modelo → selecciónalo manualmente → envía un Chat mínimo → encuentra el registro en Activity → prueba Agent y tools → acepta Tab como función integrada separada. Así cada fallo queda localizado en endpoint, clave, modelo, tools, crédito o rate limit.
