Codexのデバイスコード認証でSSH環境にログイン
リモートのサーバーや開発コンテナへ SSH でつないで Codex CLI を入れたものの、codex login を打つとブラウザが立ち上がらず、サインインがそこで止まってしまう——というつまずきは珍しくない。ローカルの PC ならブラウザの ChatGPT サインインで済む処理が、画面のないヘッドレス環境では完結しないからだ。この壁を越えるのがデバイスコード認証で、別の端末のブラウザを借りて手元の CLI を認証する仕組みになっている。本記事では、その有効化の手順と確認方法を OpenAI の公式情報に沿って整理する（出典: https://developers.openai.com/codex/auth）。
デバイスコード認証は、サインインする端末と、ブラウザを開く端末を分けられるログイン方式だ。Codex CLI が短いコードと認証用 URL を表示し、利用者はスマホや手元の PC のブラウザでその URL を開いてコードを入力し、ChatGPT アカウントで承認する。承認が通ると、SSH 先の CLI 側へ資格情報が渡って ~/.codex/auth.json にキャッシュされる。ブラウザを起動できないサーバー・コンテナ・WSL でサインインを完結させるための正攻法だと考えてよい（出典: https://developers.openai.com/codex/auth）。
通常の codex login は、ローカルホストへのコールバックを使ってブラウザの ChatGPT サインインと CLI を結びつける。この経路はブラウザとローカルポートの両方が使える環境を前提にしているため、画面のないリモートではそのまま動かない。デバイスコード認証はこのコールバックの代わりに「URL とコードを人間が手で運ぶ」設計になっており、踏み台越しの開発環境や CI に近い無人サーバーでも一度だけ対話的にサインインできる。スクリプトから完全無人で回したい用途では、後述の API キー認証のほうが向く場合もある（出典: https://github.com/openai/codex）。
運用面では、認証が一度通れば資格情報が ~/.codex/auth.json に保存され、以降のコマンドは再サインインなしで動く。この auth.json はパスワードと同等の機密情報であり、リポジトリへのコミットや共有は避け、サーバーを破棄するときは確実に消す。サインインの状態は codex login status で確認でき、おかしくなったら codex logout で資格情報を消してから入れ直すのが基本だ。本記事の後半では、コードが期限切れになる・URL が開けないといった典型的な詰まりどころの切り分けもまとめる（出典: https://developers.openai.com/codex/auth）。
目次 (13)
デバイスコード認証とは何か
デバイスコード認証とは、サインインの操作を行う端末（ブラウザを開ける端末）と、実際に認証されたいデバイス（Codex CLI が動いているサーバー）を分離してログインを成立させる方式のことだ。Codex CLI 側は短い確認コードと認証用の URL を画面に表示するだけで、利用者はその URL を手元のスマホやノート PC のブラウザで開き、表示されたコードを入力し、ChatGPT アカウントでサインインして承認する。承認が完了すると、CLI 側がバックグラウンドで認証の完了を検知し、資格情報を受け取ってローカルにキャッシュする。つまり「コードと URL を人間が別端末へ運ぶ」ことで、CLI が動いている環境にブラウザがなくてもサインインを完結させられるのがこの方式の核心だ。Codex のサインインは最終的に資格情報を ~/.codex/auth.json に保存して再利用するため、一度デバイスコード認証を通してしまえば、その後のコマンド実行ごとに毎回認証をやり直す必要はない（出典: https://developers.openai.com/codex/auth）。
なぜヘッドレス環境で必要になるのか
通常の codex login は、CLI がローカルホスト上に一時的な受け口を開き、ブラウザでの ChatGPT サインインが終わるとそのローカルポートへ結果が返ってくる、という流れで動く。この経路はブラウザが自動で立ち上がり、かつ同じマシン上のローカルポートへアクセスできる環境を暗黙の前提にしている。ところが SSH で接続しただけのサーバー、GUI を持たない Linux、Docker コンテナ、リモート開発環境などでは、そもそもブラウザが存在しなかったり、ローカルポートへの折り返しが成立しなかったりする。その結果、codex login が URL を表示したまま待ち続け、サインインが先へ進まない。デバイスコード認証は、このローカルコールバックを「人間が URL とコードを別端末へ手で運ぶ」操作で置き換えることで、画面のない環境でも一度だけ対話的にサインインを通せるようにする回避策だ。Codex CLI が安定版として広く配布されるにつれ、開発者が手元の PC ではなくリモートのサーバーやクラウドの開発環境に Codex を入れて使う場面が増えており、その流れでデバイスコード認証を必要とする人も増えている（出典: https://github.com/openai/codex）。
事前に確認しておく前提
手順に入る前に、いくつか前提を整えておくと失敗が減る。準備が不十分なまま進めると、コードの有効期限切れや既存の認証情報との競合でつまずきやすいためだ。
Codex CLI のバージョンを最新にする
デバイスコード認証まわりの挙動は CLI の更新で改善されることがあるため、まず手元の Codex CLI を最新の安定版へ上げておく。古いバージョンではフラグ名やメッセージが異なる場合があり、公式ドキュメントの記述と画面表示がずれて混乱の原因になる。インストール直後であっても、サインインの前にバージョンを確認し、必要なら更新してから認証に進むのが安全だ（出典: https://github.com/openai/codex）。
既存の認証情報と環境変数を確認する
サインインで詰まる原因の多くは、過去の資格情報や環境変数が残っていることにある。サーバー側のシェルや .env に OPENAI_API_KEY が設定されていると、ChatGPT サインインを済ませても CLI がそのキーを優先してしまい、意図しない認証状態になることがある。デバイスコード認証を試す前に、いま CLI がどの認証モードを見ているのかを codex login status で把握し、不要な OPENAI_API_KEY が紛れ込んでいないかを確認しておく。古いセッションが壊れている場合は、先に codex logout で資格情報を消してまっさらな状態から始めるとよい（出典: https://developers.openai.com/codex/auth）。
別端末でブラウザと ChatGPT アカウントを用意する
デバイスコード認証は、CLI が動いている端末とは別に、ブラウザを開ける端末がもう一台あることを前提にする。スマホでもよいので、認証用 URL を開けて ChatGPT にサインインできる環境を手元に用意しておく。利用したい Codex のプランに紐づく ChatGPT アカウントでサインインすることも忘れないようにする。承認に使うアカウントを取り違えると、サインインは成功しても期待した利用枠やモデルにアクセスできないことがあるためだ。
デバイスコード認証でログインする手順
準備が整ったら、実際のサインインに進む。流れ自体はシンプルで、CLI 側で認証を開始し、表示された URL とコードを別端末で処理し、CLI 側へ戻って完了を確認する、という三段構えになる。
- SSH で接続したサーバー上で、Codex のサインインをデバイスコード方式で開始する。CLI 側に認証用の URL と短い確認コードが表示される。OpenAI のヘッドレス向けサインイン手順に従ってコマンドを実行する（出典: https://developers.openai.com/codex/auth）。
- 手元のスマホやノート PC のブラウザで、表示された URL を開く。
- 画面の案内に従い、CLI に出ていた確認コードを入力する。
- 利用したい Codex プランに紐づく ChatGPT アカウントでサインインし、デバイスの接続を承認する。
- 承認が完了すると、SSH 先の CLI 側が自動的にサインイン完了を検知し、資格情報を
~/.codex/auth.jsonに保存する。表示が「サインイン済み」に切り替わったことを確認する。
コードには有効期限があるため、URL を開いてからの操作はあまり間を置かずに進める。途中で席を外して期限が切れた場合は、CLI 側でサインインをやり直して新しいコードを発行すればよい。
サインイン後の確認と認証情報の扱い
サインインが終わったら、状態が正しく保存されているかを確認する。最も手軽なのは codex login status で、現在どの認証モードでサインインしているか、資格情報が有効かを表示してくれる。ここで「サインイン済み」と出れば、以降は通常どおり Codex のコマンドを実行できる。生成された ~/.codex/auth.json には、再サインインを省くための資格情報がキャッシュされており、これはパスワードと同等の機密情報として扱う必要がある。リポジトリにコミットしない、他人と共有しない、ログに貼り付けないといった基本を守る。とりわけ複数人で使う踏み台サーバーや、使い捨てのクラウド開発環境では、自分の auth.json が他の利用者から読めない権限になっているかを確認し、サーバーを破棄するときは資格情報を確実に削除してから廃棄する。サインインの状態がおかしくなったときは、codex logout でいったん資格情報を消してから、改めてデバイスコード認証でサインインし直すのが安全なリセット手順になる（出典: https://developers.openai.com/codex/auth）。
うまくいかないときの切り分け
デバイスコード認証で詰まるパターンは、いくつかの典型に分かれる。原因ごとに対処が異なるため、どこで止まっているのかを切り分けることが復旧の近道になる。
コードが期限切れ・無効になる
URL を開いてから確認コードを入力するまでに時間がかかりすぎると、コードの有効期限が切れてサインインが失敗する。この場合は焦らず、CLI 側でサインインをやり直して新しいコードを取得し、URL を開いたら間を置かずにコードを入力する。コードの打ち間違いでも同じく失敗するため、表示された文字列を正確に転記する。複数のサインインを並行して走らせると、どのコードが有効か分からなくなるので、一度に一つの認証だけを進めるのが確実だ。
URL を開いても承認が CLI に反映されない
別端末で承認したのに CLI 側がいつまでも完了を検知しない場合は、サインインに使った ChatGPT アカウントが、CLI 側で意図している認証と食い違っていないかを疑う。複数アカウントでブラウザにログインしていると、別のアカウントで承認してしまうことがある。いったん CLI 側でサインインを中断し、ブラウザ側で正しいアカウントに切り替えてからやり直す。ネットワークの遮断やプロキシが原因で CLI 側が承認結果を受け取れていないこともあるため、サーバーから OpenAI への通信が許可されているかも確認する。
環境変数が認証を上書きしている
サインイン自体は成功しているのにコマンドが認証エラーになるときは、OPENAI_API_KEY などの環境変数が ChatGPT サインインを上書きしている可能性が高い。codex login status で現在の認証モードを確認し、意図しない API キーが使われている場合は、その環境変数を一時的に外してから Codex を起動して切り分ける。環境変数によるキー指定と対話的なサインインのどちらを使うかを最初に決めておくと、こうした競合は起きにくくなる（出典: https://developers.openai.com/codex/auth）。
API キー認証との使い分け
デバイスコード認証は「一度だけ人が介在してサインインする」用途に向いた方式だが、無人で動かす自動処理には別の選択肢がある。OpenAI ダッシュボードで発行した API キーを使うサインインだ。こちらは標準の API 料金が適用され、スクリプトや CI のように人が画面を操作できない環境で資格情報を渡したいときに使われる。判断の目安はシンプルで、開発者が手元の別端末を使って一度サインインを済ませ、その後は対話的に Codex を使うならデバイスコード認証が、完全に無人で繰り返し実行するパイプラインに組み込むなら API キー認証が向く。どちらの方式でも、最終的に資格情報は機密として扱う点は変わらない。API キーをソースコードや共有ストレージに直接書かない、デバイスコード認証で生成した auth.json を公開しない、という原則を守れば、ヘッドレス環境でも安全に Codex を運用できる（出典: https://developers.openai.com/codex/auth）。
