> ## 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.

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

> Runbook per devin airgap doctor su Devin CLI e Desktop air-gapped: cosa verifica ciascun controllo, cosa significano pass, warn e FAIL e cosa inviare al supporto.

> [!NOTE]
>
> Questa documentazione riguarda le distribuzioni di Devin per il governo federale. [Torna alla documentazione di Devin](/it/get-started/devin-intro)

`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):

```sh theme={null}
devin airgap doctor
```

```text theme={null}
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](/it/federal/air-gapped/error-codes), 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:

```sh theme={null}
devin airgap doctor --json
```

```json theme={null}
{
  "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](/it/federal/air-gapped/license)).

| 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](/it/federal/air-gapped/error-codes#lic-license). |

### `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](/it/federal/air-gapped/network-and-certificates). |

### `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](/it/federal/air-gapped/models-file). 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](/it/federal/air-gapped/models-file#api-key-environment-variables). 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](/it/federal/air-gapped/network-and-certificates). |

### `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](/it/federal/air-gapped/models-file#api-key-environment-variables) |
| 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](/it/federal/air-gapped/on-disk-formats) |
| `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](/it/federal/air-gapped/sso#revalidation-in-running-sessions) 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](/it/federal/air-gapped/network-and-certificates) |
| `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](/it/federal/air-gapped/license#check-the-key-id) |
| `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.

1. L'output di doctor:

   ```sh theme={null}
   devin airgap doctor --json > doctor.json
   ```

   ```text theme={null}
   (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.

2. Il report dei dati diagnostici, con i dati sensibili oscurati:

   ```sh theme={null}
   devin diagnostics --output devin-diagnostics.txt
   ```

   ```text theme={null}
   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.

3. Il messaggio di errore esatto mostrato all'utente, compreso il relativo codice, e l'output di `devin --version`.

4. Per i problemi di SSO, gli eventi `auth` pertinenti del [registro di audit](/it/federal/air-gapped/on-disk-formats#audit-log) (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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.