Codex CLIとは何か｜Macのプロジェクトで動かすまで

「codex cli」で調べる人がいま知りたいのは、ターミナルで動くOpenAIのエージェントが自分のMacで何をしてくれるのか、入れるには何が要るのか、そして勝手にファイルを書き換えられないかという3点です。 インストール自体は1行で終わりますが、入れ方が4つあり、選び方によって更新のしかたも置き場所も変わります。 この記事では、Codex CLIの性質、Macで動かすまでの流れ、権限の初期値、そしてつまずきやすい場所を順に整理します。

Codex CLIは手元のリポジトリで動くエージェント

Codex CLIは、OpenAIが提供する、手元のコンピュータで動くコーディングエージェントです。 ブラウザで動くCodex cloudや、エディタに入れる拡張機能とは別の入口で、ターミナルで codex と打って起動します。 起動したフォルダのファイルを読み、編集し、そこにある開発ツールを実行しながら作業を進めます。

公式のドキュメントは、この道具の使い道を対話とスクリプトの両方に置いています。

Use Codex interactively or call codex exec from repeatable workflows and pipelines. 出典: learn.chatgpt.com

対話で使うときは、画面に出ているスラッシュコマンドが入口になります。 /init はそのプロジェクト向けの AGENTS.md を作り、次回以降のセッションで前提として読ませるファイルになります。 /status はいまのセッションの設定、/permissions は許可の範囲、/model はモデルと推論の強さを切り替えます。 /review は変更点を見て問題を指摘させるための入口です。

対話の外では、codex exec が非対話の実行にあたります。 CIや定時実行から呼べるので、コミット前の点検や、毎朝の差分要約のような定型作業に組み込めます。 過去のやり取りに戻りたいときは codex resume、画面のスクリーンショットを見せたいときは codex --image、最新の情報が要る調べ物では codex --search を使います。

Macで動かすまでに必要なもの

公式のインストール手順が挙げている条件は短く、macOS 12 以上、メモリは4GB以上（8GB推奨）、Gitは任意ですがプルリクエスト補助のために2.23以上が推奨、という内容です。 Node.js は、npmで入れる場合を除いて要りません。 本体はRustで書かれた実行ファイルとして配られるためです。

アカウントの側も先に確かめておきます。 OpenAIの料金ページでは、Codexは ChatGPT の Free、Go、Plus、Pro、Business、Edu、Enterprise の各プランに含まれ、上位のプランほど使える量が増える、と案内されています。 月額はGoが8ドル、Plusが20ドル、Proが100ドルからという表示です。 もう1つの経路がAPIキーで、この場合は通常のAPI料金で課金され、プランに含まれる枠は使いません。 公式は、APIキーでの認証はCIのような自動化に向くとしたうえで、クラウド連携の一部機能が使えなくなると書いています。

入れ方は4つ。混ぜないことが肝心

方法	コマンド	置き場所	更新のしかた
公式インストーラ	curl -fsSL https://chatgpt.com/codex/install.sh | sh	~/.local/bin	同じコマンドを再実行、または codex update
npm	npm install -g @openai/codex	npmのグローバル領域	同じコマンドを再実行
Homebrew	brew install --cask codex	Homebrewのbin	brew upgrade --cask codex
GitHubリリース	配布物を展開して置く	置いた場所	次の版を落とし直す

公式のクイックスタートが示すのは1行目のインストーラです。 実行ファイルを ~/.local/bin に置き、そのフォルダが PATH に入っていなければシェルの設定ファイルに追記します。

Homebrewで入れる場合、Codexはformulaではなくcaskとして配られています。 brew install codex では見つからず、brew install --cask codex と書く必要があります。 コマンドラインの道具はformulaが多いので、ここで引っかかる人がいます。

よくある混乱は、2つの入れ方が同居している状態です。 インストーラ自身も、管理された実体が複数あると PATH の順で動くものが決まるので曖昧になる、と警告を出します。 春にHomebrewで入れ、最近インストーラを使った、という状態だと実体が2つあり、更新したほうと動いているほうが食い違います。 which -a codex で実体の一覧を出し、要らないほうを消してから、新しいターミナルで codex --version を確かめてください。 設定と認証情報は ~/.codex にある config.toml などに入っており、実行ファイルを消しても残ります。

権限とサンドボックスの初期値を知っておく

インストールと同じくらい大事なのが、エージェントに何を許すかです。 公式のセキュリティ解説によると、ローカルで動くCodexは既定でネットワークを遮断し、書き込みできる範囲を作業中のワークスペースに限定します。 この制限はモデルの判断ではなく、OSの仕組みで強制されます。

既定のAutoの組み合わせでは、作業フォルダの中でファイルを読み、編集し、コマンドを実行するところまでは自動で進みます。 そのうえで、ワークスペースの外を編集するときや、ネットワークを使うコマンドを実行するときには確認を求めます。 読むだけ・考えるだけにしたいときは /permissions から read-only に切り替えます。 知らないリポジトリを最初に眺めるときは、この形から入ると安全です。

古い記事を参考にする人が引っかかるのが、廃止された設定です。 approval_policy = "untrusted" は既に廃止されており、~/.codex/config.toml に残っているとCodexが起動しないことがある、と公式に明記されています。 対話で読むだけの運用に置き換えるなら、sandbox_mode = "read-only" と approval_policy = "on-request" の組み合わせ、またはコマンドラインで codex --sandbox read-only --ask-for-approval on-request です。 入れ直しても起動しないときは、実行ファイルではなく設定ファイルを先に疑ってください。

最初の1回をどう進めるか

入れ終わったら、ホームフォルダではなくプロジェクトのフォルダに入って codex と打ちます。 初回はサインインの選択が出るので、ChatGPTのアカウントで入るか、APIキーを使うかを選びます。 ブラウザが開いて認証が終わると、資格情報が保存され、次回からは選択を求められません。 プロンプトが出ないときは codex login を直接実行します。

最初の依頼は、変更を伴わないものから始めると様子がつかめます。 「このプロジェクトの構成を説明して」「テストはどのコマンドで走るか」といった問いなら、読むだけで答えが返ります。 そのうえで /init を実行し、AGENTS.md にプロジェクトの前提を書き出しておくと、次のセッションからは説明の手間が減ります。 書く内容は、ビルドとテストのコマンド、触ってはいけない生成物の場所、命名や書式の決まりなど、毎回言い直している事柄です。

公式のクイックスタートは、もう1つ習慣を勧めています。 作業の前後にGitのチェックポイントを作っておくことです。 こうしておけば、結果が気に入らないときに1コマンドで戻せます。 エージェントに元へ戻させるより速く、確実です。

つまずきやすい場所

• command not found: codex は、ほぼ PATH の問題です。インストーラで入れたなら実体は ~/.local/bin/codex にあります。新しいターミナルを開くか、export PATH="$HOME/.local/bin:$PATH" を実行し、同じ行を ~/.zshrc にも書いておきます
• npmで入れた場合は npm prefix -g で場所を確かめます。Nodeのバージョン管理ツールを使っていると、入れたときのバージョンでないとコマンドが見えません
• ブラウザでGitHubのリリースから落とした実行ファイルは、macOSの検疫属性が付いていて起動を止められます。xattr -d com.apple.quarantine ./codex で外すか、システム設定のプライバシーとセキュリティから許可します
• 起動はするが様子がおかしいときは codex doctor を実行します。インストール、設定、認証、実行環境、Git、ターミナルの状態を診断レポートにまとめてくれます
• ログインの状態は codex login status、認証を消すのは codex logout です。APIキーで入るときは printenv OPENAI_API_KEY | codex login --with-api-key のように標準入力から渡すと、シェルの履歴にキーが残りません

起動するフォルダが作業の質を決める

Codex CLIは起動したフォルダを基準に動きます。 AGENTS.md はそのフォルダから読み、書き込みを許す範囲もそのフォルダで決まり、codex resume が出す履歴もリポジトリ単位です。 ホームフォルダで起動すれば、プロジェクトの前提を持たないまま考え始め、書き込みの範囲も意図しない場所になります。

毎日の手間は、この「目的のフォルダまで降りる」部分に集まります。 Finderで場所を探し、ターミナルを開き、同じパスへ移動してから起動する、という往復が毎回入るからです。 フォルダとターミナルとAIが同じ窓にある作りのファイル管理アプリなら、いま見ているフォルダでそのまま codex を起動できます。 何ができるかはできることに、ほかのファイル管理アプリとの違いは他のファイル管理との比較にまとめています。 料金の考え方は料金、残りの疑問はよくある質問で確かめられます。

エージェントが確認を求めて止まっているとき、Macの前を離れていると作業が進みません。 外出先から続きを返す方法はiPhone・iPadから続きをで説明しています。