Dépannage de Devin en air gap : guide d’exploitation de doctor

Cette documentation concerne les déploiements fédéraux de Devin. Retour à la documentation Devin

devin airgap doctor est la première commande à lancer lorsque la CLI ou Desktop ne démarre pas, ne parvient pas à joindre un modèle ou affiche un code d’erreur. Elle exécute toutes les vérifications locales et réseau dont dépend l’agent, affiche une ligne par vérification et renvoie un code de sortie non nul en cas d’échec. Cette page détaille chaque vérification et la marche à suivre, puis indique les éléments à rassembler pour une demande d’assistance.

Exécuter doctor

Exécutez-le sous le compte utilisateur qui utilisera Devin, dans le même environnement (les variables de clé d’API doivent être définies dans ce 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)

Chaque ligne suit le format <status> <check> <detail>. Pour les échecs et avertissements associés à un code, le détail est précédé du code d’erreur, par exemple FAIL model 'llama-3.3-70b': endpoint reachability NET003: ....

Statut	Signification	Code de sortie
`pass`	La vérification a réussi.
`warn`	Devin fonctionnera, mais un point nécessitera bientôt votre attention (licence sur le point d’expirer, `/models` non implémenté, sonde ignorée).	`0`
`FAIL`	Devin ne fonctionnera pas correctement tant que ce problème ne sera pas corrigé.	non nul, avec `doctor found N failing check(s)`

Pour l’automatisation, --json affiche {"ok": <bool>, "checks": [...]}, où chaque vérification comporte check, status (pass, warn, fail) et detail, ainsi que code pour les avertissements et échecs associés à un code, et latency_ms pour une sonde d’inférence réussie :

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 utilise la même CLI intégrée : exécutez donc doctor depuis un terminal sur l’hôte Desktop pour diagnostiquer aussi les problèmes de Desktop.

Référence des vérifications

Les vérifications s’exécutent dans l’ordre ci-dessous. Lorsqu’une vérification dépend d’une vérification antérieure qui a échoué, elle est ignorée plutôt que répétée : si le fichier de modèles est introuvable, la ligne models file parse n’apparaît pas et aucune sonde n’est envoyée aux endpoints.

`license`

Charge et vérifie le fichier de licence (voir Licence).

Résultat	Détail	Action
`pass`	`seat <label> (account <id>), expires <YYYY-MM-DD>`	Aucune.
`warn`	`... (<n> day(s) left) — contact your administrator to renew it` lorsqu’il reste moins de 30 jours ; `(less than a day left)` ; ou `already expired (within the clock-skew grace period)`	Renouvelez et remplacez la licence avant la fin du délai de grâce de 24 heures.
`FAIL`	`LIC00n: <message>` suivi de `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.`	Suivez les instructions de la ligne `LIC` dans Codes d’erreur.

`models file path`

Détermine l’emplacement du fichier de modèles (/etc/devin/models.json, C:\ProgramData\Devin\models.json sous Windows, ou DEVIN_MODELS_FILE) et vérifie qu’un fichier s’y trouve.

Résultat	Action
`pass` avec le chemin déterminé	Aucune.
`FAIL CFG003`	Installez le fichier de modèles ou corrigez la valeur de `DEVIN_MODELS_FILE`. Toutes les vérifications portant sur le fichier de modèles et les endpoints sont ignorées.

`config dir writable` et `data dir writable`

Crée si nécessaire les répertoires de configuration et de données du produit, puis écrit un fichier de test dans chacun d’eux.

Résultat	Action
`pass` avec le chemin du répertoire	Aucune.
`FAIL CFG001`	Le détail indique si le répertoire n’a pas pu être déterminé, créé ou n’est pas accessible en écriture. Corrigez le propriétaire et les autorisations pour l’utilisateur qui exécute Devin, ou définissez `XDG_CONFIG_HOME` / `XDG_DATA_HOME` sur un emplacement accessible en écriture. Sous Windows, la CLI ne lit pas les variables `XDG_*` : corrigez les autorisations sur `%APPDATA%\devin\`.

`CA bundle`

Indique si DEVIN_CA_BUNDLE est défini, puis le charge.

Résultat	Détail	Action
`pass`	`not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)`	Aucune, sauf si vos endpoints utilisent une autorité de certification (CA) privée.
`pass`	`<path> (<n> certificate(s))`	Aucune.
`FAIL CFG004`	Raison pour laquelle le fichier n’a pas pu être chargé	Corrigez le chemin ou le contenu PEM ; consultez Réseau et certificats.

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

Analyse le fichier de modèles avec le même validateur que devin models validate, puis vérifie que la variable api_key.env de chaque modèle est bien définie dans l’environnement actuel.

Résultat	Action
`pass models file parse <n> model(s) configured`	Aucune.
`FAIL models file parse <message> (run devin models validate for structured MDL diagnostics)`	Exécutez `devin models validate` et corrigez chaque code `MDL` ; consultez Fichier de modèles. Les sondes d’endpoint ne sont pas exécutées.
`pass model '<name>': API key env var <VAR> is set`	Aucune.
`FAIL CFG002 environment variable '<VAR>' (referenced by api_key.env) is not set`	Exportez la variable dans ce shell ou, pour Desktop, ajoutez-la à `devin.acp.agentEnv` ; consultez Variables d’environnement des clés d’API. Les sondes d’endpoint de ce modèle ne sont pas exécutées et renvoient un `warn`.

`custom subagent profiles`

Liste les définitions de sous-agents personnalisés issues de agents/**/AGENT.md. none configured ou <n> profile(s) loaded signale une réussite ; CFG005 indique une définition qui n’a pas pu être analysée. Cette vérification est commune avec la commande devin doctor standard et n’a aucun lien avec la configuration en air gap.

`model '<name>': endpoint reachability`

Envoie GET {base_url}/models avec la clé d’API du modèle, avec un délai d’expiration de 10 secondes et la même configuration TLS que celle utilisée pour l’inférence.

Résultat	Détail	Action
`pass`	`GET <url> -> 200 OK`	Aucune. Si le détail mentionne `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`, le paquet est indispensable : conservez-le configuré sur chaque hôte.
`warn NET004`	`GET <url> -> 404 Not Found (server may not implement /models)`	Aucune ; l’endpoint est joignable et c’est la sonde d’inférence ci-dessous qui constitue le véritable test.
`warn CFG002`	`skipped: API key env var '<VAR>' is not set`	Définissez la variable (voir ci-dessus).
`FAIL NET006`	`GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	La variable est définie, mais sa valeur n’est pas valide pour cet endpoint.
`FAIL NET004`	`GET <url> -> <status>`	Vérifiez les log de l’endpoint et le chemin `base_url`.
`FAIL NET001` / `NET002` / `NET005`	Chaîne d’erreurs DNS, TCP ou de délai d’expiration	Depuis le même poste de travail, vérifiez la résolution de noms, les règles de pare-feu et de proxy, ainsi que l’état de fonctionnement de l’endpoint.
`FAIL NET003`	Chaîne d’erreurs TLS, puis le certificat présenté par le serveur (sujet, émetteur, expiration), puis soit `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA`, soit `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem`	Comparez l’émetteur affiché avec les certificats de votre paquet ; consultez Réseau et certificats.

`model '<name>': inference conformance`

Ignoré lorsque le test d’accessibilité a échoué au niveau du transport. Envoie une requête d’un seul token pour vérifier que l’endpoint parle bien l’API configurée : POST {base_url}/chat/completions avec max_tokens: 1 pour chat_completions, ou POST {base_url}/responses avec max_output_tokens: 16 pour responses.

Résultat	Détail	Action
`pass`	`POST <url> -> 200 OK (<n> ms)`	Aucune. La latence constitue une référence utile pour des comparaisons ultérieures.
`FAIL NET006`	`POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	Corrigez la clé.
`FAIL NET004`	`POST <url> -> <status>: <first 200 characters of the response body>`	Le corps de la réponse indique généralement l’origine du problème : nom de modèle inconnu (la requête utilise le `name` défini dans votre fichier de modèles, qui doit correspondre au modèle servi par le serveur), valeur `api` incorrecte pour ce serveur, ou erreur côté serveur.
`FAIL NET00n`	Chaîne d’erreurs de transport	Comme pour le test d’accessibilité.

Problèmes courants

Symptôme	Cause probable	Où chercher
Doctor réussit dans un terminal, mais Desktop ne parvient pas à joindre le modèle	L’agent intégré à Desktop n’hérite pas de l’environnement de votre shell : la variable de la clé d’API n’est donc pas définie	Variables d’environnement de la clé d’API
Tous les utilisateurs d’un hôte réussissent, sauf un	État propre à chaque utilisateur : autorisations sur `~/.config/devin` ou `~/.local/share/devin` (`%APPDATA%\devin` sous Windows), ou fichier `sso_tokens.toml` obsolète (`IDP006`)	Formats sur disque
`devin auth login` réussit, mais les sessions s’arrêtent au bout d’un certain temps	Échec de la revalidation : l’utilisateur a été retiré de `required_group` ou la session de l’IdP a été révoquée	SSO et l’événement d’audit `sso_revalidation_failed`
`NET003` uniquement sur certains hôtes	`DEVIN_CA_BUNDLE` non défini, ou pointant vers un autre paquet, sur ces hôtes	Réseau et certificats
`LIC004` après l’installation d’une mise à jour, ou dans un nouvel environnement	Le build et la licence proviennent d’environnements différents, ou une rotation de clé a eu lieu	Licence : vérifier l’identifiant de la clé
`MDL014` lors de l’enregistrement des modèles dans Desktop	Le fichier des modèles appartient à root ou à un autre utilisateur (sous Windows, à un administrateur alors que vous êtes un utilisateur standard)	Modifiez le fichier sur disque en tant que propriétaire

Éléments à envoyer au support

Rassemblez les éléments suivants sur le poste de travail concerné. Relisez chaque fichier avant de l’envoyer ; aucun d’entre eux n’est téléversé automatiquement.

La sortie de doctor :
devin airgap doctor --json > doctor.json
(no output; the command exits nonzero if a check failed)
Les chaînes de caractères de détail contiennent les URL de vos endpoints et vos noms d’hôte, mais jamais les valeurs des clés d’API.
Le rapport de diagnostic expurgé :
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.
Le rapport indique les versions, l’existence et la validité syntaxique de chaque fichier de configuration, les noms des modèles, si chaque variable de clé d’API est définie ou non, ainsi que des statistiques du journal d’audit. Il ne contient jamais de prompts, de code, de contenu de fichiers, de valeurs secrètes, d’URL d’endpoints ni de valeurs de variables d’environnement.
Le message d’erreur exact affiché à l’utilisateur, y compris son code, ainsi que la sortie de devin --version.
Pour les problèmes de SSO (authentification unique), les événements auth pertinents du journal d’audit (champs error_code et action) et les entrées correspondantes dans les log de votre IdP.

N’envoyez ni le fichier de licence, ni les valeurs des clés d’API, ni sso_tokens.toml, ni sessions.db.

​Exécuter doctor

​Référence des vérifications

​license

​models file path

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

​Problèmes courants

​Éléments à envoyer au support

Exécuter doctor

Référence des vérifications

`license`

`models file path`

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

Problèmes courants

Éléments à envoyer au support