Codexでtoken expiredエラーが出る原因と対処法｜再ログイン手順まとめ

Codex CLIで作業中に突然「token expired」や「refresh token was already used」と出て止まってしまった開発者・ブロガー向けに、最短の再ログイン手順をまとめます。エラー文は数種類ありますが、原因は「トークンの更新失敗」にほぼ集約されます。本記事を読めば、自分のエラー文から最短の復旧ルートを選べます。

token expiredの正体と、まず試す再ログイン手順

token expiredエラーで実際に起きていること

このエラーは「ログインが切れた」状態を表します。何が壊れているのかを先に理解すると、対処の選択を迷いません。

アクセストークンの期限切れと更新失敗の違い

Codexは短命なアクセストークンと、それを更新するためのrefresh tokenの2つを持っています。アクセストークンは短時間で切れますが、通常はrefresh tokenが裏で自動更新するため、ユーザーは期限切れを意識しません。

token expiredが表面化するのは、この自動更新そのものが失敗したときです。公式ドキュメントも「ChatGPTサインインのセッションは、期限切れ前に使用中へ自動でトークンを更新する」と説明しています（Authentication – Codex 公式、2026年6月8日確認）。

つまり読者がやるべきことは、切れたトークンを手で延ばすことではなく、新しいトークンを取り直す再ログインです。設定ファイルをいじって有効期限を伸ばすような対処は不要で、むしろ状態を複雑にするだけです。

なぜ「refresh tokenが使用済み」になるのか

refresh tokenは一度使うと新しいものに置き換わる仕組みです。これは盗用を防ぐためのセキュリティ設計で、同じrefresh tokenを2回使おうとすると拒否されます。

そのため、複数のCodexプロセス（CLIとIDE拡張など）が同時に更新を試みたり、古い認証状態が残っていると「すでに使われたtoken」として弾かれます。GitHubでも同型の報告が複数あります（openai/codex Issue #6036）。

この設計のため、いったんこの状態に陥ると、手元のトークンを使い回そうとするほど弾かれ続けます。新しいトークンを取り直す再ログインだけが正しい抜け道です。

ただし、原因が環境変数の干渉である場合は再ログインだけでは直りません。後述の確認項目で切り分けてください。

出たエラー文の原文から原因を切り分ける

token expired系のエラー文は表現が複数あります。原文を見れば「再ログインで直る系」か「別原因系」かを1分で判断できます。

再ログインで直る系のエラー文

次のメッセージが出たら、ほぼ再ログインで復旧します。いずれもrefresh tokenの更新失敗を示すものです。

たとえば Error loading configuration: Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again はその代表例です（openai/codex Issue #15754、v0.116.0で報告）。

もう1つ、Failed to refresh token: 401 Unauthorized: Your refresh token has already been used to generate a new access token. Please try signing in again. も同じ系統です。文中で「sign in again」を促している点が共通の目印になります。

別原因が疑われるエラー文

同じ401でも、文面に「Missing scopes」や「insufficient permissions」が含まれる場合は要注意です。再ログインでは直らないことがあります。

具体的には Unexpected status 401 Unauthorized: You have insufficient permissions for this operation. Missing scopes: api.responses.write. です。

これは環境変数 OPENAI_API_KEY がOAuthトークンを黙って上書きしているサインで、権限不足という表示は誤誘導です（openai/codex Issue #15151）。

この型を再ログインだけで何度も試すと、毎回同じ401が再発します。先に環境変数を消すのが正解です。

主な原因を3つに整理する

token expiredの背後にある原因は、おおむね次の3つに分けられます。どれに当たるかで対処が変わります。

refresh tokenの競合・使い回し

最も多いのがこの型です。複数プロセスの同時更新や、古い認証ファイルが残っていることで「使用済みtoken」と判定されます。

たとえばターミナルでCLIを動かしながら、同じマシンのVS Code拡張からもCodexを起動していると、両者がほぼ同時にrefresh tokenを更新しようとして片方が弾かれます。

この場合は codex logout で古い状態を一掃してから入り直せば直ります。CLIとIDE拡張を両方使っている人は、片方を閉じてから再ログインすると競合を避けられます。

環境変数 OPENAI_API_KEY の干渉

OPENAI_API_KEY がシェルに設定されていると、ChatGPTでログインしてもCodexは黙ってそのAPIキーを使います。キーの権限が足りないと、OAuthとは無関係な401が出ます。

やっかいなのは、エラー文が「権限不足」と表示されるため、ログインのやり直しを延々と試して時間を浪費しやすい点です。GitHubでも同じ混乱が報告されています（openai/codex Issue #15151）。

切り分けは簡単で、いったん環境変数を外して起動するだけです。Mac/Linuxなら unset OPENAI_API_KEY && codex のように一時的に消して確認します。恒久対策はエイリアス化です（後述）。

ライブセッション中の期限切れ

実行中のCodexセッションの最中にトークンが切れた場合、別のターミナルでログインし直しても、いま動いているセッションは復旧しません。

意外と見落とされがちなのが、この「セッション再起動が必要」という点です。再ログイン後はCodexを一度終了して開き直してください（openai/codex Issue #17041）。

長時間の自動実行や夜間バッチでCodexを動かしている場合は、この型に当たりやすくなります。処理の途中でトークンが切れて止まったときは、ログインを直してからジョブごと再起動するのが確実です。

最短の再ログイン手順

原因が分かったら、次の順番で実行します。ローカルのcodex-cli 0.137.0で各コマンドの存在を確認済みです（2026年6月8日）。

状態確認からログインまでの4ステップ

手順は4つだけです。上から順に実行してください。

1. codex login status で現在のログイン状態を確認する
2. codex logout で保存済みの認証情報を削除する
3. OPENAI_API_KEY を一時的に外す（OS別の外し方は後半「環境別の対処」で解説）
4. codex login でChatGPTに入り直す（ブラウザが開かなければ表示URLを手動で開く）

多くのケースはこの4ステップで復旧します。codex login status は「Show login status」、codex logout は「Remove stored authentication credentials」と公式ヘルプに明記されています。

APIキー方式・デバイスコード方式の使い分け

ChatGPTログインが使えない環境では、別の方式を選べます。用途に応じて使い分けてください。

APIキーで入る場合は printenv OPENAI_API_KEY | codex login --with-api-key を使います。SSH先などブラウザを開けない環境では codex login --device-auth でデバイスコード認証に切り替えます。

個人開発でChatGPTプランを使うなら通常ログイン、CIや共有サーバーでキーを使い回すならAPIキー方式、と運用で分けると混乱が減ります。なお、APIキー方式とChatGPTログインを同じマシンで混在させると、前述のOPENAI_API_KEY干渉が起きやすくなる点には注意してください。

auth.json削除より先にlogoutを回す理由

ネット上では「auth.jsonを消せば直る」とよく書かれますが、それだけでは直らない環境があります。

ログイン情報の保存先は2通りある

結論として、最初の一歩は codex logout にしてください。理由は保存先が一律ではないからです。

公式は「Codexはログイン情報を平文ファイル ~/.codex/auth.json またはOSのクレデンシャルストアにキャッシュする」と説明しています（Authentication – Codex 公式、2026年6月8日確認）。

保存先は設定 cli_auth_credentials_store の値で決まり、file（ファイル保存）／keyring（OSのキーリング）／auto（OSストア優先・無ければファイル）から選べます。

キーリング保存の場合、auth.jsonというファイル自体が存在しないため、削除しても認証情報は残ったままです。だからファイル操作より codex logout が確実なのです。

ファイルを消すなら退避してから

logout後もまだ詰まる場合に限り、auth.jsonを手で消します。ただし削除ではなくリネーム退避が安全です。

たとえば mv ~/.codex/auth.json ~/.codex/auth.json.bak としておけば、別アカウントの設定など必要な情報が混じっていた場合に戻せます。退避後に codex login で入り直してください。

環境別の対処と、再ログインしても直らない場合

ここからはOSごとの具体コマンドと、再ログインで直らなかった時の確認項目を解説します。auth.jsonの場所と環境変数の消し方はOSで異なります。

Windowsの場合

WindowsではPowerShellとコマンドプロンプトで書き方が変わります。まずパスと環境変数を押さえます。

auth.jsonの場所と削除

Windowsの保存先は既定で %USERPROFILE%\.codex\auth.json です。PowerShellでは $env:USERPROFILE\.codex\auth.json として参照します。

退避するなら Rename-Item "$env:USERPROFILE\.codex\auth.json" auth.json.bak、削除するなら Remove-Item "$env:USERPROFILE\.codex\auth.json" です。CODEX_HOME を設定している場合はそのフォルダ配下を見てください。

エクスプローラーから探す場合、.codex は先頭がドットの隠しフォルダなので、表示設定で隠しファイルを表示にしないと見つかりません。

ただしキーリング保存だとこのファイルが無いので、先に codex logout を回す前提は同じです。

環境変数OPENAI_API_KEYの外し方

権限不足の401が出た場合、Windowsでも環境変数を外して確認します。シェルによって書き方が違います。

PowerShellなら Remove-Item Env:OPENAI_API_KEY、コマンドプロンプトなら set OPENAI_API_KEY=（値を空にする）です。外した状態で codex login を実行し、401が消えるか確認してください。

なお、これらは現在のターミナルだけの一時的な変更です。システム環境変数やユーザー環境変数に登録している場合は、設定画面から削除するか、エイリアス相当の起動スクリプトで毎回外す運用にしないと再発します。Windowsで「環境変数の編集」を開き、ユーザー環境変数とシステム環境変数の両方を確認しておくと取りこぼしが減ります。

Macの場合

MacはCodexの主要な動作環境で、GitHubの不具合報告も多くがmacOSです。標準的な手順がそのまま使えます。

auth.jsonの場所と退避

Macの保存先は ~/.codex/auth.json です。logout後も直らない場合のみ、このファイルを退避します。

コマンドは mv ~/.codex/auth.json ~/.codex/auth.json.bak です。退避後に codex login で入り直し、ChatGPTのサインインを完了させてください。

Finderからは Command + Shift + .（ドット）で隠しファイルを表示できますが、編集ミスを避けるため、退避はターミナルからのコマンド操作をおすすめします。

キーリング保存時の注意

Macではログイン情報がOSのキーチェーンに入ることがあります。この場合、auth.jsonを探しても見つかりません。

たとえば ~/.codex/auth.json が存在しないのにtoken expiredが出るなら、キーチェーン保存の可能性が高いです。codex logout で確実に消してから再ログインしてください。

キーチェーンを直接いじる必要はありません。logoutが保存先を問わず認証情報を消すので、まずはコマンド一本で十分です。

環境変数とログインの確認

Macでも、ログインし直す前にOPENAI_API_KEYの残留を確認してください。シェルの設定ファイルから自動で読み込まれていることがあります。

確認は printenv OPENAI_API_KEY、一時的に外すなら unset OPENAI_API_KEY です。~/.zshrc や ~/.bash_profile などに export OPENAI_API_KEY=... が書かれていないかもあわせて見ておくと、再発を防げます。記述を消したあとは、新しいターミナルを開き直してから再ログインすると確実です。

Linuxの場合

LinuxやWSL、SSH先のサーバーではブラウザを開けないことが多く、ログイン方式の選択が重要になります。

auth.jsonの場所とCODEX_HOME

Linuxの保存先も ~/.codex/auth.json です。環境変数 CODEX_HOME を変えている場合は $CODEX_HOME/auth.json を見ます。

削除は rm -f ~/.codex/auth.json、環境変数を外すのは unset OPENAI_API_KEY です。サーバー運用ではこのAPIキー干渉が起きやすいので、まず外して確認すると早いです。

WSL（Windows上のLinux）で使っている場合は、WindowsとWSLで別々のホームディレクトリを持つ点に注意してください。WSL側の ~/.codex/auth.json と、Windows側の %USERPROFILE%\.codex は別物です。

ブラウザを開けない環境のログイン

SSH先などGUIが無い環境では、通常の codex login がブラウザを開けずに止まります。ここでデバイスコード認証を使います。

codex login --device-auth を実行すると、別端末のブラウザで開けるコードが表示されます。これでヘッドレス環境でもサインインを完了できます。

手元のPCのブラウザでコードを入力して認証すれば、サーバー側のCodexにトークンが渡ります。踏み台サーバーやコンテナ内でも、この方式なら期限切れからの復旧が回せます。

サーバー運用での自動更新の注意

常駐させているサーバーでは、トークンの自動更新が走る前提でジョブを組むと、更新失敗時に丸ごと止まります。失敗時の再ログインを手順化しておくと安全です。

CI/CDで使う場合は、対話ログインではなくAPIキーやアクセストークンを環境変数で渡す方式が向いています。公式もCI向けの認証維持方法を別途案内しているので、運用前に確認しておくと安定します。トークンの有効期限を前提に、定期的な再認証や失敗時の通知を組み込んでおくと、夜間に止まっていたという事故を防げます。

再ログインしても解決しない場合の確認項目

ここまでやっても直らないときは、原因が別にあります。次の順でつぶしていきます。再ログインで直らない時は、ほぼ環境変数の残留かライブセッションの未再起動が原因です。

環境変数とプロセス競合をつぶす

まず確認すべきは、OPENAI_API_KEY が本当に消えているかです。消したつもりでも別の設定ファイルから再注入されることがあります。

Mac/Linuxは printenv OPENAI_API_KEY、PowerShellは echo $env:OPENAI_API_KEY で残留を確認します。残っていれば恒久対策として alias codex='unset OPENAI_API_KEY && command codex' を設定しておくと再発を防げます。

次に、CLIとIDE拡張、app-serverなど複数のCodexが同時に動いていないかを確認します。これらの同時更新は、refresh token競合を引き起こす典型的な原因です。

バージョンとセッションを見直す

古いバージョンで既知の認証バグを踏んでいることもあります。codex --version で確認し、古ければ更新してください。

更新は npm i -g @openai/codex です。あわせて、実行中だったセッションは再ログイン後に必ず開き直します。ライブセッションは外部での再ログインでは復旧しないためです。

それでも直らない場合は、別のエラーが重なっている可能性があります。エラー文をもう一度読み、本文の早見表（エラー文と対処の対応表）と照らし合わせて、自分がどの型に当たるかを切り分け直してください。同じ対処を繰り返すより、型の見直しが近道です。

関連エラーと公式情報の確認先

token expiredと前後して出やすい関連エラーと、一次情報の確認先をまとめます。鮮度の確認に使ってください。

あわせて出やすい関連エラー

同じ認証まわりでは、次の文言も近い原因で発生します。どれもログインの取り直しが基本対応です。

• OAuth token has expired（OAuthトークンの期限切れ）
• access token could not be refreshed（更新失敗・refresh token使用済み）
• Missing scopes: api.responses.write（OPENAI_API_KEY干渉の誤誘導401）
• token_exchange_failed（ログイン時のトークン交換失敗・ブラウザ起因）

このうちMissing scopesだけは環境変数が真因なので、再ログインの前に切り分けてください。

公式情報と更新履歴

仕様やコマンドは更新されるため、最終的には一次情報で確認してください。本記事は2026年6月8日時点の情報です。

「Codexはログイン情報を平文ファイル ~/.codex/auth.json またはOSのクレデンシャルストアにキャッシュする。auth.json はパスワードと同じく扱うこと。」

（OpenAI 公式 Authentication ドキュメントより要約・2026年6月8日確認）

確認先は公式の Authentication – Codex と、不具合報告が集まる openai/codex の GitHub Issues です。CI/CDで認証を維持したい場合は、公式のCI向け認証ガイドもあわせて確認してください。更新履歴: 2026年6月8日 初版（codex-cli 0.137.0で各コマンドの存在を確認）。

よくある質問（FAQ）

token expired周りで読者から多い疑問を、本文の結論にそろえてまとめました。

復旧前の最終チェックリスト

再ログイン前に、次の5項目を上から確認すると一発で通りやすくなります。いずれも本文で解説した要点を1行にまとめたものです。