OpenAI
Codex ベストプラクティス
Codex CLI の設定(config.toml)、AGENTS.md、Hooks、サブエージェント、Skills、Goal、アプリの Automations の使い方を整理しています。
2026-11-02 に照合済み(設定キーは openai/codex の設定スキーマ、機能説明は developers.openai.com の公式ドキュメント)
最新アップデート
ニュースに収録済みの直近3件です。全件はニュースから確認できます。
2026-10-29Codex CLI 0.165.0〜0.166.0 — Vertex AI プロバイダーを内蔵、新規プロファイルで Memory v2 が既定に
0.165.0 で組み込みの Google Cloud Vertex AI プロバイダー(model_provider = "gcp")を追加。新規プロファイルでは Memory v2 が既定に。0.166.0 でトランスクリプトのキーボード選択・検索、codex queue --resume、codex doctor --network-only を追加。
セキュリティ: チェックしたホストと別のホストへ Git が接続できたマーケットプレイス URL 検証の抜け穴を修正。ニュースを読む
2026-10-26GPT-6.1 Terra — 中位モデルが Codex でも利用可能に(報道ベース)
報道によると、GPT-5.6 Terra の後継となる中位モデル GPT-6.1 Terra(API 名 gpt-6.1-terra)がリリースされ、ChatGPT Work と Codex で利用可能に。Codex CLI は 0.165.0 でモデルカタログに、0.166.0 で Vertex AI・Amazon Bedrock のカタログにも追加。ニュースを読む
2026-10-23Codex CLI 0.164.0 — プロンプトを10スロットに保存する /presets、/model・/permissions のインライン引数
/presets でプロンプトやスラッシュコマンドを番号付きの10スロットに保存し、キーボードメニューから呼び出せるように。/model・/permissions に引数でモデル・推論 effort・権限プロファイルを直接指定できるように。
セキュリティ: リモート Bash コマンドと Zsh スナップショットのセッションで認証情報をマスク。macOS のサンドボックスチェックを強化。ニュースを読む
概要
- OpenAI 製。CLI・IDE 拡張・デスクトップアプリ(Codex app)・Web で動作
- 設定は TOML 形式の
config.toml(ユーザー単位とプロジェクト単位) - AGENTS.md でプロジェクトの指示を渡す
- Hooks は設定スキーマ上で14種類のイベント
- カスタムエージェントを TOML ファイルで定義してサブエージェントとして使える
- Skills(SKILL.md)で手順を再利用
/goalで目標とトークン予算を決めて継続的に作業させる- 定期実行はデスクトップアプリの Automations で設定
ベストプラクティス 10
- プロンプトには目的・前提・制約・完了条件をまとめて書く
- 実装の前に Plan mode などでリポジトリを調べさせ、方針を確認する
- AGENTS.md には build / test / lint のコマンドと完了条件を書く
- 危険なコマンドの拒否は指示文ではなく PreToolUse hook と承認ポリシーで行う
- 組織では
requirements.tomlで管理者の Hook だけを許可する設定を検討する - サブエージェントは1つに1つの役割を持たせ、
developer_instructionsで振る舞いを明確にする - Skill の
descriptionは「何をするか」と「いつ使うか」を具体的に書く(暗黙的な起動の精度が上がる) - 長い作業は
/goalにトークン予算を付けて任せ、途中で状態を確認する - Automations はまず通常のスレッドで手順を安定させてから登録する
- フルアクセスのサンドボックスで Automations を動かさない(確認なしでファイル変更やネットワークアクセスが起きる)
設定(config.toml)
ユーザー単位の ~/.codex/config.toml と、プロジェクト単位の .codex/config.toml があります。組織の制約は requirements.toml で管理者が配布します。
[approval_policy]・[automations]・[goal]・[provider] テーブルや hooks.managed_dir を使った設定例を載せていましたが、いずれも Codex の設定スキーマに存在しないキーでした。また、プロファイルの例も 0.134.0 で廃止された [profiles.<name>] 形式のままでした。下の例に差し替えています。01config.toml の例(承認・サンドボックス・プロバイダー・Hook)
# ~/.codex/config.toml
approval_policy = "on-request" # "on-request" / "never"、細かく決めるなら { granular = { ... } } のテーブル
sandbox_mode = "workspace-write" # read-only / workspace-write / danger-full-access
# 独自のモデルプロバイダー(例: Azure OpenAI)
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"
# Hook(PreToolUse で Bash を検査)
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/policy.py"
timeout = 30
statusMessage = "Checking Bash command policy"
- プロバイダーを使うときは、ユーザー設定(
~/.codex/config.toml)にmodel_provider = "azure"とmodel(Azure 側のデプロイ名)を合わせて書きます - プロジェクトの
.codex/config.tomlではmodel_provider・model_providers・openai_base_url・chatgpt_base_url・notify・otel・profile・profilesなどが無視され、起動時に警告が出ます
02設定ファイルの種類
| ファイル | 場所 | 対象 |
|---|---|---|
| ユーザー設定 | ~/.codex/config.toml | 自分・全プロジェクト |
| プロジェクト設定 | .codex/config.toml | リポジトリ(Git 管理できる) |
| 組織の制約 | requirements.toml | 管理者が配布。例: allow_managed_hooks_only = true でユーザー・プロジェクト・セッションの Hook を無視し、管理者の Hook だけを有効にする |
03プロファイル(--profile)
プロファイルは、プロファイルごとの別ファイル ~/.codex/<name>.config.toml にトップレベルのキーで書き、codex --profile <name> で切り替えます。
# ~/.codex/review.config.toml
model_reasoning_effort = "high"
sandbox_mode = "read-only"
# 実行例
codex --profile review "このブランチの差分をレビューして"
0.134.0 以降、config.toml の [profiles.<name>] テーブルとトップレベルの profile = "..." は読み込まれません。古い設定は新しい形式のファイルに移し、config.toml から削除します。
出典: Config reference · config.schema.json(openai/codex) · docs/config.md
AGENTS.md
セッション開始時に読み込まれるプロジェクトの指示ファイルです。
01AGENTS.md の例
# AGENTS.md
## Project
TypeScript monorepo (pnpm workspaces)
Node 22 / React 19 / PostgreSQL 16
## Build & Test
build: pnpm build | test: pnpm test | lint: pnpm lint
## Rules
- Never commit to main directly
- All API endpoints require Zod validation
## Done when
- pnpm test passes
- pnpm lint is clean
- pnpm tsc --noEmit succeeds
- 信頼していないプロジェクトの AGENTS.md の指示は読み込まれません(0.150.0 から)
- Codex は各ディレクトリで AGENTS.override.md → AGENTS.md の順に探し、1ディレクトリにつき1ファイルだけを読みます。
project_doc_fallback_filenamesに CLAUDE.md などを追加すると、AGENTS.md がないディレクトリではそのファイルが代わりに読まれます(AGENTS.md があれば読まれません)
出典: AGENTS.md guide · 0.150.0 のニュース
Hooks
ライフサイクルの決まった時点でコマンドや MCP ツールを実行する仕組みです。既定で有効で、[features] hooks = false で無効にできます。
01イベント(設定スキーマ上の14種類)
| イベント | タイミング |
|---|---|
SessionStart / SessionEnd | セッションの開始・終了 |
UserPromptSubmit | プロンプト送信時 |
PreToolUse / PostToolUse | ツール実行の前後(matcher はツール名の正規表現) |
PermissionRequest | 承認を求める時 |
PreModelRequest / PostModelRequest | モデルへのリクエストの前後 |
PreCompact / PostCompact | コンテキスト圧縮の前後 |
SubagentStart / SubagentStop | サブエージェントの開始・終了 |
Stop | ターンの終了時 |
Interrupt | トップレベルのターンを中断した時(0.150.0 で追加) |
一覧は安定版 0.166.0 の設定スキーマで確認したものです。各イベントの対象ツールや入出力の形式は公式ドキュメントで確認してください。
02書き方と注意点
- Hook は
hooks.jsonか、config.tomlの[hooks]テーブルに書きます。ユーザー(~/.codex/)とリポジトリ(.codex/)の両方にある場合はすべて読み込まれます。ただしリポジトリ側の設定は、そのプロジェクトを信頼した場合にだけ読み込まれます - ハンドラーには
type = "command"(command・timeout・statusMessage・commandWindowsなど)と、MCP サーバーのツールを呼ぶtype = "mcp_tool"(必須:server・tool、任意:input)があります timeoutを省略すると600秒です- PreToolUse で Bash を止めても、モデルがスクリプトをファイルに書いて実行するなど抜け道はあり得ます。完全な強制ではなく安全策の一つとして使い、サンドボックスと承認ポリシーを併用します
サブエージェント
カスタムエージェントを1ファイル1エージェントの TOML で定義し、サブエージェントとして並列に動かせます。
01カスタムエージェントの定義
# .codex/agents/security-reviewer.toml
name = "security-reviewer"
description = "Reviews diffs for security issues."
developer_instructions = "You are a senior security reviewer. Report only specific, actionable findings."
sandbox_mode = "read-only"
model_reasoning_effort = "high"
nickname_candidates = ["Sherlock", "Inspector"]
- 必須は
name・description・developer_instructions - 保存先: 個人用
~/.codex/agents/、プロジェクト用.codex/agents/ modelやsandbox_modeなど省略した項目は親セッションから引き継ぎますnickname_candidatesは表示名だけで、起動にはnameが使われます
02並列数と深さの上限
config.toml の [agents] で上限を設定します。同時に動かせるスレッド数は、公式ドキュメントでは max_threads(既定6)、0.166.0 の設定スキーマでは max_concurrent_threads_per_session と書かれています。名前が変わった可能性があるため、使っているバージョンで確認してください。max_depth は入れ子の深さ(既定1)です。設定スキーマでは max_depth は旧方式(V1)のエージェントにだけ効き、Multi-agent V2 では無視されると説明されています。
03並列レビューと Remote Control
- PR のレビューを、セキュリティ・バグ・テストなど観点ごとのサブエージェントに分けて並列で実行するのが効果的です
- Remote Control(2026年6月 GA)を使うと、ChatGPT モバイルアプリから接続済みの Mac / Windows ホストで作業を始めたり続けたりできます。2026-07-18 のアップデートで、端末とホストを QR コードで1対1にペアリングする方式に変わりました。7/18 のニュースを読む
出典: Subagents · config.schema.json(AgentsToml) · Codex changelog(Remote Control GA)
Skills
SKILL.md に手順を書いたフォルダです。起動時には名前・説明・パスだけが読み込まれ、必要になったときに本文が読まれます。
01SKILL.md の例と保存場所
# .agents/skills/commit/SKILL.md
---
name: commit
description: Stage and commit changes in semantic groups.
Use when the user wants to commit or organize commits.
---
1. Do not run `git add .`. Stage in logical groups.
2. Group: feat → test → docs → refactor → chore.
3. Write concise commit messages.
- リポジトリ: 作業ディレクトリからリポジトリのルートまでの各階層の
.agents/skills - 個人用:
$HOME/.agents/skills - 組み込みの
$skill-creatorを使うと、対話しながら Skill を作れます - 同じ
nameの Skill が2つあっても統合はされず、両方が選択肢に出ます
出典: Agent Skills
Goal(/goal)
達成したい目標を設定すると、Codex がその目標に向けて作業を続けます。
[goal] テーブルの timeout = "72h"・checkpoint = "8h" で設定し、チェックポイントごとに自動でコミットされると説明していましたが、設定スキーマにそのようなキーはなく、根拠を確認できませんでした。01使い方
- TUI で
/goalを使って目標を設定・編集します。引数なしの/goalで現在の目標の概要を表示します - 目標は一時停止・再開でき(
/goal resume)、トークン予算を付けられます - 新しい目標の既定の予算と上限は
config.tomlの[goals] max_goal_token_budgetで指定します - ネストしたサブエージェントのトークン消費もルートの目標の予算に計上されます(0.151.0 で修正)
Automations(Codex app)
デスクトップアプリで、繰り返し実行するバックグラウンドの作業を登録する機能です。config.toml ではなくアプリから設定します。
012つの種類と設定方法
| 種類 | 動き | 向いている用途 |
|---|---|---|
| Standalone | スケジュールごとに新しい実行を始め、結果を Triage の受信箱に送る | 毎回独立した作業、複数プロジェクトにまたがる作業 |
| Thread | 今のスレッドに定期的に戻ってくる | 同じ会話を続けながら定期的に確認する作業 |
- 通常のスレッドで「この作業を毎朝実行して」のように頼むと、Codex がプロンプト・種類・スケジュールを設定します
- 独自の間隔は cron 式で指定します
- Git リポジトリでは、ローカルのプロジェクトか専用のバックグラウンド worktree のどちらで動かすかを選べます
- プロジェクト単位の Automations は、アプリが起動していてプロジェクトがディスク上にあるときだけ動きます
出典: Automations
更新ログ
codex execは未信頼ディレクトリでは--sandbox workspace-writeでもプロジェクト設定とMCPサーバーを無効のまま。信頼の保存はcodex exec/codex reviewに--trust。ターミナルからカスタムモデルプロバイダーを追加・編集、コマンドセンターで過去タスク検索。[features]のincremental_tools_legacy_gcp = false(リリースノート記載どおり)codex agents --no-daemonでエージェントコマンドセンター、セッションピッカーから接続中バックエンドを切替、/experimentalでmacOS/Windowsのシステムプロキシをopt-in、承認待ち中にパッチ詳細を展開。ネットワーク承認は同一エンドポイントへの同時リクエストを1件ずつ確認。詳細はニュース参照。model_provider = "gcp")、新規プロファイルでMemory v2が既定、会話途中の推論effort変更が既定有効に。codex queue --resume・codex doctor --network-only追加。マーケットプレイスURL検証の抜け穴修正・スレッド再開/フォーク時の承認設定保持🔒。詳細はニュース参照。gpt-6.1-terra・$1/$5 per Mtokとされる)がCodexで利用可能に。Codex CLI 0.165.0以降のカタログに追加。詳細はニュース参照。/presets、/model・/permissionsのインライン引数を追加。リモートBash/Zshスナップショットでの認証情報マスク、macOSのサンドボックスチェック強化🔒。詳細はニュース参照。/configで設定を横断検索・即時変更、応答中のフォローアップで即時steer、/keymapでリーダーキー(既定Ctrl+X、音声ミュートはF9へ移動)。Daybreakが対象アカウントで既定有効に。ネットワークプロキシのDNS前権限確認・重複Hostヘッダー拒否など🔒。0.162.0で信頼済みプロジェクトのgit worktree作成/一覧ツール追加。詳細はニュース参照。/mcp login <name>で実行中のターミナルからMCPサーバー認証が可能に。Daybreakは--enable cli_daybreak等の明示opt-inが必要に。ファイルシステム昇格時も拒否済みの読み取り・ネットワーク制限を維持。詳細はニュース参照。plugin-creatorスキルを廃止、0.159.1で既定モデルをGPT-6.1 Solに変更。詳細はニュース参照。/tui・音声会話が既定で有効化(F8で切替)・トークン/プラグイン/スキルの利用状況を確認できる/usage分析ダッシュボードを追加。既定でworktreeセッションを使用するように変更。詳細はニュース参照。--%をPowerShell本体と異なる解釈をしていたため、悪意あるリポジトリを開いた場合にファイル書き込み系gitコマンドが承認プロンプトなしに実行されうる脆弱性が公表された。macOS/LinuxでもPowerShell Core(pwsh)がインストールされていれば影響。ファイルシステムサンドボックス自体は無効化されないため既定設定なら影響は限定的。修正済みとされるが具体的な修正バージョンは未確認。詳細はニュース参照。--worktree・/worktreeで分離checkoutを作成できる実験的worktreeサポートを追加。作業を継続したままインラインで質問に回答できる機能・Vim R置換モード(undo/dot-repeat対応)・Windowsのバックグラウンド共有Codexサーバーも追加。非推奨のcodex mcp-serverエントリポイントは廃止。詳細はニュース参照。gpt-6-astra、コンテキスト1Mトークン)を発表。7月のHugging Faceインシデントを受け安全対策を追加してリリース。一般提供版はサイバーセキュリティ関連の一部プロンプトを拒否。Codex CLIは0.153.1〜0.153.4(9/3〜9/4)で順次対応、Amazon Bedrockのモデル選択肢にも追加。詳細はニュース参照。u(undo)・Ctrl+R(redo)を追加し、貼り付け内容や添付ファイルを含む下書き全体を維持したまま元に戻し可能に。プラグインCLIがリモートマーケットプレイスからのプラグイン一覧表示・インストール・削除に対応。app-server切断後の自動再接続で下書き・トランスクリプトを保持。Guardianのレビュー履歴がcompaction・再起動・フォークをまたいで保持されるように改善。詳細はニュース参照。.git/configのcore.fsmonitorを悪用し、git status等のコンテキスト収集コマンド実行だけで任意コード実行を許してしまう脆弱性がgoose・Claude Code・Codex等7ツールで公表(Manifold Security)。OpenAIは同日、Codexの同種脆弱性について3件のCVEを独自発行。.git付きでzip等から受け取ったリポジトリの.git/configは開く前に確認を推奨。詳細はニュース参照。/・?によるドラフト内検索を追加。レート制限バナーが利用量確認・クレジット管理・プラン変更のアクションを提供するように刷新。MCPサーバー名に:・@・/・.を使用可能に。個別MCPツールにoutput_token_limit設定を追加。planningツールが既定で無効化(⚠️)。Guardian承認レビューがモデルメタデータ経由のNode REPLポリシーを正しく反映するよう修正(🔒)。詳細はニュース参照。@メンションで他のCodexタスクを参照しターミナルから読み取り・作成・メッセージ送信が可能に。/copyが全文/コードブロック単位/blockquote単位のピッカー形式に。トップレベルターン中断時にコマンド/MCPハンドラーを実行するInterrupthooksを新設。信頼されていないプロジェクトはプロジェクト単位のAGENTS.md指示を供給できなくなり、権限変更後もmanaged deny-readルールが維持されるよう修正(🔒)。0.150.1でリモートcompactionの画像トークン予算計算を修正。詳細はニュース参照。codex agents」ダッシュボードを追加。TUI向け作業ディレクトリ操作コマンド(/cd・/pwd・/cwd)・既存セッションにメッセージを送るcodex queueも新設。codex doctorの診断範囲をエンドポイント保護・ネットワーク/プロキシ障害まで拡充。詳細はニュース参照。/exportでMarkdown書き出し可能に。codex exec forkでセッションフォーク、resumeピッカーからアーカイブ/復元も可能に。AWSプロファイル/リージョン設定・GPT-5.6ルーティングに対応したAmazon Bedrock Runtimeを組み込みプロバイダーとしてサポート。コマンドHookが非同期実行・MCPツール呼び出しに対応。サンドボックスが拒否/読み取り不能パスに対しLinux/Windows双方でfail-closedに(🔒)。詳細はニュース参照。--approve-for-meフラグで自動レビュー承認。会話を永続セクションに整理し長いトランスクリプトを段階閲覧。Cursor管理スキルのインポート・Claude/Cursor会話の重複なし同期に対応。MCP 2026-07-28プロトコル(オプトイン)。表示コマンドのシークレット・ベアラートークンを完全マスクするよう修正。codex exec --full-autoを削除。詳細はニュース参照。@openai/codex-security, v0.1.1, Apache 2.0)を公開。リポジトリの脆弱性スキャン・検出結果追跡・修正確認・CI/CD組み込みが可能。Codex本体とは別のスタンドアロンツール。詳細はニュース参照。/importでCursor・Claude Codeの設定(MCPサーバー・プラグイン・セッション・コマンド・記憶)を移行可能に。詳細はニュース参照。rmの亜種を追加検出・拒否理由を明確化)。承認フローの挙動が一部変わる可能性あり。詳細はニュース参照。