Codex CLIのインストール方法 Mac・Windows・Linux別の手順と認証・エラー対処

Codex CLIは導入方法が複数用意されており、公式のインストールスクリプト、パッケージ管理の仕組み、配布されている実行ファイルのどれからでも入れられます。選択肢が多いぶん、どれを選べばよいか決めきれずに手が止まる場面が出てきます。

つまずきの多くは、経路を決めないまま複数の方法を試したことが原因です。ネイティブ環境とLinux環境が混ざる、古い実行ファイルが残る、といった状態になると、原因の切り分けに時間がかかります。

本記事では、導入前に決めておく3点を整理したうえで、OSごとの具体的な手順、認証と動作確認、つまずいたときの対処、更新と削除の方法までをまとめました。最初の1回で確実に動く状態にしたい方に向けた内容です。

確認したいポイント	結論	詳細
導入前に決めることは？	環境・経路・認証の3点	動かす場所、どの方法で入れるか、どう認証するかを先に決めると失敗しません。
インストール方法は何種類？	スクリプト・パッケージ・実行ファイル	公式スクリプト、npmやHomebrew、配布されている実行ファイルから選べます。
Node.jsは必須？	npmで入れる場合のみ必要	公式スクリプトから入れる場合は不要です。npm利用時は版の要件を確認します。
WindowsはWSL2が必要？	ネイティブでも動作する	手軽に試すならネイティブ、業務で継続利用するならWSL2が安定します。
導入後に何をする？	バージョン確認と認証	コマンドが認識されるか確かめ、契約中のアカウントでログインします。
コマンドが見つからない時は？	ターミナルを開き直す	パスが反映されていないことが多く、開き直しで解決する場合がほとんどです。
更新はどうする？	入れた経路と同じ方法で	経路を混ぜると古い版が呼ばれ続けるため、導入時の仕組みで更新します。
社内導入で確認する点は？	通信の許可と参照範囲	配布元への接続許可を事前に調整し、鍵や接続情報は対象から外します。

この記事でわかること

• インストール前に決めておくべき環境・経路・認証方法の3点
• Mac・Windows・Linuxそれぞれの導入手順と、経路ごとの違い
• 認証の済ませ方と、正しく入ったかを確認する方法
• コマンドが見つからない、認証が終わらないといった症状への対処
• バージョンの更新、特定版への固定、削除の手順と業務導入時の確認事項

開発現場へのAI導入を検討している方へ 導入そのものは短時間で終わりますが、開発フローに定着させるには設計と教育が必要です。ネクストスケールでは、組み込み方の検討から社内ルールの整備、エンジニア向けの研修までを一貫して支援していますので、まずは無料相談をご利用ください。 ▶ 開発現場のAI活用について相談する

インストール前に決めておく3つのこと

作業に入る前に、方針を固めておきます。ここを決めずにコマンドを打ち始めると、後から切り分けが難しい状態になります。

動作させる環境を決める

macOSとLinuxであれば迷う余地はありません。判断が必要なのはWindowsで、ネイティブ環境で動かすか、WSL2の中で動かすかを先に決めます。

手軽に試したいだけならネイティブ環境で問題ありません。業務で継続的に使う、Linux系のツールを日常的に併用するといった場合は、WSL2のほうが安定した動作を期待できます。

避けたいのは両方に入れてしまう状態です。どちらのコマンドが動いているのか分からなくなり、認証やパスの問題が起きたときに原因を追えなくなります。

導入経路を決める

経路は主に3つあります。公式が配布するインストールスクリプトを実行する方法、パッケージ管理の仕組みから入れる方法、配布されている実行ファイルを取得する方法です。

Node.jsの環境をすでに持っているならnpmから、macOSでHomebrewを使っているならそちらから入れると、更新や削除も同じ仕組みで管理できます。環境に合わせて選ぶのが基本です。

開発環境をあまり触りたくない、あるいはNode.jsを入れていない場合は、公式のスクリプトが手数の少ない選択になります。

経路を1つに決めたら、その方法だけで導入から更新までを通します。途中で別の方法を試すと、どちらのコマンドが有効なのか分からなくなります。

認証方法を決める

契約中のアカウントでログインする方法と、APIキーを設定する方法の2択です。個人の開発で使うなら前者、自動化の仕組みに組み込むなら後者が基本になります。

前者は契約しているプランの枠内で使う形になり、追加の設定はほとんど必要ありません。後者は使った分だけ課金される形式で、鍵の管理方法もあわせて決めておく必要があります。

組織で使う場合は、どちらを標準にするかを事前に統一しておきます。担当者ごとに方式が異なると、利用状況の把握が難しくなります。

関連記事：Codex CLIとは？OpenAI発AIコーディングエージェントの特徴・使い方・料金を解説

事前準備｜動作環境の確認

方針が決まったら、環境側の条件を確認します。ここでの見落としが、後のエラーの大半を占めます。

対応するOSと必要な条件

macOS、Linux、Windowsに対応しています。Windowsについては、以前はWSL2が前提とされていましたが、現在はネイティブ環境でも動作する構成が用意されています。

ターミナルから操作するため、コマンドの実行に抵抗がないことが前提になります。画面上の操作で完結させたい場合は、デスクトップ向けの提供形態も用意されています。

インターネットへの接続は必須です。処理は外部のサービスと通信しながら進むため、通信ができない環境では動作しません。

利用にはアカウントが必要です。事前に登録を済ませておくと、導入後の認証で止まらずに進められます。

Node.jsの確認と導入

npmから入れる場合は、Node.jsのバージョンが要件を満たしているかを先に確認します。古い版が入っていると、インストールの途中で処理が止まります。

node -v と npm -v を実行して、表示される数値を確認します。要件を下回っている場合は、バージョン管理の仕組みを使うか、公式サイトから安定版を取得して更新します。

公式のスクリプトから入れる場合は、Node.jsは必須ではありません。環境を増やしたくない場合はこちらを選びます。

ネットワークの制限を確認する

社内のネットワークに制限がある環境では、配布元への接続が許可されているかを事前に確認します。許可されていないと、途中で処理が失敗します。

配布は公式のサーバーから行われ、状況によって別の場所が使われる構成になっています。許可リストを設定している場合は、どちらも登録しておくと接続の失敗を避けられます。

独自の証明書を使っている環境では、証明書の設定を先に済ませておきます。この設定が抜けていると、認証の段階で処理が進まなくなります。

関連記事：Codex CLIの使い方｜インストール手順と基本コマンド・承認モードの設定を解説

Macでのインストール手順

macOSでは3つの経路が使えます。どれを選んでも動作は同じで、違いは更新と削除の管理方法にあります。

公式のスクリプトから入れる

ターミナルで公式が案内しているスクリプトを実行する方法です。Node.jsやパッケージ管理の仕組みを用意していなくても導入できる点が利点になります。

実行すると必要なファイルが取得され、コマンドが使える状態になります。処理が終わったら、次の項目で説明する動作確認へ進みます。

導入先は利用者の領域に置かれるため、管理者権限は基本的に必要ありません。権限を求められる場合は、経路が想定と違っていないか確認します。

スクリプトを実行する前には、取得元が公式の案内どおりかを確認します。ネット上に転載された古いコマンドをそのまま使うと、意図しない場所から取得する可能性があります。

Homebrewから入れる

すでにHomebrewで開発環境を管理しているなら、この方法が扱いやすくなります。更新も削除も同じ仕組みで完結するため、環境の把握が楽になります。

brew install –cask codex のような形で導入します。導入後の更新は brew upgrade で行えるため、他のツールとまとめて管理できます。

すでにnpmで入れている状態でHomebrewからも入れると、両方が残ります。乗り換える場合は、先に元の経路から削除してから進めます。

npmから入れる

Node.jsの環境がある場合は、npm install -g @openai/codex を実行します。-g を付けることで、どのディレクトリからでもコマンドを呼び出せる状態になります。参考：npm公式パッケージページ（@openai/codex）

権限のエラーが出る場合は、管理者権限で実行するのではなく、Node.jsのバージョン管理の仕組みを使う構成に切り替えるほうが安全です。システム領域に直接書き込む運用は避けます。

導入の先にある活用設計をご相談ください コーディングエージェントは、開発フローのどこに置くかで効果が変わります。ネクストスケールでは、現在の開発体制をうかがったうえで、無理なく組み込める形と運用ルールをご提案しています。 ▶ 導入支援サービスの詳細を見る

関連記事：CodexはWindowsで使える?デスクトップアプリのインストール方法と使い方を解説

Windowsでのインストール手順

Windowsは選択肢が分かれるため、最初に決めた経路から外れないように進めることが重要です。

PowerShellから入れる場合

Windows標準のコマンド画面で、公式が案内しているコマンドを実行します。追加の環境を用意せずに始められるため、まず試したい場合に向いた方法です。

実行ポリシーの制限で処理が止まることがあります。公式の案内では、そのコマンドの実行時だけ制限を回避する形が示されているため、案内どおりの記述で実行します。

導入後は、PowerShellを開き直してからコマンドが認識されるかを確認します。開いたままの画面では、パスの変更が反映されない場合があります。

ネイティブ環境では、制限のかかった状態でコマンドが動く構成になっています。挙動が不安定に感じる場合は、WSL2での構成に切り替えて比較すると原因を絞れます。

WSL2で入れる場合

Windowsの中でLinux環境を動かし、その中に導入する方法です。Linux系のツールとの組み合わせが多い環境や、業務で継続的に使う場合はこちらが安定します。

WSL2が有効になっていない場合は、管理者権限のPowerShellから wsl –install を実行して有効化し、再起動します。その後はLinuxの手順と同じ流れで進められます。

導入もログインもLinux環境の中で行います。Windows側とLinux側の両方で作業すると、どちらに認証情報があるのか分からなくなります。

WSL2を使うときの注意点

扱うプロジェクトの置き場所に注意が必要です。Windows側のドライブを参照する経路にファイルを置くと、読み書きが遅くなり作業効率が落ちます。

Linux環境側のホームディレクトリにプロジェクトを配置するのが基本です。速度の差は、ファイル数が多いリポジトリほど大きくなります。

セキュリティ対策のソフトが常時監視している環境では、動作が重くなる場合があります。改善しないときは、対象から除外する設定を検討します。

Linuxでのインストール手順

Linuxでは公式のスクリプトかnpmを使う方法が中心です。手順そのものはmacOSとほぼ同じになります。

公式のスクリプトとnpmのどちらを選ぶか

Node.jsを使っていない環境であれば、公式のスクリプトが手数の少ない選択です。すでにNode.jsで開発している環境なら、npmから入れて他のツールとまとめて管理するほうが整理しやすくなります。

サーバー上で自動化の仕組みに組み込む場合も、npmから入れる形が扱いやすくなります。構築手順をスクリプトに残しやすいためです。

配布形態はディストリビューションを問わず共通です。特定の環境向けのパッケージを探す必要はありません。

権限まわりの注意

グローバルに導入する際、権限のエラーが出ることがあります。管理者権限で強引に実行するより、書き込み先を利用者の領域に変更する構成に切り替えるほうが安全です。

共有のサーバーに導入する場合は、他の利用者への影響も考慮します。利用者ごとに環境を分ける構成にしておくと、認証情報の混在も防げます。

インストール後の認証と動作確認

導入が終わったら、使える状態になっているかを確認してから作業に入ります。ここで確認しておくと、後の切り分けが楽になります。

バージョンを表示して確認する

最初に行うのは、コマンドが認識されるかの確認です。バージョンを表示するオプションを付けて実行し、数値が返ってくれば導入は成功しています。

何も表示されない、あるいはコマンドが見つからないと出る場合は、ターミナルを開き直してから再度試します。それでも解決しない場合は、後述する対処を確認します。

表示された版は控えておきます。不具合の報告や問い合わせを行う際に、環境を伝える情報として使えます。

認証を済ませる

ログイン用のコマンドを実行すると、ブラウザが開いて認証画面が表示されます。契約中のアカウントでログインすれば、その後は追加の操作なしで使えます。

画面のない環境や、ブラウザが自動で開かない環境では、コードを入力して認証する方式に切り替えます。この方式であれば、別の端末で認証を進められます。

APIキーを使う構成では、環境変数として設定します。鍵をソースコードに直接書き込む運用は避け、外部に流出しない形で管理します。

作業ディレクトリで起動する

起動したディレクトリが、参照と変更の対象になります。バージョン管理下にあるディレクトリで起動し、変更を元に戻せる状態を確保しておきます。

最初は範囲を絞り、読み取りだけの依頼から試します。挙動を把握してから変更を伴う作業に移る進め方が安全です。

初回の起動時には、そのフォルダでの作業を許可するかどうかの確認が表示されます。内容を読んだうえで選択します。

起動後の操作や承認モードの設定は、Codex CLIの使い方と基本コマンドで詳しく解説しています。

エンジニア向けのAI研修をご用意しています 導入しても、使い方が定まらないまま放置されるケースは少なくありません。ネクストスケールの研修では、実際のリポジトリを題材にした演習を通じて、開発チームが自走できる状態をつくります。 ▶ 法人向けAI研修の内容を確認する

インストールでつまずいたときの対処

起きやすい症状は限られています。原因の切り分け方を知っておけば、短時間で復旧できます。

コマンドが見つからないと表示される

最も多い症状です。多くの場合、導入したコマンドの場所がパスに反映されていないことが原因で、ターミナルを開き直すだけで解決します。

それでも解決しない場合は、コマンドの場所を確認する指令で導入先を調べます。想定と異なる場所に入っている、あるいは古い実行ファイルが残っている場合は、手動で整理します。

複数の経路で導入した場合は、どれか1つに絞ります。混在した状態のままでは、更新しても古い版が呼ばれ続けることがあります。

シェルの設定ファイルを編集している環境では、記述の順序によってパスが上書きされている場合もあります。設定を見直すと原因が見つかります。

認証が完了しない

ブラウザが開いても処理が戻ってこない場合は、コードを入力して認証する方式に切り替えると進むことがあります。画面のない環境でも同じ方法が使えます。

社内のプロキシや独自の証明書を使っている環境では、通信そのものが遮断されている可能性があります。証明書の設定を済ませてから再度試します。

WSL2を使っている場合は、Linux環境の中でログインしているかを確認します。Windows側で認証していると、Linux側からは認証済みとして扱われません。

インストール自体が失敗する

途中で処理が止まる場合は、バージョンの要件を満たしているか、配布元への通信が許可されているかの2点を確認します。

権限のエラーであれば、書き込み先を利用者の領域に変更する構成に切り替えます。管理者権限で強引に実行すると、後の更新で別の問題が起きやすくなります。

一時的な通信の不調で失敗する場合もあります。同じ手順を時間をおいて試すだけで通ることがあるため、設定を変える前に一度やり直します。

動作が重い、不安定になる

WSL2でWindows側のドライブにプロジェクトを置いていると、読み書きが遅くなります。Linux環境側にファイルを移すだけで改善するケースが多く見られます。

セキュリティ対策のソフトが常時監視している環境では、処理が重くなる場合があります。改善しない場合は、監視の対象から除外する設定を検討します。

設定ファイルが壊れている可能性もあります。挙動が明らかにおかしいときは、設定を初期の状態に戻して切り分けます。

アップデートとアンインストール

更新は頻繁に行われます。入れた経路と同じ方法で管理することが、混乱を避ける基本です。

バージョンの確認と更新

現在の版はバージョン表示のオプションで確認できます。新しい版では機能の追加や不具合の修正が入るため、動作がおかしいときはまず更新を試します。

一定の版からは、自身を更新するコマンドが用意されています。それ以前の版を使っている場合は、導入に使った仕組みから更新します。

npmから入れた場合は最新版を指定して再度導入し、Homebrewから入れた場合はアップグレードの指令を使います。経路を混ぜないことが重要です。

特定のバージョンに固定する

更新後に挙動が変わって困る場合は、版を指定して導入し直すことで以前の状態に戻せます。npmであれば版を明示して実行します。

チームで使う場合は、検証を終えた版に揃える運用も選べます。全員が同じ版を使っていれば、問題が起きたときの切り分けが容易になります。

固定したままにせず、定期的に検証と更新を行う周期を決めておきます。古い版を使い続けると、修正済みの不具合を踏み続けることになります。

アンインストールの手順

削除も、導入に使った仕組みから行います。npmであればグローバルから削除し、Homebrewやパッケージ管理の仕組みから入れた場合はそれぞれの削除指令を使います。

削除後も設定や認証情報が残る場合があります。完全に初期化したい場合は、利用者の領域に作られた設定用のディレクトリもあわせて整理します。

業務環境へ導入する際の確認事項

個人の環境と組織の環境では、確認すべき点が変わります。先に整理しておけば、導入後に差し戻しになる事態を避けられます。

ネットワークと証明書の設定

制限のある環境では、配布元と通信先の両方が許可されている必要があります。情報システム部門と事前に調整しておくほうが、個々の担当者が個別に対応するより早く進みます。

許可の設定に漏れがあると、明確なエラーにならず機能が一部だけ動かない状態になることがあります。導入後の動作確認では、通信を伴う処理まで含めて確かめておきます。

検証用の端末で先に導入を試し、必要な設定を洗い出してから展開すると、問い合わせの数を抑えられます。

認証方式と情報の取り扱い

参照させるディレクトリに、鍵や接続情報が含まれていないかを確認します。利用してよい範囲と、参照させてはいけない領域を先に定めておくことが前提です。

IPAは組織向けの脅威として人工知能の利用をめぐるリスクを上位に挙げ、利用者側での対策の必要性を示しています。参考：IPA「AI利用者のためのセキュリティ豆知識」

社内での基準の整え方は、生成AI利用時のセキュリティ対策で詳しく解説しています。

チームで手順を統一する

担当者ごとに導入経路が異なると、問題が起きたときの切り分けに時間がかかります。推奨する経路と版、認証方式を文書化して共有します。

自律的に作業を進める仕組み全般の考え方は、AIエージェントの仕組みと業務への活かし方で整理しています。

他のツールと併用する場合の役割分担は、AIツールの使い分けと選び方もあわせてご確認ください。

チーム全体で使い方の水準をそろえたい場合は、AI研修の選び方と導入手順が参考になります。自社での開発体制の見直しを含めて検討する段階であれば、AI受託開発の依頼先の選び方と費用相場もご覧ください。

まとめ

Codex CLIの導入でつまずかないための鍵は、動作環境、導入経路、認証方法の3点を先に決めることにあります。経路を混ぜないだけで、起きる問題の大半は避けられます。

macOSとLinuxは公式のスクリプトかパッケージ管理の仕組みから、Windowsはネイティブ環境かWSL2のどちらかを選んで進めます。導入後はバージョンを表示して確認し、認証を済ませてから作業用のディレクトリで起動します。

コマンドが見つからない場合はターミナルの開き直しとパスの確認、認証が進まない場合はコード入力方式への切り替えと証明書の設定を確認します。組織で導入する際は、通信の許可と参照範囲の基準を先に整えておくと、後の手戻りを防げます。

開発現場のAI活用を成果につなげませんか ネクストスケールは、法人企業向けにAI研修・システム開発・業務改革の支援を提供しています。ツールの導入から開発フローへの定着までを伴走します。現状の課題をうかがったうえでご提案しますので、まずはお気軽にご相談ください。 ▶ 無料相談・資料請求はこちら