气隙 Devin 的网络与证书

本文档适用于 Devin 的联邦部署。返回 Devin 文档

气隙版 CLI 和 Desktop 会连接以下目标：模型文件中的模型端点、认证文件中的身份提供商签发方，以及您在本地配置的所有 MCP 服务器。本页介绍这些连接对网络的要求：TLS 信任、可选代理，以及连接失败时显示的错误代码。

TLS 要求

每个模型的 base_url 以及 SSO (单点登录) 的 issuer 都必须使用 https://。只有回环主机 (localhost、127.0.0.0/8、[::1]) 才允许使用普通的 http://。
证书会通过操作系统的信任存储进行验证 (macOS 上为 Security.framework，Linux 上为系统 CA 存储) 。如果您的端点由工作站上已安装的 CA 签名，则无需额外配置。
如果您的端点由不在操作系统信任存储中的私有 CA 签名，请按下文所述，通过 DEVIN_CA_BUNDLE 添加该 CA。CLI 始终不会禁用证书验证。

使用 `DEVIN_CA_BUNDLE` 信任私有 CA

DEVIN_CA_BUNDLE 用于指定一个 PEM 文件，其中的证书会在操作系统信任存储之外额外获得信任。该设置适用于推理请求、devin airgap doctor 探测，以及 CLI 在 SSO (单点登录) 登录和重新验证期间向您的 IdP 发出的所有请求。

组装文件包

将私有 CA 的根证书 (以及中间证书，如有) 放入同一个 PEM 文件中。该文件可以包含多个 -----BEGIN CERTIFICATE----- 块。

sudo install -m 0644 ./corp-root-ca.pem /etc/devin/ca-bundle.pem

各端点无需共用同一证书或同一 CA。整个智能体进程只使用一个文件包，且该文件包适用于所有连接。因此，如果不同端点由不同的私有 CA 签发，请将这些 CA 全部合并到同一个文件中：

cat ./corp-root-ca.pem ./ml-platform-ca.pem ./idp-root-ca.pem | sudo tee /etc/devin/ca-bundle.pem > /dev/null
sudo chmod 0644 /etc/devin/ca-bundle.pem

使用该文件包后，https://vllm.corp.example (由 corp-root-ca 签发) 、https://models.ml.example (由 ml-platform-ca 签发) 以及您的 IdP (由 idp-root-ca 签发) 都将受到信任。如果端点由操作系统信任存储中已有的 CA 签发，则无需添加条目。模型文件不提供按模型设置的证书或 TLS 字段，也不支持为每个端点单独配置文件包。

在智能体的环境中导出该变量

export DEVIN_CA_BUNDLE=/etc/devin/ca-bundle.pem

该变量必须对运行智能体的进程可见。对于终端 CLI，请在每个用户的 shell Profile 中设置该变量。对于 Desktop，请按照设置模型 API 密钥变量的方式进行设置 (参见 API 密钥环境变量) ：将其添加到 devin.acp.agentEnv 设置中，或在 macOS 上运行 launchctl setenv DEVIN_CA_BUNDLE /etc/devin/ca-bundle.pem (open 不会将 shell 环境传递给应用) 。

使用 doctor 确认

devin airgap doctor

…
pass  CA bundle                                 /etc/devin/ca-bundle.pem (3 certificate(s))
pass  model 'llama-3.3-70b': endpoint reachability  GET https://vllm.corp.example/v1/models -> 200 OK (trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)
pass  model 'qwen3-vl-32b': endpoint reachability  GET https://models.ml.example/v1/models -> 200 OK (trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)
…

后缀 trusted only via DEVIN_CA_BUNDLE 表明端点正是借助该文件包才获得信任：doctor 会对每个可达端点仅使用操作系统信任存储重试一次，并报告该次尝试是否在 TLS 阶段失败。如果未设置该变量，CA bundle 一行将显示 not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)。

如果文件无法读取、包含无效的 PEM 段或不含任何证书，doctor 会将 CA bundle 检查判定为失败，并给出 CFG004 及解析器的报错信息 (例如 failed to read CA bundle '/etc/devin/ca-bundle.pem': No such file or directory) 。而在运行时，同样的情况并不会导致致命错误：CLI 会输出一行 warning: ignoring DEVIN_CA_BUNDLE: …，并回退到操作系统信任存储。因此，路径拼写错误不会表现为启动错误，而是表现为访问端点时出现 NET003 TLS 失败项。请修复文件包，然后重新运行 doctor。

代理

气隙 CLI 的出站代理处理方式与标准 Devin CLI 相同。默认情况下 ("mode": "system") ，它会遵循 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY 环境变量，以及操作系统的 PAC/自动代理设置。如需强制使用特定代理或完全绕过代理，请在用户配置文件 (即共享 Devin 配置目录中的 config.json；参见磁盘存储格式) 中添加 proxy 块：

{
  "proxy": {
    "mode": "manual",
    "url": "http://proxy.corp.example:8080",
    "no_proxy": "localhost,127.0.0.1,.corp.example"
  }
}

`mode`	行为
`"system"` (默认)	使用代理环境变量和平台 PAC 设置。
`"manual"`	所有流量均经由 `url` (`http://`、`https://` 或 `socks5://`) 转发，并忽略通过环境变量配置的代理。
`"off"`	直接连接，忽略所有代理设置。

no_proxy 在所有模式下均生效，语法与 NO_PROXY 环境变量相同。若要为主机上的所有用户统一设置代理，请将相同的 proxy 块放入全系统策略文件 system.json (Linux 上为 /etc/devin/system.json，macOS 上为 /Library/Application Support/Devin/system.json，Windows 上为 C:\ProgramData\Devin\system.json) ；如果两个文件都定义了 proxy，CLI 将拒绝启动，直到你删除用户级的副本。完整的选项说明请参阅 CLI 配置文件参考。如果代理会终止 TLS 并用自己的 CA 对流量重新签名，则该代理视同私有 CA：请将其证书添加到 DEVIN_CA_BUNDLE。连接仍然只会发往本页顶部列出的目标地址；代理改变的只是连接路径，而非目标地址范围。

超时

连接	超时时间
`devin airgap doctor` 探测 (连接及总时长)	每个请求 10 秒
发往 IdP 的 SSO (单点登录) 请求 (自动发现、令牌、JWKS)	每个请求 30 秒
推理请求	连接超时 30 秒；超过 300 秒未收到数据则放弃读取

探测超时会报告为 NET005。

NET 代码

devin airgap doctor 会为每个失败的端点探测附上以下代码之一。你在支持请求中看到的也是这些代码。完整目录请参阅错误代码页面。

代码	含义	处理方法
`NET001`	端点主机的 DNS 解析失败。	检查模型文件或认证文件中的主机名，并确认工作站的解析器能够解析该主机名 (`getent hosts <host>` 或 `dig <host>`) 。
`NET002`	无法建立 TCP 连接 (连接被拒绝、被重置或无法路由) 。	检查该端口能否从工作站访问，以及防火墙或代理是否放行。
`NET003`	TLS 握手失败 (证书不受信任、已过期或不匹配) 。如果能够获取，doctor 会附上服务器出示的证书信息 (`subject`、`issuer`、`expires`) ，并注明 `DEVIN_CA_BUNDLE` 是否生效。	如果签发方是你的私有 CA，请设置或修正 `DEVIN_CA_BUNDLE`。如果证书已过期或其名称与 URL 不匹配，请修复服务器证书。
`NET004`	端点返回了 401/403 以外的非成功 HTTP 状态码。`GET {base_url}/models` 返回 `404` 仅视为警告，因为部分 OpenAI 兼容服务器未实现 `/models`。	检查 `base_url` 是否包含正确的前缀 (通常为 `/v1`) ，以及服务器是否运行正常。
`NET005`	请求超时。	检查网络延迟，并确认端点未过载；`/models` 探测应在 10 秒内返回响应。
`NET006`	端点拒绝了已配置的凭据 (HTTP 401/403) 。	检查模型的 `api_key.env` 所指定的环境变量的值。

代码	含义	处理方法
`CFG002`	模型的 `api_key.env` 所指定的环境变量未在智能体的环境中设置，Doctor 将跳过该模型的网络探测。	在启动智能体的环境中导出该变量；请参阅模型文件。
`CFG004`	`DEVIN_CA_BUNDLE` 文件缺失、无法读取，或不含任何有效的 PEM 证书。	修复路径或文件内容；错误消息中会指明具体的解析错误。

​TLS 要求

​使用 DEVIN_CA_BUNDLE 信任私有 CA

​代理

​超时

​NET 代码

​相关 CFG 代码

TLS 要求

使用 `DEVIN_CA_BUNDLE` 信任私有 CA

代理

超时

NET 代码

相关 CFG 代码