O Cursor é um editor de código com IA amplamente usado. Além dos modelos e da cota incluídos no produto, ele também permite informar sua própria chave de API e Base URL. Para equipes que precisam de um caminho de acesso estável, fatura centralizada e troca entre modelos, conectar o Cursor a um gateway compatível com OpenAI é uma opção prática.

Este artigo segue a ordem real de operação: preparação, configuração, verificação, limitações e implantação em equipe. Os nomes de menu podem variar entre versões; use como referência o Cursor Settings instalado na sua máquina.

Nota: Cursor é uma marca da Anysphere, Inc. Este texto é apenas uma explicação técnica e não implica vínculo, representação ou endosso da Cursor/Anysphere; interface, planos e regras de cobrança seguem as páginas oficiais da Cursor.

1. Primeiro, distinga os dois tipos de "API do Cursor"

O primeiro é a API que a própria plataforma Cursor oferece, como Cloud Agents e interfaces de administração; a chave é criada na conta Cursor e serve para chamar serviços da Cursor. O segundo é o "traga sua própria chave" (BYOK): você informa no Cursor a chave de um fornecedor de modelos e o editor usa sua conta para chamar o modelo. Este artigo trata do segundo caso.

Há uma premissa que costuma passar despercebida: as requisições de modelo do Cursor são encaminhadas pelos servidores da Cursor, não saem da sua máquina diretamente. Portanto, a Base URL precisa ser acessível pela internet pública. Um gateway disponível apenas na rede interna da empresa normalmente causa timeout no lado do Cursor. O ZSQH AI Gateway é um serviço público e, em geral, não sofre essa restrição.

2. Prepare a chave, a Base URL e o nome do modelo

Antes de começar, prepare três itens: uma chave de API, um endereço compatível e um ID de modelo correto.

  1. Abra a página de cadastro do ZSQH AI Gateway, registre-se e entre no console.
  2. Vá em "Chaves de API", crie uma nova chave e deixe o nome claro, por exemplo cursor-notebook-trabalho.
  3. Defina um teto de gastos e uma data de expiração. Mesmo em conta pessoal, vale configurar para evitar consumo anormal.
  4. Copie a chave e guarde no gerenciador de senhas. O console costuma exibir o valor completo apenas uma vez.
  5. Abra a tabela de preços dos modelos e anote o ID do modelo que pretende usar. Preços e modelos mudam; use o que a página mostra no momento.

A configuração dos três itens fica assim:

Base URL: https://ai.zhongshangqihang.com/v1
API Key:  sk-... (criada no console; guarde apenas no gerenciador de senhas)
Model:    use o ID exibido atualmente na página "Preços dos modelos"

A Base URL usa o endereço compatível com OpenAI e termina em /v1. Não preencha o endereço raiz da Anthropic nem acrescente /chat/completions por conta própria, pois isso costuma duplicar o caminho.

3. Preencha a configuração no Cursor

O caminho comum é Cursor Settings → Models → API Keys. As versões variam nos detalhes, mas os passos centrais são parecidos.

  1. Abra o Cursor Settings; o atalho costuma ser Cmd/Ctrl + ,.
  2. Entre em Models e expanda API Keys.
  3. Ative OpenAI API Key, cole a chave criada e clique em Save.
  4. Ative Override OpenAI Base URL e informe https://ai.zhongshangqihang.com/v1.
  5. Clique em + Add Custom Model (em algumas versões, + Add model), preencha o ID do modelo da página de preços e ative-o.
  6. No seletor de modelos da conversa, escolha esse modelo e envie uma requisição simples.

Se não encontrar Override OpenAI Base URL, a versão ou o plano atual não permite apontar tráfego compatível com OpenAI para um endereço personalizado. Nesse caso, não fique tentando repetidamente: atualize a versão ou use uma instalação que ofereça essa opção.

O nome do modelo é um identificador de roteamento, não uma anotação. Maiúsculas, hífens e sufixo de versão precisam coincidir com o gateway. Quando o preenchimento está errado, o sintoma comum é modelo inexistente, erro 404 ou requisição recusada.

4. Como escolher o modelo

É possível adicionar vários modelos personalizados no Cursor, mas o sucesso da requisição depende de o gateway oferecer o modelo com o mesmo nome e suportar o modo de chamada correspondente.

Cenário de uso Faixa sugerida Como preencher Observações
Perguntas do dia a dia, pequenas alterações Modelo leve e rápido Copiar o ID da página de preços Baixa latência; capacidade limitada em refatorações complexas
Alterações em vários arquivos, agentes Modelo principal para código Copiar o ID da página de preços Precisa suportar chamada de ferramentas
Desenho de arquitetura, investigação difícil Modelo de alta capacidade Copiar o ID da página de preços Custo maior; usar sob demanda
Autocomplete Tab Modelo interno do Cursor Não passa pela chave personalizada BYOK não cobre o autocomplete

O modo Agent pode depender da Responses API ou de chamada de ferramentas. Se o gateway só for compatível com Chat Completions, parte das funções de Agent falhará. Nesse caso, valide primeiro em uma conversa comum e depois determine se o problema é do modelo ou de incompatibilidade de recurso.

Além disso, Auto, Composer e o autocomplete Tab não necessariamente usam sua chave. Segundo a página de ajuda da Cursor, o autocomplete Tab sempre usa os modelos internos; o modo Auto também pode ser roteado pela própria Cursor. Trate o modelo personalizado como um canal que só entra em ação quando você o seleciona explicitamente; isso reflete melhor a realidade.

5. Verifique se a configuração está funcionando

Ver apenas se o Cursor respondeu é insuficiente, porque a resposta pode ter vindo do canal interno. Siga esta ordem:

  1. Crie uma conversa vazia para evitar interferência do contexto anterior.
  2. Selecione explicitamente o modelo personalizado no seletor; não use Auto.
  3. Envie uma requisição curta, por exemplo pedir a explicação de um trecho de até dez linhas.
  4. Abra o uso ou o log de requisições no console do gateway e confirme um registro no mesmo horário, com o mesmo modelo e a mesma chave.
  5. Registre o resultado da verificação. Se não houver registro no log, a requisição não chegou ao gateway; volte a checar a Base URL e a opção ativada.

Erros comuns podem ser comparados assim:

  • 401 ou 403: chave incorreta, desativada ou sem saldo.
  • 404: caminho da Base URL incorreto ou nome de modelo inexistente.
  • 429: limite de taxa atingido ou teto de gastos da chave alcançado.
  • Timeout: endpoint inacessível ou problema no caminho de rede.
  • Falha apenas no Agent: provável incompatibilidade de recursos da interface, não necessariamente problema da chave.

6. Limitações que você precisa conhecer

  • O BYOK cobre principalmente modelos de chat; o autocomplete Tab continua usando os modelos internos do Cursor.
  • A abrangência do suporte a chaves OpenAI varia por versão. A página de ajuda da Cursor menciona que a chave própria da OpenAI cobre apenas modelos de chat padrão sem raciocínio; modelos de raciocínio e parte dos recursos novos podem não estar disponíveis.
  • As requisições passam pelos servidores da Cursor, então o endpoint personalizado precisa ser acessível pela internet pública.
  • Requisições com chave própria não necessariamente seguem a política de retenção zero de dados da Cursor; o tratamento depende do fornecedor do modelo e do gateway. Equipes com exigências rígidas de retenção devem avaliar antes.
  • Mesmo com chave própria, planos de equipe e empresariais podem continuar cobrando a taxa de plataforma da Cursor; confirme na página de cobrança da Cursor.
  • A Cursor atualiza com frequência; nomes de menu, modelos suportados e regras de cobrança podem mudar.

7. Passos para implantar na equipe

  • Faça primeiro um piloto pequeno: escolha de três a cinco desenvolvedores, defina um modelo principal e rode por uma semana.
  • Registre três tipos de dados: taxa de sucesso das requisições, latência média e consumo diário por pessoa.
  • Crie uma chave individual por pessoa no gateway, com teto por usuário; não use chave compartilhada.
  • Mantenha uma tabela de mapeamento de modelos: o que preencher no Cursor, o que corresponde no gateway e para o que trocar em caso de falha.
  • Documente a configuração internamente, incluindo Base URL, IDs de modelo e tratamento dos erros comuns.
  • Depois de observar o custo, decida quais membros usam chave própria e quais continuam com a cota do plano. Os preços seguem a tabela de preços dos modelos.
  • Ao desligamento, troca de máquina ou fim do projeto, desative a chave correspondente no mesmo dia.

8. Lista de segurança

  • Uma chave por finalidade, sem reutilização entre dispositivos.
  • Defina teto de gastos e data de expiração.
  • Não coloque a chave em código, .env, capturas de tela ou tickets.
  • Não mantenha a chave salva por longos períodos em computador compartilhado.
  • Faça rotação periódica; em suspeita de vazamento, desative primeiro e investigue depois.
  • Na equipe, passe tudo pelo gateway e mantenha logs de requisição para auditoria.
  • Em repositórios sensíveis, confirme antes se os dados saem da máquina e para quais serviços vão.

9. Perguntas frequentes

O Cursor aceita qualquer interface compatível com OpenAI?

Não necessariamente. O uso depende de a versão do Cursor oferecer Override OpenAI Base URL e de a interface ser compatível com o caminho e os parâmetros realmente chamados. Valide primeiro em uma conversa comum e depois teste os recursos de Agent.

Por que ainda aparece a exigência de assinatura mesmo com minha chave?

Ter chave própria não desbloqueia todos os recursos. Parte dos recursos do editor, da gestão de equipe e dos modelos internos continua limitada pelo plano; vale a regra atual do plano da Cursor.

Por que o autocomplete Tab não consome minha chave?

Segundo a página de ajuda da Cursor, o autocomplete Tab sempre usa os modelos internos da Cursor e não passa pela chave própria. Isso é design do produto, não erro de configuração.

A Base URL deve ser o endereço raiz ou terminar em /v1?

No protocolo compatível com OpenAI, preencha até /v1. Não inclua /chat/completions, para evitar caminho duplicado e erro 404.

A equipe pode compartilhar uma única chave?

Tecnicamente, sim; na prática, não é recomendado. Uma chave compartilhada não permite distinguir o consumo por membro e dificulta a investigação em caso de vazamento. Uma chave por pessoa, com teto e logs, é mais seguro.

Próximos passos

Registre-se no ZSQH AI Gateway, crie uma chave exclusiva para o Cursor e preencha a Base URL e o modelo conforme este artigo. Depois de validar a conversa comum, ajuste o modelo principal e os limites com base na tabela de preços dos modelos.

Leitura relacionada: