Codex — OpenAI のコーディングエージェント
プロジェクトのフォルダーで codex と入力すると始まります。プロジェクトを読み、ファイルを編集し、コマンドを実行して自分の作業を確かめます。このページではインストールと最初の実行を案内し、詳しい内容は 講座の章につなぎます。
基礎 — インストールして最初の作業をする
初めてならここから始めましょう。Codex が何かを知り、インストールして、最初の 5 つのステップをたどります。すべて終えたら、上の [中級] タブに進んでください。
どんなものか
Codex は OpenAI のです。(Codex )、の拡張機能、ChatGPT アプリで動きます。codex を使えば、クラウド環境に作業を任せ、その結果を自分のコンピューターに適用することもできます。
プロジェクトのルールは AGENTS.md に書きます。AGENTS.md は多くのコーディングエージェントが読むオープンな形式です。Codex に何を許すかは /permissions で決めます。
必要なもの
- アカウント：ChatGPT でサインインします(Plus・Pro・Business・Edu・Enterprise プラン)。API キーでもサインインできますが、追加の設定が必要です。
- コンピューター：macOS または Linux(インストールスクリプト)、または Windows(PowerShell のインストールスクリプト)。npm や Homebrew でもインストールできます。
- 作業するプロジェクトのフォルダー — すべての変更を見直して元に戻せるよう、Git リポジトリが理想です。
インストール
macOS と Linux では 1 行目を、Windows では PowerShell の行を実行してください。スクリプトでインストールした場合は、同じコマンドをもう一度実行すると更新されます。
- macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh- Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"- npm
npm install -g @openai/codex- Homebrew
brew install --cask codex
インストールを確かめる
新しいターミナルウィンドウを開きます。codex --version でバージョン番号が表示されれば大丈夫です。“command not found” と出たら、ターミナルを開き直して PATH を確認してください。
codex --version
最初の実行 — 5 つのステップ
- プロジェクトのフォルダーに移動して codex を実行し、“Sign in with ChatGPT” を選びます。
- 「このプロジェクトについて教えて」と聞いて、プロジェクトを読ませます。
- /init で AGENTS.md を作り、テストのコマンドと守るべきルールを書きます。
- /permissions で、Codex が聞かずにしてよいことを決めます。
- ファイル・動作・確かめ方をはっきり書いて作業を頼みます。 を読み、テストを自分で実行してからします。
よく使う機能
- AGENTS.md — セッションごとに読まれるプロジェクトの指示(/init で始める)
- /permissions — ファイルの編集やコマンドの実行をどこまで許すか
- codex exec "…" — チャット画面なしで実行(スクリプトやパイプライン向け)
- codex cloud — クラウド環境に作業を任せ、結果を手元に適用する
- コードエディターの拡張機能と ChatGPT アプリ — 同じ Codex をほかの場所で
- エージェントスキル — .agents/skills/ の SKILL.md フォルダーでくり返す作業を教える
安全に使う
- 頼んだ以上に変更したら止めさせ、git restore で元に戻し、正確なファイル名を挙げてもう一度頼みます。
- テストに通っても diff を読み、自分が理解したものだけをコミットします。
- 大きな作業は、まず計画を出してもらい、小さく分けて任せます。
SONUB でもっと学ぶ
公式ドキュメント
2026-10-18 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。
中級 — 毎日の習慣：AGENTS.md・承認とサンドボックス・コマンド
インストールして最初の作業も済んだら、毎日使う習慣を身につけましょう。AGENTS.md を上手に書き、Claude Code などの別の と同じ指示を共有し、承認とサンドボックスでどこまで任せるかを決め、チャットのコマンドと上手な頼み方を学びます。
AGENTS.md を上手に書く
Codex は作業を始めるときに AGENTS.md を読みます。まずあなたのグローバルファイル(~/.codex/AGENTS.md)を読み、次にプロジェクトの一番上(ふつうは の一番上)から今のフォルダーまで下りながら、フォルダーごとにファイルを一つ見つけて順番につなげます。今のフォルダーに近いファイルほど後に来るので、そちらが優先されます。
- ~/.codex/AGENTS.md — すべてのプロジェクトで使う自分の指示
- プロジェクトの一番上の AGENTS.md — チームで共有する指示(コミットする)
- サブフォルダーの AGENTS.md — そのフォルダーで作業するときだけ足される指示
- AGENTS.override.md — 同じフォルダーにあれば AGENTS.md の代わりに読まれます(しばらく変更を試すとき用)。
- 初期設定では合計 32 KiB までしか読まれません(project_doc_max_bytes)。別の名前のファイルを使うには project_doc_fallback_filenames に書きます。
# AGENTS.md
## Setup
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint
## Code style
- TypeScript strict mode, single quotes.
- Keep functions small. Add a test for every bug fix.
## Don't
- Don't edit generated files in dist/.
- Don't commit .env files.
~/.codex/AGENTS.md ← you, every project (read first)
my-project/AGENTS.md ← team rules (commit it)
my-project/web/AGENTS.md ← only for web/ (read last, so it wins)
/init はプロジェクトを読んで最初の AGENTS.md を書きます。AGENTS.md は実行ごとに一度だけ読まれるので、編集したら Codex を再起動してください。
承認とサンドボックス — どこまで任せるか
Codex は二つの方法で安全を守ります。サンドボックスは技術的に何ができるか(ファイルの書き込み、ネットワーク)を決め、承認ポリシーはいつあなたに聞くかを決めます。二つを一緒に選びましょう。
- read-only — 読むだけで何も変えません。よく知らないプロジェクトを見て回るときに使います。
- workspace-write — 作業フォルダーの中でだけ編集し、コマンドを実行します。Git リポジトリでは初期設定が「Auto」で、これと on-request の組み合わせです。ネットワークは初期設定でオフで、.git・.codex・.agents には書き込めません。
- danger-full-access — サンドボックスなしで、何でもできます。隔離されたコンテナーの中でだけ使ってください。
- 承認ポリシー(-a): on-request はサンドボックスの外に出る必要があるときに聞き、never は聞きません(サンドボックスの中でだけ働きます)。
- /permissions で会話の途中にモードを切り替え、/status で今の設定を見ます。
codex --sandbox read-only # look only, change nothing
codex --sandbox workspace-write # edit inside this folder ("Auto" in a Git repo)
codex -a never --sandbox workspace-write # never ask, but stay inside the sandbox
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
古い記事にある --full-auto はもうありません。同じことには --sandbox workspace-write を使います。--yolo(--dangerously-bypass-approvals-and-sandbox)はサンドボックスと承認の両方をオフにするので、隔離された場所でだけ使ってください。
チャット画面のコマンド
Codex のチャット画面で / を入力すると、コマンドの一覧が出ます。毎日使うものから覚えましょう。
- /model — モデルと、どれだけ深く考えるか(reasoning effort)を選びます。
- /diff — このセッションで変わったファイルを見ます。/review — 変わったコードをレビューさせます。
- /compact — 会話を要約して空きを作ります。/new — 新しい会話を始めます。
- /resume — 前の会話を選んで続けます。ターミナルでは codex resume または codex resume --last。
- /status — モデル・権限・作業フォルダーなど今の設定を見ます。/mcp — つながっている MCP サーバーを見ます。
- @ — ファイルを探して頼みごとに添付します。$ — スキルを呼びます。! — シェルコマンドをすぐ実行します(!git status)。
- -i picture.png — スクリーンショットを添付して始めます(会話の途中なら貼り付けます)。--search — リアルタイムの Web 検索をオンにします。
- /init — AGENTS.md を作ります。/plan — まず計画を立てさせます。
Claude Code から来ましたか? /import で Claude Code の設定と最近の会話を取り込めます。
上手に任せる — どこで・何を・どう確かめるか
よい頼み方には 3 つの部分があります。どこで(ファイルとフォルダー)、何を(望む動き)、どう確かめるか(テスト・コマンド・画面)。この 3 つがはっきりしているほど、Codex は迷わず、自分の結果をよく確かめます。
- あいまいな頼み方:「カートを直して」
- はっきりした頼み方:「@src/cart.ts で、数量が 0 のとき合計が NaN になります。数量が 0 ならその商品を消すようにし、tests/cart.test.ts にテストを足して、pnpm test が通ることを確かめてください。」
- 大きな作業は「まず計画だけ見せて」から始め、計画を直してから続けさせます。
- 頼んだ以上のことを変えたら止めて、git restore で巻き戻し、ファイルを名指しして頼み直します。
- エラーの出力は全部貼り付けます — 要約より原文のほうが正確です。
- 終わったら /diff で変更を読み、自分でテストを実行してからコミットします。
中級の練習 — 自分のプロジェクトでやってみる
- /init で AGENTS.md を作り、テストコマンドと 3 つのルールを整えます。
- Claude Code も使うなら、プロジェクトに CLAUDE.md がないことを確かめて、両方の AI が同じ AGENTS.md を読むようにします。
- codex --sandbox read-only でプロジェクトを見て回らせ、それから workspace-write で小さな修正を任せます。
- /diff と /review で変更をレビューします。
- /status で今の設定を見て、codex resume --last で会話を続けます。
5 つとも終わりましたか? [上級] タブに進みましょう。
公式ドキュメント
2026-10-18 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。
上級 — 広げる：config.toml・codex exec・MCP・スキル・フック
設定ファイルとプロファイルで Codex を自分の働き方に合わせ、codex exec でスクリプトに入れ、外部ツールは でつなぎ、くり返す作業はで教え、必ず守るべきルールはフックで強制します。
config.toml とプロファイル — 自分の働き方に合わせる
Codex の設定は ~/.codex/config.toml にあります。毎回付けていたオプションも、ここに書けば初期値になります。作業によって変わる設定はプロファイルファイルに入れます。
- model · model_reasoning_effort — 使うモデルと、どれだけ深く考えるか
- approval_policy · sandbox_mode — 承認ポリシーとサンドボックス(中級で学んだ値)
- プロファイルは ~/.codex/<名前>.config.toml というファイルです。codex -p <名前> で選ぶと、その値が基本の設定の上に重なります(以前の [profiles.x] テーブルはもう読まれません)。
- -c key=value はこの実行だけ設定を変えます(例: -c sandbox_workspace_write.network_access=true)。
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
# a profile: codex -p review
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
codex -p review
codex -c sandbox_workspace_write.network_access=true
プロジェクトの .codex/config.toml はそのプロジェクトだけの設定です — 信頼済みにしたプロジェクトでだけ読まれます。
codex exec — チャット画面なしで自動化する
codex exec "…" はチャット画面なしで作業を一度して終わります。進み具合は stderr に、最終的な答えは stdout に出るので、スクリプト・cron・ によく合います。
- 初期設定は読むだけです。ファイルを編集させるには --sandbox workspace-write を付けます。
- --json は進み具合を JSON の行(JSONL)で送り、-o <ファイル> は最終的な答えをファイルに保存し、--output-schema <ファイル> は JSON Schema に合う答えを受け取ります。
- プロンプトなしで実行すると標準入力がプロンプトになり、プロンプトと一緒にパイプで入力を渡すと、その入力が後ろに足されます。
- Git リポジトリの外では --skip-git-repo-check が必要です。codex exec resume --last は前回の実行を続けます。
# Ask once, print the answer (read-only by default)
codex exec "Summarize what changed in the last 5 commits"
# Allow edits inside this folder
codex exec --sandbox workspace-write "Fix the failing test in tests/cart.test.ts"
# Pipe input in
cat error.log | codex exec "Find the cause"
# For scripts: JSON events, the final answer in a file, a JSON Schema answer
codex exec --json "List the TODOs in src/" > events.jsonl
codex exec -o notes.md "Write release notes for this week"
codex exec --output-schema schema.json "Rate the test coverage of each file"
# Continue the last run
codex exec resume --last "Now add tests for it"
CI では CODEX_API_KEY を Codex を動かすステップにだけ渡し、ほかのステップのスクリプトからキーが見えないようにします。
MCP — 外部ツールをつなぐ
MCP(Model Context Protocol)は、 ツールが外部サービス(課題管理ツール、、、ドキュメントツール)を使えるようにする公開標準です。Codex に MCP を追加すると、そのサーバーのツールを使えます — Claude Code が使うのと同じサーバーがそのまま動きます。
- codex mcp add <名前> -- <コマンド> — 自分のコンピューターで動くサーバー(stdio)を追加します。
- codex mcp add <名前> --url <url> — リモートサーバー(streamable HTTP)を追加します。
- 追加したサーバーは config.toml の [mcp_servers.<名前>] テーブルに保存されます。会話の途中では /mcp で状態が見られます。
# A server that runs on your computer (stdio)
codex mcp add playwright -- npx @playwright/mcp@latest
# A remote server (streamable HTTP)
codex mcp add notion --url https://mcp.notion.com/mcp
codex mcp list
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
tool_timeout_sec = 60
信頼できる MCP サーバーだけを追加しましょう。外部の文章を取ってくるサーバーは、その文章に隠された指示を持ち込むことがあります(プロンプトインジェクション)。
エージェントスキル — くり返す作業を教える
スキルは SKILL.md が入ったフォルダーです — Claude Code と同じ公開フォーマットです。ふだん Codex は各スキルの名前と説明だけを知っていて、作業が説明に合うと本文を読んでそのとおりにします。以前のカスタム(~/.codex/prompts)は、今はスキルに変えましょう。
- .agents/skills/<名前>/SKILL.md はこのリポジトリ用、~/.agents/skills/ はすべてのプロジェクト用です。
- $<スキル名> で直接呼ぶか、/skills で一覧から選びます。description が合えば自分で使うこともあります。
- name と description を書き、スクリプトや参考ドキュメントは scripts/ と references/ に置きます。
- 組み込みの $skill-creator に頼むと、新しいスキル作りを手伝ってくれます。
---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes or a changelog.
---
1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed, in plain sentences.
フック — 決まったタイミングで必ず動くコマンド
フックは Codex が決まったタイミングで必ず実行するコマンドです。AGENTS.md のお願いは忘れられることがありますが、フックは毎回動きます。フォーマッターを動かす、危険なコマンドを止める、作業が終わったら通知を受ける、といったことにフックを使います。
- ~/.codex/hooks.json(自分)か、リポジトリの .codex/hooks.json(プロジェクト)に置きます。
- PreToolUse と PostToolUse(ツールの前と後)、UserPromptSubmit(頼みごとを送ったとき)、Stop(答えを終えたとき)、SessionStart(セッションが始まったとき)などのタイミングにつなぎます。
- matcher でツールを選び、コマンドが終了コード 2 で終わるとその動作は止められます。
- 通知だけが必要なら、config.toml の notify にプログラムを入れます — ターンが終わるたびに JSON の引数付きで実行されます。
新しいフックは /hooks で信頼済みにしてから動きます。ほかの人のフックは、コマンドを読んで理解してから信頼しましょう。
上級の練習
- ~/.codex/config.toml に初期の承認とサンドボックスを書き、読むだけのレビュー用プロファイル(review.config.toml)を作って codex -p review で使います。
- 今週のコミットを codex exec -o でファイルに要約するスクリプトを書きます。
- MCP サーバーを一つ追加し、/mcp で確かめます。
- よくする作業を一つ .agents/skills/ のスキルにして、$name で呼びます。
- PostToolUse フックで、ファイルを編集するたびにフォーマッターが動くようにし、/hooks で信頼済みにします。
5 つとも終わりましたか? [マスター] タブに進みましょう。
公式ドキュメント
2026-10-18 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。
マスター — サブエージェント・クラウド・GitHub・複数の AI を一緒に
作業をとに任せ、 で @codex からレビューを受け、Claude Code などの別の と互いの作業をレビューし合い、チームが同じ設定で働けるようにします。
サブエージェント — 作業の一部を任せる
Codex にサブエージェントを立ち上げるよう頼むと、調査・実装・レビューを分けて同時に進めます。それぞれが自分の会話を持つので、メインの会話はすっきりしたままです。
- 組み込みの default・worker・explorer は最初からあり、/subagents でサブエージェントの間を行き来します。
- 自分のサブエージェントは .codex/agents/(プロジェクト)か ~/.codex/agents/(自分)に TOML ファイルで作ります — name、description、developer_instructions。
- サブエージェントは親のサンドボックスと承認の設定を受け継ぎます。
- 「reviewer で今の diff をレビューして、その間に worker にテストを書かせて」のように、頼みごとの中で役割を分けます。
name = "reviewer"
description = "Reviews diffs for bugs and missing tests. Read-only."
developer_instructions = """
Run git diff. List bugs with file and line, then missing tests.
Never edit files.
"""
model_reasoning_effort = "high"
Codex クラウド — 作業をクラウドに任せる
codex cloud は OpenAI のクラウド環境で作業を動かします。自分のコンピューターを使わないので、いくつもの作業を一度に任せ、できあがった結果から選んだものだけを自分のファイルに適用できます。
- まず ChatGPT の Codex 設定で環境(リポジトリ、セットアップスクリプト、シークレット、インターネット接続)を作ります。
- codex cloud でタスクの一覧を見て、新しいタスクを始めます。codex cloud exec --env <環境 ID> "…" で直接任せることもできます。
- codex apply <タスク ID> は、クラウドで作った変更を自分のリポジトリに適用します(git apply)。
- 同じ作業を何回か試させて(--attempts)、いちばんよい結果を選びます。
codex cloud # see and start cloud tasks
codex cloud exec --env <ENV_ID> "Add input checks to the signup form"
codex cloud list
codex apply <TASK_ID> # apply the result to your files
GitHub — PR で @codex review
GitHub を Codex につなぐと、 のコメントに @codex review と書くだけでレビューを受けられます。GitHub Action(openai/codex-action)を使えば、PR ごとに自動で動かすこともできます。
- @codex review — その PR をレビューし、深刻な問題(P0、P1)だけを報告します。Codex の設定で、すべての PR の自動レビューをオンにできます。
- それ以外の @codex … コメントは、その内容でクラウドタスクを始めます。
- openai/codex-action@v1 は prompt と sandbox を受け取って Codex を動かし、最終的な答えを final-message で返します — 次のステップでそれをコメントに投稿します。
- キーはリポジトリのシークレット(OPENAI_API_KEY)で渡し、読むだけのレビューなら sandbox は read-only のままにします。
name: Codex review
on:
pull_request:
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- uses: openai/codex-action@v1
id: codex
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: "Review this pull request. List bugs and missing tests."
sandbox: read-only
# the answer is in steps.codex.outputs.final-message
AGENTS.md に ## Code Review Rules の節を入れると、Codex の PR レビューがそのルールに従います。
複数の AI を一緒に使う — 互いにレビューする
ある AI が書いたを別の AI がレビューすると、一つだけでは見落とす問題が見えてきます。AGENTS.md で同じ指示を共有していれば、一つのプロジェクトで Codex と Claude Code を簡単に行き来できます。
役割を分けるのも一つの方法です。一つの AI が計画して作り、もう一つがレビューしてテストし、人が最後の を読んでマージするかを決めます。
- codex review --uncommitted — コミットしていない変更を Codex がレビューします。--base <ブランチ> はブランチ全体をレビューします。
- git diff | claude -p "…" — Codex が作った変更を Claude Code がレビューします。
- 別の AI のセッションの中から、codex exec で作業を一つ Codex に任せられます(例: テストを書く、画像を作る)。
- 二つの AI の意見が分かれたら、両方に根拠(ファイル、行、テスト結果)を出させ、人が確かめて選びます。
# Claude Code wrote the change — Codex reviews it
codex review --uncommitted
# Codex wrote the change — Claude Code reviews it
git diff | claude -p "Review this diff. List bugs and missing tests."
# From inside another AI's session, hand one job to Codex
codex exec --sandbox workspace-write "Write unit tests for src/price.ts"
チームの設定を運用する — 同じ設定で一緒に
一つのリポジトリでたくさんの人とたくさんの AI が働くと、設定はすぐに増えていきます。何を共有し何を個人にするか、何をお願いにし何を強制するかを決めましょう。
- 共有(コミットする): AGENTS.md、.codex/config.toml、.codex/hooks.json、.codex/agents/、.agents/skills/
- 個人(コミットしない): ~/.codex/config.toml、プロファイルファイル、~/.codex/AGENTS.md
- AGENTS.md は短く保ちます。同じ失敗がくり返されたときだけルールを足し、間違ったルールは消します。
- 必ず守るべきことは、指示ではなくサンドボックス・承認・フックで強制します。
- CI のキーは Codex を動かすステップにだけ渡し、レビューは read-only で動かします。
マスターのチェックリスト
- 共通のルールは AGENTS.md に — Claude Code などの別の AI も同じ指示で働く
- サンドボックスと承認は作業に合わせて選び、初期値は config.toml とプロファイルに書いてある
- くり返す作業はスキルに、必ず守るべきルールはフックに、外部ツールは MCP で
- くり返す作業は codex exec と GitHub Action で自動化する
- 大きな作業はサブエージェントと codex cloud に分け、選んだ結果だけを適用する
- AI どうしで互いの作業をレビューし、最後の diff とテストは人が確かめる
ツールはよく変わります。コマンドが動かないときは、まず codex --help と公式ドキュメントを確かめましょう。古い記事のオプション(--full-auto、[profiles.x])はもう変わっているかもしれません。
公式ドキュメント
2026-10-18 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。