气隙 Devin 故障排查：doctor 运维手册

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

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

运行 doctor

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

devin airgap doctor

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>。对于带错误码的失败项和警告，详情会以错误码作为前缀，例如 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：

devin airgap doctor --json

{
  "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`

加载并验证许可证文件 (参见许可证) 。

结果	详情	操作
`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.`	请参照错误代码中 `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 内容；请参阅网络与证书。

`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` 代码；请参阅模型文件。此时将跳过端点探测。
`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 密钥环境变量。该模型的端点探测将被跳过，并标记为 `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`	将输出中的签发方与您的文件包中的证书进行比对；参见网络与证书。

`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 密钥环境变量
同一主机上仅有一名用户检查未通过	用户级状态问题：`~/.config/devin` 或 `~/.local/share/devin` (Windows 上为 `%APPDATA%\devin`) 的权限有误，或 `sso_tokens.toml` 已过时 (`IDP006`)	磁盘文件格式
`devin auth login` 成功，但会话运行一段时间后终止	重新验证失败：用户已被移出 `required_group`，或 IdP 会话已被撤销	SSO (单点登录) 以及 `sso_revalidation_failed` 审计事件
仅部分主机出现 `NET003`	这些主机未设置 `DEVIN_CA_BUNDLE`，或使用了不同的证书文件包	网络与证书
安装更新后或在新环境中出现 `LIC004`	构建与许可证来自不同环境，或发生了密钥轮换	许可证：检查密钥 ID
在 Desktop 中保存模型时出现 `MDL014`	模型文件归 root 或其他用户所有 (在 Windows 上则归管理员所有，而你是标准用户)	以文件所有者身份直接在磁盘上编辑该文件

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

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

doctor 输出：
devin airgap doctor --json > doctor.json
(no output; the command exits nonzero if a check failed)
其中的详细信息字符串会包含您的端点 URL 和主机名，但绝不会包含 API 密钥值。
已脱敏的诊断信息报告：
devin diagnostics --output devin-diagnostics.txt
Diagnostics written to devin-diagnostics.txt The report is plain text and stays on this machine; review it before sharing.
该报告会记录版本信息、各配置文件是否存在及能否正常解析、模型名称、各 API 密钥变量是否已设置，以及审计日志统计信息。报告中绝不会包含提示、代码、文件内容、敏感值、端点 URL 或环境变量值。
向用户显示的完整错误消息 (包括错误码) ，以及 devin --version 的输出。
如果是 SSO (单点登录) 问题，请提供审计日志中相关的 auth 事件 (error_code 和 action 字段) ，以及您的 IdP 日志中对应的条目。

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

​运行 doctor

​检查项参考

​license

​models file path

​config dir writable 和 data dir writable

​CA bundle

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

​custom subagent profiles

​model '<name>': endpoint reachability

​model '<name>': inference conformance

​常见问题

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

运行 doctor

检查项参考

`license`

`models file path`

`config dir writable` 和 `data dir writable`

`CA bundle`

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

`custom subagent profiles`

`model '<name>': endpoint reachability`

`model '<name>': inference conformance`

常见问题

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