> ## 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. # File dei modelli di Devin air-gapped > Riferimento dello schema ed esempio commentato del file models.json che indirizza Devin air-gapped verso i tuoi endpoint di modelli compatibili con OpenAI, con l'elenco dei codici MDL. > [!NOTE] > > Questa documentazione riguarda le distribuzioni di Devin per il governo federale. [Torna alla documentazione di Devin](/it/get-started/devin-intro) Devin air-gapped legge la configurazione dei modelli da un unico file JSON creato da te. Il file definisce gli endpoint dei modelli e l'inferenza viene inviata agli endpoint compatibili con OpenAI in esso elencati. ## Posizione | Precedenza | Origine | | - | - | | 1 | `$DEVIN_MODELS_FILE` (percorso assoluto) | | 2 | `/etc/devin/models.json` (Windows: `C:\ProgramData\Devin\models.json`) | La CLI, `devin models validate` e la sezione **Modelli** delle impostazioni dell'app Desktop individuano il file allo stesso modo. Il percorso di sistema appartiene in genere a root; per le impostazioni specifiche di un singolo utente, usa `DEVIN_MODELS_FILE`. Su Windows, [proteggi `C:\ProgramData\Devin\`](/it/federal/air-gapped/install#windows-lock-down-the-configuration-folder) prima di collocarvi il file. ## Esempio 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 } ] } ``` L'esempio mostra tutti i campi, entrambe le funzionalità API (`chat_completions` e `responses`) e un endpoint `http://` di loopback. Copialo in `/etc/devin/models.json` (`C:\ProgramData\Devin\models.json` su Windows) e modificalo secondo le tue esigenze. ## Riferimento dello schema (versione 0) Livello top-level: | Campo | Obbligatorio | Significato | | - | - | - | | `schema_version` | sì | Deve essere `0`. | | `models` | sì | Array non vuoto di voci di modello. | Ogni voce in `models`: | Campo | Obbligatorio | Significato | | - | - | - | | `name` | sì | Slug univoco del modello. Gli utenti lo selezionano con `--model` nella CLI o con `/model` in una sessione. | | `display_name` | no | Etichetta leggibile dall'utente mostrata nei menu. Il valore predefinito è `name`. | | `base_url` | sì | URL di base dell'endpoint compatibile con OpenAI. Deve usare `https://`; il semplice `http://` è accettato solo per host di loopback (`localhost`, `127.0.0.0/8`, `[::1]`), ad esempio un server vLLM o Ollama sulla stessa macchina. | | `api_key.env` | sì | **Nome** della variabile d'ambiente che contiene la chiave API. Il valore della chiave non compare mai nel file, nei dati diagnostici o nell'interfaccia Settings di Desktop. | | `api` | no | `chat_completions` (predefinito) o `responses`. | | `capabilities` | no | Uno o più valori tra `vision`, `reasoning`, `parallel_tool_calls`. | | `max_context_tokens` | sì | Finestra di contesto in token; deve essere diversa da zero. | | `max_output_tokens` | no | Limite di output in token; deve essere diverso da zero e non può superare `max_context_tokens`. | | `default` | no | Indica il modello predefinito. Può essere impostato su una sola voce al massimo. | Lo schema è rigoroso: **i campi sconosciuti vengono rifiutati**, quindi un errore di battitura fa fallire la convalida invece di essere ignorato senza avvisi. Non esistono un blocco endpoint top-level né una chiave API inline. ## Variabili d'ambiente per le chiavi API `api_key.env` è un riferimento indiretto: l'agente legge la chiave dal **proprio ambiente di processo** all'avvio. La variabile deve essere **impostata** per ogni modello elencato, anche per gli endpoint che ignorano la chiave (come Ollama o un vLLM senza autenticazione); può anche essere vuota. In caso contrario, l'agente non si avvia e restituisce l'errore `model '': API key environment variable '' is not set`. * **CLI:** esporta la variabile nella shell, o nella unit systemd/launchd, che esegue `devin`. * **Desktop:** l'agente incluso nel bundle eredita l'ambiente dell'**app Desktop**, non quello del tuo terminale. Una variabile esportata in `~/.zshrc` di norma non è visibile a un'app avviata da Dock, Finder o Spotlight. Forniscila in uno dei seguenti modi: * **Consigliato:** l'impostazione `devin.acp.agentEnv` (**Settings → Devin Local → Environment Variables**, oppure in `settings.json`): ```json theme={null} "devin.acp.agentEnv": { "devin-cli": { "VLLM_API_KEY": "...", "OLLAMA_API_KEY": "ollama" } } ``` I valori vengono combinati con l'ambiente dell'agente al momento del suo avvio. Dopo averli modificati, riavvia l'agente o l'app. Usa la stessa impostazione per `DEVIN_MODELS_FILE` se il file non si trova nel percorso predefinito. * **Ambiente di avvio:** su macOS, `open` non passa all'app l'ambiente della tua shell. Puoi eseguire `launchctl setenv VAR value` per rendere una variabile visibile alle app avviate da Dock e Finder fino al login successivo, oppure avviare l'app da una shell in cui le variabili sono esportate, eseguendo direttamente l'eseguibile in `/Applications/Devin - Airgap.app/Contents/MacOS/`. Su Linux, imposta le variabili nel launcher `.desktop` o nell'ambiente utente di systemd. Verifica dallo stesso ambiente in cui viene eseguito l'agente: ```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 … ``` ## Convalidare il file ```sh theme={null} devin models validate ``` ```text theme={null} /etc/devin/models.json: OK ``` Opzioni: | Opzione | Significato | | - | - | | `--file ` | Convalida un file diverso da quello predefinito determinato dal sistema. | | `--format text` (predefinito) o `--format json` | Formato di output. | Se vengono rilevati problemi, ogni messaggio diagnostico viene stampato insieme al relativo codice e al modello a cui si riferisce, e il comando termina con un codice di uscita diverso da 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]) ``` L'output in formato JSON restituisce `{"path": …, "valid": false, "diagnostics": [...]}` per l'uso in automazione. `devin models validate` funziona anche senza una licenza valida, quindi puoi preparare il file prima di installare la licenza. ## Applicare le modifiche I backend dei modelli vengono inizializzati all'avvio del processo. Dopo aver modificato il file, riavvia la CLI, oppure l'agente incluso nel bundle in Desktop, per caricare la nuova configurazione. Se il file manca o non è valido, la CLI autonoma non si avvia e mostra l'errore. L'agente incluso nel bundle in Desktop si avvia in modalità **degradata**, senza modelli: le sessioni non possono eseguire l'inferenza e la sezione **Modelli** delle impostazioni mostra i dati diagnostici `MDL`, così puoi correggere il file direttamente. Desktop convalida il file prima di salvarlo, non scrive mai un file non valido, esegue scritture atomiche e si rifiuta (`MDL014`) di sostituire un file di proprietà di un altro utente: di conseguenza, un file `/etc/devin/models.json` di proprietà di root può essere modificato solo da un amministratore, direttamente su disco. Su Windows, se il file dei modelli è di proprietà di un amministratore, un utente standard non può salvare le impostazioni dei modelli da Desktop (il salvataggio viene rifiutato con `MDL014`), mentre un amministratore sì. ## Codici di errore | Codice | Significato | Cosa fare | | - | - | - | | `MDL001` | Il file non è un JSON valido per lo schema v0, ad esempio perché contiene campi sconosciuti | Correggi il JSON; rimuovi i campi non presenti nella tabella dello schema riportata sopra | | `MDL002` | `schema_version` non supportato | Imposta `"schema_version": 0` | | `MDL003` | `models` è vuoto | Aggiungi almeno una voce di modello | | `MDL004` | Un modello ha un `name` vuoto | Assegna a ogni voce un `name` univoco | | `MDL005` | `name` del modello duplicato | Rinomina una delle voci | | `MDL006` | `base_url` vuoto | Imposta l'URL dell'endpoint | | `MDL007` | `api_key.env` vuoto | Indica il nome della variabile d'ambiente che contiene la chiave | | `MDL008` | `max_context_tokens` è zero | Imposta la finestra di contesto del modello | | `MDL009` | Più di un modello contrassegnato come `default` | Lascia `default: true` su una sola voce | | `MDL010` | `base_url` non è un URL `https://` con un host (`http://` è consentito solo per il loopback) | Usa `https://` oppure un indirizzo di loopback per un server sullo stesso host | | `MDL011` | `max_output_tokens` supera `max_context_tokens` | Riduci `max_output_tokens` | | `MDL012` | Il file esiste ma non è stato possibile leggerlo (autorizzazioni insufficienti o UTF-8 non valido) | Correggi le autorizzazioni per l'utente che esegue Devin; salva il file in UTF-8 | | `MDL013` | `max_output_tokens` è zero | Rimuovi il campo o imposta un valore positivo | | `MDL014` | Il file appartiene a un altro utente, quindi Desktop si rifiuta di sostituirlo | Modifica il file su disco come suo proprietario, oppure fai puntare `DEVIN_MODELS_FILE` a un file di tua proprietà | I problemi di raggiungibilità degli endpoint e di inferenza rilevati da `devin airgap doctor` vengono segnalati con codici `NET` e `CFG`; consulta [Codici di errore](/it/federal/air-gapped/error-codes). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.