Codex CLI を AI エージェントとして使うための実務ドキュメント

作成日: 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 login

API キーを標準入力から渡す場合:

printenv OPENAI_API_KEY | codex login --with-api-key

アクセストークンを標準入力から渡す場合:

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

デバイス認証を使う場合:

codex login --device-auth

ログアウト:

codex logout

4. AI エージェントとしての依頼の出し方

Codex CLI には、最終成果物、制約、検証方法を明確に渡すほど安定します。

要求仕様書や基本設計書から依頼する場合は、単に「この仕様で作成」と投げるより、仕様の場所、実装範囲、確認してほしい観点、実装前に止まる条件を明示します。特に業務ルール、受け入れ条件、既存仕様との互換性、テスト方法を先に伝えると、AI エージェントが勝手に仕様を補完しにくくなります。

仕様書は Markdown でなくても依頼できます。Codex が読み取れる場所にあるファイルであれば、テキスト、HTML、JSON、YAML、CSV、ソースコード内のコメント、README、OpenAPI 定義、SQL、ログなども対象にできます。PDF、Word、Excel、画像化された設計書は、環境やツールによって直接読める場合と、テキスト化やスクリーンショット添付が必要な場合があります。重要なのは形式ではなく、「どのファイルを仕様の根拠にするか」「どこまで実装してよいか」「不明点があれば止まるか」を明示することです。

要求仕様・基本設計から依頼するときの基本形:

入力: docs/requirements/order-filter.md、docs/design/order-filter-basic-design.md
作業: 既存コードを確認し、実装対象、影響範囲、不明点、テスト観点を整理すること。
制約: 要求仕様または基本設計と既存仕様が矛盾する場合、実装に入らず先に報告すること。
実装: 問題がなければ、既存設計に合わせて実装し、関連テストを追加または更新すること。
報告: 実行した検証コマンド、結果、残課題を最後にまとめること。

Markdown 以外の仕様を指定する例:

仕様根拠: spec/order-filter.html、api/openapi.yaml
さらに data/order_status.csv のステータス一覧を正とする。
確認事項: 仕様、API 定義、既存実装が矛盾する場合は、実装前に差分を報告すること。
実装方針: 問題がなければ、既存 UI と API 設計に合わせて実装すること。

PDF や Word など、読み取りに不安がある形式を使う場合:

入力: docs/basic-design.pdf
最初の確認: この PDF を読めるか確認すること。
読める場合: 画面項目、API、エラー処理、受け入れ条件を抽出し、実装計画を作ること。
読めない場合: 勝手に推測せず、必要な変換方法または追加で必要な情報を報告すること。
制約: コード編集なし。

まだ実装せず、仕様の読み解きだけを依頼する例:

制約: まだ編集しない。
入力: docs/requirements/payment-cancel.md、docs/design/payment-cancel-basic-design.md
調査: 現在のコードベースで、影響を受ける画面、API、DB、テストを確認すること。
出力: 受け入れ条件ごとに、必要な実装とテスト観点を表でまとめること。
補足: 仕様が曖昧な点や、実装前に確認すべき質問も列挙すること。

基本設計に沿って実装まで依頼する例:

入力: docs/design/user-role-basic-design.md
目的: ユーザー権限管理の実装。
対象外は、監査ログの永続化と管理画面の一括更新。
既存の認証・認可設計、UI コンポーネント、テスト方針に合わせること。
制約: 基本設計にない挙動は追加しないこと。
検証: 実装後に unit test と lint を実行すること。
報告: 失敗が残る場合は理由を説明すること。

良い依頼例:

目的: このリポジトリでユーザー一覧 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 つです。

承認ポリシー指定:

codex --ask-for-approval untrusted
codex --ask-for-approval on-request
codex --ask-for-approval never

通常の開発では、次の組み合わせが扱いやすいです。

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-interactive

9. モデルと推論量

モデルは --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 ollama

10. 設定ファイル

CLI の設定は通常 ~/.codex/config.toml に保存されます。プロジェクト単位の設定を置きたい場合は、信頼済みプロジェクトの .codex/config.toml にプロジェクトスコープの上書きを置けます。

一時的に設定を上書きするには -c を使います。値は TOML として解釈されるため、文字列は引用符を含めて渡します。

codex -c model='"gpt-5.3-codex"' \
  -c approval_policy='"on-request"' \
  -c sandbox_mode='"workspace-write"'

ネストしたキーはドット区切りで指定できます。

codex -c features.fast_mode=true
codex -c shell_environment_policy.inherit='"all"'

よく使う基本設定例:

# ~/.codex/config.toml
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
model_verbosity = "medium"

sandbox_mode = "workspace-write"
approval_policy = "on-request"

web_search = "cached"
file_opener = "vscode"
check_for_update_on_startup = true

代表的な設定項目:

サンドボックスと承認の設定例:

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
writable_roots = ["/Users/toru/WorkSpace/shared"]
network_access = false

ネットワークアクセスを必要に応じて許可する場合は、作業内容と接続先を確認してから有効化します。

[sandbox_workspace_write]
network_access = true

用途別にプロファイルを分ける例:

profile = "work"

[profiles.work]
model = "gpt-5.3-codex"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "cached"

[profiles.review]
model = "gpt-5.3-codex"
sandbox_mode = "read-only"
approval_policy = "untrusted"
model_reasoning_effort = "high"

[profiles.oss]
oss_provider = "ollama"
sandbox_mode = "workspace-write"

プロファイルを起動時に指定します。

codex --profile review
codex exec --profile work "目的: この変更のリスク確認。出力: 懸念点と確認方法。"

MCP サーバーを設定ファイルに書く例:

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

[mcp_servers.localSpecSearch]
command = "node"
args = ["./tools/mcp/spec-search.js"]
cwd = "/Users/toru/codex-cli-agent-docs"
startup_timeout_sec = 10
tool_timeout_sec = 60

Bearer token が必要な MCP サーバーでは、値そのものではなく環境変数名を設定します。

[mcp_servers.internalDocs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "INTERNAL_MCP_TOKEN"

スキルを設定ファイルで有効化・無効化する例:

[[skills.config]]
path = "/Users/toru/.codex/skills/requirements-to-plan"
enabled = true

[[skills.config]]
path = "/Users/toru/.codex/skills/old-skill"
enabled = false

シェル環境変数の引き継ぎを調整する例:

[shell_environment_policy]
inherit = "core"
exclude = ["*_SECRET", "*_TOKEN"]
set = { NODE_ENV = "development" }

プロジェクト内の指示ファイルを調整する例:

project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md", "README.md"]

Web 検索ツールを細かく制御する例:

web_search = "cached"

[tools.web_search]
context_size = "medium"
allowed_domains = ["developers.openai.com", "platform.openai.com"]

設定の確認や切り分けには、ヘルプ、MCP 詳細、対話中の /status、/debug-config を使います。

codex --help
codex mcp get openaiDeveloperDocs --json

VS Code や Cursor で TOML の補完や診断を使いたい場合は、公式の JSON Schema を指定できます。

#:schema https://developers.openai.com/codex/config-schema.json

注意点として、設定キーは Codex CLI のバージョンで変わることがあります。古い設定名が残っている場合は、現在の codex --help と公式の config reference を優先します。

11. MCP 連携

MCP は Model Context Protocol の略で、Codex に外部システム、社内ツール、ドキュメント、データソース、専用 API などを接続するための仕組みです。通常のファイル読み取りや Web 検索だけでは足りない情報を、MCP サーバー経由で Codex から利用できるようにします。

たとえば、公式ドキュメント検索、社内ナレッジ、チケット管理、仕様書データベース、GitHub、デザイン管理ツール、ローカルで動く独自検索サーバーなどを接続できます。MCP は「Codex が何を見に行けるか」「どのツールを呼べるか」を増やすための拡張ポイントです。

MCP サーバーには大きく 2 種類あります。

MCP サーバー一覧を確認します。

codex mcp list

特定の MCP サーバー設定を確認します。JSON で確認したい場合は --json を付けます。

codex mcp get <name>

codex mcp get <name> --json

HTTP MCP サーバーを追加する基本形:

codex mcp add <name> --url <url>

例: OpenAI developer docs MCP を追加する場合:

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

Bearer token が必要な HTTP MCP サーバーでは、トークンを直接コマンドに書かず、環境変数名を指定します。

export INTERNAL_MCP_TOKEN="..."
codex mcp add internalDocs --url https://mcp.example.com/mcp --bearer-token-env-var INTERNAL_MCP_TOKEN

stdio MCP サーバーを追加する基本形:

codex mcp add <name> -- <command> <args>

例: Node.js で作ったローカル MCP サーバーを登録する場合:

codex mcp add localSpecSearch -- node ./tools/mcp/spec-search.js

例: 環境変数を渡して stdio MCP サーバーを起動する場合:

codex mcp add jiraMcp --env JIRA_BASE_URL=https://jira.example.com --env JIRA_TOKEN=$JIRA_TOKEN -- node ./tools/mcp/jira.js

認証が必要な MCP サーバーでは、ログインとログアウトを使います。OAuth などの認証フローを持つサーバーでは、初回利用前にログインが必要になることがあります。

codex mcp login <name>
codex mcp logout <name>

不要になった MCP サーバーは削除できます。

codex mcp remove <name>

MCP を使って依頼する例:

利用ツール: $openaiDeveloperDocs
目的: Codex CLI の最新設定項目の確認。
確認対象: この記事の「サンドボックスと承認」セクションに古い記述がないか。

利用ツール: $localSpecSearch
目的: 注文ステータスフィルタの要求仕様の検索。
出力: 見つかった仕様を根拠に、既存実装との差分とテスト観点を整理。
制約: コード編集なし。

MCP がうまく使えない場合は、まず一覧、詳細、認証状態、設定ファイルを確認します。

codex mcp list
codex mcp get <name> --json
codex mcp login <name>

注意点として、MCP は Codex に見える情報や実行できる操作を増やします。社内情報、個人情報、秘密情報、書き込み系ツールを接続する場合は、認証、権限、利用範囲、ログに残る情報を確認してから使います。

12. スキル

スキルは、Codex に特定分野の作業手順や判断基準を追加するための仕組みです。毎回長い指示を書かなくても、画像生成、OpenAI 公式ドキュメント確認、プラグイン作成、独自ワークフローなどを再利用しやすくできます。

典型的には、各スキルは SKILL.md を中心に構成されます。そこに、いつ使うか、どの手順で進めるか、参照すべきテンプレートやスクリプトがあればその場所を書きます。

配置例:

~/.codex/skills/
  imagegen/
    SKILL.md
    references/
    scripts/
  openai-docs/
    SKILL.md

本文で出てくるスキル名の意味は次のとおりです。実際に使えるスキル名や配置場所は環境によって変わるため、手元の ~/.codex/skills/ やプロジェクト内のスキル定義を確認します。

自分でスキルを追加する基本手順:

mkdir -p ~/.codex/skills/design-implementation
vi ~/.codex/skills/design-implementation/SKILL.md

SKILL.md には、先頭に YAML frontmatter として name と description を書き、その下に実際の手順を書きます。Codex はこの説明を見てスキルを使うか判断するため、description には「いつ使うスキルか」を具体的に書くのが重要です。

---
name: "requirements-to-plan"
description: "要求仕様書や基本設計書を読み、実装範囲、影響範囲、不明点、テスト観点に分解するときに使う"
---

# Requirements To Plan

## When to use
- 要求仕様や基本設計から実装計画を作るとき
- まだコードを編集せず、仕様と既存実装の差分を確認したいとき

## Workflow
1. 指定された仕様ファイルを読む
2. 既存コード、テスト、設定、データ構造を確認する
3. 実装対象、影響範囲、不明点、リスクを整理する
4. 受け入れ条件ごとにテスト観点を出す
5. 実装前に確認すべき質問を列挙する

必要に応じて、スキルのフォルダには補助ファイルも置けます。長い仕様テンプレートやチェックリストは references/、繰り返し実行する変換や検証は scripts/、テンプレートや画像などの素材は assets/ に分けると扱いやすくなります。

~/.codex/skills/requirements-to-plan/
  SKILL.md
  references/
    acceptance-criteria-checklist.md
  scripts/
    extract_requirements.py
  assets/
    report-template.md

スキルを追加したら、新しい Codex セッションで次のように明示して動作を確認します。

利用スキル: $requirements-to-plan
入力: docs/requirements/order-filter.md
出力: 実装計画。
制約: 編集なし。

標準のスキル探索場所とは別の場所に置く場合は、~/.codex/config.toml の skills.config にパスを追加できる環境もあります。環境差があるため、反映されない場合は codex --help や設定リファレンス、手元の Codex バージョンを確認します。

依頼時に明示する場合は、スキル名を含めると意図が伝わりやすくなります。

利用スキル: $imagegen
目的: この記事のアイキャッチ画像作成。

利用スキル: $openai-docs
目的: 最新の Responses API の使い方確認。

目的: このリポジトリ用のレビュー手順を skill として整理。

スキルは、要求仕様書や基本設計書をもとに実装を依頼する用途にも向いています。たとえば「要求仕様を読んで実装範囲を分解する」「基本設計と既存コードの差分を確認する」「設計どおりに実装し、テスト観点まで作る」といった作業手順をスキルとして固定できます。

この場合、Codex に渡す情報は次のように整理すると安定します。

• 要求仕様: 利用者、目的、業務ルール、受け入れ条件、対象外
• 基本設計: 画面、API、データ項目、状態遷移、エラー処理、権限
• 実装範囲: 変更してよいファイル、触らない領域、既存仕様との互換性
• 検証方法: unit test、integration test、lint、手動確認手順
• 出力形式: 先に計画を出す、実装まで進める、レビューだけにする、など

要求仕様から実装計画を作らせる例:

利用スキル: $requirements-to-plan
入力: docs/requirements/order-filter.md
制約: 編集なし。
作業: 既存コードを確認し、実装対象、影響範囲、未確定事項、テスト観点を整理すること。
報告: 実装前に確認すべき質問があれば列挙すること。

基本設計から実装まで依頼する例:

利用スキル: $design-implementation
入力: docs/design/order-filter-basic-design.md
作業: 関連する画面、API、状態管理、テストの確認後に実装へ進むこと。
制約: 基本設計と矛盾する既存仕様があれば、勝手に変更せず先に報告すること。
検証: 関連テストを追加または更新し、実行した検証コマンドと結果を報告すること。

要求仕様と基本設計の整合性だけを確認する例:

利用スキル: $design-review
入力: docs/requirements/、docs/design/
制約: コード編集なし。
作業: 要求仕様、基本設計、現在の実装の不整合を見つけること。
出力: 「重大度」「根拠ファイル」「影響」「修正案」の形式で整理すること。

この用途のスキルは、実装を急がせるよりも「仕様を読む」「既存実装と照合する」「不明点を出す」「合意後に実装する」という順序を明記すると扱いやすくなります。

要求仕様から実装するための SKILL.md 例:

---
name: "design-implementation"
description: "要求仕様書と基本設計書をもとに、既存コードへ安全に実装する"
---

# Design Implementation

## When to use
- 要求仕様書、基本設計書、詳細設計書から実装するとき
- 仕様と既存コードの差分を確認後に変更したいとき
- 実装とテスト観点を仕様にひも付けたいとき

## Workflow
1. 要求仕様、基本設計、対象外、受け入れ条件を読む
2. 関連する既存コード、テスト、設定、データ構造を確認する
3. 仕様と既存実装の不整合、不明点、リスクを先に報告する
4. 実装計画を小さな作業単位に分ける
5. 合意済み範囲だけを既存設計に合わせて変更する
6. 仕様に対応するテストを追加または更新する
7. 実行した検証コマンド、結果、残課題を報告する

## Rules
- 仕様に書かれていない挙動を勝手に追加しない
- 既存仕様と矛盾する場合は実装前に止めて確認する
- 受け入れ条件とテスト観点の対応が分かるように報告する
- 大きな変更になる場合は、先に計画を出してから進める

スキルを作るときは、汎用的な知識を詰め込みすぎるより、特定の作業で迷わないための手順に絞ると扱いやすいです。

おすすめの 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
- 重点的に見るべきリスク
- セキュリティや互換性の注意点

対話中に新規作成する場合は、スラッシュコマンドからひな形を生成できます。

/init

15. 対話中のスラッシュコマンド

Codex 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 -rf
• git reset --hard
• git 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-dir

Git リポジトリ外で実行できない

非対話実行では --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 --help

20. 補助サブコマンド

開発作業以外にも、更新、補完、差分適用、プラグイン、デスクトップアプリ、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 --version

22. 参照情報

• OpenAI Help Center: Codex CLI Getting Started

https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started

help.openai.com

• OpenAI Help Center: Codex CLI and Sign in with ChatGPT

https://help.openai.com/en/articles/11381614

help.openai.com

• OpenAI Help Center: Using Codex with your ChatGPT plan

https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan

help.openai.com

• OpenAI: Introducing Codex

https://openai.com/index/introducing-codex/

openai.com

• OpenAI: Introducing upgrades to Codex

https://openai.com/index/introducing-upgrades-to-codex/

openai.com

• OpenAI Developers: Codex use cases

Codex use cases

Explore example workflows, teams, and tasks you can hand to Codex.

developers.openai.com

• OpenAI Developers: Codex Quickstart

Quickstart – Codex | OpenAI Developers

Start using Codex in your IDE, CLI, or the cloud

developers.openai.com

• OpenAI Developers: Codex configuration reference

Configuration Reference – Codex | OpenAI Developers

Complete reference for Codex config.toml and requirements.toml

developers.openai.com

• OpenAI Developers: Slash commands in Codex CLI

Slash commands in Codex CLI | OpenAI Developers

Control Codex during interactive sessions

developers.openai.com

• OpenAI API Models: GPT-5.3-Codex

GPT-5.3-Codex Model | OpenAI API

developers.openai.com

• OpenAI API Models: codex-mini-latest

codex-mini-latest Model | OpenAI API

developers.openai.com