はじめに：Codex CLIを「毎日使える道具」にする
前回の記事「Codex CLI 機能 逆引き辞典」では、コマンドの使い方を「やりたいこと」から引ける形でまとめました。
この記事では、その次のステップとして、Codex CLIを「安全に・再現性高く・迷わず」運用するための設定を解説します。
設定をしっかり固めることで、「便利だけど怖い」が「便利で安心」に変わります。config.toml、profile、AGENTS.md、Custom Prompts、MCPまで、順を追って見ていきましょう。
1. 設定の全体像（まず何を決める？）
Codex CLIの設定は、4つの層で考えると整理しやすくなります。
設定の4層構造
- 基礎設定：モデル、承認ポリシー（approvals）、サンドボックス
- 運用分離：profile（用途別に設定を切り替える）
- プロジェクト知識：AGENTS.md（暗黙知をCodexに渡す）
- 繰り返し作業：Custom Prompts（定型作業をコマンド化）
さらに必要に応じて、MCP（外部ツール連携）を追加します。
この順番で整えていくと、段階的に「使いこなせている感」が増していきます。焦らず、一つずつ固めていきましょう。
2. config.toml の基本（場所・優先順位）
2-1. 設定ファイルの場所
Codex CLIの設定ファイルは、以下の場所に配置します。
~/.codex/config.tomlホームディレクトリの .codex フォルダ内に config.toml を作成します。フォルダがなければ作成してください。
2-2. 設定値の優先順位（超重要）
「設定を書き換えたのに反映されない」というトラブルの99%は優先順位の問題です。設定値は以下の順番で決まります。
- CLIフラグ（例：
--model gpt-5） --profile <name>で指定したprofile内の値- config.toml のルート値
- 組み込みの既定値
上にあるものほど優先度が高く、下を上書きします。つまり、config.tomlを編集しても、CLIフラグやprofile指定で上書きされていれば反映されません。
「設定が効かない」と思ったら、まずはCLIフラグやprofile指定を確認しましょう。
3. 事故らない初期設定（おすすめテンプレート）
最初は「安全寄り」の設定から始めることを強くおすすめします。慣れてきたらprofileで段階的に強くしていけばOKです。
おすすめ初期設定テンプレート
# ~/.codex/config.toml
# 使用するモデル
model = "gpt-5.2"
# 承認ポリシー：操作の前に確認を挟む
approval_policy = "on-request"
# サンドボックス：作業ディレクトリ内への書き込みのみ許可
sandbox_mode = "workspace-write"
# 子プロセスに渡す環境変数を制限（秘密情報の混入を防ぐ）
[shell_environment_policy]
include_only = ["PATH", "HOME"]
# 便利機能は最初は慎重に
[features]
shell_snapshot = true
web_search_request = false各設定項目の解説
approval_policy（承認ポリシー）
Codexがファイル操作やコマンド実行を行う際の確認レベルを設定します。
- on-request：操作の前に確認を求める（推奨）
- never：確認なしで自動実行（上級者向け）
最初は必ず on-request にしておきましょう。
sandbox_mode（サンドボックスモード）
Codexがアクセスできる範囲を制限します。
- workspace-write：作業ディレクトリ内のみ書き込み可能（推奨）
- read-only：読み取りのみ（変更不可）
- full：制限なし（危険）
workspace-write から始めて、必要に応じて調整するのが安全です。
shell_environment_policy（環境変数ポリシー）
Codexが実行するコマンドに渡される環境変数を制限します。include_only で必要最小限の変数だけを許可することで、APIキーなどの秘密情報が意図せず漏れるリスクを減らせます。
features（機能フラグ）
Web検索やスナップショットなどの追加機能のON/OFFを制御します。最初は web_search_request = false にしておき、必要になってから有効にするのがおすすめです。
4. profile運用（用途別に設定を分離する）
「普段は慎重に、必要なときだけ強めに」を実現するのがprofile機能です。用途別にプリセットを作っておくと、運用が安定します。
おすすめprofile構成（3種類）
- default：安全寄り（普段使い）
- fast：高速化（雑務を素早く片付けたいとき）
- readonly：読み取り専用（設計相談・調査用）
設定例
# ~/.codex/config.toml
# ルート設定（普段使い・安全寄り）
model = "gpt-5.2"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# 高速化profile（確認を省略）
[profiles.fast]
approval_policy = "never"
sandbox_mode = "workspace-write"
# 読み取り専用profile（相談モード）
[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"profileの使い方
# 読み取り専用モードで起動（設計相談に）
codex --profile readonly
# 高速モードで起動（雑務処理に）
codex --profile fast運用上の注意点
組織管理のPCやセキュリティポリシーが厳しい環境では、「強い設定」が禁止されている場合があります。その場合は以下の対応を検討してください。
fastprofileを作らないsandbox_modeはworkspace-write限定で運用- どうしても必要な操作は
!で明示的に実行（ログが残る）
5. AGENTS.md：プロジェクトの暗黙知を固定化
毎回Codexに説明していること（テストの実行方法、コーディング規約、触ってはいけないファイル）を、AGENTS.mdに書いて「常識化」しましょう。これだけで回答のブレが大幅に減ります。
5-1. AGENTS.mdの置き場所
リポジトリのルートディレクトリに AGENTS.md という名前で配置します。Codexはこのファイルを自動的に読み込み、プロジェクトのコンテキストとして活用します。
5-2. 最小テンプレート（コピペOK）
まずは以下の最小構成から始めてみてください。
# AGENTS.md
## How to run
- Install:
- npm ci
- Test:
- npm test
- Lint/Format:
- npm run lint
- npm run format
## Rules
- Keep changes minimal and focused.
- Prefer existing patterns in this repo.
- Do not modify generated files unless explicitly requested.
- If unsure, propose a plan before editing.
## Areas to avoid
- /vendor
- /dist
- Anything marked as generated5-3. 各セクションの解説
How to run（実行方法）
インストール、テスト、リント/フォーマットの実行コマンドを記載します。Codexが「テストを実行して」と言われたとき、正しいコマンドを使えるようになります。
Rules（ルール）
コーディング時に守ってほしいルールを記載します。「変更は最小限に」「既存パターンを優先」「迷ったら提案してから編集」など、チームの暗黙知を明文化しましょう。
Areas to avoid（触ってはいけない領域）
自動生成ファイルやサードパーティのコードなど、編集してほしくないディレクトリを指定します。
5-4. 運用のコツ
- まずは「テスト手順」と「触るな領域」だけでも十分効果あり
- 徐々に追加：命名規則、例外処理方針、ログ出力ルール、セキュリティ基準など
- チームで共有すると、「Codex経由の変更品質」が安定する
6. Custom Prompts：繰り返し作業をコマンド化
PR本文の作成、コミットメッセージ、変更ログの生成…こうした「定型作業」ほど、プロンプト化すると作業が速く＆安定します。
6-1. 置き場所の作成
mkdir -p ~/.codex/prompts6-2. プロンプトファイルの作成例
例として、PR（プルリクエスト）の下書きを生成するプロンプトを作ってみましょう。
ファイル：~/.codex/prompts/draftpr.md
---
description: Draft a PR description in our style
---
Please draft a PR description with:
- Summary
- Motivation
- Changes
- Test plan
- Risks & rollout
- Screenshots (if UI)
Use short bullet points. Keep it concise.6-3. 呼び出し方
対話セッション内で以下のように呼び出せます（環境やバージョンにより仕様が異なる場合があります）。
/prompts:draftpr6-4. 作っておくと便利なプロンプト例
- draftpr：PR本文の下書き
- changelog：変更ログの生成
- reviewcheck：レビュー観点チェックリスト
- commit：コミットメッセージの提案
- bugfix：バグ修正時の確認項目
チームで使うプロンプトは、リポジトリ内の共有ディレクトリに置いておくと、全員で同じ品質の出力を得られます。
7. MCP：外部ツール連携の導入と設計
MCP（Model Context Protocol）は、Codexに「外部の手足」を生やす仕組みです。ドキュメント検索、データベース参照、社内API連携など、様々なツールを会話の中から呼び出せるようになります。
7-1. MCPツールの追加方法
例として、Context7（ドキュメント検索ツール）を追加する場合は以下のようにします。
codex mcp add context7 -- npx -y @upstash/context7-mcp7-2. 利用可能なツールの確認
対話セッション内で、現在使えるMCPツールを確認できます。
/mcpこのコマンドで、登録されているツールの一覧と、それぞれの機能が表示されます。
7-3. MCP設計のベストプラクティス
MCPは便利ですが、いきなり増やしすぎると逆効果です。以下の原則に従って、段階的に導入しましょう。
原則1：まずは「読む系」から
最初に導入するのは、以下のような「読み取り専用」のツールがおすすめです。
- ドキュメント検索
- ナレッジベース参照
- コード検索
原則2：「書く系」は承認フローを固めてから
以下のような「変更を伴う」ツールは、承認フローを確立してから導入しましょう。
- データベース更新
- チケット作成
- ファイル操作
原則3：1〜2個から始める
ツールが多すぎると、Codexが「どれを使うべきか」迷い、かえって遅くなることがあります。必要なものだけ厳選して追加しましょう。
8. Web検索・ネットワーク許可の扱い方
Codexは環境によって、Web検索がデフォルトでオフになっていたり、ネットワークアクセスが制限されていたりします。
推奨運用：「必要なときだけON」
セキュリティと再現性を考慮すると、普段はOFF、必要なときだけONにする運用がおすすめです。
設定例（一時的にONにする場合）
# ~/.codex/config.toml
[features]
web_search_request = true
[sandbox_workspace_write]
network_access = true運用パターン
- 普段：OFF（安全性と再現性を確保）
- 仕様確認・最新情報が必要なとき：一時的にON
Web検索をONにすると、最新のドキュメントやAPIリファレンスを参照できて便利ですが、結果の再現性が下がるデメリットもあります。用途に応じて使い分けましょう。
9. トラブルシューティング
9-1. config.toml を書き換えたのに反映されない
以下の順番でチェックしてください。
- CLIフラグで上書きしていないか？（例：
--model） --profileを使っていないか？（profile側の値が優先される）- config.toml の場所は正しいか？（
~/.codex/config.toml）
設定の優先順位は「CLIフラグ > profile > config.toml > 既定値」です。上位で上書きされていると、config.toml の変更は反映されません。
9-2. 強めの設定（fast profile）にしたいのに禁止される
組織のセキュリティポリシー（requirements）により、危険な設定がブロックされている可能性があります。
対処法：
fastprofile を諦め、Auto/confirm運用で回すsandbox_modeをworkspace-write限定にして安全性を担保- どうしても必要な操作は
!で明示的に実行（ログが残る）
9-3. MCPツールが認識されない
以下を確認してください。
codex mcp addコマンドが正常に完了したか/mcpコマンドでツール一覧に表示されるか- ツールの実行に必要な依存関係（npm、Pythonパッケージなど）がインストールされているか
10. 仕上げチェックリスト
以下のチェックリストを完了すれば、Codex CLIの「運用基盤」は完成です。
基本設定
- ☐
~/.codex/config.tomlを作成した（安全寄りの設定） - ☐
readonly/fastprofile を用意した（必要に応じて）
プロジェクト設定
- ☐ リポジトリに
AGENTS.mdを配置した（最低限、テスト手順と禁止区域） - ☐ よく使う作業を Custom Prompt 化した（PR下書き、CHANGELOGなど）
外部連携
- ☐ MCP は 1〜2 個から導入した（読む系から始める）
- ☐ Web検索・ネットワーク許可は「必要時のみON」の方針を決めた
運用習慣
- ☐ 変更は必ず
/diffで確認してから自分でコミットする - ☐ 迷ったら
/compactか/newでリセットする習慣をつけた
まとめ
この記事では、Codex CLIを「毎日使える道具」にするための設定と運用方法を解説しました。
ポイントの振り返り
- config.toml：安全寄りの初期設定から始める
- profile：用途別に設定を分離して切り替える
- AGENTS.md：プロジェクトの暗黙知を固定化する
- Custom Prompts：定型作業をコマンド化して効率化
- MCP：外部ツール連携は「読む系」から段階的に
設定を一度しっかり固めてしまえば、あとは安心してCodex CLIを使い倒せます。「便利だけど怖い」を「便利で安心」に変えて、開発効率を最大化しましょう。
コメント