气隙 Devin 错误代码参考

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

气隙 CLI 和 Desktop 可诊断的每一类故障，都会以 XXXnnn 格式的固定代码报告。这些代码会出现在终端错误消息的开头、devin airgap doctor 的输出、Desktop 诊断信息，以及 auth 审计事件的 error_code 字段中。代码编号对应的是故障情形，而非提示文字，因此你可以据此编写支持运行手册、配置 SIEM 告警。

命名空间	涵盖范围	详细页面
`LIC`	许可证文件验证	许可证
`MDL`	模型文件验证	模型文件
`IDP`	SSO (单点登录) 和身份提供商	SSO
`NET`	端点可达性、TLS、HTTP 探测	网络和证书
`CFG`	本地路径、配置、环境	网络和证书、模型文件

`LIC` 许可证

输出格式为 LIC00n: <message>，随后会显示所检查的路径以及如何覆盖该路径 (DEVIN_LICENSE_FILE) 。

代码	含义	处理方法
`LIC001`	`/etc/devin/license.devin-onprem-license` (Windows 上为 `C:\ProgramData\Devin\license.devin-onprem-license`) 或 `DEVIN_LICENSE_FILE` 所指路径下的许可证文件缺失或无法读取。在 Windows 上，标准用户尝试通过 Desktop 替换管理员所有的许可证时，也会返回此错误。	将文件安装到默认路径，或设置 `DEVIN_LICENSE_FILE`；检查运行 Devin 的用户是否具有读取权限。
`LIC002`	文件格式错误：不是有效的 EdDSA JWT，或标头中缺少 `kid`。	从门户重新下载许可证，并确保逐字节传输 (不得添加换行符、自动折行或更改编码) 。
`LIC003`	签名验证失败。	载荷在签名后遭到篡改。请重新下载许可证。
`LIC004`	未知的 `kid`：此构建中未内置与之匹配的公钥。	运行 `kid` 检查。该许可证由其他环境签发，或您的构建早于某次密钥轮换；请安装当前发布版本。
`LIC005`	已过期，且已超出 24 小时宽限期。	通过门户续订许可证。
`LIC006`	尚未生效：签发时间晚于当前时间 24 小时以上。	检查主机时钟；如果时钟无误，请联系您的支持团队。
`LIC007`	`product` 声明错误 (不是 `devin-onprem`) 。	该文件不是气隙 Devin 许可证。请从门户重新下载。

`MDL` 模型文件

以下诊断由 devin models validate、devin airgap doctor、Desktop 的模型设置报告，也会在智能体启动时报告。每条诊断都会注明其对应的模型条目。

代码	含义	处理方法
`MDL001`	文件不是符合 schema v0 的有效 JSON (包括含有未知字段的情况) 。	修复 JSON；移除 schema 中未定义的字段。
`MDL002`	不支持的 `schema_version`。	设置 `"schema_version": 0`。
`MDL003`	`models` 为空。	至少添加一个模型条目。
`MDL004`	某个模型的 `name` 为空。	为每个条目设置唯一的 `name`。
`MDL005`	模型 `name` 重复。	重命名其中一个条目。
`MDL006`	`base_url` 为空。	设置端点 URL。
`MDL007`	`api_key.env` 为空。	指定存放密钥的环境变量名称。
`MDL008`	`max_context_tokens` 为零。	设置该模型的上下文窗口。
`MDL009`	有多个模型被标记为 `default`。	仅在一个条目上保留 `default: true`。
`MDL010`	`base_url` 不是带主机名的 `https://` URL (仅环回地址允许使用 `http://`) 。	使用 `https://`；若服务器位于同一主机，也可使用环回地址。
`MDL011`	`max_output_tokens` 超过 `max_context_tokens`。	调低 `max_output_tokens`。
`MDL012`	文件存在但无法读取 (权限问题或 UTF-8 编码无效) 。	为运行 Devin 的用户修复读取权限；将文件保存为 UTF-8 编码。
`MDL013`	`max_output_tokens` 为零。	移除该字段或将其设为正值。
`MDL014`	文件归其他用户所有，因此 Desktop 拒绝替换该文件。	以文件所有者身份直接在磁盘上编辑该文件，或将 `DEVIN_MODELS_FILE` 指向你拥有的文件。

`IDP` SSO (单点登录) 与身份提供商

以下错误码由 devin auth login、devin auth status 报告，也会在智能体启动时以及 Desktop 登录流程中报告。发生 sso_login_denied 事件时，IDP004 和 IDP005 还会被写入审计日志；任何 IDP code 都可能出现在 sso_revalidation_failed 事件中。

Code	含义	处理方法
`IDP001`	认证文件无法读取或无效。	修复 `/etc/devin/auth.json` (Windows 上为 `C:\ProgramData\Devin\auth.json`) ，或 `DEVIN_AUTH_FILE` 所指路径下的文件；错误消息会指出出错的字段。
`IDP002`	没有已配置签发方的缓存登录信息。	运行 `devin auth login`。
`IDP003`	登录无效或已过期，且无法静默刷新 (包括 IdP 返回 `invalid_grant` 响应的情况) 。	重新运行 `devin auth login`。
`IDP004`	已登录，但用户不是 `required_group` 的成员。	在 IdP 中将该用户添加到该组，或更正认证文件中的 `required_group` / `groups_claim`。
`IDP005`	无法连接 IdP、IdP 返回错误，或返回的 ID 令牌未通过验证。	检查网络连通性、TLS 信任 (`DEVIN_CA_BUNDLE`) 、`issuer` 值以及 IdP 自身的日志。
`IDP006`	本地 SSO 令牌缓存无法读取、格式错误，或并非当前用户私有。	运行 `devin auth login`；重新登录后，缓存会以仅所有者可访问的权限重新写入。

`NET` 网络

此类错误由 devin airgap doctor 的端点探测以及推理请求和 IdP 请求报告。每个 NET 故障都会附带底层错误链。

代码	含义	处理方法
`NET001`	端点主机的 DNS 解析失败。	检查模型文件或认证文件中的主机名，以及工作站上的 DNS 配置。
`NET002`	无法建立 TCP 连接 (连接被拒绝、被重置或不可路由) 。	检查端点是否在该端口上监听，以及防火墙或代理规则是否允许工作站访问该端点。
`NET003`	TLS 握手失败：证书不受信任、已过期或不匹配。如能获取，`devin airgap doctor` 会打印服务器提供的证书信息 (主题、签发方、到期时间) ，并显示 `DEVIN_CA_BUNDLE` 是否生效。	通过 `DEVIN_CA_BUNDLE` 信任私有 CA，或修复服务器证书 (名称、证书链、到期时间) 。
`NET004`	端点返回了除 401/403 以外的非成功 HTTP 状态码。`GET {base_url}/models` 返回 `404` 时仅作为警告报告，因为部分 OpenAI 兼容服务器未实现 `/models`。	检查端点自身的日志以及 `base_url` 路径 (例如是否缺少 `/v1`) 。
`NET005`	请求超时 (doctor 探测为 10 秒，IdP 请求为 30 秒，推理请求为连接 30 秒 / 读取 300 秒) 。	检查端点及所有中间代理的负载；参见超时。
`NET006`	端点拒绝了已配置的凭据 (HTTP 401/403) 。	检查 `api_key.env` 变量中的值，并确认该密钥对该端点有效。

`CFG` 配置

由 devin airgap doctor 报告，启动时也会报告。

代码	含义	处理方法
`CFG001`	必需的配置目录或状态目录缺失或不可写 (`~/.config/devin`、`~/.local/share/devin` 或 `cli-federal` 产品目录；在 Windows 上为 `%APPDATA%\devin` 或其 `cli-federal` 子目录) 。	创建该目录，或为运行 Devin 的用户修复该目录的所有权和权限。
`CFG002`	配置中引用的环境变量 (模型的 `api_key.env`) 未在智能体的环境中设置。	导出该变量，或通过 Desktop 的 `devin.acp.agentEnv` 设置项进行设置；参见 API 密钥环境变量。
`CFG003`	在 `/etc/devin/models.json` (Windows 上为 `C:\ProgramData\Devin\models.json`) 或 `DEVIN_MODELS_FILE` 覆盖设置指定的路径中找不到模型文件。	安装模型文件；参见模型文件。
`CFG004`	`DEVIN_CA_BUNDLE` 文件缺失、不可读，或不包含有效的 PEM 证书。	修正路径或文件内容；参见网络和证书。
`CFG005`	无法解析自定义子智能体定义 (`agents/**/AGENT.md` 或扁平结构的 `agents/<name>.md`) ，最常见的原因是 YAML 前置元数据无效；该 Profile 会被跳过。如果定义中声明了 Devin 不读取的前置元数据键 (例如写成 `allowed_tools` 而非 `allowed-tools`) ，也会报告警告，但该 Profile 仍会加载。	根据 `devin doctor` 输出的解析错误，修复其指出的文件。
`CFG006`	设置了会被 OTLP 导出忽略的 `OTEL_EXPORTER_OTLP_*` 环境变量 (除 `ENDPOINT`、`HEADERS`、`TIMEOUT`、`PROTOCOL` 以外的任何字段；任何 `TRACES_` 变量；或不受支持的 `PROTOCOL`) 。此项为警告，只会输出变量名，绝不会输出变量值。	删除或更正该变量。

CFG005 和 CFG006 来自标准的 devin doctor 检查，并非气隙构建所特有。

解读失败信息

以下是一个典型的验证失败示例：

devin models validate

/etc/devin/models.json: 1 problem(s) found
  MDL010 [model 'qwen3-vl-32b']: model 'qwen3-vl-32b': `base_url` must be an https:// URL (plain http:// is only allowed for loopback addresses: localhost, 127.0.0.0/8, or [::1])

在上方表格中找到对应的代码，按说明处理，然后重新运行 devin airgap doctor，直到所有检查均通过。如果某个代码未在此列出，说明您的构建版本比本页面更新；请运行 devin --version，并按照故障排查中的说明，在支持请求中附上完整的报错信息。

​LIC 许可证

​MDL 模型文件

​IDP SSO (单点登录) 与身份提供商

​NET 网络

​CFG 配置

​解读失败信息

`LIC` 许可证

`MDL` 模型文件

`IDP` SSO (单点登录) 与身份提供商

`NET` 网络

`CFG` 配置

解读失败信息