はじめに
個人開発で Codex CLI を WSL と SSH 先のサーバーから使えるようにしようとして、ログインまわりでしばらくハマりました。 通常のブラウザログインも、デバイスコード認証も通らず、CLI を入れたところから先に進めない状態でした。
本記事では、WSL と SSH 先で Codex CLI のログインに失敗したとき、Windows 側で認証して ~/.codex/auth.json をコピーするまでの流れをまとめます。 本記事は自身の管理下の環境で行うトラブルシュートを前提としています。認証情報を扱うため、共有端末や管理外のサーバーでは同じ手順を実行しないでください。
背景
Codex CLI はログイン時にブラウザを開き、ローカルのコールバック経由で認証結果を CLI に返します。 手元の Windows で直接実行する場合は自然に動きますが、WSL や SSH 先ではブラウザと CLI の実行環境が分かれます。
そのため、ブラウザは Windows 側で開いているのに、トークンを受け取る CLI は WSL やリモートサーバー側にいる、という状態になりがちです。 この構成では、localhost の向きやネットワーク制約によってログインが失敗することがあります。
最初はデバイスコード認証で回避できると思っていました。 しかし筆者の環境では、デバイスコードを発行する段階でエラーになりました。
codex auth login --device-auth出ていたエラーは次の内容です。
Error logging in with device code: error sending request for url (https://auth.openai.com/api/accounts/deviceauth/usercode)この時点では、CLI の問題なのか、ネットワークの問題なのか、アカウント設定の問題なのかを切り分けられていませんでした。 結果としては、Windows 側でログインして生成された認証キャッシュを WSL と SSH 先へコピーする方法で解決しました。
使用環境
今回の前提は次のとおりです。
| 項目 | 内容 |
|---|---|
| ローカル OS | Windows |
| 開発環境 | WSL |
| 追加の実行環境 | SSH 接続先の Linux サーバー |
| 利用ツール | Codex CLI |
| 認証方式 | ChatGPT アカウントでのログイン |
Codex CLI のコマンド名は、バージョンによって codex login と案内される場合があります。 筆者の手元では codex auth login を使っていましたが、公式ドキュメントでは codex login が使われています。 実行時は、自分の環境の codex --help でサブコマンドを確認すると安全です。
codex --help失敗したログイン方法
通常のログイン
まずは通常のログインを試しました。
codex auth loginこの方法では、ブラウザを使った認証フローに進みます。 Windows 側でブラウザが開くところまでは期待できますが、WSL や SSH 先では CLI が待っているコールバックに認証結果が戻らないことがあります。
特に SSH 先のサーバーでは、ブラウザがサーバー上に存在しないか、存在していても手元のブラウザとは別物です。 そのため、ログイン URL をコピーして Windows 側のブラウザで開いても、CLI 側の待ち受けに戻せずに失敗しやすくなります。
デバイスコード認証
次に試したのがデバイスコード認証です。 ヘッドレス環境ではブラウザログインより扱いやすいはずなので、最初に期待した回避策でした。
codex auth login --device-authしかし筆者の環境では、認証コードを表示する前に次のエラーになりました。
Error logging in with device code: error sending request for url (https://auth.openai.com/api/accounts/deviceauth/usercode)このエラーだけでは原因を断定できません。 auth.openai.com への到達性、プロキシ、証明書、アカウント側の設定など、複数の可能性があります。
ここで長く掘り続けるより、まず使える状態にすることを優先しました。 公式ドキュメントを確認すると、ブラウザログインできるマシンで認証して、そのキャッシュをヘッドレス環境へコピーするフォールバック手順が案内されていました。
参考:
- https://developers.openai.com/codex/auth#fallback-authenticate-locally-and-copy-your-auth-cache
なぜ auth.json のコピーで解決できるのか
Codex CLI はログイン後の情報をローカルにキャッシュします。 ファイルベースの保存では、デフォルトで ~/.codex/auth.json が使われます。
つまり、ブラウザログインが成功する環境で先に認証を完了し、その auth.json を別の環境へ置けば、コピー先の CLI も同じログイン情報を利用できます。 公式ドキュメントでも、ヘッドレス環境向けのフォールバックとしてこの方法が紹介されています。
一方で、auth.json はただの設定ファイルではありません。 アクセストークンを含むため、実質的にはパスワードと同じ扱いが必要です。
筆者のケースでは、WSL と SSH 先のサーバーは自分の管理下にあるため、コピーしても問題ないと判断しました。 ただし、共有端末や管理外のサーバーでは同じ手順を実行しないでください。
手順
1. Windows 側の PowerShell でログインする
まず、ブラウザログインが自然に動く Windows 側で Codex CLI にログインします。 PowerShell を開き、次のコマンドを実行します。
codex auth login公式ドキュメントのコマンド体系に合わせる場合は、次の形式になることがあります。
codex loginログインが完了したら、auth.json が作成されているか確認します。 PowerShell では、ホームディレクトリは $HOME で参照できます。
Test-Path "$HOME\.codex\auth.json"True が返れば、認証キャッシュが作成されています。
Trueもし False になる場合は、OS の資格情報ストアに保存されている可能性があります。 その場合は Codex CLI の設定でファイル保存を使う必要があります。 公式ドキュメントでは、cli_auth_credentials_store に file、keyring、auto を指定できると説明されています。
ファイル保存に寄せる場合は、~/.codex/config.toml に次のような設定を入れます。
cli_auth_credentials_store = "file"設定後にもう一度ログインすると、~/.codex/auth.json に保存される形にできます。
2. Windows から WSL へ auth.json をコピーする
次に、Windows 側で作られた auth.json を WSL 側へコピーします。 WSL から Windows のホームディレクトリを参照できる場合は、次のようにコピーできます。
mkdir -p ~/.codex
cp /mnt/c/Users/<Windowsユーザー名>/.codex/auth.json ~/.codex/auth.json
chmod 600 ~/.codex/auth.json<Windowsユーザー名> は自分の Windows ユーザー名に置き換えます。 mkdir -p ~/.codex は、コピー先のディレクトリがない場合に作成するためのコマンドです。 chmod 600 は、所有者だけが読み書きできる権限にするために付けています。
コピー後、WSL 側でファイルが存在するか確認します。
ls -l ~/.codex/auth.json権限が -rw------- になっていれば、最低限の権限設定はできています。
-rw------- 1 user user 1234 May 26 22:30 /home/user/.codex/auth.jsonここで表示されるサイズや日時は環境によって変わります。 重要なのは、ファイルが存在し、読み取り権限が広くなりすぎていないことです。
3. WSL 側でログイン状態を確認する
auth.json を置いたあと、WSL 側で Codex CLI を起動します。
codexログインを求められずに起動できれば、WSL 側で認証情報を利用できています。 明示的に状態確認できるコマンドがある場合は、それを使っても構いません。
例:
codex doctor4. SSH 先のサーバーへ auth.json をコピーする
SSH 先でも同じ考え方です。 まず、サーバー側に ~/.codex ディレクトリを作ります。
ssh user@example.com 'mkdir -p ~/.codex'次に、ローカルの auth.json をサーバーへコピーします。 WSL 側にコピー済みであれば、WSL から scp できます。
scp ~/.codex/auth.json user@example.com:~/.codex/auth.jsonコピー後、サーバー側で権限を整えます。
ssh user@example.com 'chmod 600 ~/.codex/auth.json'scp を使いたくない場合は、標準入力で渡す方法もあります。 公式ドキュメントにも同じ考え方の一行コマンドが紹介されています。
ssh user@example.com 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json
ssh user@example.com 'chmod 600 ~/.codex/auth.json'この方法は一時ファイルを作らずに済みます。 ただし、入力元の ~/.codex/auth.json を間違えないように注意が必要です。
5. SSH 先で起動確認する
最後に、SSH 先で Codex CLI を起動します。
ssh user@example.com
codexログイン画面に戻らずに利用できれば成功です。 ここまでで、Windows、WSL、SSH 先の三つの環境から同じ認証キャッシュを使える状態になります。
ハマったポイント
コマンド名がドキュメントと手元で違って見える
筆者の手元では codex auth login を実行していましたが、公式ドキュメントでは codex login が使われていました。 CLI のバージョンや配布形態によって、案内されるコマンドが変わる可能性があります。
このようなときは、ブログ記事や過去のメモをそのまま信じるより、手元の --help を見るのが早いです。
codex --help
codex auth --help今回の本質は「ブラウザログインできる環境で認証し、生成された認証キャッシュをヘッドレス環境へ渡す」ことです。 コマンド名の細かな差分より、この構造を理解しておくと応用しやすくなります。
auth.json は設定ファイルではなく認証情報
auth.json という名前だけを見ると、単なる設定ファイルのように感じます。 しかし中身はログイン済みセッションの情報です。
そのため、次のような扱いは避ける必要があります。
- Git リポジトリにコミットする
- Issue やチャットに貼り付ける
- 共有サーバーの他ユーザーから読める権限にする
- バックアップ先に暗号化なしで置く
最低限、Linux 側では chmod 600 ~/.codex/auth.json を実行しておくことをおすすめします。 また、作業が終わったサーバーでは codex logout 相当のコマンドや auth.json の削除でログアウト状態に戻せます。
反省
今回いちばん反省したのは、エラーメッセージから原因を追いすぎたことです。 deviceauth/usercode にリクエストできないという表示を見て、ネットワーク、DNS、証明書、プロキシなどを順に疑いました。
もちろんそれらの切り分けが必要な場面もあります。 ただ、今回の目的は Codex CLI を WSL と SSH 先で使えるようにすることでした。 公式ドキュメントには、ヘッドレス環境でのログイン方法とフォールバックが整理されていました。
先にドキュメントを読んでいれば、auth.json をコピーする方法にもっと早くたどり着けたはずです。 ドキュメントはしっかり読みましょう、という話でした。
代替案
今回は auth.json のコピーで解決しましたが、状況によっては別の方法のほうが向いています。
SSH ポートフォワードを使う
SSH 先の標準的なブラウザログインを使いたい場合は、ローカルコールバック用のポートを転送する方法があります。 公式ドキュメントでは、標準のコールバックとして localhost:1455 が案内されています。
ssh -L 1455:localhost:1455 user@example.comこの SSH セッション内で codex login を実行し、表示された URL を手元のブラウザで開く形です。 認証情報をファイルとしてコピーしない点はきれいですが、ポートの向きが分かりにくい場合があります。
まとめ
WSL や SSH 先で Codex CLI のログインがうまくいかない場合、ブラウザログインできる Windows 側で先に認証し、~/.codex/auth.json をコピーすることで復旧できました。 公式ドキュメントにもヘッドレス環境向けのフォールバックとして整理されており、筆者のケースではこの方法が一番早かったです。
今回の作業で改めて感じたのは、認証まわりのエラーは原因調査に入る前に公式ドキュメントのフォールバックを確認したほうがよい、ということです。 ただし auth.json はアクセストークンを含むため、コピー先を自分の管理下に限定し、権限設定と共有漏れには注意が必要です。
コメント