Codex CLIワークスペース設定とプロジェクト管理の完全ガイド

「Codex CLIの設定が複雑でどこから手をつければいいか分からない」「プロジェクトごとに最適な設定を管理したい」——Codex CLIを本格的に使い始めると、ワークスペースの設計が生産性に直結することに気づくはずです。

結論から言うと、config.toml＋codex.md＋承認モードの3つを適切に設定すれば、Codex CLIの生産性は飛躍的に向上します。

この記事はOpenAI Codex CLI完全攻略シリーズとして、ワークスペース設定とプロジェクト管理の全機能を実践的に解説します。

Codex CLIのワークスペース構造を理解する

作業ディレクトリとcodex.mdの役割

Codex CLIはカレントディレクトリを作業ディレクトリとして認識し、そのディレクトリ内のファイルを操作対象とします。

my-project/
├── codex.md          # プロジェクト固有の指示書
├── .codex/
│   └── config.toml   # ローカル設定
├── src/
├── tests/
└── README.md

codex.mdはClaude CodeのCLAUDE.mdに相当するファイルで、プロジェクトのコーディング規約、アーキテクチャの方針、技術スタックの情報などを記載します。Codex CLIはこのファイルを自動的に読み込み、タスク実行時のコンテキストとして活用します。

# codex.md

## プロジェクト概要
Next.js 15 + TypeScript + Prisma のWebアプリケーション

## コーディング規約
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- CSS Modules を使用
- テストは Jest + React Testing Library

## ディレクトリ構成
- src/app/ - App Routerのページ
- src/components/ - 共有コンポーネント
- src/lib/ - ユーティリティ関数

—working-directoryフラグの使い方

現在のディレクトリとは別のディレクトリを作業対象にしたい場合、--working-directoryフラグを使用します。

# 別のディレクトリを対象に実行
codex --working-directory /path/to/other-project "テストを追加して"

# 短縮形
codex -w /path/to/other-project "テストを追加して"

Codex CLIの基本操作については「OpenAI Codex CLI入門ガイド」を参照してください。

config.tomlによる設定管理

設定ファイルの場所と基本構文

Codex CLIの設定ファイルは以下の2つの場所に配置できます。

設定ファイル	場所	優先度	用途
グローバル設定	~/.codex/config.toml	低	ユーザー共通のデフォルト値
ローカル設定	.codex/config.toml	高	プロジェクト固有の設定

# ~/.codex/config.toml（グローバル設定の例）

[model]
default = "o3-mini"
reasoning_effort = "medium"

[approval]
mode = "auto-edit"  # デフォルトの承認モード

[sandbox]
type = "docker"     # サンドボックスの種類

ローカル設定はグローバル設定を上書きします。プロジェクトごとに異なるモデルや承認モードを使い分けたい場合に便利です。

-cフラグによる一時的なオーバーライド

設定ファイルを変更せずに一時的に設定を上書きするには、-cフラグを使用します。

# モデルを一時的に変更
codex -c model.default=o4-mini "このバグを修正して"

# 承認モードを一時的に変更
codex -c approval.mode=full-auto "テストを実行して結果を報告して"

# 複数の設定を同時にオーバーライド
codex -c model.default=o3 -c model.reasoning_effort=high "アーキテクチャを提案して"

機能フラグの有効化・無効化

Codex CLIの実験的機能やオプション機能は、機能フラグで制御します。

[features]
multi_file_edit = true    # 複数ファイルの同時編集
auto_context = true       # 自動コンテキスト収集
git_checkpoint = true     # Gitチェックポイント機能

設定の詳細は「Codex CLI設定リファレンス」で全項目を解説しています。

承認モードの選択と運用

Suggest・Auto Edit・Full Autoの違い

Codex CLIには3つの承認モードがあり、セキュリティと効率のバランスを調整できます。

モード	ファイル編集	コマンド実行	適したシーン
Suggest	承認必要	承認必要	初めてのプロジェクト、セキュリティ重視
Auto Edit	自動実行	承認必要	日常的な開発作業
Full Auto	自動実行	自動実行	信頼できるプロジェクト、CI/CD

OpenAI公式ドキュメント「Codex CLI」でも承認モードの詳細が説明されています。

プロジェクト特性に応じたモード選択基準

適切な承認モードを選ぶための基準を示します。

Suggestモードが適切な場合：

• 本番環境に直結するリポジトリ
• 大規模な変更を行う場合
• チームメンバーがCodex CLIに不慣れな場合

Auto Editモードが適切な場合：

• 日常的な開発・リファクタリング
• テストが充実しているプロジェクト
• 変更のロールバックが容易な環境

Full Autoモードが適切な場合：

• CI/CDパイプライン内での使用
• サンドボックス環境での実験
• コード生成・テスト生成などの定型タスク

セキュリティとのバランス

Full Autoモードは生産性が最も高い反面、以下のリスクがあります。

• 意図しないファイルの削除や上書き
• 外部API呼び出しやネットワーク通信
• 機密情報を含むファイルの操作

安全に使うためのベストプラクティス：

1. Gitチェックポイントを必ず有効にする
2. .codexignoreで機密ファイルを除外する
3. サンドボックス環境内で実行する
4. 変更後は必ずgit diffで差分を確認する

Gitチェックポイント戦略

タスク前後の自動コミットの仕組み

Codex CLIのGitチェックポイント機能は、タスク実行前後に自動的にGitコミットを作成します。

タスク実行フロー:
1. [自動] git stash（未コミットの変更を退避）
2. [自動] チェックポイントコミット作成
3. [実行] Codexがファイルを編集
4. [自動] 変更後のコミット作成
5. [自動] git stash pop（退避した変更を復元）

変更の確認とロールバック手順

Codexが行った変更を確認・ロールバックする方法：

# Codexの変更を確認
git log --oneline -5
git diff HEAD~1

# 変更を取り消す場合
git revert HEAD

# 特定のチェックポイントまで戻す
git reset --hard <checkpoint-hash>

セッション管理とトランスクリプト活用

セッション履歴の保存場所と再開方法

Codex CLIのセッション履歴は~/.codex/sessions/ディレクトリに保存されます。

# セッション一覧の確認
ls ~/.codex/sessions/

# 前回のセッションを再開
codex --resume

# 特定のセッションを再開
codex --resume <session-id>

過去のセッションをコンテキストとして活用

過去のセッションの内容を新しいタスクの参考にすることができます。

• セッショントランスクリプト：過去の会話と変更を確認
• 成功パターンの再利用：うまくいったプロンプトを再利用
• エラーの回避：過去のエラーパターンを参考に指示を改善

マルチファイル編集については「Codex CLIマルチファイルワークスペースガイド」で解説しています。

複数プロジェクトの効率的な運用

プロジェクトごとの設定分離

複数のプロジェクトをCodex CLIで管理する場合、以下の方法で設定を分離します。

# プロジェクトA（フロントエンド）
project-a/.codex/config.toml
  → model: o4-mini, mode: auto-edit

# プロジェクトB（インフラ）
project-b/.codex/config.toml
  → model: o3, mode: suggest

# プロジェクトC（データ分析）
project-c/.codex/config.toml
  → model: o3-mini, mode: full-auto

プロジェクトの性質に応じてモデルと承認モードを使い分けることで、コストと安全性を最適化できます。

APIキーとコスト管理のベストプラクティス

複数プロジェクトを運用する際のコスト管理のポイント：

• プロジェクト別のAPIキー：コストを分離して追跡
• モデルの使い分け：定型作業はo4-mini、複雑な設計はo3を選択
• reasoning_effortの調整：タスクの複雑さに応じてlow/medium/highを切り替え
• セッション時間の制限：長時間のセッションはコストが膨らむため、タスクを分割

チームでの運用については「Codex CLIチームワークフローガイド」を参照してください。

まとめ：ワークスペース設計で生産性を最大化

Codex CLIのワークスペース管理のポイントをまとめます。

• codex.mdでプロジェクトのコンテキストを正確に伝える
• config.tomlのグローバル/ローカル設定でプロジェクトごとに最適化
• 承認モードはプロジェクトのリスクレベルに応じて使い分ける
• Gitチェックポイントで変更のロールバックを常に可能にしておく
• セッション管理で作業の継続と過去の知見の再利用を促進

ワークスペースの設計を丁寧に行うことで、Codex CLIは安全かつ効率的な開発パートナーになります。