codex doctorで接続を診断する方法｜0.166.0
「Codexが急に返事をしなくなった」「社内のネットワークだとCodexがつながらない」——原因がCodexの設定なのか、会社のネットワークなのか、OpenAI側なのかが分からないまま、再インストールやログインのやり直しを繰り返してしまう。Codexを仕事で使い始めると、多くの人が一度はここで手が止まります。
結論から言うと、つながらないときに最初に打つのは codex doctor --network-only です。2026年10月29日（米国時間）に公開されたCodex CLI 0.166.0で追加されたオプションで、設定の読み込み・プロキシなどの環境・OpenAIへのHTTP接続・WebSocket接続の4項目だけを診て、どこで止まっているかを1画面で示します。修理はしませんが、直す場所が分かるので無駄な再インストールが要らなくなります。
株式会社Fyveは中小企業のAI活用を月額で伴走しており、自社でもCodex CLIを無人の定期ジョブの中で毎日動かしています。本記事では、2026年11月2日に私たちのMac miniで0.166.0を実際に動かし、わざとプロキシ・証明書・設定ファイルを壊して出力を確かめた結果をもとに、使い方と表示の読み方を整理します。
codex doctor --network-only とは｜接続まわりだけを診る診断
codex doctor は、Codex CLIに入っている自己診断のコマンドです。OpenAIの公式CLIリファレンスでは「Stable（安定版）」の扱いで、「サポートに問い合わせる前や、壊れたインストールを調べるときに診断レポートを作る」コマンドと説明されています。インストール・設定・認証・実行環境・Git・端末・バックグラウンドのサーバー・会話履歴の整合まで、まとめて点検します。
0.166.0で追加された --network-only は、この点検を接続まわりの4項目に絞るオプションです。公開されたプルリクエスト（#57606）の説明では、「有効な設定・ネットワーク環境・提供元へのHTTP到達・Responses WebSocketの確認に限り、データベースやMCPの走査など関係のない診断は飛ばす」と書かれています。
項目 | 何を見るか | 表示名 |
|---|---|---|
設定 |
| config |
ネットワーク環境 | プロキシの環境変数・macOSのシステムプロキシ・独自の証明書の指定 | network |
WebSocket | 応答を受け取る常時接続（WebSocket）が張れるか | websocket |
HTTP到達 | 使っている提供元（OpenAIなど）の窓口にHTTPで届くか | reachability |
大事なのは、このコマンドは何も直さないという点です。ソースコードの冒頭にも「問題を修理しない。失敗は報告に載せ、終了コードを0以外にする」と明記されています。自動で直してくれる道具ではなく、どこを直せばよいかを指す道具だと捉えてください。
使い方｜まず版を確かめてから打つ
手順1：Codex CLIの版を確かめる
--network-only は0.166.0からのオプションです。古い版では使えません。私たちのMac miniには、定期ジョブ用に0.144.0が入ったままになっていました。そこで打つと、次のように「そんな引数は知らない」と返されて止まります。
$ codex --version
codex-cli 0.144.0
$ codex doctor --network-only
error: unexpected argument '--network-only' foundこのエラーが出たら、Codex自体の問題ではなく版が古いだけです。入れ方（npm・Homebrewなど）に合わせて更新してから打ち直します。版の確かめ方と更新の手順は、次の記事にまとめています。
手順2：codex doctor --network-only を打つ
0.166.0で打つと、次のような表示が出ます。2026年11月2日に私たちの環境で実行した結果です（作業フォルダの行など、環境に固有の行は省いています）。
$ codex doctor --network-only
Codex Doctor v0.166.0
Configuration
✓ config loaded
Connectivity
✓ network no proxy env vars
✓ websocket connected (HTTP 101 Switching Protocols) · 15s timeout
✓ reachability active provider endpoints are reachable over HTTP
4 ok · 0 warn · 0 fail ok4項目すべてに ✓ が付けば、少なくとも「この端末からOpenAIまでの道」は通っています。その場合、つながらない原因は接続以外（ログインの状態や利用上限など）にあると絞り込めます。
所要時間は、私たちの環境で3回測ってそれぞれ0.8〜1.0秒でした。オプションなしの codex doctor（20項目以上を点検）も同じ環境では0.8〜1.4秒で、速さの差はほとんどありません。--network-only の価値は速さではなく、接続と関係のない行が出ないので、どこが悪いかを読み違えにくいことにあります。
よく使うオプション
オプション | 働き | 使う場面 |
|---|---|---|
| 項目ごとの1行と、最後の集計だけを出す | まず全体の結果だけ見たいとき |
| 機械で読める形で出す。秘密になりうる値は伏せられる | スクリプトで判定したいとき・人に送るとき |
| 長い一覧を省略せずに出す | 機能フラグなどを全部見たいとき |
| 色を付けない／記号をASCIIにする | 結果をテキストに貼るとき |
オプションを付けない表示（詳しい表示）では、各項目の下に理由の行が並びます。たとえばWebSocketの項目では、使っている提供元・認証の方式（ChatGPTのログインかAPIキーか）・接続の待ち時間（15秒）・DNSの結果・接続の結果が出ます。接続先のURLは途中が <redacted> と伏せられて表示されるので、画面をそのまま社内の担当者に見せても、URLの細部までは漏れません。
表示の読み方｜✓・⚠・✗ と終了コード
各項目の頭には3種類の印が付きます。記号の意味と、終了コード（コマンドが終わったときに返す数字。スクリプトで成否の判定に使う）の関係は次のとおりです。
印 | 意味 | 終了コード |
|---|---|---|
✓（ok） | 問題なし | 0（警告だけなら0のまま） |
⚠（warn） | 動くかもしれないが注意が要る | |
✗（fail） | 必須の項目が通っていない | 1 |
この区別は私たちの実験でもそのとおりでした。証明書の指定を壊したとき（警告のみ）は終了コード0、プロキシを壊したときと設定ファイルを壊したとき（失敗あり）は終了コード1でした。スクリプトで「0なら大丈夫」と判定すると、警告は素通りする点に注意してください。警告まで拾いたいときは、--json の出力にある全体の状態（overallStatus）を読みます。
私たちの環境で --json を付けると、全体の状態と4項目の状態が次の名前で返りました。
overallStatus: ok
checks:
config.load ok
network.env ok
network.provider_reachability ok
network.websocket_reachability ok壊して確かめた3つの症状と直し方
表示の読み方は、実際に壊れた画面を見るのがいちばん早く身につきます。私たちはMac miniの上で、元に戻せる範囲で3つの状態をわざと作り、出力を記録しました（本番の設定には触れず、一時的な環境変数と、別の場所に置いた設定ファイルで試しています）。
症状1：プロキシの指定が間違っている
存在しないプロキシ（HTTPS_PROXY=http://127.0.0.1:9）を指定して打つと、次のように出ました。
Connectivity
✓ network network-related environment looks readable
proxy env vars present HTTP_PROXY, HTTPS_PROXY
⚠ websocket Responses WebSocket failed; HTTPS fallback may still work
✗ reachability one or more required provider endpoints are unreachable over HTTP
2 ok · 2 notes · 1 warn · 1 fail failed読み方のこつは、networkの行が ✓ でも安心しないことです。networkの項目は「プロキシの環境変数が読めるか」を見ているだけで、そのプロキシが正しいかまでは見ません。詳しい表示に proxy env vars present HTTP_PROXY, HTTPS_PROXY とあれば、プロキシ経由で外に出ようとしていることが分かります。その上でreachabilityが ✗ なら、疑う順番は「プロキシの住所・番号」「プロキシの認証」です。
ソースコードを読むと、プロキシが認証を求めて断った場合（HTTP 407）は「proxy authentication required」と、証明書の検証で止まった場合は「TLS handshake or certificate validation failed」と、原因の種類を分けて表示する作りになっています。社内のネットワークで止まったときは、この1行をそのまま情報システムの担当者に伝えれば話が早くなります。
見るプロキシの環境変数は HTTP_PROXY・HTTPS_PROXY・ALL_PROXY・NO_PROXY（小文字の書き方も含む）です。以前の作業で設定したまま忘れている変数が残っていないかも、この行で分かります。
症状2：独自の証明書の指定が壊れている
会社のネットワークによっては、通信を検査するために独自の証明書を入れていて、SSL_CERT_FILE や CODEX_CA_CERTIFICATE でその証明書の場所を指定することがあります。この指定先にファイルが無い状態を作ると、次のように出ました。
Connectivity
⚠ network no proxy env vars
SSL_CERT_FILE /tmp/nonexistent.pem (No such file or directory (os error 2))
⚠ websocket Responses WebSocket failed; HTTPS fallback may still work
✓ reachability active provider endpoints are reachable over HTTPこの場合は ✗ が出ず、終了コードも0でした。HTTPでは届いているので「動くこともある」状態です。ただ、--summary の1行表示ではnetworkの行が「no proxy env vars」としか出ず、何が悪いのか読み取れませんでした。⚠ が出たら、--summary を外して詳しい表示で理由の行を読むのが確実です。指定先のファイルを正しい場所に直すか、要らない指定なら環境変数を消します。
症状3：設定ファイルの書き方が間違っている
config.toml に閉じていない引用符と角かっこを書いて読ませると、次のように出ました。
Configuration
✗ config config could not be loaded — Fix the reported config error, then rerun codex doctor.
error invalid configuration
file <CODEX_HOME>/config.toml
line 2
column 5
network diagnostics effective network configuration is unavailable
0 ok · 1 notes · 0 warn · 1 fail failed設定が読めないと、接続の診断（network・websocket・reachability）には進まずに止まります。プルリクエストの説明にも「設定の読み込みに失敗したら、伏せた形でエラーを示して止まり、推測した宛先に接続を試さない」とあります。表示された行（line）と列（column）の場所を直してから、もう一度打ちます。このとき、エラーの中身として設定の値そのものは表示されません。社外の人に画面を見せても、設定に書いた値までは出ない作りです。
症状から見る切り分けの順番
3つの実験と公開されたソースコードの内容を合わせると、つながらないときの切り分けは次の順番で進めるのが無駄がありません。
- configが ✗ → 設定ファイルの書き方を直す。ほかの行は、ここが直るまで判断材料にならない
- networkが ⚠ → 詳しい表示で証明書の指定（
SSL_CERT_FILE・CODEX_CA_CERTIFICATE）を確かめる - reachabilityが ✗ → プロキシの環境変数・VPN・ファイアウォール・DNSを確かめる。社内ネットワークなら表示の1行を担当者に渡す
- websocketだけが ⚠ → HTTPでは届いているので、作業はできることがある。続くようなら、WebSocketの常時接続を止めるネットワークの決まりが無いかを担当者に確かめる
- 4項目とも ✓ → 接続は問題なし。ログインの状態・利用上限・Codex本体の起動の問題へ進む
macOSでは、システムの設定にプロキシがあるのにCodexがそれを使っていない場合、HTTP到達の失敗に「macOSのシステムプロキシが設定されているが使われていない。組織で必要なら、開発中の機能 respect_system_proxy を有効にしてよいか管理者に確かめる」という案内が付く作りになっています（ソースコードで確認。私たちの環境はシステムプロキシが無いため、この表示は再現していません）。会社のMacで「ブラウザはつながるのにCodexだけつながらない」ときは、この案内が出ていないかを見てください。
4項目が通っているのに起動しない・画面が固まる場合は、接続以外の原因です。症状ごとの切り分けは次の記事にまとめています。
無人のジョブに組み込むときの考え方
私たちはCodex CLIを、人が見ていない時間に動く定期ジョブの中で使っています。たとえば記事のサムネイル画像の生成です。こうした使い方では、失敗したときに「Codexの中で何かが失敗した」のか「そもそもOpenAIに届いていない」のかが分からないと、原因の調査に時間がかかります。
--network-only は終了コードで成否を返すので、ジョブの最初に1行挟むだけで、接続の失敗を本処理の前に切り分けられます。組み込むときに私たちが押さえておくべきだと考えている点は3つです。
- 終了コード1は「失敗」だけ。警告（⚠）では0が返る。WebSocketの警告も拾いたいなら
--jsonの全体の状態を読む - ジョブが使う版で打つ。端末で使う版と定期ジョブが使う版が違うことがある。私たちのMac miniでも、定期ジョブの版は0.144.0のままで、このオプション自体が無かった
- 結果は残しても危なくない形で残す。
--jsonは秘密になりうる値を伏せた形で出るので、ログとして保存しやすい
2つ目は、今回の検証で私たち自身が気づいたことです。普段の作業では新しい版を使っているつもりでも、無人のジョブは入れた当時の版で動き続けていることがあります。新しい診断の道具を使う前に、そのジョブが実際に呼んでいる codex の版を確かめるのが先です。
0.166.0 でほかに変わったこと
同じ0.166.0では、--network-only のほかにも次の変更が入っています（GitHubのリリースノートとOpenAIの公式の変更履歴で確認）。
区分 | 変更 |
|---|---|
新機能 | 会話の記録をキーボードで選択できるように（単語・行・ページ単位の移動、検索との連携、ショートカットの変更） |
新機能 |
|
新機能 | 安全上の理由で止めたときの説明を分かりやすくし、より安全な頼み方を選べるように |
新機能 | GPT-6.1 Terraを、標準・Vertex AI・Amazon Bedrockのモデル一覧に追加 |
不具合修正 | 画面の再接続からの立ち直りを改善（オフラインでの |
不具合修正 | 会話を再開・分岐したときに、承認済みの許可の設定を保つように |
不具合修正 | 再開・分岐の後も推論のトークン数の計算を保ち、早すぎる圧縮を避けるように |
「再接続からの立ち直りの改善」は、ネットワークが不安定な環境でCodexを使う人に関係します。--network-only で接続の問題を見つけて直したあとも、途中で切れたときの挙動はこの修正で変わっている可能性があるので、古い版のまま使っている人は更新する理由が2つあることになります。
Codexのエラー全般（認証・権限・利用上限など）の対処は、次の記事で症状別にまとめています。
よくある質問
codex doctor --network-only は問題を直してくれますか？
直しません。どの項目で止まっているかと、直す方向（たとえば「プロキシ・VPN・ファイアウォール・DNS・独自の証明書を確かめる」）を示すだけです。設定を書き換えることもありません。
オプションなしの codex doctor と、どちらを打てばよいですか？
「つながらない」「応答が返ってこない」なら --network-only です。起動しない・画面が固まる・履歴がおかしいなど接続以外が疑わしいときは、オプションなしで全体を点検します。私たちの環境では、どちらも1秒前後で終わりました。
結果を人に見せても大丈夫ですか？
接続先のURLの途中は伏せて表示され、設定ファイルのエラーでも設定の値そのものは出ません。--json も秘密になりうる値を伏せる作りです。ただし、詳しい表示には作業フォルダや設定ファイルの場所（パソコンのユーザー名を含むことがある）が出るので、社外に送る前に一度目で確かめてください。
Windowsでも使えますか？
コマンドそのものはCodex CLIに含まれています。ただし、macOSのシステムプロキシに関する行と案内はmacOSだけの機能です。私たちが確かめたのはmacOS（Apple Silicon）での動きだけです。
まとめ｜つながらないときは、直す前に4行を読む
codex doctor --network-onlyは0.166.0（2026年10月29日公開）で追加された、接続まわり4項目だけの診断- 見るのは config（設定）・network（プロキシと証明書）・websocket・reachability（HTTP到達）の4つ
- 何も直さない。失敗があれば終了コード1、警告だけなら0
- configが ✗ なら接続の診断には進まない。まず設定ファイルを直す
- networkの ✓ は「プロキシの指定が読める」だけ。正しいかはreachabilityで見る
- 古い版では「unexpected argument」で止まる。無人のジョブが使う版を先に確かめる
つながらないときにやみくもに入れ直す前に、この1行を打って4行を読むだけで、直す場所はかなり絞り込めます。株式会社Fyveでは、こうした道具の挙動を自社の環境で確かめたうえで、AIツールを業務に組み込むお手伝いをしています。
Codexを使い始める前に、「絶対に」見直してほしい5つのこと
学習の設定・確認なしの操作・戻せる状態など。Codexにそのまま貼れる頼み方つき（全9ページ）
Codexは便利な一方で、設定ひとつで「聞かずに動く」ようになります。この資料を作るために自分の設定を開いたら、本番のデータベースを書き換える操作が、覚えのないうちに確認なしで動く状態になっていました。使い始める前に見直してほしい5つを、Codexにそのまま貼れる頼み方と一緒にまとめました。
- 仕事の画面や資料を、AIの学習に使わせない設定
- 取り返しのつかない操作が確認なしになっていないか、Codexに調べさせる頼み方
- AGENTS.mdのいちばん上に書く「絶対にしないこと」の例
- 失敗しても戻せる状態で始める方法と、使えなくなったAIの指定の直し方
メールアドレス登録で他にも様々な資料を閲覧できます
＋10PDF 19点・合計499ページ ＋ すぐ使えるzip素材 3点
どれも登録後の受け取りページから、まとめてダウンロードできます。
毎週配信の無料ニュースレター「AIネイティブ超研究」の購読特典です。メール登録後すぐ、受け取りページのご案内が届きます。そこにはこの資料に加えて、過去の特典もすべてまとめて置いてあります。あわせて、AI活用に関するお知らせやお役に立てそうなご案内をお送りすることがあります。解除はいつでも1クリック。
御社の業務に合わせたCodex導入支援
「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。