この記事でわかること
- AI CLI（Claude Code、GitHub Copilot CLI、Codex CLI など)で認証エラーが起きる典型的な原因の切り分け方
- エラーメッセージ別に「まず確認すべき箇所」を手順化したチェックリスト
- ローカル環境で実際に発生した認証エラーの再現条件と回避策
- 日本国内のネットワーク環境・法人プロキシ配下で起きやすい固有の詰まりどころ
AI CLI の認証エラーが起きる典型的な原因
AI CLI ツールの認証エラーは、大きく分けると「資格情報そのものの問題」「保存場所の問題」「通信経路の問題」の3種類に集約される。まず資格情報そのものの問題は、APIキーやOAuthトークンの有効期限切れ、権限スコープ不足、複数アカウントを切り替えた際の古いセッションの残存などが該当する。次に保存場所の問題は、macOS であればキーチェーン、Linux であれば ~/.config 配下の設定ファイルに保存された値が、OSアップデートや権限変更によって読めなくなるケースを指す。最後に通信経路の問題は、社内プロキシやファイアウォールが認証サーバーへのリクエストを遮断し、CLI 側には単に「401」や「Unauthorized」としか表示されないため原因がわかりにくいというものだ。
これら3種類のどれに当たるかを最初に切り分けないまま、キーを再発行したり再ログインを繰り返したりすると、根本原因が環境側にあるケースを見落とす。GitHub の公式ドキュメントでも、CLI 認証のトラブルシューティングは「トークンの権限スコープを確認する」ことが最初のステップとして案内されており、これは Git 系だけでなく AI CLI 全般に応用できる考え方である（Managing your personal access tokens）。
エラーメッセージ別の切り分け手順
401 系のエラーはほぼ確実に資格情報の失効か権限不足なので、再ログインで直る場合が多い。403 系は権限スコープの不足やアカウント種別の制限で、キーの再発行だけでは直らないことが多い。タイムアウト系は通信経路側の問題であることが多く、プロキシやVPNの設定を疑う必要がある。GitHub CLI の公式マニュアルでも、gh auth login 実行時のトラブルはまずこの3分類のどれに当たるかを確認するよう案内されている（gh auth login）。
実際に試してわかったこと
macOS で security find-generic-password -w を使ってキーチェーンから値を取り出す運用をしている場合、値に印字不可能なバイトが含まれていると16進文字列で返ってくることがある。これに気づかずそのままトークンとして CLI に渡すと、見た目は値が入っているのに認証エラーになるという厄介な状態になる。実際にこの現象を踏んだ際は、取り出した文字列をそのまま比較するのではなく、実際にAPIを1回呼び出して疎通確認することでしか判別できなかった。保存した値をターミナルに表示して目視確認する運用は、値が漏洩するリスクもあるため避け、疎通確認一発で判断する方式に切り替えたところ再発しなくなった。
もう一点、環境変数とCLI内部の設定ファイルの両方に資格情報を置いていたケースでは、環境変数側が優先されて古いキーが読まれ続け、設定ファイルを更新しても反映されないという事象が起きた。優先順位はツールごとに異なるため、env | grep -i key のような形で環境変数側に古い値が残っていないかを先に確認する癖をつけると、原因特定にかかる時間が大きく減った。再ログイン直後にもエラーが再発する場合は、9割方この環境変数の残留が原因だった。
日本で使う場合の注意
日本国内の法人ネットワークでは、SSL/TLSインスペクションを行う中間プロキシを経由させている企業が少なくない。この構成では、AI CLI が認証サーバーと通信する際に自己署名証明書がクライアント側で「信頼されていない」と判定され、認証エラーではなく証明書エラーとして現れることがある。表示上は認証エラーと見分けがつきにくいため、社内ネットワークで初めてCLIを使う際は、まず個人のモバイル回線やテザリングなど別経路で同じコマンドを試し、社内ネットワーク特有の問題かどうかを切り分けるのが早い。
また、日本の会社員が個人アカウントと業務アカウントを1台のマシンで併用しているケースも多く見られる。この場合、CLIのグローバル設定に業務アカウントのトークンが残ったまま個人アカウントでログインし直しても、内部的には古いトークンを参照し続けてエラーになることがある。アカウントを切り替える際は、ログアウトコマンドで明示的に資格情報を削除してから再ログインする方が、トラブルの再現率が低かった。
まとめ
AI CLI の認証エラーは、エラーメッセージだけを見て場当たり的にキーを再発行するのではなく、「資格情報」「保存場所」「通信経路」のどこで詰まっているかを順番に切り分けることで解決までの時間を大きく短縮できる。特に環境変数の残留や証明書の信頼設定は見落としやすく、日本の法人ネットワーク環境ではこの2つが原因になっているケースが体感でも多い。まずは本記事の切り分け手順に沿って、どの段階でエラーが発生しているかを1つずつ確認するところから始めてほしい。
