Pular para o conteúdo principal
Algumas redes corporativas e empresariais encaminham o tráfego por proxies HTTP/HTTPS. O plugin do Windsurf nos IDEs da JetBrains precisa acessar serviços externos do Windsurf (para autenticação e recursos de IA), então pode ser necessário configurar um proxy para que tudo funcione de forma confiável.

​
Quando a configuração de proxy pode ser necessária

A configuração de proxy pode ser necessária se:
  • Você vir “Failed to connect” ou erros de rede semelhantes no Windsurf
  • O painel do Windsurf no IDE ficar em branco e nunca carregar
  • O Cascade ou outros recursos do Windsurf não conseguirem se conectar ou esgotarem o tempo limite
Este guia aborda:
  • Como verificar se sua rede usa um proxy
  • Como configurar o proxy do IDE
  • Como ativar a detecção de proxy do Windsurf
  • Como configurar as configurações de proxy para o JetBrains Remote

​
Verifique se sua rede usa proxy

Antes de mudar qualquer coisa: Pergunte à equipe de TI/infra/rede:
  • Usamos um proxy HTTP/HTTPS para tráfego de saída?
  • Se sim, ele é configurado automaticamente (configurações do sistema/arquivo PAC/gerenciamento de dispositivos) ou preciso configurá-lo manualmente nos aplicativos?
Se sua organização não usa proxy, geralmente você não precisa alterar essas configurações. Se sua organização usar, reúna os detalhes do proxy (endereço, porta e possíveis credenciais). Você pode compartilhar capturas de tela das configurações de HTTP Proxy do JetBrains e do Windsurf para que possam dizer exatamente o que preencher.

​
Configurar o proxy do IDE JetBrains

Primeiro, certifique-se de que o próprio IDE consegue acessar a internet pelo seu proxy — em particular, que consegue acessar windsurf.com.
  1. Abra Settings / Preferences no seu IDE JetBrains. Por exemplo: File → Settings… (Windows/Linux) ou ⌘, → Settings… (macOS).
  2. Vá em Appearance & Behavior → System Settings → HTTP Proxy.
Configurações de Proxy HTTP do JetBrains
  1. Escolha a opção adequada conforme a orientação da sua equipe de TI:
    • No proxy – se sua rede não usa proxy.
    • Auto-detect proxy settings ou Use system proxy settings – se o proxy estiver configurado globalmente na sua máquina.
    • Manual proxy configuration – se a TI forneceu um host/porta específicos do proxy (e, opcionalmente, nome de usuário/senha) para informar aqui.
  2. Use Check connection… (se disponível) para verificar a configuração — de preferência teste a conectividade com https://windsurf.com a partir desta janela.
  3. Aplique as alterações e reinicie o IDE se solicitado.
Se o IDE não conseguir acessar a rede (por exemplo, se o marketplace de plugins, as atualizações ou recursos web integrados falharem, ou se você não conseguir acessar https://windsurf.com de dentro do IDE), corrija isso aqui primeiro. O Windsurf depende dessa conectividade.

​
Ativar a detecção de proxy do Windsurf no JetBrains

Depois que o proxy no nível do IDE estiver configurado (ou confirmado como desnecessário), ajuste como o Windsurf utiliza essas configurações. O plugin do Windsurf tem sua própria opção Detectar proxy nas configurações:
  1. No seu IDE JetBrains, abra Settings / Preferences.
  2. Vá em Tools → Windsurf Settings.
  3. Encontre a alternância Detectar proxy.
Configurações de detecção de proxy do Windsurf
  1. Ative Detectar proxy se:
    • O proxy estiver configurado no nível do SO ou do IDE, e
    • A equipe de TI esperar que os aplicativos “simplesmente utilizem” essas configurações.
  2. Clique em Apply e OK, se necessário, e reinicie o IDE.
  3. Tente usar o Windsurf novamente:
    • Abra o painel do Windsurf na barra lateral do IDE
    • Execute o Cascade ou tente novamente a operação que estava falhando com “Failed to connect” ou exibindo uma tela em branco
Se você observar novos problemas de conexão após ativar Detectar proxy, você pode:
  • Desativar novamente o Detectar proxy,
  • Conferir a configuração de HTTP Proxy do seu IDE (incluindo se ele consegue acessar https://windsurf.com), e
  • Confirmar com a TI se alguma configuração manual adicional é necessária.

​
Configuração de proxy no JetBrains Remote

Se você usa o JetBrains Remote Development (por exemplo, via JetBrains Gateway, um backend remoto ou um ambiente de desenvolvimento em nuvem), existem basicamente dois lugares onde as configurações de proxy são relevantes:
  • Sua máquina local, executando o thin client.
  • A máquina remota, onde o backend do IDE (e o Windsurf) realmente roda.
Quando você se conecta pelo JetBrains Remote, as solicitações de rede do Windsurf partem da máquina remota, não do seu laptop local. Isso significa:
  • A configuração de proxy no IDE remoto afeta como o Windsurf se conecta aos serviços do Windsurf.
  • A máquina remota pode precisar de sua própria configuração de proxy, mesmo que sua máquina local já esteja configurada corretamente.
Para desenvolvimento remoto no JetBrains, você deve usar o plugin dedicado “Windsurf (Remote Development)”, não o plugin padrão do Windsurf. Certifique-se de ter instalado o Windsurf (Remote Development) conforme descrito na seção de Remote Development do guia de introdução do Windsurf para JetBrains.

​
Configurar o proxy para o ambiente remoto

  1. Conecte-se ao seu backend remoto usando o JetBrains Remote / Gateway.
  2. Abra Settings / Preferences na sessão do IDE remoto (isso abre as configurações do IDE em execução na máquina remota).
  3. Configure o proxy para o IDE remoto:
    • Vá em Appearance & Behavior → System Settings → HTTP Proxy no IDE remoto.
    • Defina o proxy conforme as instruções da sua equipe de TI (No proxy / Auto-detect / Use system proxy / Manual).
    • Se o IDE tiver o botão Check connection…, use-o para testar a conectividade com https://windsurf.com a partir da máquina remota.
  4. Configure o Windsurf no IDE remoto:
    • Vá em Tools → Windsurf Settings (ainda na sessão remota).
    • Ative Detect proxy se a sua equipe de TI espera que os aplicativos no host remoto usem as configurações de proxy do sistema/IDE.
  5. Aplique as alterações e, em seguida, reinicie o backend do IDE remoto ou desconecte-se e reconecte-se à sessão remota.
  6. Abra o painel do Windsurf novamente no IDE remoto e tente executar novamente a ação que falhou anteriormente.
É comum em ambientes corporativos que tanto a sua máquina local quanto a máquina remota tenham suas próprias regras de proxy. Siga a orientação da TI para cada lado; corrigir apenas o proxy local não ajudará se o próprio host remoto não conseguir acessar a internet (incluindo https://windsurf.com) sem a sua própria configuração de proxy.

​
Quando mudar o que

​
Altere apenas o proxy HTTP local do IDE

Se:
  • Você não estiver usando o JetBrains Remote, e
  • Outros recursos do JetBrains já funcionarem após configurá-lo, e
  • O Windsurf funcionar sem alterar suas próprias configurações, e
  • O IDE conseguir acessar https://windsurf.com.

​
Ativar “Detect Proxy” do Windsurf

(Local ou remoto) se:
  • O proxy já estiver configurado no nível do SO ou do IDE nessa máquina, e
  • O Windsurf for o único que não consegue se conectar ou exibe um painel do Windsurf em branco.

​
Configurar proxy no IDE remoto

Se:
  • Você usa o JetBrains Remote,
  • Instalou o plugin Windsurf (Remote Development) nesse ambiente, e
  • Os erros ocorrem apenas quando conectado a um backend remoto, ou
  • A equipe de TI informa que o servidor remoto também precisa passar por um proxy para acessar a internet (incluindo https://windsurf.com).

​
Fale com TI/Infra

Se:
  • Você não tem certeza se o seu ambiente usa algum proxy, ou
  • Você configurou o HTTP Proxy + o proxy Windsurf Detect (local e/ou remoto) e verificou a conexão com https://windsurf.com, mas ainda vê painéis do Windsurf em branco ou falhas de conexão.
Sua equipe de TI/Infra é a fonte definitiva — eles podem confirmar se você precisa de um proxy na sua máquina local, na remota ou em ambas, como isso deve ser configurado no JetBrains e se a opção de proxy do Windsurf Detect deve estar habilitada no seu ambiente.