Como conectar o Cursor ao OpenRouter: configuração, limites de recursos e solução de erros
Guia para configurar o Cursor com OpenRouter, comprovar a rota no Activity, testar Chat, Agent, Tab e tools separadamente e diagnosticar endpoint, modelo, créditos e limites.
Conteúdo
O ponto principal é: receber uma resposta no Cursor não prova que todos os recursos estão usando o OpenRouter. Em 4 de outubro de 2026, o OpenRouter ainda classificava a integração com o Cursor como Beta e exigia o Base URL dedicado https://openrouter.ai/api/v1/cursor. Requisições do modelo em Chat e Agent podem passar por essa rota quando um modelo do OpenRouter é selecionado manualmente. O Tab Completion não usa a API Key personalizada, e o uso de tools depende do endpoint e do suporte do modelo a tools.
A validação correta é uma cadeia de evidências: campos corretos → modelo escolhido manualmente → requisição mínima → registro correspondente no OpenRouter Activity → testes separados de Agent e tools. Este guia segue a documentação oficial e não afirma ter testado uma conta, chave ou versão específica do Cursor de ponta a ponta.
Quais recursos usam a chave personalizada
| Recurso do Cursor | Rota esperada | Limite importante | Como verificar |
|---|---|---|---|
| Modelo escolhido manualmente em Chat ou Ask | Normalmente OpenRouter | O modelo deve estar disponível pela rota OpenAI-compatible | Enviar um prompt mínimo e conferir horário e modelo no Activity |
| Modelo escolhido manualmente em Agent | A chamada do modelo costuma passar; nem toda ação interna é comprovada | A documentação cobre a escolha no Agent, não cada requisição auxiliar | Observar o Activity e as ações visíveis de tools no Cursor |
| Tab Completion | Não | Tab continua usando modelos internos do Cursor | Não usar sugestões de Tab como prova do OpenRouter |
| Tools no Agent | Condicional | É preciso o endpoint /cursor e um modelo com tools | Validar Chat primeiro e depois uma tarefa somente leitura |
| Seleção automática | Evidência ruim para aceite | O cliente pode escolher outra rota | Desativar Auto e selecionar explicitamente o modelo adicionado |
É essencial separar requisição ao modelo de execução da ferramenta. A documentação de tool calling do OpenRouter explica que o modelo propõe a chamada e o cliente executa a ferramenta. Um registro no Activity confirma a requisição ao modelo, mas não prova sozinho que a leitura de arquivo ou o comando local foram executados no OpenRouter.
O que preparar
- Uma versão atual do Cursor com
Cursor Settings→Models→API Keys. - Sua própria API Key do OpenRouter. Não a cole em chats, repositórios, capturas ou mensagens de suporte.
- O Model ID exato copiado do catálogo atual do OpenRouter.
- Para tools do Agent, um modelo confirmado no filtro de modelos com tools.
Os botões podem variar entre versões: ativar, salvar, confirmar ou verificar. A relação continua igual: chave em OpenAI API Key, endpoint em Override OpenAI Base URL e modelo com o ID completo do OpenRouter.
Configuração passo a passo
1. Abra as configurações de API Keys
Vá para Cursor Settings → Models, expanda API Keys e localize OpenAI API Key e Override OpenAI Base URL.
2. Informe a chave do OpenRouter
Cole em OpenAI API Key a chave criada na sua conta do OpenRouter. Use somente a interface de configurações e conclua a ação de salvar, habilitar ou validar mostrada pelo cliente.
3. Use o endpoint dedicado do Cursor
Ative Override OpenAI Base URL e informe:
https://openrouter.ai/api/v1/cursor
Não use o genérico https://openrouter.ai/api/v1 e não acrescente /chat/completions. O endpoint /cursor normaliza o formato do Cursor; no endpoint genérico, tools e alguns formatos podem falhar.
4. Adicione o Model ID exato
Em Models, clique em + Add model e copie o ID completo da página atual do modelo. Para aliases de roteador, copie a sintaxe inteira. Não use nome comercial, abreviação ou ID de tutorial antigo.
5. Selecione o modelo manualmente
Volte ao Chat ou Agent e escolha explicitamente o modelo adicionado. Não use seleção automática no primeiro teste, pois uma resposta não informa qual rota foi usada.
Como comprovar que está funcionando
Envie no Chat uma requisição mínima, sem código ou segredos, como pedir uma frase fixa. Abra imediatamente o OpenRouter Activity e confira:
- o horário coincide com o teste;
- o modelo registrado coincide com o Model ID selecionado;
- a requisição terminou com sucesso e apresenta uso;
- a evidência interna não contém a chave, o prompt completo ou código sensível.
A resposta no Cursor é evidência fraca; um registro correspondente no Activity é evidência mais forte de roteamento. Se houver resposta sem registro, marque a rota como não confirmada.
Em equipes, registre apenas horário, modelo, status, identificador necessário, versão do Cursor e modo de teste. Isso facilita repetir a validação se o comportamento Beta mudar.
Teste Chat, Agent, Tab e tools separadamente
Chat: estabeleça a linha de base
Selecione o modelo manualmente e envie um prompt curto e determinístico. O Chat só passa quando aparece um registro correspondente no Activity. Se falhar, não avance para Agent, que adiciona variáveis de contexto, permissões e ferramentas.
Agent: separe o roteamento da orquestração
Use um repositório descartável ou fácil de restaurar. Peça primeiro uma tarefa de baixo risco, como ler o README e sugerir melhorias, sem autorizar escrita ou comandos destrutivos. Verifique dois sinais:
- O Activity contém a requisição ao modelo.
- O Cursor mostra a leitura do arquivo ou outra ação esperada.
O primeiro prova o roteamento do modelo; o segundo prova a orquestração do Agent. A documentação não demonstra que toda requisição auxiliar do Agent use sempre a mesma chave, então não generalize um teste bem-sucedido para todo o tráfego interno.
Tab: ausência no Activity é esperada
Uma sugestão de Tab testa somente o Tab Completion. A documentação oficial informa que chaves personalizadas funcionam com modelos de chat, enquanto Tab usa modelos internos. “Chat aparece no Activity e Tab não” é comportamento esperado.
Tools: valide endpoint e capacidade do modelo
Depois de validar Chat, escolha um modelo que declare tools. Em um repositório de teste, solicite uma ação somente leitura, como listar arquivos ou ler um arquivo pequeno. Se Chat funcionar e tools não, verifique:
- Base URL exatamente
https://openrouter.ai/api/v1/cursor; - suporte explícito a
tools; - ausência de troca automática de modelo;
- permissão da ferramenta no Cursor;
- reprodução em outro modelo conhecido por suportar tools.
Solução por sintoma
| Sintoma | Causa provável | Primeira checagem | Reteste |
|---|---|---|---|
| Chave rejeitada | Chave inválida, revogada, com espaços ou misturada a endpoint de outro provedor | Copiar novamente a chave ativa e confirmar o provedor | Reiniciar a sessão, repetir o Chat mínimo e conferir Activity |
| Model not found / 404 | ID errado, alias incompleto ou modelo indisponível na rota compatível | Copiar o ID completo do catálogo | Selecionar manualmente e repetir o prompt |
| Chat funciona e tools falham | Endpoint genérico /api/v1 ou modelo sem tools | Conferir /cursor e supported_parameters=tools | Executar uma tarefa somente leitura e revisar Activity |
| Chat funciona e Tab não aparece | Tab não usa a chave personalizada | Não alterar chave nem endpoint | Aceitar Chat e Tab separadamente |
| Resposta 402 | Créditos, limite por chave ou orçamento em andamento insuficiente | Revisar página de créditos/chave e metadata do erro | Aguardar, reduzir a requisição ou adicionar créditos |
| Resposta 429 | Limite do OpenRouter ou do provedor upstream | Ver Retry-After e headers; não reenviar imediatamente | Esperar com exponential backoff ou escolher outra rota |
| Cursor responde sem registro no Activity | Modelo interno, Auto ou configuração não aplicada | Selecionar o modelo adicionado e revisar os campos | Reiniciar a sessão e repetir a requisição mínima |
| Campos não aparecem | Mudança de versão, plano ou UI | Atualizar Cursor e abrir a documentação BYOK atual | Recriar a mesma relação de campos e retestar |
Para 429, siga o guia de limites do OpenRouter, respeite Retry-After e use exponential backoff. Criar mais chaves não garante contornar capacidade global. Para falhas de tools, corrija endpoint e suporte do modelo antes de alterar configurações avançadas do Agent.
BYOK não é conexão direta do editor ao OpenRouter
A documentação BYOK do Cursor informa que as requisições ainda passam pelo backend do Cursor para a montagem final do prompt. Equipes com código sensível devem revisar as práticas do Cursor e do provedor. Não inclua chaves reais, dados de clientes ou código privado em capturas de diagnóstico; use uma reprodução mínima sanitizada.
Planos, cobrança e UI podem mudar. Antes de produção, reabra as páginas oficiais e confirme o comportamento da data.
BetterToken é uma rota separada
Se você quer outro gateway OpenAI-compatible, e não especificamente o OpenRouter, o BetterToken possui uma configuração própria para Cursor. O Base URL é https://www.bettertoken.ai/v1 e deve ser usado com API Key e Model ID do BetterToken.
Não combine uma chave OpenRouter com o endpoint BetterToken, nem uma chave BetterToken com https://openrouter.ai/api/v1/cursor. Ao trocar de provedor, repita o Chat mínimo e verifique o uso no painel correspondente.
Ordem final de aceite
Use esta sequência: configure um modelo → selecione-o manualmente → envie um Chat mínimo → encontre o registro no Activity → teste Agent e tools → aceite Tab como recurso interno separado. Assim cada falha fica localizada em endpoint, chave, modelo, tools, crédito ou rate limit.
