Risoluzione dei problemi di Devin air-gapped: Runbook di doctor

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

devin airgap doctor è il primo comando da eseguire quando la CLI o Desktop non si avvia, non riesce a raggiungere un modello o mostra un codice di errore. Esegue tutti i controlli locali e di rete da cui dipende l’agente, stampa una riga per ciascun controllo e restituisce un codice di uscita diverso da zero se un controllo non va a buon fine. Questa pagina illustra ciascun controllo e come intervenire, quindi descrive cosa raccogliere per una richiesta di supporto.

Eseguire doctor

Eseguilo con lo stesso utente che userà Devin e nello stesso ambiente (le variabili della chiave API devono essere impostate in quella shell):

devin airgap doctor

pass  license                                seat alice@example.gov (account acme), expires 2027-03-01
pass  models file path                       /etc/devin/models.json
pass  config dir writable                    /home/alice/.config/devin/cli-federal
pass  data dir writable                      /home/alice/.local/share/devin/cli-federal
pass  CA bundle                              not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)
pass  models file parse                      1 model(s) configured
pass  model 'llama-3.3-70b': API key env var  LOCAL_LLAMA_API_KEY is set
pass  custom subagent profiles               none configured
pass  model 'llama-3.3-70b': endpoint reachability  GET https://models.internal:8000/v1/models -> 200 OK
pass  model 'llama-3.3-70b': inference conformance  POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)

10 check(s): 10 passed, 0 warning(s), 0 failure(s)

Ogni riga ha il formato <status> <check> <detail>. Per gli errori e gli avvisi associati a un codice, il dettaglio è preceduto dal codice di errore, ad esempio FAIL model 'llama-3.3-70b': endpoint reachability NET003: ....

Stato	Significato	Stato di uscita
`pass`	Il controllo è riuscito.
`warn`	Devin verrà eseguito, ma a breve qualcosa richiederà attenzione (licenza in scadenza, `/models` non implementato, probe saltato).	`0`
`FAIL`	Devin non funzionerà correttamente finché il problema non sarà risolto.	diverso da zero, con `doctor found N failing check(s)`

Per l’automazione, --json stampa {"ok": <bool>, "checks": [...]}, dove ogni controllo contiene check, status (pass, warn, fail) e detail, oltre a code per avvisi ed errori associati a un codice e latency_ms per una verifica di inferenza riuscita:

devin airgap doctor --json

{
  "ok": true,
  "checks": [
    {
      "check": "license",
      "status": "pass",
      "detail": "seat alice@example.gov (account acme), expires 2027-03-01"
    },
    {
      "check": "model 'llama-3.3-70b': inference conformance",
      "status": "pass",
      "detail": "POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)",
      "latency_ms": 412
    }
  ]
}

Desktop usa la stessa CLI inclusa nel bundle, quindi per diagnosticare anche i problemi di Desktop esegui doctor da un terminale sull’host di Desktop.

Riferimento dei controlli

I controlli vengono eseguiti nell’ordine indicato di seguito. I controlli successivi che dipendono da un errore precedente vengono saltati anziché ripetuti: se il file dei modelli non viene trovato, non compare la riga models file parse e non vengono eseguite le probe degli endpoint.

`license`

Carica e verifica il file di licenza (vedi Licenza).

Risultato	Dettaglio	Azione
`pass`	`seat <label> (account <id>), expires <YYYY-MM-DD>`	Nessuna.
`warn`	`... (<n> day(s) left) — contact your administrator to renew it` quando mancano meno di 30 giorni; `(less than a day left)`; oppure `already expired (within the clock-skew grace period)`	Rinnova e sostituisci la licenza prima che scada il periodo di tolleranza di 24 ore.
`FAIL`	`LIC00n: <message>` seguito da `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.`	Segui le indicazioni della riga `LIC` in Codici di errore.

`models file path`

Determina il percorso del file dei modelli (/etc/devin/models.json, C:\ProgramData\Devin\models.json su Windows, oppure DEVIN_MODELS_FILE) e verifica che il file esista in quella posizione.

Risultato	Azione
`pass` con il percorso determinato	Nessuna.
`FAIL CFG003`	Installa il file dei modelli o correggi il valore di `DEVIN_MODELS_FILE`. Tutti i controlli sul file dei modelli e sugli endpoint vengono ignorati.

`config dir writable` e `data dir writable`

Crea, se necessario, le directory di configurazione e dei dati del prodotto e scrive un file di prova in ciascuna.

Risultato	Azione
`pass` con il percorso della directory	Nessuna.
`FAIL CFG001`	Il dettaglio indica se non è stato possibile determinare, creare o scrivere nella directory. Correggi proprietario e autorizzazioni per l’utente che esegue Devin, oppure imposta `XDG_CONFIG_HOME` / `XDG_DATA_HOME` su un percorso scrivibile. Su Windows la CLI non legge `XDG_*`: correggi le autorizzazioni di `%APPDATA%\devin\`.

`CA bundle`

Indica se DEVIN_CA_BUNDLE è impostato e lo carica.

Risultato	Dettaglio	Azione
`pass`	`not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)`	Nessuna, a meno che i tuoi endpoint non usino una CA privata.
`pass`	`<path> (<n> certificate(s))`	Nessuna.
`FAIL CFG004`	Motivo per cui non è stato possibile caricare il file	Correggi il percorso o il contenuto PEM; consulta Rete e certificati.

`models file parse` and `model '<name>': API key env var`

Analizza il file dei modelli con lo stesso validatore usato da devin models validate, quindi verifica che la variabile api_key.env di ciascun modello sia impostata nell’ambiente attuale.

Risultato	Azione
`pass models file parse <n> model(s) configured`	Nessuna.
`FAIL models file parse <message> (run devin models validate for structured MDL diagnostics)`	Esegui `devin models validate` e correggi ciascun codice `MDL`; consulta File dei modelli. I probe degli endpoint vengono saltati.
`pass model '<name>': API key env var <VAR> is set`	Nessuna.
`FAIL CFG002 environment variable '<VAR>' (referenced by api_key.env) is not set`	Esporta la variabile in questa shell oppure, per Desktop, aggiungila a `devin.acp.agentEnv`; consulta Variabili d’ambiente della chiave API. I probe degli endpoint per quel modello vengono saltati con un `warn`.

`custom subagent profiles`

Elenca le definizioni dei sottoagenti personalizzati presenti in agents/**/AGENT.md. Il controllo ha esito positivo con none configured o <n> profile(s) loaded; CFG005 indica una definizione che non è stato possibile analizzare. Questo controllo è condiviso con il comando standard devin doctor e non riguarda la configurazione air-gapped.

`model '<name>': endpoint reachability`

Invia GET {base_url}/models con la chiave API del modello, con un timeout di 10 secondi e la stessa configurazione TLS usata per l’inferenza.

Risultato	Dettaglio	Azione
`pass`	`GET <url> -> 200 OK`	Nessuna. Se il dettaglio riporta anche `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`, il bundle è indispensabile: mantienilo configurato su ogni host.
`warn NET004`	`GET <url> -> 404 Not Found (server may not implement /models)`	Nessuna: l’endpoint è raggiungibile e il vero test è la verifica di inferenza descritta più avanti.
`warn CFG002`	`skipped: API key env var '<VAR>' is not set`	Imposta la variabile (vedi sopra).
`FAIL NET006`	`GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	La variabile è impostata, ma il suo valore non è valido per questo endpoint.
`FAIL NET004`	`GET <url> -> <status>`	Controlla i log dell’endpoint e il percorso `base_url`.
`FAIL NET001` / `NET002` / `NET005`	Catena di errori DNS, TCP o di timeout	Dalla stessa workstation, controlla la risoluzione dei nomi, le regole di firewall e proxy e lo stato operativo dell’endpoint.
`FAIL NET003`	Catena di errori TLS, seguita dal certificato presentato dal server (soggetto, emittente, scadenza) e infine da `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` oppure `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem`	Confronta l’emittente indicato con i certificati presenti nel tuo bundle; vedi Rete e certificati.

`model '<name>': inference conformance`

Viene saltato se il controllo di raggiungibilità non è riuscito a livello di trasporto. Invia una richiesta da un solo token per verificare che l’endpoint supporti l’API configurata: POST {base_url}/chat/completions con max_tokens: 1 per chat_completions, oppure POST {base_url}/responses con max_output_tokens: 16 per responses.

Risultato	Dettaglio	Azione
`pass`	`POST <url> -> 200 OK (<n> ms)`	Nessuna. La latenza è un utile valore di base per i confronti successivi.
`FAIL NET006`	`POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	Correggi la chiave.
`FAIL NET004`	`POST <url> -> <status>: <first 200 characters of the response body>`	In genere il corpo della risposta indica il problema: nome del modello sconosciuto (la richiesta usa il `name` indicato nel tuo file dei modelli, che deve corrispondere al modello eseguito dal server), valore `api` errato per questo server oppure un errore server-side.
`FAIL NET00n`	Catena di errori di trasporto	Come per la raggiungibilità.

Problemi comuni

Sintomo	Causa probabile	Dove verificare
Doctor ha esito positivo in un terminale, ma Desktop non riesce a raggiungere il modello	L’agente incluso nel bundle di Desktop non eredita l’ambiente della tua shell, quindi la variabile della chiave API non è impostata	Variabili d’ambiente della chiave API
Il controllo ha esito positivo per tutti gli utenti di un host tranne uno	Stato Per-user: autorizzazioni su `~/.config/devin` o `~/.local/share/devin` (`%APPDATA%\devin` su Windows), oppure un file `sso_tokens.toml` inattivo (`IDP006`)	Formati su disco
`devin auth login` riesce, ma dopo un po’ le sessioni terminano	Rivalidazione non riuscita: l’utente è stato rimosso da `required_group` oppure la sessione dell’IdP è stata revocata	SSO e l’evento di audit `sso_revalidation_failed`
`NET003` solo su alcuni host	Su quegli host `DEVIN_CA_BUNDLE` non è impostata oppure punta a un bundle diverso	Rete e certificati
`LIC004` dopo l’installazione di un aggiornamento o in un nuovo ambiente	La build e la licenza provengono da ambienti diversi, oppure è avvenuta una rotazione della chiave	Licenza: verificare l’ID della chiave
`MDL014` durante il salvataggio dei modelli in Desktop	Il file dei modelli appartiene a root o a un altro utente (su Windows, a un amministratore, mentre tu sei un utente Standard)	Modifica il file su disco come suo proprietario

Cosa inviare al supporto

Raccogli quanto segue sulla workstation interessata. Controlla ogni file prima di inviarlo: nessuno di essi viene caricato automaticamente.

L’output di doctor:
devin airgap doctor --json > doctor.json
(no output; the command exits nonzero if a check failed)
Le stringhe di dettaglio contengono gli URL dei tuoi endpoint e i nomi host, ma mai i valori delle chiavi API.
Il report dei dati diagnostici, con i dati sensibili oscurati:
devin diagnostics --output devin-diagnostics.txt
Diagnostics written to devin-diagnostics.txt The report is plain text and stays on this machine; review it before sharing.
Il report riporta le versioni, se ciascun file di configurazione esiste e viene analizzato correttamente, i nomi dei modelli, se ciascuna variabile della chiave API è impostata e le statistiche del registro di audit. Non contiene mai prompt, codice, contenuti dei file, valori segreti, URL degli endpoint o valori delle variabili d’ambiente.
Il messaggio di errore esatto mostrato all’utente, compreso il relativo codice, e l’output di devin --version.
Per i problemi di SSO, gli eventi auth pertinenti del registro di audit (campi error_code e action) e le voci corrispondenti nei log del tuo IdP.

Non inviare il file di licenza, i valori delle chiavi API, sso_tokens.toml né sessions.db.

​Eseguire doctor

​Riferimento dei controlli

​license

​models file path

​config dir writable e data dir writable

​CA bundle

​models file parse and model '<name>': API key env var

​custom subagent profiles

​model '<name>': endpoint reachability

​model '<name>': inference conformance

​Problemi comuni

​Cosa inviare al supporto

Eseguire doctor

Riferimento dei controlli

`license`

`models file path`

`config dir writable` e `data dir writable`

`CA bundle`

`models file parse` and `model '<name>': API key env var`

`custom subagent profiles`

`model '<name>': endpoint reachability`

`model '<name>': inference conformance`

Problemi comuni

Cosa inviare al supporto