> ## 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. # Arquivo de modelos do Devin air-gapped > Referência do schema e exemplo comentado do arquivo models.json, que aponta o Devin air-gapped para seus endpoints de modelos compatíveis com a OpenAI, além dos códigos MDL. > [!NOTE] > > Esta documentação se aplica às implantações federais do Devin. [Voltar para a Documentação do Devin](/pt-BR/get-started/devin-intro) 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\`](/pt-BR/federal/air-gapped/install#windows-lock-down-the-configuration-folder) antes de colocar o arquivo lá. ## Exemplo completo ```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 } ] } ``` 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 '': API key environment variable '' 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`): ```json theme={null} "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: ```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 … ``` ## Valide o arquivo ```sh theme={null} devin models validate ``` ```text theme={null} /etc/devin/models.json: OK ``` Opções: | Opção | Significado | | - | - | | `--file ` | 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: ```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]) ``` 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](/pt-BR/federal/air-gapped/error-codes). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.