Codex CLIのインストールと設定：Windows・macOS・Linux対応

Codex CLIを使い始めるときは、検索で見つけた古いコマンドをそのまま実行するより、自分のOSと管理しやすい導入経路を先に決めるほうが確実です。現在はスタンドアロンインストーラーがmacOS・LinuxだけでなくWindowsにも用意され、npmとHomebrewも選べます。Windowsだから必ずWSL、あるいはどの環境でもNode.jsが必須、というわけではありません。

この記事では、インストールを「ファイルが入った」で終わらせません。端末がcodexを認識すること、プロジェクト内で初回起動できること、課金元を理解して認証できること、最小限のconfig.tomlで権限境界を保てることを順に確認します。高度なMCPやprovider設定は、動く基準線を作った後の別作業です。

自分に合う導入経路を選ぶ

2026年9月1日に確認したCodex CLIの公式ドキュメントでは、macOS/Linux用とWindows用のスタンドアロンインストーラー、Homebrew cask、npmが案内されています。導入方法は更新される可能性があるため、実行直前にもリンク先のコマンドと対応OSを確認してください。

導入経路ごとに、対応環境、前提、選ぶ目安を縦に確認すると迷いません。

• スタンドアロン
  • 対応環境：macOS、Linux、Windows
  • 事前に必要なもの：対応するシェルとダウンロード環境
  • 選ぶ目安：Codex CLIのためだけにNode.jsを用意したくない場合
• Homebrew cask
  • 対応環境：Homebrewを利用中のmacOS
  • 事前に必要なもの：Homebrew
  • 選ぶ目安：既存のbrew運用にまとめたい場合
• npm
  • 対応環境：Node.js/npmをすでに管理している環境
  • 事前に必要なもの：Node.jsとnpm
  • 選ぶ目安：Node.js系のCLIと同じ方法で管理したい場合

ここで重要なのは、Node.jsが必要なのはnpm経路を選ぶ場合だという点です。スタンドアロンやHomebrewを選ぶ場合まで、先にNode.jsを導入する必要はありません。

Windowsでも、公式のPowerShell向けstandalone installerを選べます。既存の開発環境がWSL上にあり、Linuxのツールチェーンと一緒に使いたい場合はWSL2を選択肢にできますが、Codex CLIを導入するためだけにWSLを必須と考える必要はありません。公式WSLガイドでは、Codex 0.115以降はWSL1が非対応です。PowerShellとWSLではファイルパス、PATH、home、設定が別になるため、日常的にプロジェクトを開く側へインストールします。WSL2ならリポジトリを/mnt/cではなく~/codeなどLinux homeへ置くほうが、I/Oと権限の問題を減らせます。

OS別にCodex CLIをインストールする

macOS：スタンドアロンかHomebrewを選ぶ

Node.jsやパッケージマネージャーを新たに用意したくない場合は、公式のmacOS/Linux向けスタンドアロンインストーラーを使います。

bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh

この同じ公式コマンドがstandalone経路の更新にも使われます。実行直前にリンク先の現行表示も確認してください。

すでにHomebrewでCLIを管理しているなら、公式に案内されているcaskを使えます。

bash
brew install --cask codex

brew install codexではなく、--caskを含むことを確認します。実行が終わったら、同じ端末で次の確認へ進みます。コマンドが見つからない場合は、いったん端末を閉じて新しいセッションを開いてから再確認してください。

Linux：スタンドアロンかnpmを選ぶ

Linuxでは、上記のmacOS/Linux向けstandaloneコマンドを第一候補にできます。ディストリビューション名だけで手順を決めず、利用中のシェル、CPUアーキテクチャ、書き込み権限が公式の案内と合うかを確認して実行します。

Node.jsとnpmをすでに運用している場合は、npm経路も選べます。

bash
npm install -g @openai/codex

この方法では、npm自身が実行できることと、グローバルパッケージの実行ファイルがPATHに入っていることが前提です。権限エラーが出たときに、理由を確認せずsudoを付けて繰り返すのは避けましょう。Node.jsを入れた方法とnpmのグローバルディレクトリを確認し、その管理方法に合う権限でやり直します。

Windows：PowerShellのスタンドアロンを第一候補にできる

Windowsでは、公式ドキュメントのstandalone installerをPowerShellで実行できます。

powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

実行ポリシーや企業端末の制限によって止まる場合は、エラーを無視してシステム全体の設定を緩めず、組織の端末ポリシーに従ってください。同じ公式コマンドがstandalone経路の更新にも使われます。

Node.js/npmをWindows側で管理済みなら、PowerShellからnpm経路を選ぶこともできます。

powershell
npm install -g @openai/codex

WSLで導入する場合は、Windows側ではなくWSLのLinux環境内でLinux向け手順を実行します。PowerShellに入れたcodexとWSLに入れたcodexは別物です。プロジェクトがどちらのファイルシステムにあり、どちらの端末から作業するかを先に決めてください。

codexが認識されるか確認する

インストール処理が正常終了しても、現在開いている端末へPATHの変更がまだ反映されていないことがあります。まずバージョン表示を試します。

bash
codex --version

バージョン情報が表示されれば、少なくともその端末はCodex CLIの実行ファイルを見つけています。macOS/Linuxでは、実体の場所も確認できます。

bash
command -v codex

PowerShellでは次を使います。

powershell
Get-Command codex

ここでcommand not foundや「用語として認識されません」と表示された場合は、まだ認証の問題ではありません。次の順で切り分けます。

1. インストール時と同じOS・シェルを開いているか確認する。とくにPowerShellとWSLを取り違えていないかを見る。
2. 端末を完全に閉じ、新しいセッションを開く。
3. npm経路ならnpmが実行でき、グローバル実行ファイルの場所がPATHに含まれるか確認する。
4. Homebrew経路ならbrewが同じユーザー・同じシェルから実行できるか確認する。
5. 複数の経路で重ねてインストールせず、選んだ一つの経路の状態を確定する。

複数のcodexが見つかる場合は、古い版が先に解決されている可能性があります。command -v codexまたはGet-Command codexで実際の場所を確認してから、不要な導入経路を整理します。

プロジェクトで初回起動する

コマンド認識を確認したら、Codexに扱わせたいプロジェクトのディレクトリへ移動します。次は例なので、自分のパスに置き換えてください。

bash
cd /path/to/your-project
codex

初回起動時は、利用可能な認証方法を選ぶ画面へ進みます。公式の一般的な流れでは、ChatGPTでサインインするか、許可されている別の認証方法を選択します。管理対象のワークスペースでは、管理者が利用できる方法を制限している場合があります。

この時点では、三つの成功状態を分けて判断すると原因を見失いません。

この区別があれば、ブラウザでのサインインに失敗したときにCLIを再インストールしたり、codex自体が見つからない段階でAPIキーを作り直したりする無駄を避けられます。

ChatGPTサインインとAPIキーを混同しない

ローカルのCodex CLIは、ChatGPTサインインとAPIキーによるアクセスに対応しています。ただし、両者のアクセス条件と請求は同じではありません。公式の認証ドキュメントによると、APIキーを使った利用はOpenAI Platformの標準API料金で請求されます。ChatGPT側の利用可否は、アカウントのプランやワークスペース権限によって異なります。

そのため、「Codex CLIをインストールすれば無料で使える」「ChatGPTの契約があればAPI利用も追加請求されない」とは判断できません。認証画面に表示された選択肢から、自分のアカウントまたは組織で許可されている方法を選んでください。費用や機能の条件は変更される可能性があるため、認証前に公式ページで再確認するのが確実です。

認証画面へ進まない、ブラウザからCLIへ戻れない、認証後に権限エラーが出る場合は、インストール成功とは別の層を調べます。

• 端末やブラウザが組織のプロキシ、VPN、ファイアウォールの制限を受けていないか
• サインインしたアカウントが意図した個人・組織アカウントか
• 管理ワークスペースでCodexや認証方法が許可されているか
• APIキーを選んだ場合、対象のPlatformアカウントと請求設定が利用可能か

ネットワークや組織ポリシーが原因なら、CLIを別の方法で入れ直しても解決しません。表示されたエラーを保存し、管理者へ確認するときは、OS、利用した導入経路、codex --versionの成否、失敗した認証方法を分けて伝えると状況を再現しやすくなります。秘密情報であるAPIキーそのものは共有しないでください。

最初のタスクはGitで観測する

対象プロジェクトでgit status --shortを記録し、codexへ「ファイルを変更せず、入口と検証コマンドを説明する」と依頼します。回答が実在ファイルに一致し、終了後のgit status --shortが元の状態と同じなら、working directoryと初回権限境界を一緒に確認できます。秘密情報や未保存の本番変更を含むリポジトリを最初の実験場所にしないでください。

最初のconfig.tomlは小さく保つ

ユーザー設定は~/.codex/config.tomlに置きます。最初からmodel、MCP、providerを大量に足すより、権限と検索の境界だけを明示すると失敗箇所を追いやすくなります。

toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

workspace-writeは通常の書き込みをworkspace境界内に保ち、on-requestはより広い操作が必要なときに承認を残します。確認回数を減らすためだけにfull accessやsandbox bypassから始めないでください。現在の優先順位とフィールドはConfig basicsとConfiguration Referenceで確認できます。

Windowsネイティブでは、ユーザー設定に優先sandboxを加えられます。

toml
[windows]
sandbox = "elevated"

Windows sandbox文書ではelevatedが推奨です。管理者承認により制限ユーザー、ファイル境界、firewall ruleを設定します。企業ポリシーなどで構築できない場合はunelevatedへ退避できますが、隔離が弱いfallbackとして扱います。

信頼したリポジトリには.codex/config.tomlを置けますが、provider、auth、profile、notification、telemetryなどmachine-localのkeyはproject layerでは無視されます。一度だけ値を試すならcodex -c key=valueがその起動だけを上書きします。設定が効かないときは、active user、CODEX_HOME、project trust、CLI overrideを先に確認し、.codex全体を削除しないでください。

導入完了を最短で判定する

最後に、次の順で確認すればインストール作業は完了です。

text
1. 自分のOSに合う公式経路を一つ選んだ
2. codex --version でCLIが認識された
3. 対象プロジェクトへ移動して codex を起動した
4. 自分に許可された方法で認証した
5. 認証後のCLI画面へ進めた
6. 有効な設定layerが分かり、読み取り専用の初回タスク後もGit状態が想定どおりだった

途中で止まったら、その番号より前へ戻って確認します。1〜2で止まるなら導入経路やPATH、3で止まるなら実行環境、4〜5で止まるならアカウント・ネットワーク・ワークスペース権限が主な確認対象です。

本記事の製品手順と認証境界は、LaoZhang AI Teamが2026年9月1日に照合しています。コマンド、対応OS、認証条件は変わり得るため、実行時点の公式表示を最終判断にしてください。複数層にまたがる不具合では、現行CLI referenceのcodex doctorでinstallation、configuration、authentication、Git、runtimeを確認できます。共有前に診断結果の秘密情報やローカルpathを除いてください。