> ## 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 模型文件

> models.json 文件的 schema 参考及带注释的示例，该文件用于将气隙 Devin 指向您的 OpenAI 兼容模型端点；另附 MDL 代码说明。

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

气隙 Devin 的模型配置来自你编写的一个 JSON 文件。模型端点均以该文件为准，推理请求会发送到其中列出的 OpenAI 兼容端点。

## 位置

| 优先级 | 来源 |
| - | - |
| 1 | `$DEVIN_MODELS_FILE` (绝对路径) |
| 2 | `/etc/devin/models.json` (Windows：`C:\ProgramData\Devin\models.json`) |

CLI、`devin models validate` 以及 Desktop 的**模型**设置部分均采用相同方式解析该文件。系统路径通常归 root 所有；如需进行用户专属覆盖设置，请使用 `DEVIN_MODELS_FILE`。在 Windows 上，将文件放入 `C:\ProgramData\Devin\` 之前，请先[锁定该文件夹](/zh/federal/air-gapped/install#windows-lock-down-the-configuration-folder)。

## 完整示例

```json theme={null}
{
  "schema_version": 0,
  "models": [
    {
      "name": "llama-3.3-70b",
      "display_name": "Llama 3.3 70B (vLLM)",
      "base_url": "https://models.internal:8000/v1",
      "api_key": { "env": "VLLM_API_KEY" },
      "api": "chat_completions",
      "capabilities": ["parallel_tool_calls"],
      "max_context_tokens": 131072,
      "max_output_tokens": 8192,
      "default": true
    },
    {
      "name": "qwen3-vl-32b",
      "display_name": "Qwen3 VL 32B (vision)",
      "base_url": "https://gateway.internal/openai/v1",
      "api_key": { "env": "GATEWAY_API_KEY" },
      "api": "chat_completions",
      "capabilities": ["vision", "reasoning", "parallel_tool_calls"],
      "max_context_tokens": 65536,
      "max_output_tokens": 16384
    },
    {
      "name": "gpt-oss-120b",
      "display_name": "gpt-oss 120B (Responses API)",
      "base_url": "https://responses.internal:8080/v1",
      "api_key": { "env": "RESPONSES_API_KEY" },
      "api": "responses",
      "capabilities": ["reasoning"],
      "max_context_tokens": 131072
    },
    {
      "name": "llama3.1:8b",
      "display_name": "Llama 3.1 8B (Ollama)",
      "base_url": "http://localhost:11434/v1",
      "api_key": { "env": "OLLAMA_API_KEY" },
      "max_context_tokens": 32768
    }
  ]
}
```

该示例展示了所有字段、两种 API 界面 (`chat_completions` 和 `responses`) ，以及一个使用 `http://` 的回环端点。将其复制到 `/etc/devin/models.json` (Windows 上为 `C:\ProgramData\Devin\models.json`) ，然后按需修改。

## Schema 参考 (版本 0)

顶层：

| 字段 | 必填 | 含义 |
| - | - | - |
| `schema_version` | 是 | 必须为 `0`。 |
| `models` | 是 | 由模型条目组成的非空数组。 |

`models` 中的每个条目：

| 字段 | 必填 | 含义 |
| - | - | - |
| `name` | 是 | 唯一的模型 slug。用户可在 CLI 中通过 `--model`、或在会话中通过 `/model` 选择该模型。 |
| `display_name` | 否 | 显示在菜单中的便于人类理解的标签。默认为 `name`。 |
| `base_url` | 是 | 兼容 OpenAI 的端点的基础 URL。必须使用 `https://`；仅回环主机 (`localhost`、`127.0.0.0/8`、`[::1]`) 允许使用普通 `http://`，例如运行在同一台机器上的 vLLM 或 Ollama 服务器。 |
| `api_key.env` | 是 | 存放 API 密钥的环境变量的**名称**。密钥值绝不会出现在该文件、诊断信息或 Desktop 设置界面中。 |
| `api` | 否 | `chat_completions` (默认) 或 `responses`。 |
| `capabilities` | 否 | 可包含 `vision`、`reasoning`、`parallel_tool_calls` 中的任意项。 |
| `max_context_tokens` | 是 | 上下文窗口大小 (以 token 计) ；必须为非零值。 |
| `max_output_tokens` | 否 | 输出上限 (以 token 计) ；必须为非零值，且不得超过 `max_context_tokens`。 |
| `default` | 否 | 将该模型标记为默认模型。最多只能有一个条目设置此字段。 |

该 schema 采用严格校验：**未知字段会被拒绝**，因此拼写错误会直接导致验证失败，而不会被静默忽略。配置中没有顶层的端点块，也不支持内联 API 密钥。

## API 密钥环境变量

`api_key.env` 是一种间接引用：智能体在启动时从其**自身进程环境**中读取密钥。列出的每个模型都必须**设置**该变量，即使端点会忽略密钥 (例如 Ollama 或未启用身份验证的 vLLM) 也不例外；变量值可以为空。否则，智能体将无法启动，并报错 `model '<name>': API key environment variable '<VAR>' is not set`。

* **CLI：** 在运行 `devin` 的 shell 或 systemd/launchd 单元中导出该变量。
* **Desktop：** 内置智能体继承的是 **Desktop 应用**的环境，而非你终端的环境。通过 Dock、Finder 或 Spotlight 启动的应用通常读取不到在 `~/.zshrc` 中导出的变量。请通过以下任一方式提供该变量：
  * **推荐：** 使用 `devin.acp.agentEnv` 设置 (**设置 → Devin Local → 环境变量**，或在 `settings.json` 中配置) ：

    ```json theme={null}
    "devin.acp.agentEnv": {
      "devin-cli": { "VLLM_API_KEY": "...", "OLLAMA_API_KEY": "ollama" }
    }
    ```

    智能体创建时，这些值会合并到其环境中。修改后请重启智能体或应用。如果 `DEVIN_MODELS_FILE` 指向的文件不在默认路径下，也可通过此设置进行配置。
  * **启动环境：** 在 macOS 上，`open` 不会将 shell 的环境传递给应用。你可以运行 `launchctl setenv VAR value`，让变量在下次登录前对通过 Dock 和 Finder 启动的应用可见；也可以在已导出这些变量的 shell 中，直接运行 `/Applications/Devin - Airgap.app/Contents/MacOS/` 下的可执行文件来启动应用。在 Linux 上，请在 `.desktop` 启动器或 systemd 用户环境中设置这些变量。

请在智能体运行的同一环境中确认：

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

```text theme={null}
…
pass  model 'llama-3.3-70b': API key env var  VLLM_API_KEY is set
FAIL  model 'qwen3-vl-32b': API key env var   CFG002: environment variable 'GATEWAY_API_KEY' (referenced by `api_key.env`) is not set
…
```

## 验证文件

```sh theme={null}
devin models validate
```

```text theme={null}
/etc/devin/models.json: OK
```

选项：

| 选项 | 含义 |
| - | - |
| `--file <path>` | 验证解析得到的默认文件之外的其他文件。 |
| `--format text` (默认) 或 `--format json` | 输出格式。 |

如果发现问题，命令会逐条打印诊断信息 (包括其代码及所适用的模型) ，并以非零状态退出：

```sh theme={null}
devin models validate --file ./models.json
```

```text theme={null}
./models.json: 2 problem(s) found
  MDL005 [model 'llama-3.3-70b']: duplicate model name 'llama-3.3-70b'
  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])
```

JSON 格式的输出会返回 `{"path": …, "valid": false, "diagnostics": [...]}`，便于自动化处理。`devin models validate` 无需有效许可证即可运行，因此你可以在安装许可证之前就准备好该文件。

## 应用更改

模型后端在进程启动时初始化。编辑该文件后，请重启 CLI，或在 Desktop 中重启内置的智能体，以加载新配置。

如果该文件缺失或无效，独立 CLI 会拒绝启动并输出错误信息。Desktop 内置的智能体则会以**降级**状态启动，且不加载任何模型：会话无法执行推理，**模型**设置部分会显示 `MDL` 诊断信息，方便你直接就地修复该文件。Desktop 会在保存前进行校验，绝不会写入无效文件，并采用原子写入；同时会拒绝替换属于其他用户的文件 (`MDL014`) ，因此属于 root 的 `/etc/devin/models.json` 只能由管理员直接在磁盘上修改。在 Windows 上，如果模型文件归管理员所有，标准用户无法通过 Desktop 保存模型设置 (保存会被拒绝，并返回 `MDL014`) ，而管理员可以正常保存。

## 错误代码

| 代码 | 含义 | 处理方法 |
| - | - | - |
| `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` 指向你拥有的文件 |

`devin airgap doctor` 检测到的端点可达性和推理问题会以 `NET` 和 `CFG` 代码报告；请参阅[错误代码](/zh/federal/air-gapped/error-codes)。


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