自己の学習用に、Codexに記載してもらいました。
作成日: 2026-05-13 確認環境: codex-cli 0.130.0
このドキュメントは、Codex CLI を単なるチャットツールではなく、ローカルのコードベースを読み、編集し、コマンドを実行し、検証まで進める AI エージェントとして使うための実務メモです。
1. Codex CLI とは
Codex CLI は、ターミナル上で動く OpenAI のコーディングエージェントです。プロジェクトのファイルを読み、必要に応じて編集し、テストやビルドなどのコマンドを実行しながら、機能追加、バグ修正、コードレビュー、調査、ドキュメント作成を支援します。
公式ヘルプでは、Codex CLI はローカル環境で動作し、コードの読み取り、変更、コマンド実行を通じて開発を支援するコマンドラインツールと説明されています。現在の手元環境では、CLI の主な操作は codex、codex exec、codex review、codex mcp などのサブコマンドで行います。
2. 基本の起動
インストールは npm または Homebrew で行えます。
npm install -g @openai/codex
brew install codexプロジェクトのルートディレクトリで起動します。
cd /path/to/project
codex最初のプロンプトを指定して起動することもできます。
codex "このリポジトリの構成を調べて、主要な起動方法とテスト方法をまとめて"別ディレクトリを作業ルートにする場合は --cd を使います。
codex --cd /path/to/project " failing test を調べて直して "画像を渡したい場合は --image を使えます。
codex --image ./screenshot.png "この画面に合わせてフロントエンドを修正して"3. 認証
ログイン状態を確認します。
codex login status通常ログイン:
codex loginAPI キーを標準入力から渡す場合:
printenv OPENAI_API_KEY | codex login --with-api-keyアクセストークンを標準入力から渡す場合:
printenv CODEX_ACCESS_TOKEN | codex login --with-access-tokenデバイス認証を使う場合:
codex login --device-authログアウト:
codex logout4. AI エージェントとしての依頼の出し方
Codex CLI には、最終成果物、制約、検証方法を明確に渡すほど安定します。
良い依頼例:
このリポジトリでユーザー一覧 API の N+1 を直して。
既存の設計に合わせること。
関連テストを追加または更新して、最後に実行したコマンドと結果を報告して。調査だけ依頼する例:
まだ編集しないで。
ログイン処理の入口、認証状態の保存場所、テスト方法を調べて説明して。レビューを依頼する例:
未コミット差分をレビューして。
バグ、回帰リスク、テスト不足を優先して、ファイルと行番号付きで指摘して。長い作業を依頼する例:
CSV インポート機能を追加して。
既存 UI のデザインに合わせること。
バリデーション、エラー表示、ユニットテストを含めること。
実装後に lint と test を実行して。5. サンドボックスと承認
Codex CLI は、AI が実行する操作の範囲をサンドボックスと承認ポリシーで制御できます。
サンドボックス指定:
codex --sandbox read-only
codex --sandbox workspace-write
codex --sandbox danger-full-access手元の codex-cli 0.130.0 では、指定可能な値は次の 3 つです。
| モード | 意味 |
|---|---|
read-only | 読み取り中心。調査やレビュー向き |
workspace-write | 作業ディレクトリへの書き込みを許可。通常の実装作業向き |
danger-full-access | 広いアクセスを許可。信頼できる環境以外では避ける |
承認ポリシー指定:
codex --ask-for-approval untrusted
codex --ask-for-approval on-request
codex --ask-for-approval never| ポリシー | 意味 |
|---|---|
untrusted | 信頼済みの読み取り系コマンド以外は承認を求める |
on-request | AI が必要に応じて承認を求める |
never | 承認を求めない。失敗はそのまま AI に返る |
通常の開発では、次の組み合わせが扱いやすいです。
codex --sandbox workspace-write --ask-for-approval on-request安全に調査だけさせたい場合:
codex --sandbox read-only --ask-for-approval untrusted--dangerously-bypass-approvals-and-sandbox は、確認なしでサンドボックスも迂回する危険なオプションです。外部で強く隔離された環境以外では使わないでください。
6. 非対話実行
codex exec は、Codex を非対話で実行します。CI、スクリプト、定型調査に向いています。
codex exec "このリポジトリのテストコマンドを特定して実行し、失敗があれば原因を説明して"標準入力からプロンプトを渡す場合:
printf '%s\n' "README を日本語に要約して" | codex exec -セッションを保存せず一回限りで実行:
codex exec --ephemeral "未使用の依存関係がないか調べて"JSONL イベント出力:
codex exec --json "型エラーを調べて"最後の応答をファイルに保存:
codex exec -o ./codex-result.md "この変更のリスクをまとめて"Git リポジトリ外で実行する場合:
codex exec --skip-git-repo-check "このディレクトリのファイル構成を整理して"最終応答の形を JSON Schema で固定したい場合:
codex exec --output-schema ./schema.json "調査結果を JSON で返して"ユーザー設定や execpolicy ルールの影響を切り分けたい場合:
codex exec --ignore-user-config "最小設定で再現確認して"
codex exec --ignore-rules "ルールを読み込まずにヘルプだけ確認して"7. コードレビュー
未コミット差分をレビュー:
codex review --uncommitted特定ブランチとの差分をレビュー:
codex review --base main特定コミットをレビュー:
codex review --commit <SHA>レビュー観点を追加:
codex review --uncommitted "セキュリティ、データ破壊、テスト不足を優先して見て"8. セッションの再開と分岐
直近セッションを再開:
codex resume --last過去セッションから選んで再開:
codex resume過去セッションを分岐して別案を試す:
codex fork --last分岐は、ある実装方針を残したまま別アプローチを試したい場合に便利です。
現在の作業ディレクトリ以外も含めてセッションを探す場合:
codex resume --all非対話実行のセッションも再開候補に含める場合:
codex resume --include-non-interactive9. モデルと推論量
モデルは --model で指定できます。
codex --model gpt-5.3-codex設定ファイルや一時オプションで値を上書きする場合は -c を使います。
codex -c model='"gpt-5.3-codex"'OpenAI のモデルページでは、Codex 系モデルは長いコーディング作業やエージェント的なソフトウェア開発向けに説明されています。手元の CLI が利用できるモデルは契約、ログイン方法、組織設定によって変わるため、利用可能性は実環境で確認してください。
ローカルのオープンソースプロバイダーを使う場合は --oss と --local-provider を使います。手元の CLI では lmstudio と ollama を指定できます。
codex --oss
codex --oss --local-provider ollama10. 設定ファイル
CLI の設定は通常 ~/.codex/config.toml に保存されます。一時的に設定を上書きするには -c を使います。
例:
codex -c model='"gpt-5.3-codex"' \
-c shell_environment_policy.inherit='"all"'ネストしたキーはドット区切りで指定できます。
codex -c features.some_feature=trueプロファイルを使う場合:
codex --profile work11. MCP 連携
MCP は、Codex に外部システムやドキュメントソースを接続する仕組みです。
MCP サーバー一覧:
codex mcp list追加:
codex mcp add <name> --url <url>詳細確認:
codex mcp get <name>削除:
codex mcp remove <name>MCP の認証:
codex mcp login <name>
codex mcp logout <name>例: OpenAI developer docs MCP を追加する場合:
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp12. スキル
スキルは、Codex に特定分野の作業手順や判断基準を追加するための仕組みです。毎回長い指示を書かなくても、画像生成、OpenAI 公式ドキュメント確認、プラグイン作成、独自ワークフローなどを再利用しやすくできます。
典型的には、各スキルは SKILL.md を中心に構成されます。そこに、いつ使うか、どの手順で進めるか、参照すべきテンプレートやスクリプトがあればその場所を書きます。
配置例:
~/.codex/skills/
imagegen/
SKILL.md
references/
scripts/
openai-docs/
SKILL.md依頼時に明示する場合は、スキル名を含めると意図が伝わりやすくなります。
$imagegen を使って、この記事のアイキャッチ画像を作って
$openai-docs を使って、最新の Responses API の使い方を確認して
このリポジトリ用のレビュー手順を skill として整理してスキルを作るときは、汎用的な知識を詰め込みすぎるより、特定の作業で迷わないための手順に絞ると扱いやすいです。
おすすめの SKILL.md 構成:
---
name: "review-checklist"
description: "このリポジトリのコードレビュー観点を適用する"
---
# Review Checklist
## When to use
- 未コミット差分や PR 差分をレビューするとき
## Workflow
1. 差分の範囲を確認する
2. バグ、回帰、セキュリティ、テスト不足を優先して見る
3. ファイル名と行番号付きで指摘する
4. 問題がなければ残るリスクだけを短く報告する注意点として、手元の codex-cli 0.130.0 では、codex skill のような専用サブコマンドは確認できませんでした。スキルの読み込み方法や配置場所は利用環境によって変わる可能性があるため、チームで使う場合は実際の Codex 環境に合わせて運用ルールを決めてください。
13. Web 検索
Web 検索を使う場合は --search を付けます。
codex --search "最新の公式ドキュメントを確認して、この SDK の使い方を説明して"ライブ情報、公式ドキュメント、ライブラリの最新仕様、価格、リリース情報などは変わるため、必要なときだけ明示的に有効化すると扱いやすいです。
14. リポジトリ内の指示ファイル
Codex には、リポジトリ内の指示ファイルを通じて作業ルールを伝えると効果的です。OpenAI の Codex 紹介記事では、AGENTS.md を使ってリポジトリのナビゲーション方法、テストコマンド、プロジェクト標準を伝えられると説明されています。
おすすめの AGENTS.md 構成:
# AGENTS.md
## Project Overview
- このプロジェクトの目的
- 主要ディレクトリ
## Setup
- 依存関係のインストール方法
- 開発サーバーの起動方法
## Test
- unit test
- lint
- typecheck
- e2e
## Coding Rules
- 命名規則
- 既存パターン
- 触ってはいけない領域
## Review Rules
- 重点的に見るべきリスク
- セキュリティや互換性の注意点対話中に新規作成する場合は、スラッシュコマンドからひな形を生成できます。
/init15. 対話中のスラッシュコマンド
Codex CLI の対話画面では、/ で始まるコマンドを使って、モデル、権限、差分確認、セッション操作などを切り替えられます。
| コマンド | 用途 |
|---|---|
/permissions | 承認や権限をセッション中に調整する |
/model | 使用モデルや推論量を切り替える |
/status | 現在のモデル、承認設定、トークン使用量などを確認する |
/diff | Codex が加えた変更差分を確認する |
/review | 作業ツリーのレビューを依頼する |
/compact | 長くなった会話を要約してコンテキストを空ける |
/resume | 保存済みセッションを再開する |
/fork | 現在の会話を分岐して別案を試す |
/mcp | 利用可能な MCP ツールを確認する |
/mention | ファイルやフォルダを会話に添付する |
/debug-config | 設定レイヤーや管理ポリシーを診断する |
/quit / /exit | CLI を終了する |
16. 実務ワークフロー
新機能を作る
codex --sandbox workspace-write --ask-for-approval on-request依頼文:
注文履歴画面にステータスフィルタを追加して。
既存の状態管理と UI コンポーネントに合わせて。
必要なテストを追加し、最後に実行した検証コマンドを報告して。バグを直す
この失敗ログをもとに原因を調べて修正して。
まず再現方法を確認し、最小限の修正で直して。
修正後に該当テストを実行して。リファクタリングする
このモジュールの重複を減らして。
外部 API と既存テストの期待値は変えないこと。
差分が大きくなる場合は、先に計画を出してから進めて。ドキュメントを書く
この機能の利用者向け README を作成して。
インストール、設定、よくある失敗、サンプルコマンドを含めて。調査だけさせる
codex --sandbox read-only "このコードベースの認証処理を調べて、編集せずに説明して"17. 依頼時のコツ
Codex に渡すとよい情報:
- 目的: 何を達成したいか
- 成果物: ファイル、機能、テスト、ドキュメントなど
- 制約: 触ってよい範囲、既存設計、互換性、性能要件
- 検証: 実行すべきテスト、ビルド、lint
- 報告形式: 最後に何を説明してほしいか
避けたい依頼:
いい感じに直して改善した依頼:
ログイン後に `/dashboard` へ遷移しない問題を調べて修正して。
認証状態の保存処理とルーティングを中心に見て。
修正後に関連する unit test を実行して、失敗が残る場合は理由を報告して。18. 安全運用
Git 管理されたディレクトリで使う:
git status作業前に差分を確認:
git diff重要な作業では、Codex にも「既存の未コミット変更を消さないで」と明示するとよいです。
危険な操作には注意してください。
rm -rfgit reset --hardgit clean -fd- 本番 DB への接続
- 秘密情報の表示や貼り付け
- 広いネットワークアクセス
danger-full-access--dangerously-bypass-approvals-and-sandbox
19. トラブルシュート
PATH 警告が出る
この環境では一部コマンドで次の警告が出ることがあります。
WARNING: proceeding, even though we could not update PATH: Operation not permittedコマンド自体が成功していれば、警告として扱えます。PATH 更新が必要な場合は、シェル設定ファイルを確認してください。
サンドボックスで失敗する
依存関係のダウンロード、外部ネットワーク、作業ディレクトリ外への書き込みは失敗する場合があります。
対応:
codex --sandbox workspace-write --ask-for-approval on-requestまたは、必要な追加ディレクトリを明示します。
codex --add-dir /path/to/extra-dirGit リポジトリ外で実行できない
非対話実行では --skip-git-repo-check を使えます。
codex exec --skip-git-repo-check "このフォルダを整理して"古い記事とオプション名が違う
公式ヘルプ記事には古い --auto-edit や --full-auto の説明が残っている場合があります。手元の codex-cli 0.130.0 では、実際のヘルプに出る --sandbox と --ask-for-approval を優先してください。
確認コマンド:
codex --help
codex exec --help
codex review --help20. 補助サブコマンド
開発作業以外にも、更新、補完、差分適用、プラグイン、デスクトップアプリ、Codex Cloud 用のサブコマンドがあります。
| コマンド | 用途 |
|---|---|
codex update | Codex CLI を最新版へ更新する |
codex completion | bash、zsh、fish などのシェル補完を生成する |
codex apply <TASK_ID> | Codex agent が生成した差分をローカル作業ツリーへ適用する |
codex sandbox | macOS、Linux、Windows のサンドボックス内でコマンドを実行する |
codex plugin | Codex プラグインやマーケットプレイスを管理する |
codex app | Codex デスクトップアプリを開く |
codex cloud | Codex Cloud のタスク確認、差分表示、ローカル適用を行う |
21. よく使うコマンド一覧
# インストール
npm install -g @openai/codex
brew install codex
# 起動
codex
# プロンプト付き起動
codex "このリポジトリを説明して"
# 作業ルート指定
codex --cd /path/to/project
# 画像付き
codex --image ./screenshot.png "この画面に合わせて修正して"
# モデル指定
codex --model gpt-5.3-codex
# OSS プロバイダー
codex --oss --local-provider ollama
# サンドボックス指定
codex --sandbox workspace-write
# 承認ポリシー指定
codex --ask-for-approval on-request
# Web 検索を有効化
codex --search
# 非対話実行
codex exec "テストを実行して失敗を直して"
# JSON Schema で出力制約
codex exec --output-schema ./schema.json "結果を JSON で返して"
# JSONL 出力
codex exec --json "型エラーを調べて"
# レビュー
codex review --uncommitted
# セッション再開
codex resume --last
codex resume --all
codex resume --include-non-interactive
# 差分を適用
codex apply <TASK_ID>
# 更新
codex update
# シェル補完
codex completion bash
# サンドボックス内でコマンド実行
codex sandbox macos ls
# プラグイン
codex plugin marketplace add <SOURCE>
# デスクトップアプリ
codex app
# Codex Cloud
codex cloud
# MCP 一覧
codex mcp list
# バージョン確認
codex --version22. 参照情報
- OpenAI Help Center: Codex CLI Getting Started
- OpenAI Help Center: Codex CLI and Sign in with ChatGPT
- OpenAI Help Center: Using Codex with your ChatGPT plan
- OpenAI: Introducing Codex
- OpenAI: Introducing upgrades to Codex
- OpenAI Developers: Codex use cases
- OpenAI Developers: Codex Quickstart
- OpenAI Developers: Codex configuration reference
- OpenAI Developers: Slash commands in Codex CLI
- OpenAI API Models: GPT-5.3-Codex
- OpenAI API Models: codex-mini-latest
コメント