Codex CLI トラブルシューティング：インストール、認証、設定、接続

完全なエラー、トリガーとなったコマンド、Codex のバージョン、OS、作業ディレクトリ、発生時刻を記録してください。最後の1行だけをコピーしたり、再インストールした後に元の状態を思い出そうとしないでください。

推奨順序は、バイナリと PATH、設定の解析、認証、provider とモデル、ネットワーク、権限、拡張機能です。毎回1つの変数だけを変更し、変更前後の結果を保存してください。

command not found の問題は通常、インストールディレクトリが PATH に含まれていないか、端末がまだ古い環境を使用していることが原因です。バージョンの不一致は npm、Homebrew、スクリプトインストールが併存する場合によく見られます。

まずヒットしたすべての codex を見つけ出し、元のインストール経路でアップグレードするか、古いコピーをアンインストールしてください。sudo でシステムディレクトリを盲目的に上書きしないでください。

TOML の重複キー、誤った階層、未知のフィールド、誤った CODEX_HOME はいずれも設定を無効にする可能性があります。元のファイルをバックアップしてから、厳格な設定チェックと doctor を実行してください。

ユーザー設定が現在のコマンドに影響している疑いがある場合は、--ignore-user-config で比較検証できます。これはユーザーの config.toml を読み込みませんが、認証では引き続き CODEX_HOME が使用されます。比較検証が成功したからといって元のファイルを削除すべきではなく、問題がユーザー設定層にあることだけを示しています。

401 や 403 の場合はまず認証情報とサーバー側の権限を確認します。未知のモデルはリクエストがサービスに到達しているがモデル名が受け入れられていないことを示します。404 は base URL のパス誤りの可能性があります。タイムアウト、DNS、TLS のエラーはネットワーク層に属します。

CodeNodex のユーザーは、まず keys または setup を実行して Key とプラットフォームを検証し、その後に Codex doctor を確認してください。TLS の検証を無効化したり、Authorization ヘッダーを表示したり、実際の Key をチケットに貼り付けてトラブルシューティングしないでください。

読み込みはできるが書き込みできない場合、通常はサンドボックスモードと作業ディレクトリを確認します。隣接ディレクトリが必要な場合は --add-dir を使用してください。ネットワークツールが利用できないことは必ずしも provider のエラーではなく、サンドボックス、プロキシ、組織ポリシーの可能性があります。

MCP の問題は、まず設定リストと個々のサーバーを確認し、その後にローカルプロセスやリモートの URL を検査します。障害のある MCP を一時的に削除することで、起動への影響を検証できますが、リモートの認証情報は別途取り消す必要があります。

doctor --json は機械可読でマスク済みのレポートを提供しますが、アップロード前に人手で確認してください。問題レポートには最小再現手順、期待される動作と実際の動作、バージョン、設定中のシークレットを含まない関連フィールド、およびユーザー設定を無視した場合でも再現するかどうかを含めるべきです。

公式 Codex の問題は公式リポジトリに報告してください。CodeNodex Key、ゲートウェイ、モデルマッピングの問題は CodeNodex サポートに報告してください。責任の境界をまず確認し、公開 issue でサードパーティの認証情報を露出させないようにしてください。