エアギャップ化された Devin のトラブルシューティング: doctor ランブック

このドキュメントは Devin の連邦政府向け導入環境を対象としています。Devin Docs に戻る

CLI または Desktop が起動しない、モデルに接続できない、エラーコードが表示されるといった場合は、まず devin airgap doctor を実行してください。このコマンドは、エージェントが依存するローカルおよびネットワークのチェックをすべて実行し、チェックごとに結果を 1 行ずつ出力します。いずれかのチェックが失敗した場合は、0 以外の終了コードで終了します。このページでは、各チェックの内容と対処方法を説明したうえで、サポートへの問い合わせ時に収集すべき情報について説明します。

doctor を実行する

Devin を利用するユーザーとして、同じ環境で実行してください (そのシェルで API キーの環境変数が設定されている必要があります) 。

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)

各行は <status> <check> <detail> の形式です。エラーコードを伴う失敗と警告では、detail の先頭にエラーコードが付きます。例えば FAIL model 'llama-3.3-70b': endpoint reachability NET003: ... のようになります。

ステータス	意味	終了ステータス
`pass`	チェックに成功しました。
`warn`	Devin は動作しますが、早めの対応が必要な事項があります (ライセンスの期限切れが近い、`/models` が未実装、プローブがスキップされた、など) 。	`0`
`FAIL`	この問題を修正するまで、Devin は正しく動作しません。	0 以外 (`doctor found N failing check(s)` を出力)

自動化で利用する場合は、--json を指定すると {"ok": <bool>, "checks": [...]} が出力されます。各チェックには check、status (pass、warn、fail) 、detail が含まれます。さらに、エラーコードを伴う警告と失敗には code が、成功した推論プローブには 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 も同じバンドル版 CLI を利用しているため、Desktop の問題を診断する場合も、Desktop のホスト上のターミナルで doctor を実行してください。

チェックリファレンス

チェックは以下の順序で実行されます。前のチェックが失敗し、その結果に依存する後続のチェックは、重複して実行されずにスキップされます。たとえば、モデルファイルが見つからない場合は models file parse の行が出力されず、エンドポイントプローブも実行されません。

`license`

ライセンスファイルを読み込んで検証します (ライセンスを参照) 。

結果	詳細	対処
`pass`	`seat <label> (account <id>), expires <YYYY-MM-DD>`	なし。
`warn`	残りが 30 日未満の場合は `... (<n> day(s) left) — contact your administrator to renew it`、残りが 1 日未満の場合は `(less than a day left)`、または `already expired (within the clock-skew grace period)`	24 時間の猶予期間が終わる前に、ライセンスを更新して置き換えてください。
`FAIL`	`LIC00n: <message>` の後に `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.` が表示されます	エラーコードの `LIC` 行の手順に従ってください。

`models file path`

モデルファイルの場所 (/etc/devin/models.json、Windows では C:\ProgramData\Devin\models.json、または DEVIN_MODELS_FILE) を決定し、そこにファイルが存在することを確認します。

結果	対応
決定されたパスを伴う `pass`	対応は不要です。
`FAIL CFG003`	モデルファイルをインストールするか、`DEVIN_MODELS_FILE` の値を修正してください。モデルファイルおよびエンドポイントに関するチェックはすべてスキップされます。

`config dir writable` と `data dir writable`

必要に応じて製品の設定ディレクトリとデータディレクトリを作成し、それぞれにプローブファイルを書き込みます。

結果	対処法
ディレクトリパス付きの `pass`	対応は不要です。
`FAIL CFG001`	詳細には、ディレクトリの解決、作成、書き込みのどれに失敗したかが表示されます。Devin を実行するユーザーに合わせて所有者と権限を修正するか、`XDG_CONFIG_HOME` / `XDG_DATA_HOME` に書き込み可能な場所を設定してください。Windows の CLI は `XDG_*` を読み取らないため、`%APPDATA%\devin\` の権限を修正してください。

`CA bundle`

DEVIN_CA_BUNDLE が設定されているかどうかを報告し、設定されている場合は読み込みます。

結果	詳細	アクション
`pass`	`not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)`	エンドポイントで非公開 CA を利用している場合を除き、対応は不要です。
`pass`	`<path> (<n> certificate(s))`	対応は不要です。
`FAIL CFG004`	ファイルを読み込めなかった理由	パスまたは PEM の内容を修正してください。詳しくはネットワークと証明書を参照してください。

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

devin models validate と同じバリデーターでモデルファイルを解析し、各モデルの api_key.env で指定された変数が現在の環境で設定されているかをチェックします。

結果	対処法
`pass models file parse <n> model(s) configured`	対応は不要です。
`FAIL models file parse <message> (run devin models validate for structured MDL diagnostics)`	`devin models validate` を実行し、各 `MDL` コードに対処してください。詳しくはモデルファイルを参照してください。エンドポイントプローブはスキップされます。
`pass model '<name>': API key env var <VAR> is set`	対応は不要です。
`FAIL CFG002 environment variable '<VAR>' (referenced by api_key.env) is not set`	このシェルで変数をエクスポートするか、Desktop の場合は `devin.acp.agentEnv` に追加してください。詳しくはAPIキーの環境変数を参照してください。該当モデルのエンドポイントプローブは `warn` としてスキップされます。

`custom subagent profiles`

agents/**/AGENT.md にあるカスタムサブエージェントの定義を一覧表示します。none configured または <n> profile(s) loaded と表示されれば合格です。CFG005 は、解析できなかった定義を示します。このチェックは標準の devin doctor と共通のもので、エアギャップ環境向けの設定とは関係ありません。

`model '<name>': endpoint reachability`

モデルのAPIキーを使用して GET {base_url}/models を送信します。タイムアウトは10秒で、推論時と同じTLS設定が適用されます。

結果	詳細	対処
`pass`	`GET <url> -> 200 OK`	なし。詳細に `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)` が付記されている場合は、このバンドルが不可欠です。すべてのホストで設定したままにしてください。
`warn NET004`	`GET <url> -> 404 Not Found (server may not implement /models)`	なし。エンドポイントには到達できており、実際の検証は後述の推論プローブで行われます。
`warn CFG002`	`skipped: API key env var '<VAR>' is not set`	変数を設定してください (上記参照) 。
`FAIL NET006`	`GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	変数は設定されていますが、値がこのエンドポイントに対して正しくありません。
`FAIL NET004`	`GET <url> -> <status>`	エンドポイントのログと `base_url` のパスを確認してください。
`FAIL NET001` / `NET002` / `NET005`	DNS、TCP、またはタイムアウトのエラーチェーン	同じワークステーションから、名前解決、ファイアウォールとプロキシのルール、エンドポイントの健全性を確認してください。
`FAIL NET003`	TLSエラーチェーン、サーバーが提示した証明書 (サブジェクト、発行者、有効期限) の順に表示され、最後に `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` または `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem` のいずれかが表示されます	表示された発行者とバンドル内の証明書を照合してください。詳しくはネットワークと証明書を参照してください。

`model '<name>': inference conformance`

到達性チェックがトランスポートレベルで失敗した場合はスキップされます。エンドポイントが設定済みの API に対応していることを確認するため、1 トークンのリクエストを送信します。chat_completions の場合は max_tokens: 1 を指定して POST {base_url}/chat/completions を、responses の場合は max_output_tokens: 16 を指定して POST {base_url}/responses を送信します。

結果	詳細	対応
`pass`	`POST <url> -> 200 OK (<n> ms)`	なし。このレイテンシは、今後の比較に役立つベースラインになります。
`FAIL NET006`	`POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	キーを修正してください。
`FAIL NET004`	`POST <url> -> <status>: <first 200 characters of the response body>`	通常、問題の内容はボディに示されています。主な原因は、不明なモデル名 (リクエストにはモデルファイルの `name` が使われるため、サーバーが処理するモデル名と一致している必要があります) 、このサーバーに合わない `api` の値、またはサーバー側のエラーです。
`FAIL NET00n`	トランスポートエラーのチェーン	到達性チェックの場合と同様に対処してください。

よくある問題

症状	考えられる原因	確認先
ターミナルでは Doctor が成功するが、Desktop からモデルに接続できない	Desktop にバンドルされたエージェントはシェルの環境を継承しないため、APIキーの変数が設定されていない	APIキーの環境変数
ホスト上で 1 人のユーザーだけが失敗し、他の全員は成功する	ユーザーごとの状態：`~/.config/devin` または `~/.local/share/devin` (Windows では `%APPDATA%\devin`) の権限、または滞留した `sso_tokens.toml` (`IDP006`)	ディスク上の形式
`devin auth login` は成功するが、しばらくするとセッションが終了する	再検証の失敗：ユーザーが `required_group` から削除されたか、IdP セッションが失効した	SSO および `sso_revalidation_failed` 監査イベント
一部のホストでのみ `NET003` が発生する	該当するホストで `DEVIN_CA_BUNDLE` が設定されていないか、別のバンドルが設定されている	ネットワークと証明書
更新のインストール後、または新しい環境で `LIC004` が発生する	build とライセンスの取得元の環境が異なる、またはキーがローテーションされた	ライセンス：キー ID を確認する
Desktop でモデルを保存すると `MDL014` が発生する	モデルファイルの所有者が root または別のユーザーになっている (Windows では、あなたが標準ユーザーで、所有者が管理者になっている)	ファイルの所有者としてディスク上のファイルを直接編集する

サポートに送付する情報

影響を受けているワークステーションで、以下の情報を収集してください。いずれのファイルも自動でアップロードされることはないため、送付前に各ファイルの内容を確認してください。

doctor の出力:
devin airgap doctor --json > doctor.json
(no output; the command exits nonzero if a check failed)
detail の文字列にはエンドポイント URL とホスト名が含まれますが、API キーの値が含まれることはありません。
秘匿化済みの診断情報レポート:
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.
このレポートには、バージョン、各設定ファイルの有無と解析可否、モデル名、各 API キー変数の設定有無、および監査ログの統計情報が記録されます。プロンプト、コード、ファイルの内容、シークレット値、エンドポイント URL、環境変数の値は一切含まれません。
ユーザーに表示されたエラーメッセージの全文 (エラーコードを含む) と、devin --version の出力。
SSO (シングルサインオン) の問題の場合は、監査ログ内の関連する auth イベント (error_code および action フィールド) と、IdP のログ内の対応する項目。

ライセンスファイル、API キーの値、sso_tokens.toml、sessions.db は送付しないでください。

​doctor を実行する

​チェックリファレンス

​license

​models file path

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

​よくある問題

​サポートに送付する情報

doctor を実行する

チェックリファレンス

`license`

`models file path`

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

よくある問題

サポートに送付する情報