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

# Fehlerbehebung für Air-Gapped Devin: doctor-Runbook

> Runbook für devin airgap doctor in der air-gapped Devin CLI und Devin Desktop: was die einzelnen Prüfungen verifizieren, was pass, warn und FAIL bedeuten und was Sie an den Support senden sollten.

> [!NOTE]
>
> Diese Dokumentation gilt für föderale Deployments von Devin. [Zurück zur Devin-Dokumentation](/de/get-started/devin-intro)

Wenn die CLI oder Desktop nicht startet, kein Modell erreicht oder einen Fehlercode anzeigt, sollten Sie zuerst `devin airgap doctor` ausführen. Der Befehl führt alle lokalen und Netzwerkprüfungen aus, auf die der Agent angewiesen ist, gibt pro Prüfung eine Zeile aus und beendet sich mit einem Exit-Code ungleich null, sobald eine Prüfung fehlschlägt. Auf dieser Seite werden die einzelnen Prüfungen und die jeweils erforderlichen Maßnahmen erläutert. Anschließend erfahren Sie, welche Informationen Sie für eine Support-Anfrage zusammenstellen sollten.

***

## doctor ausführen

Führen Sie den Befehl als der Nutzer aus, der Devin verwenden wird, und zwar in derselben Umgebung (die Umgebungsvariablen für den API-Schlüssel müssen in dieser Shell gesetzt sein):

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

Jede Zeile hat das Format `<status>  <check>  <detail>`. Bei Fehlschlägen und Warnungen mit Code wird dem Detail der [Fehlercode](/de/federal/air-gapped/error-codes) vorangestellt, zum Beispiel `FAIL  model 'llama-3.3-70b': endpoint reachability  NET003: ...`.

| Status | Bedeutung | Exit-Status |
| - | - | - |
| `pass` | Die Prüfung war erfolgreich. | |
| `warn` | Devin läuft, aber etwas sollte bald behoben werden (Lizenz läuft ab, `/models` nicht implementiert, Test übersprungen). | `0` |
| `FAIL` | Devin funktioniert erst wieder korrekt, wenn das Problem behoben ist. | ungleich null, mit `doctor found N failing check(s)` |

Für Automatisierungen gibt `--json` die Ausgabe `{"ok": <bool>, "checks": [...]}` aus. Jede Prüfung enthält dabei `check`, `status` (`pass`, `warn`, `fail`) und `detail`, bei Warnungen und Fehlschlägen mit Code zusätzlich `code` und bei einem erfolgreichen Inferenztest `latency_ms`:

```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 verwendet dieselbe mitgelieferte CLI. Führen Sie doctor daher in einem Terminal auf dem Desktop-Host aus, um auch Probleme mit Desktop zu diagnostizieren.

## Referenz der Prüfungen

Die Prüfungen werden in der unten aufgeführten Reihenfolge ausgeführt. Spätere Prüfungen, die von einem vorherigen Fehler abhängen, werden übersprungen statt wiederholt: Wird die Modelldatei nicht gefunden, gibt es weder eine Zeile `models file parse` noch Endpunktprüfungen.

### `license`

Lädt die Lizenzdatei und prüft sie (siehe [Lizenz](/de/federal/air-gapped/license)).

| Ergebnis | Detail | Aktion |
| - | - | - |
| `pass` | `seat <label> (account <id>), expires <YYYY-MM-DD>` | Keine. |
| `warn` | `... (<n> day(s) left) — contact your administrator to renew it`, wenn weniger als 30 Tage verbleiben; `(less than a day left)`; oder `already expired (within the clock-skew grace period)` | Verlängern und ersetzen Sie die Lizenz, bevor die 24-stündige Kulanzfrist abläuft. |
| `FAIL` | `LIC00n: <message>`, gefolgt von `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.` | Gehen Sie gemäß der `LIC`-Zeile unter [Fehlercodes](/de/federal/air-gapped/error-codes#lic-license) vor. |

### `models file path`

Ermittelt den Speicherort der Modelldatei (`/etc/devin/models.json`, unter Windows `C:\ProgramData\Devin\models.json`, oder `DEVIN_MODELS_FILE`) und prüft, ob dort eine Datei vorhanden ist.

| Ergebnis | Aktion |
| - | - |
| `pass` mit dem ermittelten Pfad | Keine. |
| `FAIL CFG003` | Installieren Sie die Modelldatei oder korrigieren Sie den Wert von `DEVIN_MODELS_FILE`. Alle Prüfungen der Modelldatei und der Endpunkte werden übersprungen. |

### `config dir writable` and `data dir writable`

Erstellt bei Bedarf die Konfigurations- und Datenverzeichnisse des Produkts und schreibt jeweils eine Testdatei hinein.

| Ergebnis | Aktion |
| - | - |
| `pass` mit dem Verzeichnispfad | Keine. |
| `FAIL CFG001` | Die Details geben an, ob das Verzeichnis nicht ermittelt, nicht erstellt oder nicht beschrieben werden konnte. Korrigieren Sie Eigentümer und Berechtigungen für den Nutzer, unter dem Devin ausgeführt wird, oder setzen Sie `XDG_CONFIG_HOME` / `XDG_DATA_HOME` auf einen beschreibbaren Speicherort. Unter Windows wertet die CLI `XDG_*` nicht aus; korrigieren Sie stattdessen die Berechtigungen für `%APPDATA%\devin\`. |

### `CA bundle`

Gibt an, ob `DEVIN_CA_BUNDLE` gesetzt ist, und lädt die Datei.

| Ergebnis | Detail | Aktion |
| - | - | - |
| `pass` | `not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)` | Keine, es sei denn, Ihre Endpunkte verwenden eine private CA. |
| `pass` | `<path> (<n> certificate(s))` | Keine. |
| `FAIL CFG004` | Grund, warum die Datei nicht geladen werden konnte | Korrigieren Sie den Pfad oder den PEM-Inhalt; siehe [Netzwerk und Zertifikate](/de/federal/air-gapped/network-and-certificates). |

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

Parst die Modelldatei mit demselben Validator wie `devin models validate` und prüft anschließend, ob die Variable `api_key.env` jedes Modells in der aktuellen Umgebung gesetzt ist.

| Ergebnis | Aktion |
| - | - |
| `pass  models file parse  <n> model(s) configured` | Keine. |
| `FAIL  models file parse  <message> (run devin models validate for structured MDL diagnostics)` | Führen Sie `devin models validate` aus und beheben Sie jeden `MDL`-Code; siehe [Modelldatei](/de/federal/air-gapped/models-file). Endpunktprüfungen werden übersprungen. |
| `pass  model '<name>': API key env var  <VAR> is set` | Keine. |
| `FAIL CFG002  environment variable '<VAR>' (referenced by api_key.env) is not set` | Exportieren Sie die Variable in dieser Shell, oder fügen Sie sie für Desktop zu `devin.acp.agentEnv` hinzu; siehe [Umgebungsvariablen für API-Schlüssel](/de/federal/air-gapped/models-file#api-key-environment-variables). Die Endpunktprüfungen für dieses Modell werden mit `warn` übersprungen. |

### `custom subagent profiles`

Listet benutzerdefinierte Subagent-Definitionen aus `agents/**/AGENT.md` auf. Bei `none configured` oder `<n> profile(s) loaded` ist die Prüfung bestanden; `CFG005` nennt eine Definition, die nicht geparst werden konnte. Diese Prüfung ist auch Teil des Standardbefehls `devin doctor` und hat nichts mit der air-gapped Konfiguration zu tun.

### `model '<name>': endpoint reachability`

Sendet `GET {base_url}/models` mit dem API-Schlüssel des Modells – mit einem Timeout von 10 Sekunden und derselben TLS-Konfiguration, die auch für die Inferenz verwendet wird.

| Ergebnis | Detail | Aktion |
| - | - | - |
| `pass` | `GET <url> -> 200 OK` | Keine. Enthält das Detail zusätzlich `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`, ist das Paket unverzichtbar: Behalten Sie die Konfiguration auf jedem Host bei. |
| `warn NET004` | `GET <url> -> 404 Not Found (server may not implement /models)` | Keine; der Endpunkt ist erreichbar, und der nachfolgende Inferenztest ist der eigentliche Test. |
| `warn CFG002` | `skipped: API key env var '<VAR>' is not set` | Setzen Sie die Variable (siehe oben). |
| `FAIL NET006` | `GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'` | Die Variable ist gesetzt, ihr Wert ist für diesen Endpunkt jedoch falsch. |
| `FAIL NET004` | `GET <url> -> <status>` | Prüfen Sie die Logs des Endpunkts und den Pfad in `base_url`. |
| `FAIL NET001` / `NET002` / `NET005` | Fehlerkette zu DNS, TCP oder Timeout | Prüfen Sie von derselben Workstation aus die Namensauflösung, die Firewall- und Proxy-Regeln sowie den Zustand des Endpunkts. |
| `FAIL NET003` | TLS-Fehlerkette, danach das vom Server vorgelegte Zertifikat (Subject, Issuer, Ablaufdatum), anschließend entweder `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` oder `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem` | Vergleichen Sie den ausgegebenen Issuer mit den Zertifikaten in Ihrem Paket; siehe [Netzwerk und Zertifikate](/de/federal/air-gapped/network-and-certificates). |

### `model '<name>': inference conformance`

Wird übersprungen, wenn die Erreichbarkeitsprüfung auf Transport-Ebene fehlgeschlagen ist. Sendet eine Anfrage mit einem einzigen Token, um nachzuweisen, dass der Endpunkt die konfigurierte API unterstützt: `POST {base_url}/chat/completions` mit `max_tokens: 1` für `chat_completions` oder `POST {base_url}/responses` mit `max_output_tokens: 16` für `responses`.

| Ergebnis | Detail | Aktion |
| - | - | - |
| `pass` | `POST <url> -> 200 OK (<n> ms)` | Keine. Die Latenz eignet sich als Ausgangsbasis für spätere Vergleiche. |
| `FAIL NET006` | `POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'` | Korrigieren Sie den Schlüssel. |
| `FAIL NET004` | `POST <url> -> <status>: <first 200 characters of the response body>` | Der Body nennt in der Regel das Problem: ein unbekannter Modellname (die Anfrage verwendet den `name` aus Ihrer Modelldatei, der mit dem vom Server bereitgestellten Modell übereinstimmen muss), ein falscher `api`-Wert für diesen Server oder ein serverseitiger Fehler. |
| `FAIL NET00n` | Kette von Transport-Fehlern | Wie bei der Erreichbarkeitsprüfung. |

## Häufige Probleme

| Symptom | Wahrscheinliche Ursache | Wo nachsehen |
| - | - | - |
| Doctor ist in einem Terminal erfolgreich, aber Desktop erreicht das Modell nicht | Der in Desktop mitgelieferte Agent erbt Ihre Shell-Umgebung nicht, daher ist die Variable für den API-Schlüssel nicht gesetzt | [Umgebungsvariablen für API-Schlüssel](/de/federal/air-gapped/models-file#api-key-environment-variables) |
| Bei allen Nutzern auf einem Host ist die Prüfung erfolgreich, nur bei einem nicht | Nutzerspezifischer Zustand: Berechtigungen für `~/.config/devin` oder `~/.local/share/devin` (`%APPDATA%\devin` unter Windows) oder eine veraltete `sso_tokens.toml` (`IDP006`) | [Formate auf dem Datenträger](/de/federal/air-gapped/on-disk-formats) |
| `devin auth login` ist erfolgreich, aber Sitzungen enden nach einer Weile | Die erneute Validierung ist fehlgeschlagen: Der Nutzer wurde aus `required_group` entfernt oder die IdP-Sitzung wurde widerrufen | [SSO](/de/federal/air-gapped/sso#revalidation-in-running-sessions) und das Audit-Ereignis `sso_revalidation_failed` |
| `NET003` nur auf einigen Hosts | `DEVIN_CA_BUNDLE` ist auf diesen Hosts nicht gesetzt oder verweist auf ein anderes Paket | [Netzwerk und Zertifikate](/de/federal/air-gapped/network-and-certificates) |
| `LIC004` nach der Installation eines Updates oder in einer neuen Umgebung | Build und Lizenz stammen aus unterschiedlichen Umgebungen, oder der Schlüssel wurde rotiert | [Lizenz: Schlüssel-ID prüfen](/de/federal/air-gapped/license#check-the-key-id) |
| `MDL014` beim Speichern von Modellen in Desktop | Die Modelldatei gehört root oder einem anderen Nutzer (unter Windows einem Administrator, während Sie als Standardnutzer angemeldet sind) | Bearbeiten Sie die Datei direkt auf dem Datenträger als deren Eigentümer |

## Was Sie an den Support senden sollten

Sammeln Sie die folgenden Informationen auf der betroffenen Workstation. Prüfen Sie jede Datei, bevor Sie sie senden – keine davon wird automatisch hochgeladen.

1. Die Ausgabe von `doctor`:

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

   ```text theme={null}
   (no output; the command exits nonzero if a check failed)
   ```

   Die Detail-Strings enthalten Ihre Endpunkt-URLs und Hostnamen, aber niemals die Werte von API-Schlüsseln.

2. Der bereinigte Diagnosebericht:

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

   Der Bericht enthält die Versionen, Angaben dazu, ob die einzelnen Konfigurationsdateien vorhanden sind und fehlerfrei geparst werden können, die Modellnamen, Angaben dazu, ob die einzelnen API-Schlüsselvariablen gesetzt sind, sowie Statistiken zum Audit-Protokoll. Er enthält niemals Prompts, Code, Dateiinhalte, geheime Werte, Endpunkt-URLs oder Werte von Umgebungsvariablen.

3. Die genaue Fehlermeldung, die dem Nutzer angezeigt wurde, einschließlich des Fehlercodes, sowie die Ausgabe von `devin --version`.

4. Bei SSO-Problemen die relevanten `auth`-Ereignisse aus dem [Audit-Protokoll](/de/federal/air-gapped/on-disk-formats#audit-log) (Felder `error_code` und `action`) sowie die zugehörigen Einträge aus den Logs Ihres IdP.

Senden Sie weder die Lizenzdatei noch die API-Schlüsselwerte, `sso_tokens.toml` oder `sessions.db`.


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