File dei modelli di Devin air-gapped

Questa documentazione riguarda le distribuzioni di Devin per il governo federale. Torna alla documentazione di Devin

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\ prima di collocarvi il file.

Esempio 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
    }
  ]
}

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 '<name>': API key environment variable '<VAR>' 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):
  "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:

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
…

Convalidare il file

devin models validate

/etc/devin/models.json: OK

Opzioni:

Opzione	Significato
`--file <path>`	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:

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

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.

​Posizione

​Esempio completo

​Riferimento dello schema (versione 0)

​Variabili d’ambiente per le chiavi API

​Convalidare il file

​Applicare le modifiche

​Codici di errore

Posizione

Esempio completo

Riferimento dello schema (versione 0)

Variabili d’ambiente per le chiavi API

Convalidare il file

Applicare le modifiche

Codici di errore