この記事でわかること
- Codexを最初に動かす順番:入口を1つ決める→インストール→ChatGPTでサインイン→読むだけの依頼→1ファイルの編集→
git diffで確かめて取り込むか捨てる - 「壊されないか」への答え:最初は
read-onlyで読ませ、編集はGitで戻せるリポジトリの中だけで頼む - Ubuntu 24.04系で
bwrap: loopback: Failed RTM_NEWADDRやbwrap: setting up uid map: Permission deniedが出て何もできないときの原因と、公式の対処 codexコマンドが見つからないのに、VS Code拡張ではCodexが動いている状態の見分け方- AGENTS.mdの置き場所と32 KiBの上限、手持ちのCLAUDE.mdをCodexに読ませる設定
この記事では、入口を1つに絞り、最初の依頼を「読むだけ」にして、インストールから最初の差分の取り込みまでを順番に説明します。筆者の環境(AppArmorで非特権のユーザー名前空間が制限されたUbuntu系)で止まったのは2か所でした。1つはLinuxのサンドボックス(bubblewrap)でbwrapのエラーが出て、AppArmorの制限の関与が疑われた件、もう1つはVS Code拡張だけを入れていてcodexコマンドがPATHに無かった件です。1つ目のAppArmorの件はLinux向けの話です。WindowsでもWSL2で動かす場合はLinuxのサンドボックス実装が使われるので、Linux側の条件を確かめてください。
この記事は手順と対処に絞ります。Codexの定義や5つの入口の比較は「Codexとは」に、料金の詳細は「Codex料金」に任せます。
1. 検証環境と、この記事で測れたもの・測れなかったもの
| 項目 | 値 |
|---|---|
| 機材 | DGX Spark(NVIDIA GB10、統合メモリ128GB、ARM64/aarch64) |
| GPU / VRAM | 使わない。この記事の構成(OpenAIのモデルをChatGPTアカウントかAPIキー経由で呼び出す)では、Codexは手元で動くが手元のGPUは使わない(筆者の理解) |
| OS | Ubuntu 24.04系(既存記事の記録)、カーネル 6.14.0-1015-nvidia(2026-11-15確認) |
| Codex CLIの版 | 0.164.0-alpha.11.1(運用ドキュメントの2026-11-01時点の記録)。VS Code拡張に同梱された版 |
| 設定ファイルのモデル | ~/.codex/config.tomlにmodel = "gpt-6.1-sol"、model_reasoning_effort = "ultra"(筆者が変更した値で、既定値ではない) |
| AppArmorの設定 | kernel.apparmor_restrict_unprivileged_userns=1(運用リポジトリのメモに記録) |
| 公式文書の確認日 | 2026-11-15 |
先に、測れなかったものを書きます。この記事の執筆セッションにはシェルを実行する手段が無く、新しくインストールし直して時間を計ることはできませんでした。そのため、最初の依頼の所要時間・承認を求められた回数・差分の行数は「未取得」です。推定値は置きません。
代わりに使ったのは、同じ機材の~/.codex/sessions/に残っていた実行記録(JSONL)です。2026年6月から11月までのセッションから、版・サンドボックスの設定・実際に出たエラー文言を拾いました。Windows と macOS は手元で測っていないため、公式の記述を引くだけにします。
2. Codexを一言で
Codexは、OpenAIのAIコーディングエージェントです。手元のファイルを読み、コマンドを実行し、コードを書き換えます。CLI本体はApache-2.0のオープンソースです(GitHub openai/codex 2026-11-15確認)。
定義、CLI・IDE拡張・cloud・アプリ・SDKの違い、手元45リポジトリの棚卸しは「Codexとは」で扱っています。
3. 第1章 入口を1つ決める
最初は、CLIかVS Code拡張のどちらか1つにします。両方を同時に入れると、どちらの設定で動いているのかが分かりにくくなります。
| こういう人は | 入口 | 理由 |
|---|---|---|
| ふだんターミナルで作業する、スクリプトから呼びたい | CLI | codexコマンドがPATHに入り、codex execで非対話実行もできる |
| ふだんVS Code・Cursor・Windsurfで書いている | IDE拡張 | エディタの横で差分を見ながら進められる |
IDE拡張が対応するのは、VS Codeと互換エディタ(Cursor・Windsurf)です。XcodeとJetBrains IDEには別の統合があります(OpenAI Codex IDE docs 2026-11-15確認)。
注意点が1つあります。筆者の環境ではIDE拡張だけを入れていたため、拡張同梱の実行ファイルにPATHが通っておらず、ターミナルからcodexとは打てませんでした。ターミナルやスクリプトでも使う予定なら、最初からCLIを入れておくほうが扱いやすいです。
4. 第2章 インストールとサインイン
CLIを入れる手順
- インストールする。公式READMEに載っている経路は4つです(GitHub openai/codex 2026-11-15確認)。macOS・Linuxでは、公式が案内する方法の1つとしてインストールスクリプトがあります。
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Node.jsが入っている環境ならnpmでも入ります。
npm install -g @openai/codex
macOSのHomebrewなら次のとおりです。
brew install --cask codex
GitHub Releasesのバイナリを使う場合、LinuxのARM64はcodex-aarch64-unknown-linux-musl.tar.gz、x86_64はcodex-x86_64-unknown-linux-musl.tar.gzです。展開すると名前にプラットフォームが付いた実行ファイルが1つ出るので、codexに名前を変えてPATHの通った場所に置きます。インストールスクリプトは既定でreleases.openai.comから取得し、失敗するとGitHub Releasesに切り替えます(同README)。
Windowsは公式READMEにPowerShellの1行がありますが、手元では未検証です。
- 入ったかを確かめる。
command -v codex
codex --version
成功すると、1行目は実行ファイルのパス、2行目は版番号を返します。1行目が何も返さないなら、PATHに入っていません。対処は第8章の表にまとめました。
- 作業するリポジトリに移って起動する。
cd ~/work/sample-repo
git status
codex
先にgit statusを打つのは、作業前の状態を確かめておくためです。未コミットの変更があるなら、先にコミットしておくと後で差分を見分けやすくなります。公式のIDE文書も、タスクの前後でGitのチェックポイントを作ることを勧めています(OpenAI Codex IDE docs 2026-11-15確認)。
- サインインする。初回の起動で「Sign in with ChatGPT」を選ぶと、ブラウザでChatGPTアカウントの認証に進みます。READMEはPlus・Pro・Business・Edu・Enterpriseの利用者にこの方法を勧めています。APIキーでも使えますが、READMEには「追加の設定が要る」とあります(GitHub openai/codex 2026-11-15確認)。
APIキーで使うと、ChatGPTの契約に含まれる利用枠ではなくAPI料金で課金されます。OPENAI_API_KEYを設定したままサインインした場合にどちらの認証が使われるかは、今回は確かめられていません。迷ったら、最初の1回は環境変数を外した状態で始めるのが確実です。
VS Code拡張を入れる手順
- VS CodeのMarketplaceで
openai.chatgptを入れる(Visual Studio Marketplace)。CursorとWindsurfには公式文書からのディープリンクがあります。 - サイドバーのCodexアイコンを開く。見当たらなければ、コマンドパレットで「Codex: Open Codex Sidebar」を実行します(OpenAI Codex IDE docs 2026-11-15確認)。
- ChatGPTアカウントでサインインする。
5. 第3章 最初の依頼は読むだけにする
最初の依頼は、ファイルを書き換えない内容にします。codex --sandbox read-onlyで起動すると、Codexはファイルを読み、読み取り専用のサンドボックスの中でコマンドを実行できますが、ファイルは書き換えられません(OpenAI approvals & security docs 2026-11-15確認)。
codex --sandbox read-only
起動したら、次のように頼みます。
このリポジトリの構成を、ディレクトリごとに1行で説明してください。テストの実行方法が書かれている場所があれば、そのファイル名も挙げてください。ファイルは変更しないでください。
読むだけの依頼には、3つの目的があります。サインインと通信が通っているかの確認、Codexがどのファイルを読みに行くかの観察、そしてAGENTS.mdが読まれているかの確認です。AGENTS.mdについては第6章で扱います。
成功していれば、ディレクトリの説明と、Codexが実行した読み取りのコマンド(ファイル一覧や中身の表示)が順に表示されます。どのコマンドも動かずにエラーで終わる場合は、第8章の表のbwrapの行を見てください。
非対話で1回だけ投げることもできます。スクリプトから呼ぶ場合はこちらです。
codex exec --sandbox read-only "List the top-level directories and describe each in one line. Do not modify files."
所要時間の実測は、「1. 検証環境」の節に書いた理由で今回は未取得です。
6. 第4章 1ファイルを直させて差分を確かめる
手順
- 対象を1ファイルに絞って頼む。
README.md のインストール手順の節だけを直してください。コマンドの誤字があれば修正し、それ以外のファイルは変更しないでください。
- このときはサンドボックスを
workspace-write、承認をon-requestにして起動します。公式のsandboxingページが、ローカル作業での低リスクな組み合わせとして挙げている設定です(OpenAI sandboxing docs 2026-11-15確認)。
codex --sandbox workspace-write --ask-for-approval on-request
- Codexが作業範囲を越える操作をしようとすると、主にその実行前に承認を求めて止まります。何をしようとしているかを読んでから許可します。作業範囲の中の編集は、承認を待たずにファイルへ書き込まれます。
- 終わったら、差分を確かめる。
git diff --stat
git diff
--statで変更されたファイルと行数を、続けて中身を見ます。頼んだ1ファイル以外が変わっていたら、まずその理由をCodexに聞きます。
- 取り込むか捨てるかを決める。
git add README.md
git commit -m "docs: fix install commands in README"
捨てる場合は次のとおりです。
git restore README.md
Codexが新しいファイルを作っていた場合、git restoreでは消えません。git statusで未追跡ファイルを確かめ、要らなければ手で削除します。
「壊されないか」への答え
壊れても戻せる状態で頼む、がいちばん確実な防ぎ方です。Gitで管理しているリポジトリの中で、コミット済みの状態から始めれば、追跡済みファイルへの変更はgit diffに、新しく作られたファイルはgit statusに出ます。ただし、Gitで管理していない場所への変更はこの確認に含まれません。逆に、Gitで管理していないフォルダやホームディレクトリ直下でworkspace-writeを使うと、何が変わったかを後から追えません。
7. 第5章 承認モードとサンドボックスの選び方
公式のsandboxingページは、サンドボックスが技術的な境界を決め、承認ポリシーがいつ止まって確認を求めるかを決める、と説明しています(OpenAI sandboxing docs 2026-11-15確認)。
| サンドボックス | できること | 使う場面 |
|---|---|---|
read-only | ファイルは書き換えない。サンドボックス内のコマンドは実行できる | 最初の依頼、コードを読ませるだけのとき |
workspace-write | 作業範囲(workspace。現在のディレクトリや/tmpなどの一時ディレクトリ)の中は書ける。公式文書はローカル作業の既定と説明 | ふだんの編集 |
danger-full-access | サンドボックスの制限なし | 使い捨てのVMやコンテナの中だけ |
| 承認ポリシー | 動き |
|---|---|
on-request | 主にサンドボックスの外に出る操作の前に止まって確認を求める |
never | 承認を求めて止まらない(公式文書の説明)。承認ポリシーとサンドボックスは別の設定なので、neverにしてもサンドボックスの設定自体は変わらない(筆者の整理) |
untrustedは、現在のCodexでは選べない値になったと公式文書に書かれています(同ページ)。CLIの会話中に/permissionsと打つと、権限を選び直す画面が開きます。
danger-full-accessとneverを組み合わせると、通常の承認の確認もサンドボックスの境界も無い状態でコマンドが走ります。公式文書に載っている組み合わせではありますが、手元の作業用マシンで常用するものではありません。
実行記録から見えた「全権限への逃げ」
2026年11月時点の運用メモでは、danger-full-accessで起動する運用になっていました。理由は第8章のbwrapのエラーです。
Codexをレビュアーとして呼ぶ自動化リポジトリの運用メモにも、「workspace-writeのサンドボックス(bwrap)はkernel.apparmor_restrict_unprivileged_userns=1のため必ず失敗する」「-s danger-full-accessで起動する」と書かれていました。動かすために全権限へ逃げる運用が、実際に定着していたことになります。これは推奨できる形ではありません。第8章の公式の対処を先に試すのが順番です。
8. 第6章 AGENTS.mdで毎回の説明を省く
テストの実行方法やコーディング規約を毎回書かずに済ませるには、リポジトリにAGENTS.mdを置きます。公式文書の読み込み規則は次のとおりです(OpenAI AGENTS.md docs 2026-11-15確認)。
- まず
~/.codex(CODEX_HOMEを設定していればそこ)を見る。AGENTS.override.mdがあればそれを、無ければAGENTS.mdを読む。この階層で使うのは最初の空でない1本だけ - 次にプロジェクトのルート(通常はGitのルート)から、今いるディレクトリまで順に下りる。各ディレクトリで
AGENTS.override.md→AGENTS.md→project_doc_fallback_filenamesに挙げた名前の順に探し、1ディレクトリにつき1本まで読む - 読んだファイルはルート側から順に連結される。今いるディレクトリに近いものほど後に来て、前の指示を上書きする
- 空のファイルは飛ばす。合計が
project_doc_max_bytes(既定32 KiB)に達した時点で読むのをやめる。公開されている実装では、この上限はプロジェクト側の指示ファイルに対するもので、上限をまたぐファイルは残りの分だけ読まれる(openai/codex agents_md.rs)
最初のAGENTS.mdは短くて構いません。たとえば次の3行です。
# AGENTS.md
- Run tests with: pytest -q
- Do not edit files under vendor/
- Write commit messages in English
手元のCLAUDE.mdをCodexに読ませる
Claude Code用のCLAUDE.mdがすでにあるなら、~/.codex/config.tomlにフォールバックのファイル名として追加します。公式文書の書式に合わせると次のとおりです。
project_doc_fallback_filenames = ["CLAUDE.md"]
AGENTS.mdが無いディレクトリでは、CLAUDE.mdが代わりに読まれます。同じディレクトリに両方あるなら、AGENTS.mdが優先です。
読まれたかを確かめるには、公式文書にあるとおり、現在の指示を要約させます。
codex --ask-for-approval never "Summarize the current instructions."
公式文書はこの要約コマンドでの確認方法を示し、読み込まれたファイルを監査したい場合はcodex -c log_dir=./.codex-logで起動して./.codex-log/codex-tui.logを確認するよう案内しています(OpenAI AGENTS.md docs 2026-11-15確認)。筆者の環境では、この設定を新しく入れて確かめる作業は今回できていません。CLAUDE.mdとAGENTS.mdの違いと、手元30本での棚卸しは「CodexとClaude Codeの比較」にまとめています。
なお、~/.codex/AGENTS.mdが空のファイルとして置かれている場合、空のファイルは飛ばされるので影響しません。
9. 第7章 手元の実行記録のまとめ
最初の依頼の所要時間・承認回数・差分行数は、前述のとおり未取得です。
10. 第8章 止まったときの対処(表示された文言別)
この表には、筆者の環境で実際に出た文言だけを入れました。
| 表示された文言・状態 | 原因 | 対処 | 出典 |
|---|---|---|---|
bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted | 公式文書によると、Ubuntu 24.04ではAppArmorが非特権のユーザー名前空間を制限しているため、bubblewrapが必要な名前空間を作れないことがある。筆者の環境で出たこのエラーもこれに該当するとみられる(筆者の推測) | 下のAppArmorプロファイルを読み込む | 手元の記録(2026-06-14・08-04)、sandboxing docs |
bwrap: setting up uid map: Permission denied | 同上とみられる(筆者の推測)。network_accessを有効にした場合にこちらが出た | 同上 | 手元の記録(2026-08-04)、同上 |
command -v codexが何も返さないのに、VS Code拡張ではCodexが動く | 現在のシェルからcodexを見つけられていない。筆者の環境では、拡張に同梱された実行ファイルだけが入っていてPATHに無かった。CLIが入っていてもPATHの設定漏れで同じ状態になりうる | 第2章の手順でCLIを別に入れる。スクリプトでは拡張内のパスを固定で書かない(拡張の更新でパスが変わる) | 手元の記録、運用メモ |
Ubuntu 24.04のbwrapの対処
まず、制限が有効かを確かめます。
sysctl kernel.apparmor_restrict_unprivileged_userns
= 1と出れば有効です。公式の対処は、bubblewrapが導入済みであることが前提です。先にcommand -v bwrapで入っているかを確かめてください。そのうえで、公式のsandboxingページは、bubblewrap用のAppArmorプロファイルを読み込む方法を示しています(OpenAI sandboxing docs 2026-11-15確認)。
sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
/usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
/etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict
apparmor_parser -rは再起動なしでプロファイルを読み込みます。代わりにsudo systemctl reload apparmor.serviceでもよいとされています。Ubuntu 25.04では、このプロファイルがapparmorパッケージに含まれています(同ページ)。
公式文書は最後の手段としてsudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0も挙げています。ただしこれはシステム全体の制限を外すため、プロファイルを読み込む方法を優先するよう書かれています。
筆者の環境では、このプロファイルの読み込みをまだ試していません。運用は第5章のとおりdanger-full-accessに逃げたままです。試した結果は、この記事の更新で追記します。
danger-full-accessに逃げる運用を勧めない理由は、Codexが実行するコマンドに、作業中のリポジトリの外への書き込みとネットワークの境界が無くなるからです。読み込んだファイルに悪意ある指示が紛れていた場合に、サンドボックスの境界による歯止めが効かなくなります。
11. 第9章 料金と上限(要点のみ)
公式の料金ページは、CodexがChatGPTのFree・Go・Plus・Pro・Business・Edu・Enterpriseの各プランに含まれると書いています。Plusの欄には、web・CLI・IDE拡張・iOSでCodexを使えると明記されています(OpenAI Codex pricing 2026-11-15確認)。プランごとに使える入口の違いは、料金記事で表にしています。
上限について押さえる点は3つです。
- PlusとStandard Businessには5時間ごとの枠があり、週の上限がかかる場合もある。Proには現在5時間の上限が無いと書かれている
- 残りは、CLIの会話中に
/statusと打つか、https://chatgpt.com/codex/settings/usageの使用量画面で確かめる - 上限に達したら、PlusとProは追加のクレジットを購入でき、APIキーを使えば標準のAPI料金で引き続き使える
(いずれもOpenAI Codex pricing 2026-11-15確認)。5時間あたりのメッセージ数はモデルによって桁が変わります。数字とクレジットの換算は「Codex料金」を見てください。
12. 第10章 用途別の頼み方の例
依頼文は、対象・やること・やらないことの3つを書くと、差分が小さくまとまります。
コードを読ませる(read-onlyで)
src/auth/ の処理の流れを、関数名を挙げて上から順に説明してください。ファイルは変更しないでください。
テストを足す
tests/test_parser.py に、空文字列を渡したときのテストを1つ追加してください。テストを実行して結果を報告してください。src/ は変更しないでください。
小さなリファクタ
utils/date.py の重複している日付の整形処理を1つの関数にまとめてください。外から呼ばれる関数名は変えないでください。変更後にテストを実行してください。
バグを再現させる
引数に負の数を渡すと calc_total が例外を出すと報告がありました。再現するテストを先に書き、失敗することを確かめてから修正案を説明してください。修正はまだしないでください。
最後の例のように、修正の前で止めるよう頼むと、差分を見る前に方針を確かめられます。
13. 第11章 注意点とセキュリティ
- 手元のGPUは使わない:この記事の構成(OpenAIのモデルをChatGPTアカウントかAPIキー経由で呼び出す)では、Codexは手元で動きますが手元のGPUは使いません(筆者の理解)
- 秘密情報:
.envや鍵ファイルがあるリポジトリでは、それを読ませない指示をAGENTS.mdに書き、コミット対象からも外しておきます。ただしAGENTS.mdはあくまで指示で、読み取りを技術的に防ぐものではありません。.gitignoreもアクセス制御ではありません - 全権限モード:
danger-full-accessは使い捨てのVMやコンテナの中に限ります。第8章のとおり、Linuxで起動できないことが理由なら、先にAppArmorの対処を試します - 作業範囲内の書き込みは承認を待たない:
on-requestで止まるのは主にサンドボックスの外に出る操作です。作業範囲の中の編集は先にファイルへ書き込まれるので、確認はgit diffで行います
14. よくある質問
Codexは無料で使えますか
公式の料金ページは、ChatGPTのFreeプランにもCodexが含まれると書いています(2026-11-15確認)。ただしFreeとGoの欄に書かれているのは「デスクトップアプリでGPT-6 LunaをStandard速度で使える(順次展開)」の1行だけで、CLIは挙がっていません。web・CLI・IDE拡張・iOSが明記されているのはPlusからです。この記事の手順どおりCLIで進めるなら、Plus以上のプランかAPIキーを用意するのが確実です。CLI本体はApache-2.0で入手は無料ですが、動かすにはサインインかAPIキーが要ります。
GPUが無いPCでも使えますか
使えます。この記事の構成(OpenAIのモデルをChatGPTアカウントかAPIキー経由で呼び出す)では、Codexは手元で動きますが手元のGPUは使いません(筆者の理解)。
CLIとVS Code拡張の両方を入れても問題ありませんか
両方入れても動きます。最初はどちらか1つで手順を通してから、もう一方を足すと切り分けが楽です。
WindowsやmacOSでも同じ手順ですか
macOSはインストールスクリプトかHomebrewで入り、手順の流れは同じです。Windowsは公式READMEにPowerShellのインストール手順があります。どちらも手元では検証していません。bwrapとAppArmorの件はLinux向けの話ですが、WindowsでもWSL2ではLinuxのサンドボックス実装が使われます(OpenAI approvals & security docs 2026-11-15確認)。
15. まとめ
- 入口はCLIかVS Code拡張の1つに絞り、ChatGPTアカウントでサインインします
- 最初の依頼は
read-onlyで読むだけにし、次に1ファイルの編集をworkspace-writeとon-requestで頼み、git diffで確かめて取り込むか捨てます - Ubuntu 24.04系で
bwrap:から始まるエラーが出たら、danger-full-accessに逃げる前に、AppArmorのbwrap-userns-restrictプロファイルを読み込みます codexが見つからないのに拡張は動くなら、現在のシェルからCLIを見つけられていません。未導入かPATHの設定漏れかを切り分け、スクリプトで使うならCLIを入れてPATHを通します- プロジェクトの決まりはAGENTS.mdに書き、既存のCLAUDE.mdは
project_doc_fallback_filenamesで読ませられます
16. 関連記事
- Codexとは──5つの入口と実行環境の選択:定義と入口の比較はこちら
- Codex料金──プラン別の上限とクレジット(購入価格はプランや契約次第と公式は説明):プラン別の上限とクレジットの詳細
- CodexとClaude Codeの比較──AGENTS.mdとCLAUDE.mdの読まれ方:指示ファイルの違いと使い分け
- Claude Codeの使い方:Claude Code側の導入手順を並べて読む場合に