气隙 Devin 模型文件

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

气隙 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\ 之前，请先锁定该文件夹。

完整示例

{
  "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 中配置) ：
  "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 用户环境中设置这些变量。

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

devin airgap doctor

…
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
…

验证文件

devin models validate

/etc/devin/models.json: OK

选项：

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

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

devin models validate --file ./models.json

./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 代码报告；请参阅错误代码。

​位置

​完整示例

​Schema 参考 (版本 0)

​API 密钥环境变量

​验证文件

​应用更改

​错误代码

位置

完整示例

Schema 参考 (版本 0)

API 密钥环境变量

验证文件

应用更改

错误代码