> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Devin Desktop 中的 TLS / SSL 检查问题

> 配置会因 SSL 检查（例如 Zscaler）而导致 TLS 证书验证或协议协商失败的企业环境。包括如何捕获控制台错误，以及应向 IT/安全团队请求哪些信息。

某些公司和企业网络会对出站 HTTPS 流量执行 TLS 拦截 (“SSL 检查”) ，通常通过 Zscaler 或类似的安全网关进行。Devin Desktop Editor 必须与外部服务建立出站 TLS 连接 (用于登录和依赖云端的功能) 。如果经过检查的流量被企业检查 CA 重新签名，而你的机器/运行时不信任该 CA (或证书链不完整) ，Devin Desktop 可能会因 SSL/证书错误或协商错误而无法连接。

尤其是在以下情况下，可能需要排查 SSL/TLS 检查问题：

* 你看到“Failed to connect”或类似的网络错误

* 编辑器或 Cascade 面板显示空白，且始终无法加载

* Cascade 或其他依赖云端的功能无法加载或连接

* 登录或激活流程意外失败

* 功能在热点或家庭网络上可用，但在公司网络上失败

* 你在 logs/devtools 中看到证书或 TLS 握手错误

<Note>
  如果你还遇到与代理相关的问题，请参阅 [Proxy Configuration](/zh/desktop/troubleshooting/windsurf-proxy-configuration)。
</Note>

***

<div id="1-check-whether-your-network-uses-ssl-inspection">
  ## 1. 检查你的网络是否使用 SSL 检查
</div>

在更改编辑器中的任何内容之前，请先向你的 IT / 安全 / 网络团队确认：

* 我们是否会对出站 HTTPS 流量进行 TLS 拦截 / SSL 检查？

* 是否已为开发人员工作站和开发工具 (而不仅仅是浏览器) 启用 SSL 检查？

* 用于对受检流量进行签名的是哪条 根 CA / 中间 CA 证书链？

* 该 CA 证书链是否已部署到端点，并且受到用于开发的应用程序/运行时信任？

如果你的组织不使用 SSL 检查，通常无需遵循本指南。如果你的组织确实使用 SSL 检查，请继续阅读下文。

***

<div id="2-capture-the-underlying-error-in-devin-desktop-developer-tools-console">
  ## 2. 在 Devin Desktop 中定位底层错误 (Developer Tools → Console)
</div>

Devin Desktop Editor (基于 VS Code) 提供了 Developer Tools，可显示实际的 TLS/证书错误。

1. 打开 **Help → Dev Tools** / **Developer Tools**

2. 选择 **Console** 选项卡

3. 查找**红色报错**

4. 展开每条错误记录，查看完整详情 (嵌套错误字段 / stack traces)

常见错误模式包括：

**证书信任失败 (CA 不受信任) ：**

* `certificate signed by unknown authority`

* `unable to verify the first certificate`

* `self signed certificate in certificate chain`

* `UNABLE_TO_VERIFY_LEAF_SIGNATURE`

**证书链构建失败 (缺少中间证书) ：**

* `unable to get local issuer certificate`

* `unable to get issuer certificate`

**TLS 协商失败：**

* `handshake_failure`

* `wrong version number`

* `protocol negotiation failed`

* `ERR_SSL_PROTOCOL_ERROR`

如果你能将展开后的控制台报错文本提供给 IT/安全团队，通常能显著缩短排查和解决时间。

***

<div id="3-what-causes-this-in-ssl-inspected-environments">
  ## 3. 在启用 SSL 检查的环境中，这种情况的成因
</div>

启用 SSL 检查后，网关会终止并重新建立 TLS 连接。客户端看到的是一个合成的服务器证书，该证书由企业检查 CA (根 CA，有时还包括中间 CA 证书) 签发。

Devin Desktop 连接失败通常发生在以下情况：

* 端点**不信任**企业检查的**根 CA**，和/或

* 检查证书**链不完整** (缺少中间 CA) ，和/或

* IDE/运行时使用了**非操作系统信任存储**，其中不包含企业检查 CA 证书链，和/或

* Enterprise 策略强制实施了会导致 TLS 协商失败的约束 (最低 TLS 版本/密码套件、阻止无法解密的流量等)

这通常是企业证书/信任/策略配置问题，而不是 Devin Desktop 本身的实现问题。

***

<div id="4-work-with-your-it-security-team-to-resolve">
  ## 4. 与你的 IT / 安全团队协作解决问题
</div>

由于 SSL 检查和证书部署由你的组织控制，因此通常需要 IT/安全团队做出相应更改才能解决。

<div id="a-validate-ssl-inspection-policy-for-devin-desktop-traffic">
  ### A) 验证 Devin Desktop 流量的 SSL 检查策略
</div>

请 IT/安全团队确认：

* SSL 检查是否适用于与 Devin Desktop 相关的出站 HTTPS 流量

* 是否会因证书验证、策略原因或 TLS 协商限制而被拦截或拒绝

<div id="b-ensure-the-enterprise-inspection-ca-chain-is-correctly-deployed-and-trusted">
  ### B) 确保企业 SSL 检查 CA 证书链已正确部署并被信任
</div>

请 IT/安全团队：

* 将企业 SSL 检查 **根 CA** 部署到开发者终端设备

* 确保所有必需的**中间 CA 证书**均已安装，且证书链正确

* 使用与 IDE/运行时相同的信任存储来验证信任状态 (操作系统存储 vs. 运行时专用存储)

<div id="c-configure-a-scoped-ssl-inspection-bypass-fallback">
  ### C) 配置有范围限制的 SSL 检查 Bypass (备用方案)
</div>

如果无法实现信任对齐，请让 IT/安全团队：

* 为所需的 Devin Desktop 服务端点创建 SSL 检查 Bypass (按照你的组织的 allowlist/网络要求流程)

* 将该 Bypass 严格限定在必要范围内，并符合你的安全策略

***

<div id="5-what-to-send-to-it-security-copypaste">
  ## 5. 发给 IT / 安全团队的内容 (可直接复制粘贴)
</div>

**问题：** Devin Desktop Editor 在企业网络中连接失败；很可能是 SSL 检查 / TLS 拦截导致的证书信任或证书链问题。

**证据：** Help → Developer Tools → Console 显示 TLS/证书或握手错误 (可提供展开后的红色控制台报错) 。

**请求：**

1. 确认是否已对与 Devin Desktop 相关的出站 HTTPS 流量启用 SSL 检查。

2. 确认企业 SSL 检查的 根 CA 及所有中间证书已在此端点上部署并受信任 (以及在 IDE 使用的任何运行时专用信任存储中也已受信任) 。

3. 如果无法完成信任对齐，请为所需的 Devin Desktop 服务端点按作用域配置 SSL 检查 Bypass。

**请附上：**

* 故障时间戳

* OS 版本

* 是否安装/启用了 Zscaler Client Connector (或类似 Agent)

* Developer Tools → Console 中展开后的控制台报错文本

* 是否在热点/家庭网络上可以正常使用，但在企业网络中失败

***

<div id="6-when-to-use-which-option">
  ## 6. 何时使用哪种选项
</div>

如果符合以下情况，请使用证书部署/信任修复：

* 错误提示包含“unknown authority”“unable to verify”“issuer not found”，或缺少中间证书

* 你希望在保持启用 SSL 检查的同时，采用最持久的修复方案

如果符合以下情况，请使用特定作用域的 SSL 检查 Bypass：

* IDE/runtime 实际上无法使用企业 CA 证书链

* 在你的环境中，信任存储难以保持一致

* IT/安全团队确认故障由检查引起，并批准了有针对性的例外

如果你不确定该用哪一种，IT/安全团队才是权威依据——他们可以确认是否启用了 SSL 检查、使用的是哪条 CA 证书链、端点如何管理，以及是否适合使用 Bypass 规则。