Pular para o conteúdo principal
Algumas redes corporativas e empresariais executam interceptação TLS (“inspeção SSL”) no tráfego HTTPS de saída (comumente por meio de Zscaler ou gateways de segurança similares). O Windsurf Editor precisa estabelecer conexões TLS de saída com serviços externos (para login e recursos baseados em nuvem). Se o tráfego inspecionado for reassinado por uma autoridade certificadora (AC) de inspeção corporativa em que sua máquina/ambiente de execução não confia (ou se a cadeia estiver incompleta), o Windsurf poderá não conseguir se conectar, apresentando erros de SSL/certificado ou de negociação. Em particular, pode ser necessário solucionar problemas de inspeção SSL/TLS se:
  • For exibida a mensagem “Failed to connect” ou erros de rede semelhantes
  • O editor ou o painel do Cascade mostrar uma tela em branco e nunca carregar
  • O Cascade ou outros recursos baseados em nuvem não conseguirem carregar ou se conectar
  • Fluxos de login ou ativação falharem inesperadamente
  • Os recursos funcionarem em uma rede doméstica/hotspot, mas falharem na rede corporativa
  • Você visualizar erros de certificado ou de handshake TLS em logs/devtools
Se você também estiver enfrentando problemas relacionados a proxy, consulte Configuração de proxy.

​
1. Verifique se sua rede usa inspeção SSL

Antes de mudar qualquer coisa no editor, pergunte à sua equipe de TI / segurança / rede:
  • Nós fazemos interceptação TLS / inspeção SSL no tráfego HTTPS de saída?
  • A inspeção SSL está habilitada para as estações de trabalho de desenvolvimento e ferramentas de desenvolvedor (não só para navegadores)?
  • Qual cadeia de CA Raiz / CA Intermediária é usada para assinar o tráfego inspecionado?
  • Essa cadeia de CA está instalada nos endpoints e é confiável pelos aplicativos/ambientes de execução usados para desenvolvimento?
Se a sua organização não usa inspeção SSL, em geral você não precisa seguir este guia. Se a sua organização usa inspeção SSL, continue abaixo.

​
2. Capture o erro subjacente no Windsurf (Developer Tools → Console)

O Windsurf Editor (baseado em VS Code) expõe o Developer Tools, que pode mostrar as falhas reais de TLS/certificado.
  1. Abra Help → Dev Tools / Developer Tools
  2. Selecione a guia Console
  3. Procure por erros em vermelho
  4. Expanda cada entrada de erro para ver todos os detalhes (campos de erro aninhados / stack traces)
Padrões de erro comuns incluem: Falhas de validação de certificado (CA não confiável):
  • certificate signed by unknown authority
  • unable to verify the first certificate
  • self signed certificate in certificate chain
  • UNABLE_TO_VERIFY_LEAF_SIGNATURE
Falhas na construção da cadeia (intermediário ausente):
  • unable to get local issuer certificate
  • unable to get issuer certificate
Falhas na negociação de TLS:
  • handshake_failure
  • wrong version number
  • protocol negotiation failed
  • ERR_SSL_PROTOCOL_ERROR
Se você puder fornecer o texto expandido do erro do console para a equipe de TI/segurança, isso geralmente reduz significativamente o tempo de resolução.

​
3. O que causa isso em ambientes com inspeção de SSL

Quando a inspeção de SSL está habilitada, o gateway encerra e restabelece conexões TLS. O cliente recebe um certificado de servidor sintético assinado por uma CA de inspeção da empresa (certificados Root CA e, às vezes, Intermediate CA). Falhas de conectividade do Windsurf normalmente ocorrem quando:
  • A Root CA de inspeção da empresa não é reconhecida como confiável no endpoint e/ou
  • A cadeia do certificado de inspeção está incompleta (falta a Intermediate CA) e/ou
  • O IDE/runtime usa um repositório de confiança próprio, diferente do do sistema operacional, que não inclui a cadeia de CA de inspeção da empresa e/ou
  • A política da empresa impõe restrições de TLS que interrompem a negociação (versão mínima de TLS/conjuntos de cifras, bloqueio de tráfego que não pode ser descriptografado, etc.)
Em geral, isso é um problema de configuração de certificados/confiança/política da empresa, não um problema específico da implementação do Windsurf.

​
4. Trabalhe com sua equipe de TI/segurança para resolver o problema

Como a inspeção SSL e a implantação de certificados são controladas pela sua organização, geralmente será necessário que a área de TI/segurança faça alterações.

​
A) Validar a política de inspeção SSL para o tráfego do Windsurf

Peça para a equipe de TI/segurança confirmar:
  • Se a inspeção SSL se aplica ao tráfego HTTPS de saída relacionado ao Windsurf
  • Se há algum bloqueio/recusa devido à validação de certificado, motivos de política ou restrições na negociação de TLS

​
B) Certifique-se de que a cadeia da CA de inspeção da empresa esteja corretamente implantada e confiável

Peça ao time de TI/segurança para:
  • Implantar a Root CA de inspeção SSL da empresa nos endpoints dos desenvolvedores
  • Garantir que quaisquer certificados de CA intermediária necessários estejam presentes e que a cadeia esteja correta
  • Validar a confiança usando o mesmo trust store (repositório de certificados confiáveis) que o IDE/runtime utiliza (armazenamento do SO vs armazenamento específico do runtime)

​
C) Configurar uma exceção de inspeção SSL com escopo limitado (fallback)

Se o alinhamento de confiança não for viável, peça à equipe de TI/segurança para:
  • Criar uma exceção de inspeção SSL para os endpoints de serviço necessários do Windsurf (seguindo o processo de lista de permissões/requisitos de rede da sua organização)
  • Manter a exceção com escopo estritamente limitado e alinhada com a sua política de segurança

​
5. O que enviar para TI / segurança (copiar/colar)

Problema: Windsurf Editor não consegue se conectar à rede corporativa; provavelmente um problema de confiança ou cadeia de certificados de inspeção SSL / interceptação TLS. Evidência: Help → Developer Tools → Console mostra erros de TLS/certificado ou de handshake (erros em vermelho detalhados disponíveis no console). Solicitação:
  1. Confirmar se a inspeção SSL está habilitada para o tráfego HTTPS de saída relacionado ao Windsurf.
  2. Confirmar se a Autoridade Certificadora raiz (Root CA) de inspeção SSL da empresa e quaisquer intermediárias estão implantadas e marcadas como confiáveis neste endpoint (e em qualquer trust store específico de runtime usado pelo IDE).
  3. Se não for viável alinhar a cadeia de confiança, configurar uma exceção de inspeção SSL com escopo limitado para os endpoints de serviço necessários do Windsurf.
Incluir:
  • Horário(s) da falha
  • Versão do sistema operacional
  • Se o Zscaler Client Connector (ou agente semelhante) está instalado/habilitado
  • Texto expandido do erro do console em Developer Tools → Console
  • Se funciona em uma rede de hotspot/casa, mas falha na rede corporativa

​
6. Quando usar cada opção

Use correções de implantação/confiança de certificados se:
  • Os erros indicarem “unknown authority”, “unable to verify”, “issuer not found” ou intermediários ausentes
  • Você quiser a correção mais durável mantendo a inspeção SSL ativada
Use um bypass de inspeção SSL com escopo limitado se:
  • O IDE/runtime não conseguir, na prática, consumir a cadeia de CA da empresa
  • O alinhamento do trust store (repositório de certificados confiáveis) for pouco confiável no seu ambiente
  • A equipe de TI/segurança confirmar que a inspeção está causando falhas e aprovar uma exceção direcionada
Se você não tiver certeza de qual se aplica, sua equipe de TI/segurança é a principal fonte de referência — ela pode confirmar se a inspeção SSL está ativada, qual cadeia de CA é usada, como os endpoints são gerenciados e se as regras de bypass são apropriadas.