Executive summary
Codex の学習設計で最も重要なのは、コンポーネントを機能別に分けて学ぶのではなく、作業面での役割ごとに積み上げることです。OpenAI の一次資料を横断すると、Codex は大きく ローカル作業面（CLI、IDE extension、App）、クラウド作業面（Codex web / Cloud）、プロジェクト適応層（AGENTS.md、config.toml、permissions、sandbox、Skills、Subagents、MCP、Plugins）、自動化・組み込み層（app-server、SDK、GitHub Action、non-interactive）に整理できます。したがって、日本語の技術ブログ連載もこの順番で進めるのが最も学習効率が高いです。
経験者向けの最短経路は、CLI で基礎操作を体得し、AGENTS.md と config.toml で再現性を作り、IDE extension と App で日常開発に埋め込み、Cloud と Subagents で長時間・並列作業へ拡張し、最後に MCP・Plugins・SDK・GitHub Action で組織的運用へ移行する流れです。特に OpenAI は、CLI/IDE では ChatGPT サインインと API キー認証の両方をサポートする一方で、Codex Cloud は ChatGPT サインインを必要とすると案内しており、ローカル起点とクラウド起点では導入条件が異なります。
安全設計は連載の中心テーマに置くべきです。公式資料では、workspace-write は既定の実践的モードであり、on-request と組み合わせるとワークスペース内編集は進めつつ、ネットワーク利用やワークスペース外操作では確認を求める構成になります。また、danger-full-access や --dangerously-bypass-approvals-and-sandbox は高リスクとして明示されており、CI でも API キーを job-level 環境変数で露出すべきではないと案内されています。したがって、本連載では 安全に学ぶ既定パターン を approval_policy = "on-request" と sandbox_mode = "workspace-write" に統一し、例外として上級章でのみ権限昇格を扱うのが妥当です。
一次資料の多くは OpenAI Developers の英語ドキュメントですが、2026年7月7日時点では、OpenAI の日本語公式ページとして Codex 概要、開始ガイド、アプリ紹介、安全運用、移動中の利用、ChatGPT プラン上での利用案内などが公開されています。本レポートでは、仕様は Developers docs を一次資料、導入文脈と運用補助は日本語公式ページで補完する構成にしています。
調査方針と一次資料
本レポートは、Codex の公式ドキュメント群を中心に調査しました。機能仕様、コマンド、設定キー、サンドボックス制御、サブエージェント、MCP、プラグイン、SDK、GitHub Action については OpenAI Developers の Codex ドキュメントを一次資料として採用し、日本語の導入・運用文脈については OpenAI 日本語サイトおよび Help Center 日本語記事を採用しました。Codex の全体像、CLI、IDE extension、App、Web/Cloud、AGENTS.md、Skills、Subagents、MCP、app-server、SDK、GitHub Action はいずれも公式に個別ページが存在します。
日本語ソースとしては、Codex の製品概要、開始方法、Codex アプリ紹介、安全運用、どこからでも使うユースケース、ChatGPT プランでの利用、および GitHub 接続に関する公式ページが確認できました。これらは詳細な機能リファレンスではありませんが、日本語読者にとって 「何を学ぶのか」「どんな運用上の注意があるか」 を伝える入口資料として有用です。
この連載の対象読者は、Python、VS Code、Docker、Git を日常的に扱う経験者開発者です。そのため、各章は「概念説明」より 実務導入に必要な判断・設定・失敗パターンの理解 を重視し、4時間単位のハンズオンで構成しています。OS は特定しませんが、CLI の導入では macOS/Linux と Windows の両方を示し、App は macOS/Windows 前提、IDE extension はエディタ依存、サンドボックスは OS により実装差があることを明示します。
コンポーネント比較表
下表の優先度と難易度は本レポートの教育設計上の推奨です。目的、典型ユースケース、前提、主な安全論点は公式資料に基づいています。
| コンポーネント | 目的 | 典型ユースケース | 優先度 | 難易度 | 必要な前提 | 主な安全論点 |
|---|---|---|---|---|---|---|
| ① Codex CLI | ローカル端末でコードを読み、変更し、コマンドを実行する主要インターフェース。macOS/Linux/Windows で利用可能。 | コード調査、最小修正、テスト実行、リポジトリ理解 | 最優先 | 初級 | シェル、Git、プロジェクト起動手順 | workspace-write と承認方針の理解が必須。ネットワークは既定でオフ。 |
| ② Codex IDE extension | IDE 内で Codex を横並びに使い、必要に応じて Cloud へ委任する。 | 開いているファイル中心の変更、差分確認、IDE からの連続対話 | 最優先 | 初級 | VS Code などのエディタ操作 | CLI と同じ認証・設定を共有するので、設定不整合に注意。 |
| ③ Codex App | 複数スレッド、worktree、automations、Git 機能をまとめたデスクトップ司令塔。macOS/Windows 対応。 | 並列タスク、worktree 隔離、レビュー、バックグラウンド自動化 | 高 | 初級から中級 | Git worktree の基礎、GUI ワークフロー | ローカル・worktree・cloud のモード差と権限差を理解する必要がある。 |
| ④ Codex Cloud | クラウド環境でバックグラウンドかつ並列にタスク実行する。ChatGPT サインインが必要。 | 長時間タスク、PR 調査、レビュー、並列実装 | 高 | 中級 | GitHub 連携、ChatGPT アカウント | 環境設定、インターネット許可、クラウド上の依存関係管理が重要。 |
| ⑤ AGENTS.md | Codex にプロジェクト固有ルールを事前注入するカスタム指示ファイル。階層的に適用される。 | コーディング規約、検証手順、レビュー方針の固定化 | 最優先 | 初級 | リポジトリ構成理解 | 曖昧で長すぎる指示は逆効果。短く実務的に保つべき。 |
| ⑥ config.toml / permissions / sandbox | モデル、承認、サンドボックス、MCP などの持続設定を定義する。 | 標準作業環境の固定、安全境界の運用 | 最優先 | 中級 | TOML、権限管理の基礎 | danger-full-access は高リスク。OS ごとのサンドボックス差も要理解。 |
| ⑦ Skills | 再利用可能なワークフローを instructions / scripts / references として束ねる。 | デプロイ、診断、文書更新、定型作業の再現 | 高 | 中級 | .agents/skills 構成、Markdown | Skill を肥大化させず、一つの仕事に絞るのがベストプラクティス。 |
| ⑧ Subagents | 明示的依頼時に専門エージェントを並列起動して集約する。 | PR レビュー分担、コードベース探索、複数観点監査 | 高 | 中級から上級 | 親タスク分解、モデル選定 | トークン消費が増え、親の sandbox を継承する。無制限 fan-out は危険。 |
| ⑨ MCP | 外部ツールや文書コンテキストへの接続標準。CLI と IDE extension がサポート。App でも設定共有。 | ブラウザ、Figma、社内 docs、専用ツール連携 | 高 | 上級 | ツール接続、認証、ネットワーク | 有効ツールの絞り込み、approval mode、トークン管理が重要。 |
| ⑩ Plugins | Skills や apps、MCP を配布可能な単位としてインストール・共有する。Skill が成熟してから導入するのが推奨。 | チーム配布、複数 repo 共有、統合ワークフロー | 中 | 上級 | Skill と MCP の理解 | プラグインはツール表面を広げるため、導入時の権限確認が重要。 |
| ⑪ Codex app-server | 自作プロダクトへ Codex を深く埋め込むための JSON-RPC インターフェース。 | 独自 GUI、会話履歴・承認 UI・ストリーミング統合 | 中 | 上級 | JSON-RPC、プロセス通信 | WebSocket は実験的で、非ループバック公開には明示認証が必要。 |
| ⑫ Codex SDK | Python/TypeScript からローカル Codex を制御する。Python SDK は app-server を操作する。 | 内部ツール化、CI 補助、自動実装フロー | 中 | 上級 | Python 3.10+ または Node 18+ | CI 用途では SDK と GitHub Action の使い分けが必要。 |
| ⑬ GitHub Action / non-interactive | CI/CD で安全に codex exec 相当を走らせる。GitHub では official action の利用が推奨。 | 自動レビュー、失敗 CI 修正提案、定期検査 | 高 | 上級 | GitHub Actions、Secrets、最小権限設計 | API キーを job-level 環境変数で渡さない。drop-sudo などの safety-strategy を活用。 |
＋⑭ChatGPT＋work : Githubと連携し、Github内のコードを改良（Codex Cloudは、GitCloneを使うのに対し、こちらは簡易実装向け）
半日ハンズオンで進める章立てカリキュラム
各章は 約240分 を想定しています。連載として公開する場合は、各章を 1 記事にしてもよいですし、読者負荷を下げるために 1 章を前後編に分けても成立します。ここでは「半日で完結する学習単位」を優先して設計しています。各章の演習は 空のサンプルリポジトリ か、既存の小規模 Python/Node リポジトリのどちらでも実施できます。Codex がコードを変更し得るため、どの章でも最初に Git checkpoint を作る運用を徹底します。
①CLI基礎と認証フロー
学習目標
Codex CLI をインストールし、認証し、現在ディレクトリを対象に安全な対話を始める。ChatGPT サインインと API キー認証の違い、codex と codex exec の役割差、既定の Agent mode を理解する。
前提
Git 管理されたプロジェクト、シェル操作、Python または Node の簡単な起動経験。
時間配分
| パート | 分 |
|---|---|
| 導入と前提確認 | 20 |
| インストールと認証 | 40 |
| 初回プロンプトと Git checkpoint | 40 |
| CLI セッション操作と小修正 | 60 |
codex exec の非対話実行入門 | 40 |
| ふりかえり | 40 |
ハンズオン演習
- 作業用リポジトリを用意し、Git checkpoint を切る。
bashコピーするgit status
git add -A
git commit -m "checkpoint before codex tutorial"
- Codex CLI をインストールする。macOS/Linux は公式インストーラ、Windows は PowerShell、代替として npm / Homebrew も使える。
bashコピーする# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
powershellコピーする# Windows
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
bashコピーする# 代替手段
npm install -g @openai/codex
brew install --cask codex
- 起動して認証する。CLI は ChatGPT サインインと API キーの両方をサポートする。Cloud は ChatGPT サインイン必須だが、CLI はローカル用途なので両対応である。
bashコピーするcodex
- 初回プロンプトを投げる。既定の Agent mode は、ファイル読取り・コマンド実行・変更作成を含む。
textコピーするこのリポジトリの目的、主要なエントリポイント、起動手順、既存テストを箇条書きではなく要約で説明して。
変更はまだ行わないで。
- 小さな編集タスクを実行する。
textコピーするREADME.md に「ローカル起動手順」セクションがなければ追加し、実行コマンドも追記して。
作業後に変更点と検証手順を要約して。
- 非対話モードの入り口として
codex execを試す。CI 本番では GitHub Action が推奨だが、ローカル自動化の最初の理解にはcodex execが使いやすい。
bashコピーするcodex exec "Explain the top 5 risks in this repository and output markdown."
期待される到達点
CLI の導入、認証、リポジトリ単位の対話、簡単な編集依頼、Git checkpoint 運用、codex exec の概念理解が終わる。ChatGPT 認証と API キー認証の違いを説明できるようになる。
よくある落とし穴
Cloud の話と CLI の話を混同して API キーで Cloud を使おうとすること、初回から大きな修正を依頼してレビュー不能な差分にすること、Git checkpoint を取らないこと、codex exec を対話セッションの代替と誤解することです。Cloud は ChatGPT サインイン前提で、CLI/IDE は両認証に対応します。
練習問題と解答
Q. CLI の最初の安全運用で、なぜ Git checkpoint を毎回作るべきか。
A. Codex は既定の Agent mode でファイル変更を行えるため、変更前後を Git で比較・復元しやすくするため。
Q. Cloud と違って CLI で API キー認証が許される理由は何か。
A. CLI はローカル Codex ワークフローをサポートし、公式に API キー認証を案内しているため。Cloud は ChatGPT サインインが必要。
公式リンク
Codex Quickstart
Authentication
Get started with Codex 日本語
ChatGPT プランで Codex を使う 日本語
②IDE extensionで日常開発へ埋め込む
学習目標
IDE extension を導入し、ローカル編集・差分確認・Cloud への委任の感覚をつかむ。CLI と IDE extension が認証状態を共有する点も理解する。
前提
CLI が動作していること。VS Code または対応 IDE を日常利用していること。
時間配分
| パート | 分 |
|---|---|
| 拡張導入 | 30 |
| サイドバーパネル確認 | 20 |
| IDE 文脈付きの質問 | 40 |
| 部分編集と差分レビュー | 70 |
| 既存テスト/ターミナル連携 | 40 |
| ふりかえり | 40 |
ハンズオン演習
- 対応 IDE に拡張を入れる。Quickstart では VS Code、Cursor、Windsurf、VS Code Insiders 向け導線が示されている。
- Codex パネルを開き、既存の認証が引き継がれているか確認する。CLI と IDE extension は同じログイン情報を共有し、片方でログアウトすると両方に影響する。
- 開いているファイルに対して文脈質問をする。
textコピーするいま開いているファイルの責務を説明し、このコードが依存している上位モジュールと下位モジュールを整理して。
- ローカルな最小変更を依頼する。
textコピーするこの関数の例外メッセージをより診断しやすいものに変えて。挙動は変えず、変更後は diff の要点を要約して。
- IDE 上で差分を確認し、必要なら Git reset で戻す。
bashコピーするgit diff
git restore path/to/file
- Cloud 委任の入り口として、同じパネルから「これはローカルより Cloud 向きか」を判断させる。
textコピーするこの課題はローカル作業と Codex Cloud のどちらが向いている？理由も述べて。
期待される到達点
CLI と IDE extension の使い分けができ、「フォルダ起点の対話は CLI、ファイル起点の反復は IDE」 という日常運用が固まる。IDE での小変更レビューがストレスなく回るようになる。
よくある落とし穴
IDE extension を単なるチャット窓として使い、IDE 側の diff や開いているファイル文脈を活かさないこと。もう一つは、Cloud に任せるべき長時間タスクをローカルで抱え込むことです。IDE extension はローカル支援にも Cloud 委任にも使えます。
練習問題と解答
Q. IDE extension と CLI の認証は別か。
A. 別ではない。公式にはキャッシュされたログイン情報を共有すると案内されている。
Q. IDE extension が特に有利なのはどんな場面か。
A. 開いているファイルや差分を見ながら、小さく安全に編集し、すぐレビューしたい場面。IDE 内で横並びに使えるのが強み。
公式リンク
Codex IDE extension
Quickstart の IDE 導入部
Codex 概要 日本語
ChatGPT プランで Codex を使う 日本語
③④Codex AppとCloudで長時間・並列作業へ広げる
学習目標
Codex App の役割、Worktree、Automations、Cloud の基本を理解し、ローカル・worktree・cloud を状況に応じて選べるようにする。Cloud 環境のセットアップスクリプトやネットワーク設定の考え方も学ぶ。
前提
Git worktree を知らなくてもよいが、Git ブランチ運用の基礎は必要。
時間配分
| パート | 分 |
|---|---|
| App の導入とモード理解 | 40 |
| Worktree での並行作業 | 60 |
| Local environments / Automations 概念 | 40 |
| Cloud タスクと環境設定 | 60 |
| 結果比較と運用判断 | 40 |
ハンズオン演習
- Codex App を導入し、プロジェクトを開く。App は macOS と Windows に対応している。
- Local モードで短いタスクを投げる。
textコピーするこのプロジェクトの既存テストを走らせ、壊れている場合は原因だけ報告して。
- Worktree モードで別タスクを並行起動する。Worktree は Git repository が前提で、開始ブランチを選んで隔離された作業を進められる。
textコピーするこのプロジェクトの lint エラーを直すための別スレッドを worktree で作って。
- Automations を使う前提を理解する。Git repository では local project または dedicated background worktree で自動化を走らせられる。
textコピーする毎朝、main ブランチのテスト失敗要因を要約する automation を設計したい。必要な skill と prompt を提案して。
- Codex Cloud を使う。Cloud ではバックグラウンドかつ並列でタスク実行できる。Cloud environments では setup script や依存追加を設定でき、setup script には internet access がある一方で、agent internet access は既定オフで必要に応じて有効化する。
textコピーするこのリポジトリのテスト環境に必要な依存を洗い出し、Cloud environment 向けの setup script 案を作って。
Cloud environment のサンプル方針
bashコピーする#!/usr/bin/env bash
set -euxo pipefail
python -m pip install -U pip
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f package.json ]; then npm ci; fi
期待される到達点
Local、Worktree、Cloud の使い分けができる。とくに 「今の手元の変更を汚したくないから Worktree」「長くて並列化したいから Cloud」 という判断ができるようになる。
よくある落とし穴
App を単なる GUI 版 CLI だと思い、Worktree と Automations を使わないこと。あるいは Cloud で依存不足に悩みながら environment を定義しないことです。公式には Cloud environments が依存管理とツール追加の中核です。
練習問題と解答
Q. Worktree を選ぶべき典型場面は何か。
A. 現在のローカル変更を汚さずに、別の修正や調査を並行で走らせたいとき。Codex App は worktree を前提に並列スレッドを扱える。
Q. Cloud task でネットワークを必要とする場合、何を確認すべきか。
A. Setup script と agent internet access は別概念なので、環境設定側で internet access 方針を確認する必要がある。
公式リンク
Codex App
Codex App Features / Worktrees / Automations
Codex web / Cloud environments
Codex アプリのご紹介 日本語
どこからでも Codex を活用 日本語
⑤⑥AGENTS.mdとconfig.tomlで再現性と安全性を固める
学習目標
AGENTS.md の階層適用を理解し、プロジェクト規約を Codex へ埋め込む。さらに config.toml でモデル、approval policy、sandbox mode、network access を固定化し、安全な既定値を作る。
前提
CLI または IDE extension が動いていること。
時間配分
| パート | 分 |
|---|---|
| AGENTS.md の適用順序 | 35 |
| 実践用 AGENTS.md 作成 | 45 |
| config.toml の重要キー | 55 |
| sandbox / approvals の検証 | 55 |
| 失敗ケースのレビュー | 50 |
ハンズオン演習
AGENTS.mdを repo root に作る。Codex は作業前に AGENTS.md を読み、~/.codex、repo root、さらに深いディレクトリの順に適用する。より具体的な場所の指示が優先される。
サンプル AGENTS.md
mdコピーする# Project instructions
## Development workflow
- Before editing files, explain the plan in 3–5 steps.
- Prefer the smallest change that fixes the issue.
- After editing, run the narrowest useful verification command.
## Code standards
- Preserve existing naming unless there is a bug or strong readability reason.
- Keep comments bilingual only when the surrounding file is bilingual.
- Do not rewrite unrelated files.
## Review guidelines
- Treat auth, secrets, logging, and migrations as high-risk areas.
- Call out missing tests before suggesting broad refactors.
## Commands
- Backend tests: pytest -q
- Frontend tests: npm test -- --runInBand
- Lint: ruff check . && npm run lint
- グローバル設定用
~/.codex/config.tomlを作る。公式の基本例では、既定モデルはgpt-5.5、承認はon-request、sandbox はworkspace-writeが代表例として示されている。
tomlコピーするmodel = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
- ネットワークを限定的に許可したい例を追加する。
workspace-writeではネットワークは既定オフで、必要なら有効化し、さらにnetwork_proxyでドメインごとのポリシーを掛けられる。
tomlコピーする[sandbox_workspace_write]
network_access = true
[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }
- CLI セッションから確認する。
bashコピーするcodex -c 'sandbox_workspace_write.network_access=true'
- 安全境界をローカルで再現確認する。公式には
codex sandbox macos/linux/windows系コマンドが案内されている。
bashコピーする# Linux の例
codex sandbox linux bash -lc 'echo hello'
期待される到達点
個々のプロンプトに毎回ルールを書かなくても、Codex が 「この repo ではどう振る舞うべきか」 を継続的に理解できるようになる。安全面では、危険な編集やネットワーク利用を既定で抑えた状態を構築できる。
よくある落とし穴
AGENTS.md を長大なポリシー文書にしてしまうこと、workspace-write を「ネットワークまで全部許可される」と誤解すること、danger-full-access を常用することです。OpenAI は danger-full-access を高リスクとして扱っています。
練習問題と解答
Q. AGENTS.md はどのように優先されるか。
A. グローバルから repo root、さらに深い階層へと重ねられ、より具体的な場所の指示が優先される。
Q. workspace-write の既定でネットワークは使えるか。
A. 使えない。sandbox_workspace_write.network_access = true のように明示的に有効化する必要がある。
公式リンク
AGENTS.md guide
Prompting guide の AGENTS.md 解説
Config basics / Agent approvals & security
OpenAI における Codex の安全な運用 日本語
⑦⑩SkillsとPluginsで再利用可能な作業にする
学習目標
反復タスクを Skill として設計し、必要に応じて Plugin へ昇格させる判断基準を身につける。Skill の配置場所、起動条件、メタデータ、無効化設定まで扱う。
前提
AGENTS.md と config の基礎が済んでいること。
時間配分
| パート | 分 |
|---|---|
| Skill の概念整理 | 30 |
| Skill 雛形の作成 | 45 |
| repo-local / user-local 配置 | 35 |
| Skill 起動と検証 | 50 |
| Plugin への昇格判断 | 40 |
| 小さな Plugin 導入体験 | 40 |
ハンズオン演習
- repo-local の Skill ディレクトリを作る。Codex は repo / user / admin の複数場所から Skill を読む。repo では
.agents/skillsをカレント directory から repo root まで探索する。user 向けは$HOME/.agents/skillsである。
bashコピーするmkdir -p .agents/skills/release-checklist
SKILL.mdを作る。公式では front matter にnameとdescriptionが必須。scripts/、references/、assets/、agents/は任意。
mdコピーする---
name: release-checklist
description: Validate a repository before release. Trigger only for release prep, pre-merge verification, or shipping checklists.
---
When this skill is selected:
1. Check git status and current branch.
2. Run the smallest reliable test suite first.
3. Summarize release blockers under headings: tests, docs, versioning, changelog.
4. Do not make release commits unless explicitly asked.
- 明示呼び出しと暗黙呼び出しを試す。CLI/IDE では
/skillsまたは$で mention でき、暗黙呼び出しはdescriptionに依存する。
textコピーする$release-checklist を使って、この repo の出荷前確認をして。
- Skill を一時無効化する。
[[skills.config]]でenabled = falseにできる。
tomlコピーする[[skills.config]]
path = "/absolute/path/to/.agents/skills/release-checklist/SKILL.md"
enabled = false
- Plugin を導入する。CLI では
codex起動後に/pluginsを開いてインストールできる。Plugin は Skill や app integration、MCP config を配布単位としてまとめるもので、まずは local skill、共有したくなったら plugin、という順が公式の勧め方です。
textコピーする/plugins
期待される到達点
Skill と Plugin の違いを説明でき、「自分だけの作業手順」 を Skill として保存し、「チーム配布したい作業手順」 を Plugin にする、という判断ができる。
よくある落とし穴
Skill を大きくしすぎて何にでも反応するようにしてしまうこと、description を曖昧に書いて暗黙起動が暴発すること、いきなり Plugin を作ろうとすることです。公式は Plugin より先に local skill を成熟させる流れを示しています。
練習問題と解答
Q. Skill の必須ファイルは何か。
A. SKILL.md。その中に name と description を含む必要がある。
Q. Plugin を作る前に Skill から始めるべきなのはなぜか。
A. 公式が、個人ワークフローや単一 repo の段階では local skill を推奨し、共有・配布段階で plugin に昇格させる設計を示しているため。
公式リンク
Agent Skills
Build plugins / Plugins overview
Using skills to accelerate OSS maintenance
Codex 概要 日本語
⑧Subagentsで調査・実装を並列化する
学習目標
Subagents を「勝手に増殖する自動魔法」ではなく、明示的に依頼したときだけ動く並列化手段として理解する。custom agent ファイルを使った専門分担も試す。
前提
単一エージェントでのタスク分解経験。
時間配分
| パート | 分 |
|---|---|
| Subagents の仕組み | 30 |
| 明示的 spawn 演習 | 50 |
| built-in agents と custom agents | 60 |
| custom agent ファイル作成 | 50 |
| 親子 sandbox の理解 | 25 |
| まとめ | 25 |
ハンズオン演習
- まずは明示的 fan-out を試す。Subagents は明示的に依頼したときだけ spawn され、トークン消費は増える。
textコピーするこのブランチを main と比較し、以下の観点ごとに 1 agent ずつ spawn して、全員の結果を待ってから統合レポートを出して。
- セキュリティ
- バグ
- テスト欠落
- 保守性
.codex/agents/に custom agent を作る。公式ではname、description、developer_instructionsが必須。 omit した項目は親セッションから継承される。
bashコピーするmkdir -p .codex/agents
tomlコピーする# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, regressions, and missing tests.
Do not propose style-only comments unless they hide a real bug.
"""
tomlコピーする# .codex/agents/pr-explorer.toml
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless explicitly asked.
"""
- オーケストレーションプロンプトを試す。これは公式の PR review 例を学習用に簡略化した形です。
textコピーするこのブランチを main と比較してレビューして。
pr_explorer に影響範囲のコード経路を整理させ、
reviewer に重大なリスクを洗い出させ、
最後に親エージェントが統合サマリーを作って。
/agentでスレッド切替を確認する。CLI では subagent のアクティビティ確認ができる。
期待される到達点
レビュー観点、調査観点、実装観点を分離した 「専門家チームとしての Codex」 を運用できるようになる。特に、親エージェントが何を統合すべきかを先に決める癖がつく。
よくある落とし穴
Subagents を明示せず「たくさん並列でやって」と曖昧に頼むこと、custom agent を何でも屋にしてしまうこと、親タスクよりも子タスクの説明が長くなり統合不能になることです。親 sandbox を継承する点も忘れやすいです。
練習問題と解答
Q. Subagents はいつ spawn されるか。
A. 明示的に依頼したときだけ。自動ではない。
Q. child agent の sandbox はどこから来るか。
A. 基本は親の現在の sandbox を継承する。個別 custom agent で override も可能。
公式リンク
Subagents
Codex Models
Codex 概要 日本語
OpenAI における Codex の安全な運用 日本語
⑨MCPで外部ツールと文脈をつなぐ
学習目標
MCP の役割、STDIO と Streamable HTTP の違い、接続設定、tool approval mode、enabled/disabled tools の考え方を理解する。
前提
認証情報を環境変数で扱えること。外部ツール連携のリスクを理解していること。
時間配分
| パート | 分 |
|---|---|
| MCP の概念整理 | 30 |
| Streamable HTTP 設定 | 50 |
| STDIO 設定 | 45 |
| ツール範囲と approval mode | 45 |
| 実タスク演習 | 40 |
| まとめ | 30 |
ハンズオン演習
- HTTP 型 MCP の設定を書く。Codex は CLI と IDE extension で MCP server をサポートする。HTTP 型では
url、bearer_token_env_var、http_headers、enabled_tools、default_tools_approval_modeなどが使える。
tomlコピーする[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
default_tools_approval_mode = "prompt"
enabled = true
- Chrome DevTools 型の例を追加する。公式例ではローカル HTTP MCP に対し、
enabled_toolsと per-tool approval override を設定している。
tomlコピーする[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
- OAuth 対応サーバならログインを行う。公式には
codex mcp login <server-name>が案内されている。
bashコピーするcodex mcp login figma
- STDIO 型の意味を理解する。STDIO では
command、args、env、env_vars、cwdなどを使う。 - 安全なタスクを試す。
textコピーするchrome_devtools を使って local preview を開き、トップページのスクリーンショットを撮り、文言崩れがないか確認して。
期待される到達点
MCP を 「AI に外部ツールを開放するための接続面」 として扱え、サーバ追加時に必要な設定項目と危険点を説明できる。特に「最初は enabled_tools を絞る」「approval_mode は prompt から始める」という設計判断ができる。
よくある落とし穴
ツールを全部有効にしておけば便利だと思うこと、OAuth や bearer token の保管方針を曖昧にすること、MCP と Plugin の違いを混同することです。Plugin は配布単位、MCP は接続面です。
練習問題と解答
Q. HTTP 型 MCP で OAuth が必要なとき、どのコマンドが案内されているか。
A. codex mcp login <server-name>。
Q. enabled_tools と disabled_tools を併用する主目的は何か。
A. 接続先サーバの全ツールを無差別に開放せず、必要な操作だけを露出させるため。公式設定キーとして用意されている。
公式リンク
Model Context Protocol
Configuration Reference の MCP キー一覧
Codex 概要 日本語
どこからでも Codex を活用 日本語
⑪⑫⑬app-server、SDK、GitHub Actionで組み込みと自動化へ進む
学習目標
app-server の位置づけ、SDK の基本 API、GitHub Action を使った安全な CI 実行、non-interactive 運用の注意点を理解する。
前提
Python 3.10+ か Node 18+ のいずれか、GitHub Actions の基礎。
時間配分
| パート | 分 |
|---|---|
| app-server の概念 | 30 |
| SDK でのスクリプト実行 | 60 |
| app-server JSON-RPC 体験 | 40 |
| GitHub Action 実装 | 70 |
| non-interactive セキュリティ確認 | 40 |
ハンズオン演習
- Python SDK を入れる。Python SDK は local Codex app-server を JSON-RPC で制御する。Python 3.10+ が必要。
bashコピーするpip install openai-codex
- 最小スクリプトを実行する。
pythonコピーするfrom openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(
model="gpt-5.4",
sandbox=Sandbox.workspace_write,
)
result = thread.run("Make a plan to diagnose and fix the CI failures")
print(result.final_response)
- 1 スレッドの継続と read-only review を試す。Python SDK では turn ごとに sandbox を切り替えられる。
pythonコピーするfrom openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
thread.run("Fix the failing test with the smallest safe change.")
review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)
print(review.final_response)
- app-server の最小起動を理解する。app-server は rich client を支える JSON-RPC interface で、CLI の自動化や CI なら SDK が推奨される。
stdioが既定の transport。
bashコピーするcodex app-server
- GitHub Action を追加する。公式 Action は
openai/codex-action@v1で、CLI インストール、Responses API proxy 起動、codex exec実行をまとめる。公式例では checkout job をcontents: readにし、別 job でコメント投稿権限を持たせている。
yamlコピーするname: codex-pr-review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
codex:
runs-on: ubuntu-latest
permissions:
contents: read
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
steps:
- uses: actions/checkout@v5
with:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
fetch-depth: 0
persist-credentials: false
- name: Run Codex
id: run_codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt-file: .github/codex/prompts/review.md
output-file: codex-output.md
sandbox: read-only
safety-strategy: drop-sudo
post_feedback:
runs-on: ubuntu-latest
needs: codex
if: needs.codex.outputs.final_message != ''
permissions:
issues: write
pull-requests: write
steps:
- name: Post Codex feedback
uses: actions/github-script@v7
with:
github-token: ${{ github.token }}
script: |
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: process.env.CODEX_FINAL_MESSAGE,
});
env:
CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
- non-interactive のセキュリティ原則を確認する。GitHub Actions では API キーを job-level 環境変数で置くのではなく official action を使うことが推奨され、他の自動化環境でも
CODEX_API_KEYは単一のcodex exec呼び出しに限定すべきとされる。
bashコピーするCODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"
期待される到達点
ローカル SDK、自作 UI 向け app-server、CI 向け GitHub Action の位置づけを明確に説明できる。「SDK と app-server は内部ツール化」「GitHub Action は CI 自動化」 という使い分けが固まる。
よくある落とし穴
CI で plain CLI を直接インストールして API キーを広い環境変数に載せること、app-server を CI 向けと誤解すること、GitHub Actions の job 権限を広くしすぎることです。公式は CI では GitHub Action を使うよう案内しています。
練習問題と解答
Q. app-server と SDK の関係は何か。
A. Python SDK は local Codex app-server を JSON-RPC で制御する。
Q. GitHub Actions で OPENAI_API_KEY を job-level env に置くべきでない理由は何か。
A. 同じ job 内の build scripts、tests、dependency lifecycle hooks、または侵害された action から読み取られ得るため。
公式リンク
Codex App Server
Codex SDK
Codex GitHub Action / Non-interactive mode
GitHub を ChatGPT に接続 日本語
ChatGPT プランで Codex を使う 日本語
再利用できるテンプレート集
以下は、連載の中で何度も参照できる「読者がそのまま貼って試せる」最小テンプレートです。いずれも OpenAI の公式仕様に沿った形で整理していますが、パスやコマンドは受講者プロジェクトに合わせて調整してください。AGENTS.md は階層適用、config.toml は persistent settings、Skills は .agents/skills 構造、Subagents は .codex/agents/*.toml、MCP は mcp_servers.*、SDK は openai-codex、CI は openai/codex-action@v1 という設計が公式に示されています。
AGENTS.md テンプレート
mdコピーする# Project instructions
## Mission
- Prefer high-confidence, minimal changes.
- If the task is ambiguous, propose a short plan before editing.
## Workflow
- Explain the plan in 3 to 5 steps before changing files.
- Run the smallest useful verification command after edits.
- Summarize changed files, risks, and validation results.
## Safety
- Treat authentication, payments, migrations, secrets, and logging as high-risk.
- Do not add new dependencies unless explicitly requested.
- Do not edit deployment or infrastructure files unless the task clearly requires it.
## Review guidelines
- Flag correctness issues first.
- Then flag security issues.
- Then flag missing tests.
- Ignore style-only comments unless they hide a bug.
## Project commands
- Test: pytest -q
- Lint: ruff check .
- Format: ruff format .
config.toml の実践最小テンプレート
tomlコピーするmodel = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
[agents]
max_threads = 6
max_depth = 1
必要に応じてネットワーク制約を追加する場合の例です。 workspace-write でネットワークを使うには明示有効化が必要で、network_proxy は許可ドメイン制御を追加する機能です。
tomlコピーする[sandbox_workspace_write]
network_access = true
[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }
Skill テンプレート
textコピーする.agents/
└─ skills/
└─ release-checklist/
├─ SKILL.md
├─ scripts/
├─ references/
└─ assets/
mdコピーする---
name: release-checklist
description: Validate a repository before release. Trigger only for release preparation, shipping checks, or pre-merge verification.
---
1. Check git status and current branch.
2. Run the smallest reliable verification commands first.
3. Report blockers under: tests, docs, versioning, changelog.
4. Do not commit or tag unless explicitly instructed.
Subagents オーケストレーション例
textコピーするこのブランチを main と比較してレビューして。
pr_explorer を使って影響範囲とコード経路を整理し、
reviewer を使って correctness / security / missing tests の観点で重大事項を抽出し、
最後に親エージェントが結果を重複排除して統合サマリーを作成して。
対応する custom agent の例です。公式は .codex/agents/*.toml に name、description、developer_instructions を置く方式を案内しています。
tomlコピーする# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, regressions, and missing tests.
"""
MCP 接続例
tomlコピーする[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
tomlコピーする[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
default_tools_approval_mode = "prompt"
enabled = true
HTTP 型では url と認証、STDIO 型では command / args / env_vars が軸になります。OAuth が必要なサーバは codex mcp login <server-name> でログインします。
Python SDK スニペット
pythonコピーするfrom openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(
model="gpt-5.4",
sandbox=Sandbox.workspace_write,
)
result = thread.run("Make a plan to diagnose and fix the CI failures")
print(result.final_response)
app-server の最小接続スニペット
tsコピーするimport { spawn } from "node:child_process";
import readline from "node:readline";
const proc = spawn("codex", ["app-server"], {
stdio: ["pipe", "pipe", "inherit"],
});
const rl = readline.createInterface({ input: proc.stdout });
const send = (message: unknown) => {
proc.stdin.write(`${JSON.stringify(message)}\n`);
};
let threadId: string | null = null;
rl.on("line", (line) => {
const msg = JSON.parse(line) as any;
console.log("server:", msg);
if (msg.id === 1 && msg.result?.thread?.id && !threadId) {
threadId = msg.result.thread.id;
send({
method: "turn/start",
id: 2,
params: {
threadId,
input: [{ type: "text", text: "Summarize this repo." }],
},
});
}
});
send({
method: "initialize",
id: 0,
params: {
clientInfo: {
name: "my_product",
title: "My Product",
version: "0.1.0",
},
},
});
send({ method: "initialized", params: {} });
send({ method: "thread/start", id: 1, params: { model: "gpt-5.4" } });
app-server は JSON-RPC 2.0 ベースで、既定 transport は stdio です。WebSocket は実験的です。CI や自動化で Coding thread を回すだけなら、公式は SDK や GitHub Action を優先するよう勧めています。
GitHub Action 例
yamlコピーするname: codex-pr-review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
codex:
runs-on: ubuntu-latest
permissions:
contents: read
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
steps:
- uses: actions/checkout@v5
with:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
fetch-depth: 0
persist-credentials: false
- name: Run Codex
id: run_codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt-file: .github/codex/prompts/review.md
output-file: codex-output.md
sandbox: read-only
safety-strategy: drop-sudo
post_feedback:
runs-on: ubuntu-latest
needs: codex
if: needs.codex.outputs.final_message != ''
permissions:
issues: write
pull-requests: write
steps:
- name: Post Codex feedback
uses: actions/github-script@v7
with:
github-token: ${{ github.token }}
script: |
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: process.env.CODEX_FINAL_MESSAGE,
});
env:
CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
この構成は、Codex 実行 job には contents: read だけを与え、別 job にコメント権限を与える最小権限パターンです。公式は prompt か prompt-file のどちらか一方を使い、safety-strategy は既定の drop-sudo を維持するよう案内しています。
連載化の設計と学習タイムライン
このカリキュラムを日本語の技術ブログ連載として出すなら、「まず使える」「次に事故らない」「その後に広げる」 という編集順が最も読者にやさしいです。OpenAI のドキュメント構造も、Quickstart → Config / Security → Skills / MCP / Subagents → SDK / GitHub Action と、導入から拡張へ積み上がる形になっています。したがって、記事順は CLI → IDE → App/Cloud → AGENTS/config/security → Skills/Plugins → Subagents → MCP → SDK/GitHub Action が自然です。
ブログ記事としては、毎回同じ骨格に揃えると学習効率が上がります。各記事は、導入シナリオ、完成イメージ、前提、ハンズオン、差分確認、落とし穴、演習問題、次回予告 の順にすると、経験者読者でも飛ばし読みしやすくなります。さらに、すべての章で「最初の Git checkpoint」「変更後の検証」「安全設定の確認」を共通ルーチンにすると、Codex を使う作法そのものが定着します。これは OpenAI の Quickstart と security guidance の趣旨にも合っています。
推奨タイムラインは、週 2 コマで 4 週間、または集中的に 4 日間で 2 コマずつです。以下は 4 週間構成の例です。
07/1307/1507/1707/1907/2107/2307/2507/2707/2907/3108/0108/0308/0508/07CLI基礎と認証IDE extensionCodex AppとCloudAGENTS.mdとconfig/securitySkillsとPluginsSubagentsMCPapp-serverとSDKとCI基礎実務導入再利用と拡張組み込みと自動化Codex学習連載の推奨タイムラインコードを表示する
実務での優先学習パスは次の通りです。個人開発者 なら CLI → AGENTS/config → IDE → App → Skills → Subagents。チーム導入担当 なら CLI → AGENTS/config/security → Cloud → Plugins/MCP → GitHub Action。内製ツール担当 なら CLI → SDK → app-server → MCP → GitHub Action の順が効率的です。Cloud はバックグラウンド並列作業に強く、GitHub Action は repeatable CI tasks に強く、app-server は deep integration に向くため、最終到達点は役割ごとに異なります。
最後に、各記事には必ず「日本語公式ページ」と「英語一次仕様」を併記するのがよいです。読者は日本語で全体像を掴みつつ、詳細キーやコマンドは Developers docs へ遷移できます。OpenAI は日本語で Codex の概要、開始方法、アプリ紹介、安全運用、ChatGPT プラン上での利用案内を公開しているため、各記事末にそれらを再掲しておくと、学習導線が安定します。
コメント