Codexを使い始めたものの、起動が遅い。ログインできているのか分からない。設定が原因なのか、Gitなのか、それともターミナルなのか。
最初は、どこから疑えばいいか分からなくて当然なんです。
そこで今回は、Codex CLIの codex doctorだけ を使います。いきなり再インストールしたり、エラーメッセージを片っ端から検索したりする前に、まず環境の健康診断を1回やってみる。そんな小さな一歩です。
この記事のゴールは、10分以内に次のどちらかを確認することです。
- 診断の最終集計が表示された
- 要確認の項目を1つ見つけた
全部が正常でなくても大丈夫です。次に見る場所が1つ分かれば成功。原因探しの時間を少し短くするのが、この機能の役割かなと思います。
公式情報は2026年9月7日に確認しました。手元ではCodex CLI 0.150.1でコマンド構文を確認しています。
codex doctorとは何か
Codexは、自然な言葉で頼んだ作業に合わせて、ファイルを読んだり、コードを直したり、コマンドを実行したりできる AIエージェント です。ここでいうAIエージェントとは、質問に答えるだけでなく、許可された範囲で道具を使って作業を進めるAIのことです。
Codex CLIの CLI は「Command Line Interface」の略で、画面上のボタンではなく、文字を入力して操作する方式です。その文字を入力するアプリが ターミナル。macOSなら「ターミナル」、WindowsならPowerShellなどが該当します。
codex doctorは、そのCodex CLIが動くローカル環境を診断するコマンドです。公式のDeveloper commandsでは、次の領域を確認する診断レポートとして説明されています。
- インストール
- 設定
- 認証
- 実行環境
- Git
- ターミナル
- app-server
- 保存されたスレッドの状態
認証 は「誰のアカウントでCodexを使うか確認する仕組み」です。Codex CLIはChatGPTアカウントまたはAPIキーでサインインできます。
ここで大事なのは、doctorが修理を全部自動で終わらせる魔法ではないこと。診断して、次に確認する場所を絞る機能です。病院の健康診断も、結果を見てから必要な対応を決めますよね。あれに近いです。
なぜ最初に診断すると便利なのか
「Codexが動かない」という一言の裏には、いろんな原因があります。
たとえば、コマンドそのものが見つからない場合と、コマンドは起動するけれど認証が切れている場合では、次にやることが違います。設定ファイルの問題とGitの問題も別物です。
ここを分けずに再インストールから始めると、正常だった部分まで変えてしまうことがあります。検索して見つけた古い手順を試し続けるのも、なかなかしんどい。
codex doctorを先に使う価値は、正解を一発で出すことではなく、調べる範囲を狭くすることにあります。
今回は詳細レポートではなく、--summaryを付けて集計を中心に見ます。最初の1回は情報量を減らした方が、どこを見ればよいか迷いにくいからです。
10分で動かす最小手順
0. この手順で変更されるもの
今回の主役は診断です。記事内では既存プロジェクトのファイルを編集しません。
ただし、Codex CLIの診断はローカルの設定や状態を読み取ります。会社や学校の管理端末では、組織のルールを先に確認してください。
1. Codex CLIが入っているか確認する
通常のターミナルを開き、次を入力します。
codex --version
次のようにバージョン番号が表示されれば、Codex CLIのコマンドは見つかっています。
codex-cli 0.150.1
数字は更新で変わるので、同じでなくて大丈夫です。
command not foundなどが出た人は、先にインストールします。2026年9月7日時点の公式ページでは、たとえばnpmを使う方法が案内されています。
npm install -g @openai/codex
npmはNode.js向けのパッケージ管理ツールです。すでに別の公式手順でCodexを導入済みなら、入れ直す必要はありません。
2. 練習用フォルダへ移動する
macOS/Linuxなら、次をそのまま実行できます。
mkdir -p codex-doctor-practice
cd codex-doctor-practice
Windows PowerShellならこちらです。
New-Item -ItemType Directory -Force codex-doctor-practice
Set-Location codex-doctor-practice
フォルダは書類を分ける箱のようなものです。今回は既存の開発フォルダと混ぜないために、空の練習場所を使います。
3. 診断サマリーを実行する
通常のターミナルで、次を実行します。
codex doctor --summary --no-color --ascii
付けたオプションの役割は次のとおりです。
-
--summary: グループごとの検査行と最終集計を中心に表示する -
--no-color: 色を使わずに表示する -
--ascii: 記号をASCII文字にして、端末による表示崩れを減らす
どれもdoctorの表示方法を調整しているだけです。別機能を追加しているわけではありません。
4. 成功を確認する
最後まで完了したら、集計や検査結果を見ます。表示内容や件数は環境によって変わるため、この記事では固定の結果を作りません。
次のどちらかができれば、最初の成功です。
- 最終集計を確認できた
- 注意や失敗になっている検査を1つ特定できた
注意が1件あったとしても、doctorの実行に失敗したわけではありません。むしろ、次に見る場所が分かったということです。
もう少し詳しく見たい時だけ
最初はsummaryで十分です。どんな表示方法があるか確認したくなったら、次を使います。
codex doctor --help
手元の0.150.1では、--json、--summary、--all、--no-color、--asciiが表示されました。
ここで--jsonは機械で読みやすい形式、--allは長い一覧を展開するためのオプションです。初回から全部を広げる必要はありません。まずsummaryで場所を絞り、必要になってから詳細を見る。これくらいがちょうどええと思います。
つまずきポイント
1. codex: command not foundと出る
Codex CLIが未導入か、導入先へターミナルから道が通っていない状態です。まず公式CLIページのインストール方法を確認し、ターミナルを開き直してから次を再実行します。
codex --version
2. doctorが利用できない
古いCodex CLIではコマンドがまだ含まれていない可能性があります。まず現在のヘルプを確認してください。
codex --help
一覧にdoctorがなければ、導入時と同じ公式方式でCodex CLIを更新します。環境ごとに導入方式が違うため、別方式を重ねて入れない方が安全です。
3. 未ログインと表示される
認証状態が原因なら、公式Authenticationページを確認してcodex loginでサインインします。
codex login
ブラウザが開いたら、画面の案内に沿って進めます。会社のワークスペースでは利用方法が制限されている場合があるため、管理者のルールを優先してください。
4. 1分以上、表示が変わらない
診断対象やローカル環境によって、完了までの時間は変わります。ずっと待ち続ける必要はありません。いったん止める時は、ターミナルでCtrl+Cを押します。
手元のCodex CLI 0.150.1では、codex doctor --helpの構文確認は完了しましたが、実診断は90秒を超えても結果が出ず、Ctrl+Cで終了しました。そのため、実診断の完走は筆者環境では動作未確認です。
この場合は、次の短い確認が通るかを切り分けの入口にできます。
codex --version
codex doctor --help
5. 記号や色が崩れて読みにくい
今回のコマンドどおり、--no-color --asciiを付けてください。
codex doctor --summary --no-color --ascii
ターミナルの種類による見え方の差を減らせます。
6. 診断結果を質問サイトへ貼ってよいか迷う
そのまま全部を貼るのは避けましょう。診断はredacted、つまり秘密情報を伏せる設計の出力も用意されていますが、共有前の人間による確認は必要です。
ユーザー名を含むパス、組織名、リポジトリ名、ホスト名、識別子、設定値などが残っていないか読み直し、必要な検査行だけを一般化して共有します。APIキーやアクセストークンは絶対に貼りません。
7. 全項目が正常なのにCodexの回答がおかしい
doctorが見るのは、CLIを動かす環境の状態です。依頼文の曖昧さ、読ませたファイル、モデルの応答内容まで保証するものではありません。
環境が正常なら、次は依頼を1つに絞り、対象ファイルと成功条件を明示して試します。ここはdoctorの担当範囲の外です。
この機能の限界と、使わなくてよい条件
codex doctorは環境診断です。AIが必ず正しい回答を返すことや、すべての不具合を自動修復することは保証しません。
また、Codexが普段どおり動いていて、設定や認証も変えていないなら、毎回実行する必要はありません。短い読み取りタスクを1回試したいだけなら、そのままCodexを起動した方が早い人もいます。
効きやすいのは、こんな時です。
- 初回導入後、どこまで準備できたか分からない
- 更新後に急に動かなくなった
- 認証、Git、設定のどれが原因か絞れない
- 問い合わせ前に、自分で確認できる範囲を整理したい
診断が長時間終わらない場合は、それ自体を追加の手がかりとして扱い、無理に待ち続けない。これも大事な判断かなと思います。
今日の最初の1歩
今日は、修復まで全部やらなくて大丈夫です。通常のターミナルで、次の1行だけ実行してみてください。
codex doctor --summary --no-color --ascii
最終集計か、要確認項目を1つ見つけられたら終了です。
「動かない」を大きな不安のまま抱えるのではなく、次に見る場所が1つ分かる状態へ変える。AIエージェントを使い始める時の、かなり具体的な一歩です。
参考リンク
最終更新: 2026年9月7日
生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています → Xで次の実践例を見る