> ## 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 故障排查：doctor 运维手册

> 气隙版 Devin CLI 和 Desktop 中 devin airgap doctor 的运维手册：各项检查的验证内容，pass、warn 和 FAIL 的含义，以及需要提供给支持团队的信息。

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

当 CLI 或 Desktop 无法启动、无法连接模型或显示错误代码时，应首先运行 `devin airgap doctor`。该命令会执行智能体所依赖的全部本地和网络检查，每项检查输出一行结果；只要有任一检查失败，就会以非零状态码退出。本页将逐项说明各检查的含义及处理方法，并介绍提交支持请求时需要收集的信息。

***

## 运行 doctor

请以将要使用 Devin 的用户身份，在同一环境中运行该命令 (必须已在该 shell 中设置 API 密钥相关变量) ：

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

```text theme={null}
pass  license                                seat alice@example.gov (account acme), expires 2027-03-01
pass  models file path                       /etc/devin/models.json
pass  config dir writable                    /home/alice/.config/devin/cli-federal
pass  data dir writable                      /home/alice/.local/share/devin/cli-federal
pass  CA bundle                              not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)
pass  models file parse                      1 model(s) configured
pass  model 'llama-3.3-70b': API key env var  LOCAL_LLAMA_API_KEY is set
pass  custom subagent profiles               none configured
pass  model 'llama-3.3-70b': endpoint reachability  GET https://models.internal:8000/v1/models -> 200 OK
pass  model 'llama-3.3-70b': inference conformance  POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)

10 check(s): 10 passed, 0 warning(s), 0 failure(s)
```

每行的格式为 `<status>  <check>  <detail>`。对于带错误码的失败项和警告，详情会以[错误码](/zh/federal/air-gapped/error-codes)作为前缀，例如 `FAIL  model 'llama-3.3-70b': endpoint reachability  NET003: ...`。

| 状态 | 含义 | 退出状态 |
| - | - | - |
| `pass` | 检查通过。 | |
| `warn` | Devin 可以运行，但存在需要尽快处理的问题 (许可证即将过期、未实现 `/models`、已跳过探测) 。 | `0` |
| `FAIL` | 在修复此问题之前，Devin 无法正常工作。 | 非零，并输出 `doctor found N failing check(s)` |

用于自动化场景时，`--json` 会输出 `{"ok": <bool>, "checks": [...]}`，其中每项检查包含 `check`、`status` (`pass`、`warn`、`fail`) 和 `detail`；带错误码的警告和失败项还会包含 `code`，通过的推理探测还会包含 `latency_ms`：

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

```json theme={null}
{
  "ok": true,
  "checks": [
    {
      "check": "license",
      "status": "pass",
      "detail": "seat alice@example.gov (account acme), expires 2027-03-01"
    },
    {
      "check": "model 'llama-3.3-70b': inference conformance",
      "status": "pass",
      "detail": "POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)",
      "latency_ms": 412
    }
  ]
}
```

Desktop 使用的是同一个内置 CLI，因此在 Desktop 所在主机的终端中运行 doctor，同样可以诊断 Desktop 的问题。

## 检查项参考

检查按以下顺序运行。如果前面的某项检查失败，依赖它的后续检查会直接跳过，而不会重复执行：例如，若找不到模型文件，就不会出现 `models file parse` 这一行，也不会进行端点探测。

### `license`

加载并验证许可证文件 (参见[许可证](/zh/federal/air-gapped/license)) 。

| 结果 | 详情 | 操作 |
| - | - | - |
| `pass` | `seat <label> (account <id>), expires <YYYY-MM-DD>` | 无。 |
| `warn` | 剩余不足 30 天时显示 `... (<n> day(s) left) — contact your administrator to renew it`；也可能显示 `(less than a day left)` 或 `already expired (within the clock-skew grace period)` | 请在 24 小时宽限期结束前续订并替换许可证。 |
| `FAIL` | `LIC00n: <message>`，随后显示 `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.` | 请参照[错误代码](/zh/federal/air-gapped/error-codes#lic-license)中 `LIC` 行的说明处理。 |

### `models file path`

解析模型文件的位置 (`/etc/devin/models.json`；Windows 上为 `C:\ProgramData\Devin\models.json`；或 `DEVIN_MODELS_FILE` 指定的路径) ，并确认该位置存在文件。

| 结果 | 操作 |
| - | - |
| `pass`，并显示解析后的路径 | 无。 |
| `FAIL CFG003` | 安装模型文件，或修复 `DEVIN_MODELS_FILE` 的值。所有模型文件检查和端点检查都将跳过。 |

### `config dir writable` 和 `data dir writable`

按需创建产品的配置目录和数据目录，并分别向其中写入一个探测文件。

| 结果 | 操作 |
| - | - |
| `pass` (附目录路径) | 无。 |
| `FAIL CFG001` | 详细信息会指明该目录是无法解析、无法创建还是无法写入。请修复目录的所有权和权限，确保运行 Devin 的用户具有相应访问权限，或将 `XDG_CONFIG_HOME` / `XDG_DATA_HOME` 设置为可写位置。在 Windows 上，CLI 不会读取 `XDG_*`，请修复 `%APPDATA%\devin\` 的权限。 |

### `CA bundle`

报告是否已设置 `DEVIN_CA_BUNDLE`，并加载该文件。

| 结果 | 详情 | 操作 |
| - | - | - |
| `pass` | `not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)` | 无需操作，除非您的端点使用私有 CA。 |
| `pass` | `<path> (<n> certificate(s))` | 无需操作。 |
| `FAIL CFG004` | 文件无法加载的原因 | 修复路径或 PEM 内容；请参阅[网络与证书](/zh/federal/air-gapped/network-and-certificates)。 |

### `models file parse` and `model '<name>': API key env var`

使用与 `devin models validate` 相同的验证器解析模型文件，然后检查当前环境中是否已设置每个模型的 `api_key.env` 变量。

| 结果 | 操作 |
| - | - |
| `pass  models file parse  <n> model(s) configured` | 无。 |
| `FAIL  models file parse  <message> (run devin models validate for structured MDL diagnostics)` | 运行 `devin models validate`，并逐一修复各个 `MDL` 代码；请参阅[模型文件](/zh/federal/air-gapped/models-file)。此时将跳过端点探测。 |
| `pass  model '<name>': API key env var  <VAR> is set` | 无。 |
| `FAIL CFG002  environment variable '<VAR>' (referenced by api_key.env) is not set` | 在当前 shell 中导出该变量；如使用 Desktop，则将其添加到 `devin.acp.agentEnv` 中。请参阅[API 密钥环境变量](/zh/federal/air-gapped/models-file#api-key-environment-variables)。该模型的端点探测将被跳过，并标记为 `warn`。 |

### `custom subagent profiles`

列出 `agents/**/AGENT.md` 中的自定义子智能体定义。结果为 `none configured` 或 `<n> profile(s) loaded` 时即为通过；`CFG005` 会指明无法解析的定义。此检查与标准 `devin doctor` 共用，与气隙配置无关。

### `model '<name>': endpoint reachability`

使用该模型的 API 密钥发送 `GET {base_url}/models` 请求，超时时间为 10 秒，TLS 配置与推理请求相同。

| 结果 | 详情 | 操作 |
| - | - | - |
| `pass` | `GET <url> -> 200 OK` | 无。如果详情中附加了 `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`，说明该文件包必不可少：请确保每台主机上都配置了它。 |
| `warn NET004` | `GET <url> -> 404 Not Found (server may not implement /models)` | 无；端点可以访问，下方的推理探测才是真正的检验。 |
| `warn CFG002` | `skipped: API key env var '<VAR>' is not set` | 设置该变量 (见上文) 。 |
| `FAIL NET006` | `GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'` | 该变量已设置，但其值不适用于此端点。 |
| `FAIL NET004` | `GET <url> -> <status>` | 检查端点的日志以及 `base_url` 路径。 |
| `FAIL NET001` / `NET002` / `NET005` | DNS、TCP 或超时错误链 | 在同一工作站上检查名称解析、防火墙和代理规则，以及端点的健康状况。 |
| `FAIL NET003` | TLS 错误链，接着是服务器出示的证书 (主体、签发方、到期时间) ，最后是 `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` 或 `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem` | 将输出中的签发方与您的文件包中的证书进行比对；参见[网络与证书](/zh/federal/air-gapped/network-and-certificates)。 |

### `model '<name>': inference conformance`

如果可达性检查在传输层失败，则跳过此项。此项会发送一个仅含单个令牌的请求，以验证该端点支持已配置的 API：对于 `chat_completions`，发送 `POST {base_url}/chat/completions` 并设置 `max_tokens: 1`；对于 `responses`，发送 `POST {base_url}/responses` 并设置 `max_output_tokens: 16`。

| 结果 | 详情 | 操作 |
| - | - | - |
| `pass` | `POST <url> -> 200 OK (<n> ms)` | 无需操作。该延迟可作为后续对比的基线环境。 |
| `FAIL NET006` | `POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'` | 修复该密钥。 |
| `FAIL NET004` | `POST <url> -> <status>: <first 200 characters of the response body>` | 响应体通常会指明问题所在：模型名称未知 (请求使用的是您的模型文件中的 `name`，它必须与服务器实际提供的模型一致) 、`api` 值与该服务器不匹配，或服务端出错。 |
| `FAIL NET00n` | 传输错误链 | 处理方式同可达性检查。 |

## 常见问题

| 症状 | 可能原因 | 排查位置 |
| - | - | - |
| Doctor 在终端中检查通过，但 Desktop 无法连接到模型 | Desktop 内置的智能体不会继承你的 shell 环境，因此 API 密钥变量未设置 | [API 密钥环境变量](/zh/federal/air-gapped/models-file#api-key-environment-variables) |
| 同一主机上仅有一名用户检查未通过 | 用户级状态问题：`~/.config/devin` 或 `~/.local/share/devin` (Windows 上为 `%APPDATA%\devin`) 的权限有误，或 `sso_tokens.toml` 已过时 (`IDP006`) | [磁盘文件格式](/zh/federal/air-gapped/on-disk-formats) |
| `devin auth login` 成功，但会话运行一段时间后终止 | 重新验证失败：用户已被移出 `required_group`，或 IdP 会话已被撤销 | [SSO (单点登录) ](/zh/federal/air-gapped/sso#revalidation-in-running-sessions)以及 `sso_revalidation_failed` 审计事件 |
| 仅部分主机出现 `NET003` | 这些主机未设置 `DEVIN_CA_BUNDLE`，或使用了不同的证书文件包 | [网络与证书](/zh/federal/air-gapped/network-and-certificates) |
| 安装更新后或在新环境中出现 `LIC004` | 构建与许可证来自不同环境，或发生了密钥轮换 | [许可证：检查密钥 ID](/zh/federal/air-gapped/license#check-the-key-id) |
| 在 Desktop 中保存模型时出现 `MDL014` | 模型文件归 root 或其他用户所有 (在 Windows 上则归管理员所有，而你是标准用户) | 以文件所有者身份直接在磁盘上编辑该文件 |

## 需要提供给支持团队的内容

请在受影响的工作站上收集以下内容。发送前请逐一检查每个文件；这些文件均不会自动上传。

1. doctor 输出：

   ```sh theme={null}
   devin airgap doctor --json > doctor.json
   ```

   ```text theme={null}
   (no output; the command exits nonzero if a check failed)
   ```

   其中的详细信息字符串会包含您的端点 URL 和主机名，但绝不会包含 API 密钥值。

2. 已脱敏的诊断信息报告：

   ```sh theme={null}
   devin diagnostics --output devin-diagnostics.txt
   ```

   ```text theme={null}
   Diagnostics written to devin-diagnostics.txt
   The report is plain text and stays on this machine; review it before sharing.
   ```

   该报告会记录版本信息、各配置文件是否存在及能否正常解析、模型名称、各 API 密钥变量是否已设置，以及审计日志统计信息。报告中绝不会包含提示、代码、文件内容、敏感值、端点 URL 或环境变量值。

3. 向用户显示的完整错误消息 (包括错误码) ，以及 `devin --version` 的输出。

4. 如果是 SSO (单点登录) 问题，请提供[审计日志](/zh/federal/air-gapped/on-disk-formats#audit-log)中相关的 `auth` 事件 (`error_code` 和 `action` 字段) ，以及您的 IdP 日志中对应的条目。

请勿发送许可证文件、API 密钥值、`sso_tokens.toml` 或 `sessions.db`。


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