> ## 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 的网络与证书

> 为您的网络配置气隙 Devin Desktop 和 CLI：使用 DEVIN_CA_BUNDLE 信任私有 CA、使用代理，以及排查 NET 和 CFG004 错误代码。

> [!NOTE]
>
> 本文档适用于 Devin 的联邦部署。[返回 Devin 文档](/zh/get-started/devin-intro)

气隙版 CLI 和 Desktop 会连接以下目标：[模型文件](/zh/federal/air-gapped/models-file)中的模型端点、[认证文件](/zh/federal/air-gapped/sso)中的身份提供商签发方，以及您在本地配置的所有 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 发出的所有请求。

**1. 组装文件包**

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

```sh theme={null}
sudo install -m 0644 ./corp-root-ca.pem /etc/devin/ca-bundle.pem
```

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

```sh theme={null}
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 字段，也不支持为每个端点单独配置文件包。

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

```sh theme={null}
export DEVIN_CA_BUNDLE=/etc/devin/ca-bundle.pem
```

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

**3. 使用 doctor 确认**

```sh theme={null}
devin airgap doctor
```

```text theme={null}
…
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`；参见[磁盘存储格式](/zh/federal/air-gapped/on-disk-formats)) 中添加 `proxy` 块：

```json theme={null}
{
  "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 配置文件参考](/zh/cli/reference/configuration/config-file#proxy)。

如果代理会终止 TLS 并用自己的 CA 对流量重新签名，则该代理视同私有 CA：请将其证书添加到 `DEVIN_CA_BUNDLE`。连接仍然只会发往本页顶部列出的目标地址；代理改变的只是连接路径，而非目标地址范围。

## 超时

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

探测超时会报告为 `NET005`。

## NET 代码

`devin airgap doctor` 会为每个失败的端点探测附上以下代码之一。你在支持请求中看到的也是这些代码。完整目录请参阅[错误代码](/zh/federal/air-gapped/error-codes)页面。

| 代码 | 含义 | 处理方法 |
| - | - | - |
| `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` 所指定的环境变量的值。 |

## 相关 CFG 代码

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.