Codexが起動しない時の原因と対処｜切り分け手順
「codex と打っても何も起きない」「画面が真っ白のまま固まる」——いざ作業を始めようとした瞬間にCodexが起動しないと、それだけで手が止まってしまいます。
結論から言うと、Codexが起動しない原因は数パターンに収れんします。やみくもに再インストールを繰り返す前に、症状を3つに切り分けてから対処すれば、その多くは数分で直ります。最初の一手は codex doctor による自己診断です。
株式会社Fyveは中小企業のAI活用を月額で伴走しており、導入支援の現場で「起動しない」というつまずきに何度も立ち会ってきました。本記事では、私が実際にたどっている切り分けの順番と、原因別の直し方を整理してお伝えします。なお、Codexとは生成AIに作業を任せる「AIエージェント」型のツールで、ここでは主にコマンド画面で動かすCLI版とアプリ版を前提にしています。
まず「起動しない」を3タイプに切り分ける
同じ「起動しない」でも、内部で起きていることはまったく違います。先に症状を分類しておくと、見るべき場所がはっきりして無駄打ちが減ります。
タイプ1：そもそも反応しない（command not found 系）
コマンドを打っても「command not found」と返る、あるいは何も起きないタイプです。これはCodex本体ではなく、導入そのものやパス（PATH＝コマンドの置き場所をパソコンが探す経路）に問題があるサインです。後述するNode.jsやパッケージ名の確認が中心になります。
タイプ2：起動はするが真っ白・フリーズ系
コマンドは通るのに、画面（TUI＝文字ベースの操作画面）が真っ白のまま、あるいは固まって進まないタイプです。設定ファイルの不正値、状態データの破損、他ツールとの干渉などが疑わしくなります。
タイプ3：ログイン・認証で止まる系
起動の途中でログイン画面から進まない、「Token exchange failed」と出る、といった認証段階のつまずきです。ネットワーク環境やアカウント連携が原因の中心になります。
切り分けの起点：codex doctor と version 確認
タイプ分けができたら、推測で動く前にまず自己診断を走らせます。OpenAIのCodexには codex doctor という点検専用コマンドが実装されており、導入状態・設定・認証・ターミナル・各種ファイルの場所・接続性を読み取り専用でチェックして、問題と対処を表示してくれます（openai/codex リポジトリの doctor.rs で確認できる確定情報）。何が悪いか分からないときの一次切り分けは、ほぼこれで足ります。
あわせて codex --version で今の版数を確認します。アプリ版の場合は、アプリ内に同梱された実行ファイルのパスを指定してバージョンを確認できます。バージョン番号が出ない時点で、導入かパスに問題があると判断できます。
ここで大事なのが「エラーメッセージは自分で読み解こうとしない」ことです。表示された英語のエラーをそのままChatGPTなどのAIに貼り付け、「これは何が原因で、どう直せばよいか日本語で教えて」と聞くのが最短です。AIありきで進めれば、専門用語が分からなくても原因の見当がつきます。Codそのものが起動していなくても、別のAIに翻訳と原因推定を任せられるのが今の時代の強みです。
タイプ1の対処：command not found・PATH・Node まわり
「反応しない」系は、ほとんどが導入の土台でつまずいています。次の順で確認します。
正しいパッケージ名で入っているか
意外な落とし穴がパッケージ名の取り違えです。Codexの正式なインストール対象は @openai/codex であり、頭の @openai/ を付けずに入れると、まったく別のソフトが入ってしまいます。解説記事の中には省略形で書かれているものもあるため、ここは公式の表記で確認するのが安全です。OpenAI公式のCLIページでも、導入にはNode.jsが必要で、サインインはChatGPTアカウントかAPIキーで行うと明記されています（OpenAI公式CLIドキュメント・確定情報）。
Node.js のバージョンを合わせる
Codexは新しめのNode.js（JavaScriptの実行環境）を前提にしています。個人の報告では、古すぎる版や新しすぎる版で不調が出やすく、安定版とされる v20 または v22 系が無難という声が目立ちます。これは公式が断定しているわけではないため、まずは無難な安定版に合わせる、という温度感で捉えてください。
WSL・非対話シェルでパスが通らない
Windowsでよくあるのが、WSL（Windows上でLinuxを動かす仕組み）や特定の起動方法でNode管理ツールが読み込まれず、コマンドが見つからなくなるケースです。GitHubの不具合報告でも、非対話シェルが環境設定を読まずにパス不在になる事象が挙がっています。ターミナルを開き直す、ログインシェルとして起動し直す、といった基本動作で直ることが多いです。
これらを一通り見ても直らないときは、いったん削除して入れ直すのが結局いちばんの近道です。バージョン更新も同じ系統の対処で、最新版へ更新するだけで解消する報告も多くあります。導入手順そのものを丁寧に踏み直したい方は、次の記事も参考にしてください。
タイプ2の対処：真っ白・フリーズ・接続できない
起動はするのに進まない系は、設定や状態データ、他ツールとの干渉が主犯です。
設定ファイル（config.toml）の不正値・重複
もっとも頻度が高いのが、設定ファイル ~/.codex/config.toml の不正値や重複です。GitHubの報告では、不正なキーや残骸が混ざって読み込みに失敗し、起動できなくなる事象が確認されています。個人の報告でも、他ツールと併用した際に設定が重複登録され、起動直後にエラーや真っ白画面になったという声があります。重複行や見覚えのない設定値を削除して再起動すると直ることが多いです。
起動さえすれば、AIに直接任せられます。Codexが立ち上がる状態なら「config.tomlの重複した行を見つけて、安全な形に直して」と頼めば、設定の修正そのものをAIに任せられます。起動できない段階では、ファイルの中身をChatGPTに貼って「不正な箇所はどこか」を聞くのが補助になります。
状態データの破損
Codexは作業状態を内部の小さなデータベースに記録しています。これがロックされたり壊れたりすると起動を妨げます。実際、リポジトリ内には破損時に「codex doctor を実行して設定を確認するよう」案内する仕組みが組み込まれています。真っ白で固まるときは、ここでも doctor が効きます。
他ツールのショートカット（shim）干渉
個人の報告で最近多いのが、別の監視ツールなどがCodexの実行ファイルに自前のショートカット（shim＝間に挟まる中継ファイル）を張り、新しい内部サーバーとかみ合わず「サーバーに接続できない」で即終了するケースです。特定の環境変数を付けて起動すると一時回避できたという声もありますが、これは投稿者個人の体験談で公式の裏取りはありません。心当たりがあれば、最近入れた監視系ツールを疑う価値はあります。
残ったプロセスの掃除
過去の起動が裏で残っていると、新しい起動と衝突します。残プロセスを終了させる、WSLなら一度シャットダウンしてから入り直す、という掃除で復旧することがあります。Windowsデスクトップ版では、内部の通信が異常終了して起動に失敗する報告も上がっており、この場合も設定の見直しと残骸プロセスの掃除が基本対処になります。
タイプ3の対処：ログイン・認証で起動できない
認証段階で止まる系は、Codex本体よりネットワークやアカウント側の問題であることが多いです。
まず認証状態を確認して入り直す
最初に codex login status で認証が切れていないかを確認し、切れていれば codex login で入り直します。「ログイン画面が出ない」「Token exchange failed（トークン交換に失敗）」「localhost:1455 に接続できない」といったログインまわりの不具合は、公式リポジトリでも多数報告されている既知の事象です（openai/codex の報告事例）。
プロキシ・社内ネットワーク環境
会社のネットワークでよくあるのが、プロキシ（社内と外部の間に立つ中継）や独自のセキュリティ証明書が認証通信をブロックするケースです。GitHubでも、企業プロキシや独自証明書、セキュリティ判定が認証を妨げる報告が確認できます。この場合は、ブラウザ経由のログインではなくAPIキー方式でのサインインに切り替えると通ることがあります。プロキシの設定値を正しく通す、という対処もあわせて検討します。
それでも直らない時の最終手段とログの見方
ここまでで多くは解決しますが、粘っても直らないときの最後の確認です。
ログを見て事実を確認する
推測で動き続けるより、記録を見るほうが早いことがあります。OpenAI公式のトラブルシュートでは、アプリ版のmacOSログが ~/Library/Logs/com.openai.codex/ 配下に日付別で保存されると案内されています。固まったときは承認待ちかどうかを確認し、作業中の処理が終わるのを待ってからアプリを再起動する、という手順も公式に示されています（OpenAI公式トラブルシュート・確定情報）。ログの中身が読めなくても、そのままAIに貼って原因を聞けば十分です。
完全に消してから入れ直す
設定もキャッシュも含めて中途半端に残っていると、不調を引きずります。関連ファイルごと完全に削除してから再インストールすると、こじれた状態が一掃されて直ることが多いです。バージョンのズレや壊れた設定をまとめてリセットできるのが利点です。
システム要件を満たしているか
最後に基本ですが、動作環境そのものを確認します。Codexのドキュメント上の要件は、macOS 12以降、Ubuntu 20.04以降、Windowsは11かつWSL2、メモリは4GB以上が目安です。古いパソコンや要件未満の環境では、そもそも安定して起動しません。
関連するエラー全般の対処は、こちらの記事にまとめています。起動できた後によく出るつまずきも含めて確認しておくと、二度手間が減ります。
まとめ：起動しないは「順番」で潰す
Codexが起動しないときは、闇雲に試さず次の順で切り分けると最短で復旧できます。
- 症状を3タイプに分ける：反応しない／真っ白・フリーズ／認証で止まる
- codex doctor と codex --version で自己診断し、エラーは丸ごとAIに貼って原因を聞く
- 反応しない系：正しいパッケージ名（@openai/codex）・Node.jsの版・パスを確認、ダメなら入れ直す
- 真っ白・フリーズ系：config.tomlの不正値や重複を削除、状態データ破損は doctor、残プロセスを掃除
- 認証で止まる系：login status で確認して入り直す、プロキシ環境はAPIキー方式へ
- 最終手段：ログ確認、完全削除して再インストール、システム要件の見直し
原因の多くは設定・環境・認証のどれかに収まります。順番に潰していけば、起動トラブルは「怖いもの」ではなく「数分で片づく定型作業」になります。なお本記事で触れたshim干渉やバージョン番号などの一部は、利用者個人の報告に基づく未確認情報であり、公式の確定情報（doctorコマンド・公式トラブルシュート・要件）と区別して捉えてください。中小企業のAI活用支援を行う株式会社Fyveの現場でも、この切り分け手順がそのまま日々の復旧に役立っています。
「Codex を自分で使いこなしたい」「自社の業務に組み込みたい」
── そんな方は、まず初回無料相談でお話ししてみませんか。
御社の業務に合わせたCodex導入支援
「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。