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

Diese Dokumentation gilt für föderale Deployments von Devin. Zurück zur Devin-Dokumentation

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

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)

Jede Zeile hat das Format <status> <check> <detail>. Bei Fehlschlägen und Warnungen mit Code wird dem Detail der Fehlercode 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:

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

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

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

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

Die Ausgabe von doctor:
devin airgap doctor --json > doctor.json
(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.
Der bereinigte Diagnosebericht:
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.
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.
Die genaue Fehlermeldung, die dem Nutzer angezeigt wurde, einschließlich des Fehlercodes, sowie die Ausgabe von devin --version.
Bei SSO-Problemen die relevanten auth-Ereignisse aus dem Audit-Protokoll (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.

​doctor ausführen

​Referenz der Prüfungen

​license

​models file path

​config dir writable and 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

​Häufige Probleme

​Was Sie an den Support senden sollten

doctor ausführen

Referenz der Prüfungen

`license`

`models file path`

`config dir writable` and `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`

Häufige Probleme

Was Sie an den Support senden sollten