Arquivo de modelos do Devin air-gapped

Esta documentação se aplica às implantações federais do Devin. Voltar para a Documentação do Devin

O Devin air-gapped obtém a configuração de modelos de um único arquivo JSON criado por você. Esse arquivo define a origem dos endpoints de modelos, e as requisições de inferência são enviadas para os endpoints compatíveis com a OpenAI listados nele.

Localização

Precedência	Origem
1	`$DEVIN_MODELS_FILE` (caminho absoluto)
2	`/etc/devin/models.json` (Windows: `C:\ProgramData\Devin\models.json`)

A CLI, o comando devin models validate e a seção Modelos das configurações do Desktop localizam o arquivo da mesma forma. O caminho do sistema normalmente pertence ao root; use DEVIN_MODELS_FILE para substituições por usuário. No Windows, restrinja o acesso a C:\ProgramData\Devin\ antes de colocar o arquivo lá.

Exemplo completo

{
  "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
    }
  ]
}

O exemplo mostra todos os campos, as duas interfaces de API (chat_completions e responses) e um endpoint http:// de loopback. Copie-o para /etc/devin/models.json (C:\ProgramData\Devin\models.json no Windows) e faça as edições necessárias.

Referência do schema (versão 0)

Nível top-level:

Campo	Obrigatório	Significado
`schema_version`	sim	Deve ser `0`.
`models`	sim	Array não vazio de entradas de modelo.

Cada entrada em models:

Campo	Obrigatório	Significado
`name`	sim	Slug único do modelo. Os usuários o selecionam com `--model` na CLI ou com `/model` em uma sessão.
`display_name`	não	Nome legível exibido nos menus. O padrão é `name`.
`base_url`	sim	URL base do endpoint compatível com OpenAI. Deve usar `https://`; `http://` simples só é aceito para hosts de loopback (`localhost`, `127.0.0.0/8`, `[::1]`), por exemplo, um servidor vLLM ou Ollama na mesma máquina.
`api_key.env`	sim	Nome da variável de ambiente que contém a chave de API. O valor da chave nunca aparece no arquivo, nos diagnósticos nem na interface de configurações do Desktop.
`api`	não	`chat_completions` (padrão) ou `responses`.
`capabilities`	não	Qualquer combinação de `vision`, `reasoning` e `parallel_tool_calls`.
`max_context_tokens`	sim	Janela de contexto em tokens; deve ser diferente de zero.
`max_output_tokens`	não	Limite de saída em tokens; deve ser diferente de zero e não pode exceder `max_context_tokens`.
`default`	não	Define o modelo padrão. No máximo uma entrada pode usar esse campo.

O schema é estrito: campos desconhecidos são rejeitados, então um erro de digitação gera falha na validação em vez de ser ignorado silenciosamente. Não existe bloco de endpoint top-level nem chave de API inline.

Variáveis de ambiente da chave de API

api_key.env é uma indireção. O agente lê a chave do ambiente do seu próprio processo na inicialização. A variável precisa estar definida para cada modelo listado, mesmo para endpoints que ignoram a chave (como Ollama ou um vLLM sem autenticação), ainda que esteja vazia. Caso contrário, o agente não inicia e exibe model '<name>': API key environment variable '<VAR>' is not set.

CLI: exporte a variável no shell (ou na unit do systemd/launchd) que executa o devin.
Desktop: o agente integrado herda o ambiente do app Desktop, não o do seu terminal. Uma variável exportada em ~/.zshrc normalmente não fica visível para um app iniciado pelo Dock, Finder ou Spotlight. Forneça-a de uma destas formas:
- Recomendado: a configuração devin.acp.agentEnv (Settings → Devin Local → Environment Variables, ou em settings.json):
  "devin.acp.agentEnv": { "devin-cli": { "VLLM_API_KEY": "...", "OLLAMA_API_KEY": "ollama" } }
  Os valores são mesclados ao ambiente do agente quando ele é iniciado. Reinicie o agente ou o app após alterá-los. Use a mesma configuração para DEVIN_MODELS_FILE se o arquivo não estiver no caminho padrão.
- Ambiente de inicialização: no macOS, o open não repassa o ambiente do seu shell para o app. Execute launchctl setenv VAR value para tornar uma variável visível para apps iniciados pelo Dock e pelo Finder até o próximo login, ou inicie o app a partir de um shell com as variáveis exportadas, executando diretamente o executável em /Applications/Devin - Airgap.app/Contents/MacOS/. No Linux, defina as variáveis no launcher .desktop ou no ambiente de usuário do systemd.

Confirme a partir do mesmo ambiente em que o agente é executado:

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
…

Valide o arquivo

devin models validate

/etc/devin/models.json: OK

Opções:

Opção	Significado
`--file <path>`	Valida um arquivo diferente do padrão resolvido.
`--format text` (padrão) ou `--format json`	Formato de saída.

Se houver problemas, cada diagnóstico é exibido com seu código e o modelo ao qual se aplica, e o comando termina com código de saída diferente de zero:

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])

O formato JSON retorna {"path": …, "valid": false, "diagnostics": [...]} para uso em automações. O devin models validate pode ser executado mesmo sem uma licença válida, então você pode preparar o arquivo antes que a licença seja instalada.

Aplicar alterações

Os backends de modelos são inicializados na inicialização do processo. Depois de editar o arquivo, reinicie a CLI (ou o agente integrado, no Desktop) para carregar a nova configuração. Se o arquivo estiver ausente ou for inválido, a CLI autônoma não inicia e exibe o erro. O agente integrado do Desktop inicia em modo degradado, sem modelos: as sessões não conseguem executar inferência, e a seção de configurações Modelos exibe os diagnósticos MDL para que você possa corrigir o arquivo ali mesmo. O Desktop valida o arquivo antes de salvar, nunca grava um arquivo inválido, grava de forma atômica e se recusa (MDL014) a substituir um arquivo pertencente a outro usuário. Assim, um /etc/devin/models.json pertencente ao root só pode ser alterado por um administrador, diretamente no disco. No Windows, quando o arquivo de modelos pertence a um administrador, um usuário padrão não consegue salvar as configurações de modelos pelo Desktop (o salvamento é recusado com MDL014), mas um administrador consegue.

Códigos de erro

Código	Significado	O que fazer
`MDL001`	O arquivo não é um JSON válido para o schema v0, incluindo campos desconhecidos	Corrija o JSON; remova os campos que não constam na tabela do schema acima
`MDL002`	`schema_version` não suportado	Defina `"schema_version": 0`
`MDL003`	`models` está vazio	Adicione pelo menos uma entrada de modelo
`MDL004`	Um modelo tem `name` vazio	Atribua um `name` único a cada entrada
`MDL005`	`name` de modelo duplicado	Renomeie uma das entradas
`MDL006`	`base_url` vazio	Defina a URL do endpoint
`MDL007`	`api_key.env` vazio	Informe o nome da variável de ambiente que contém a chave
`MDL008`	`max_context_tokens` é zero	Defina a janela de contexto do modelo
`MDL009`	Mais de um modelo marcado como `default`	Mantenha `default: true` em apenas uma entrada
`MDL010`	`base_url` não é uma URL `https://` com host (`http://` apenas para loopback)	Use `https://` ou um endereço de loopback para um servidor no mesmo host
`MDL011`	`max_output_tokens` excede `max_context_tokens`	Reduza `max_output_tokens`
`MDL012`	O arquivo existe, mas não pôde ser lido (permissões ou UTF-8 inválido)	Corrija as permissões do usuário que executa o Devin; salve o arquivo em UTF-8
`MDL013`	`max_output_tokens` é zero	Remova o campo ou defina um valor positivo
`MDL014`	O arquivo pertence a outro usuário, por isso o Desktop se recusa a substituí-lo	Edite o arquivo no disco como proprietário dele ou aponte `DEVIN_MODELS_FILE` para um arquivo seu

Problemas de conectividade com o endpoint e de inferência detectados pelo devin airgap doctor são reportados com os códigos NET e CFG; consulte Códigos de erro.

​Localização

​Exemplo completo

​Referência do schema (versão 0)

​Variáveis de ambiente da chave de API

​Valide o arquivo

​Aplicar alterações

​Códigos de erro

Localização

Exemplo completo

Referência do schema (versão 0)

Variáveis de ambiente da chave de API

Valide o arquivo

Aplicar alterações

Códigos de erro