OpenAI Codexのconfig.toml書き方と設定構築完全ガイド
AIを使った開発がどんどん進化している今日この頃ですが、OpenAIのCodexをローカル環境で使いこなすのってワクワクしますよね。でも、いざ自分好みにカスタマイズしようとすると、設定ファイルの記述で迷ってしまうことも多いのではないでしょうか。特に、エージェントの挙動や安全性をコントロールする中心的なファイルであるconfig.tomlの書き方について、何から手を付ければいいのか分からないという声をよく耳にします。自動でコマンドを実行してくれるのは便利だけど、意図しない動きをしないか不安、あるいは起動時にエラーが出てクラッシュしてしまったなど、設定周りの悩みは尽きないかも知れません。この記事では、そんな不安や疑問をすっきり解消できるように、基本からエラーの対処法まで分かりやすく解説していきますね。
- config.tomlを配置する正しいディレクトリ構造と優先順位の仕組み
- 安全にCodexを動かすための承認ポリシーやサンドボックスの設定方法
- 新バージョンで変更されたプロファイル機能の正しいマイグレーション手順
- 記述ミスで起動エラーやクラッシュが起きたときの具体的な解決ステップ
codex config.toml書き方の基本
まずは基本となる設定ファイルの仕組みについて見ていきましょう。Codexの設定システムは、ただ1つのファイルを読み込むだけではなく、実行する環境やプロジェクトに応じて設定を重ね合わせる階層化管理を採用しています。どこにファイルを置いて、どう記述すればいいのかを整理していきますね。
設定ファイルの配置場所と役割
設定ファイルであるconfig.tomlを配置する場所は、大きく分けて「グローバルレベル」と「プロジェクトレベル」の2つに明確に区分されています。これらを正しく理解して使い分けることが、安全で快適な開発環境を構築するための第一歩になります。記述ミスや配置ミスは、予期せぬ挙動や起動エラーの原因になるので、それぞれの役割をじっくり確認していきましょう。
グローバルレベルの設定は、ユーザーのホームディレクトリ直下にある「~/.codex/config.toml」に配置します。もし環境変数として「CODEX_HOME」が定義されている場合は、そちらのパスが最優先で利用される仕組みです。ここには、普段メインで使いたいデフォルトのAIモデルや、PC全体に適用するセキュリティルールなど、プロジェクトをまたいで永続的に使いたい開発者個人の好みを記述するのが一般的かなと思います。一度設定してしまえば、どのプロジェクトを開いても基本設定として機能してくれるので、共通の土台として非常に重要な役割を持っています。
一方、プロジェクトレベルの設定は、各リポジトリのルート直下に「.codex/config.toml」という形で配置します。こちらには、そのプロジェクト専用のコード規約、使用する特定のリンターやフォーマッタのコマンド、チームで定めたサンドボックスの保護基準など、リポジトリごとに管理したい固有のポリシーを書き込んでいきます。プロジェクト固有の設定を分離しておくことで、チームメンバー間で同じ開発環境の挙動を簡単に共有できるようになり、複数人での開発が格段にスムーズになるかなと思います。
グローバルとローカルの違い
グローバル設定とローカル（プロジェクト）設定の最大の違いは、影響を与える「範囲」と「目的」にあります。これらを混同して記述してしまうと、個人用の秘匿情報がチームのリポジトリに混入してしまったり、特定のプロジェクトでしか使わない実験的な設定がPC全体の挙動に悪影響を及ぼしたりするリスクがあります。お互いの性質をしっかりと理解しておきましょう。
グローバル設定（~/.codex/config.toml）
- PC内のすべてのCodex実行に適用される基本レイヤー
- 個人の認証情報や、共通で使用する基盤モデルなどの共通定義を記述する
ローカル設定（プロジェクトルート/.codex/config.toml）
- 該当するリポジトリ内でのみ適用される個別レイヤー
- チーム共有のツール定義やプロジェクト固有の安全基準を記述する
基本的には、個人のPC環境に依存する部分（APIの利用制限やローカルのパス設定など）はグローバルに、成果物であるコードの品質やビルドパイプラインに関する部分はローカルに書き分けるのが綺麗な運用のコツです。このように責任範囲を明確に分けておくことで、プロジェクトを切り替えた際にもCodexが混乱せず、常に最適なコンテキストで賢くサポートしてくれるようになりますよ。
ディレクトリ分離の注意点
プロジェクトのルートディレクトリ内を設定する際、特に注意したいのが「.codex」フォルダと「.agents」フォルダの厳格な境界線です。これらは役割が完全に分離されているので、混同しないように気をつけましょう。AIツールに慣れていないうちは、どちらもエージェント関連の設定に見えてしまい、ファイルを置く場所を間違えてしまいがちなので注意が必要です。
「.codex」ディレクトリは、サンドボックスの制限や対話型の承認ルール、OpenAI Codex独自の動作環境をカスタマイズするための設定ファイルを格納する専用の場所です。いわば、Codexというシステム自体の「コントローラー」を置く場所ですね。それに対して「.agents」ディレクトリは、他の外部エージェントツールとも共有できる共通フォーマットに準拠したカスタムスキル（SKILL.mdなど）や、再利用可能なプロンプトのテンプレートなどを配置する「知識・技能の倉庫」のような空間になっています。
この物理的な境界線はとても厳格なので、例えば再利用したいワークフロー手順を書いた「SKILL.md」を間違えて「.codex」配下に置いてしまうと、Codexはそれを完全に無視してしまい、ロードに失敗してしまいます。逆に、システム設定であるconfig.tomlを「.agents」に入れても何も認識されません。配置するフォルダは間違えないように、作業後に必ずエクスプローラーやターミナルでチェックしてくださいね。
設定が競合したときの優先度
複数の場所にconfig.tomlが存在する場合や、コマンド実行時にオプションを付けた場合、どの設定値が優先されるのか気になりますよね。Codexでは、明確な優先度階層に基づいて競合を解決しています。このルールを知っておくことで、「設定を変えたのに全然反映されない！」といったトラブルが起きたときも、どこが原因で上書きされているのかをすぐに見つけ出すことができますよ。
具体的な優先順位を以下の表にまとめてみました。数字が小さいほど優先度が高く、上の設定が下の設定を上書きする形になります。基本的には、実行する瞬間のコマンドに近い設定ほど強いパワーを持っていると覚えると分かりやすいかなと思います。
| 優先度 | 設定ソース / レイヤー | 実務的な挙動と影響 |
|---|---|---|
| 1（最高） | CLIフラグ（コマンド引数） | 単一のコマンド実行時のみ最優先。テスト時の一時的な変更に便利。 |
| 2 | アクティブプロファイル（–profile指定） | 別ファイルから読み込まれ、標準のグローバル・ローカル設定を上書き。 |
| 3 | プロジェクトローカルの .codex/config.toml | カレントディレクトリに最も近い設定を適用。信頼されたプロジェクトのみ有効。 |
| 4 | グローバルユーザーデフォルト（~/.codex/config.toml） | 開発者のローカルPC全体で共通して適用される、永続的な基本定義。 |
| 5 | システム全体設定（/etc/codex/config.toml） | 企業のシステム管理者などにより、マシン全体に一律で配備される初期値。 |
| 6（最低） | ビルトインデフォルト（内蔵設定） | 設定ファイルがどこにも存在しない場合にエージェントが適用する既定値。 |
プロジェクトを信頼する設定
ここで非常に重要なセキュリティ上の仕組みについてお話ししますね。安全上の観点から、リポジトリ内に用意されたプロジェクトレベルの設定（.codex/config.toml）は、そのプロジェクトが明示的に「信頼（Trusted）」として登録されていない限り、完全に無視される仕様になっています。せっかくローカルに細かく設定を書いても、これをしていないと動かないので注意が必要です。
もし信頼されていないリポジトリでCodexを起動すると、エージェントはローカル設定を完全にスルーし、親切な警告メッセージすら出さずにサイレントでグローバル設定のみを適用します。これは一見不便に思えるかもしれませんが、インターネットからクローンしてきた見知らぬリポジトリに悪意あるシェルコマンド実行ルールが仕込まれていた場合でも、勝手に実行されないようにするための大切なガードレールです。ユーザーの安全を最優先に考えた設計なんですね。
特定のプロジェクトを信頼環境として登録するには、グローバルな「~/.codex/config.toml」内に以下のような記述を追加しておく必要があります。パスは環境に合わせて絶対パスできっちり指定してあげてくださいね。
プロジェクトの信頼登録の記述例：
[projects."/Users/username/projects/my-project"]trust_level = "trusted"
記述してはいけない機密キー
プロジェクトのconfig.tomlには、安全のために記述しても強制的に無視される「上書き禁止キー」が存在します。Gitなどでチーム共有される可能性のあるファイルに、個人の重要なトークンやセキュリティを脅かす設定が混入するのを防ぐための防衛策です。もしこれらがプロジェクト固有の設定ファイル内に書かれていると、接続先を不正に偽装して機密情報を盗み出すリスクがあるため、パーサーが検知した時点で無視し、スタートアップ警告を出すようになっています。
以下のようなパラメータは、プロジェクトレベルのファイルには絶対に記述せず、必ずグローバルユーザー設定（~/.codex/config.toml）にだけ書くように徹底してくださいね。チーム開発でトラブルを起こさないためにも、このルールは厳格に守るのがベストかなと思います。
- 接続先プロキシやベースURLに関するもの：openai_base_url、chatgpt_base_url、experimental_realtime_ws_base_url
- プロバイダーや認証に関するもの：model_provider、model_providers
- 測定・外部通知に関するもの：notify、otel、apps_mcp_product_sku
- プロファイル選択に関するもの：profile、profiles
codex config.toml書き方の実践
ここからは、実際に手元のconfig.tomlにどのようなパラメータをどう書き込んでいけばいいのか、具体的な記述例や新バージョンへの対応方法を含めて実践的な内容を解説します。
主要パラメータの設定方法
TOML形式のファイルを記述するときの鉄則として、ブラケットで囲まれたセクション（例：[features]など）よりも前に、すべてのルートキー（トップレベルのパラメータ）を記述しなければならないというルールがあります。この記述順序を間違えると、TOMLの仕様上、構文エラー（キーがどのセクションに属しているか分からない状態）になって読み込みエラーになってしまうので注意してくださいね。
以下に、主要なパラメータのデータ型や既定値をまとめました。これらを踏まえて、ファイルの一番上の部分に設定したい値を書き込んでいきましょう。適切な値を選ぶことで、AIの回答の質や動作スピードを最適化することができますよ。
| パラメータ名 | データ型 / 許容値 | 役割と記述の効果 |
|---|---|---|
model | 文字列 | 通常のタスクやコマンド実行で使用する主モデルの識別子を指定。 |
review_model | 文字列 | コード変更履歴や差分を検証する「/review」コマンド専用のモデル。 |
model_reasoning_effort | “minimal”, “low”, “medium”, “high” | モデルが解答を出力する前の「内部思考ステップ数」の深さを調整。 |
model_verbosity | “low”, “medium”, “high” | 生成される解説などの冗長さを調整。”low”にするとコード記述に集中します。 |
sandbox_mode | “read-only”, “workspace-write”, “danger-full-access” | OSレイヤーでの実行サンドボックスのアクセス権限レベルを定義。 |
承認ポリシーの安全な設定
エージェントが自動で提案してきたコマンドやファイルのパッチを、実際に自分のマシン上で実行してもよいか判断させる基準が「approval_policy」です。これはセキュリティ設計の根幹になるので、ご自身の作業環境に合わせてしっかり選ぶのがおすすめです。適当に緩い設定にしてしまうと、予期せぬファイルの破壊などにつながる可能性もあるので、慎重に設定しましょう。
設定値には以下の3つがあります。それぞれの特徴を掴んでみてください。
- “untrusted”：一番保守的で安全な設定。どんなに軽微なファイル変更や安全なコマンドであっても、毎回ターミナル上でユーザーに「[y/n]」の対話型承認プロンプトを表示します。最初は少し手間に感じるかもしれませんが、不慣れなうちはこれが一番安心かなと思います。
- “on-request”：最もおすすめのバランス設定。害のない明白なファイルの読み込みや単純なリサーチは自動で行いますが、環境へ影響が出そうなシェルコマンドの実行や、エージェント自身が「これは確認が必要だ」と迷ったときだけ承認を求めてきます。
- “never”：全自動のCI/CD環境や、壊れてもすぐに作り直せる使い捨てのDockerコンテナ環境専用の設定。人間に一切確認をせず、提案されたすべてのコマンドをバックグラウンドで全自動実行します。個人のメインPCでこれを使うのは、少しリスクが高いかも知れません。
過去のバージョンで使われていた「”on-failure”」（コマンド実行に失敗したときだけ承認を求める設定）は、実行する前に悪意ある処理を止めることができないため、安全上のリスクがあるとして現在は非推奨（Deprecated）になっています。これから新しく環境を構築する場合は、安全のために必ず「”on-request”」か、用途に応じた他の設定を選ぶようにしてくださいね。
サンドボックスの制御方法
AIエージェントの動的な変更から、自分の大事な開発環境やOSのシステムファイルをしっかりと守るために、サンドボックスの制御は欠かせません。AIが自律的に動くのは便利ですが、万が一のバグでシステムディレクトリを書き換えられたら大変ですよね。普段の開発では「sandbox_mode = “workspace-write”」を設定して、ワークスペース内だけの書き込みを許可するのが標準的なスタイルになります。
さらに、特定のフォルダへのアクセスを部分的に許可したり、逆にセキュリティを極限まで高めたりしたい場合は、以下のように詳細なパラメータを使って要件を追加できます。細かく制御することで、利便性と安全性を両立させることが可能になります。
サンドボックス制御の記述例：
sandbox_mode = "workspace-write"[sandbox_workspace_write]writable_roots = ["/tmp/build-cache", "/var/log/app"] # 外部で例外的に書き込みを許すパスnetwork_access = false # シェルコマンドからの外部通信を遮断して情報漏洩を防止
このように設定しておけば、プロジェクト外の重要なファイルを誤って改ざんされる心配がなくなります。特にnetwork_access = falseは、機密性の高いソースコードを扱っているときに、外部の未知のサーバーへデータを勝手に送信されるのを防ぐ強力な盾になってくれますよ。
機能フラグのカスタマイズ
Codexの特定の実験的機能や、パフォーマンスを向上させる新しい仕組みをON/OFFしたいときは、「[features]」セクションを配置してフラグ制御を行います。デフォルトのままでも動きますが、自分の開発スタイルに合わせて最適化すると、開発のテンポがさらに良くなるかなと思います。
以下によく使われる実用的な設定例を挙げておきますね。Boolean型（true / false）で直感的に切り替えることができます。
[features]セクションのカスタマイズ例：
shell_snapshot = true（同一コマンドの繰り返し実行を高速化するために、環境状態の差分を一時的に保存する機能）codex_git_commit = false（エージェントがコードを書いた後、Gitコミットメッセージを自動生成して勝手にコミットする挙動を無効化。自分で確認してからコミットしたい人におすすめ）hooks = true（特定の動作の前後に自作のスクリプトを割り込ませるインラインフック処理を有効化）multi_agent = true（役割が異なる複数のサブエージェントを裏で立ち上げ、複雑なタスクを分担して並行解決させる機能を有効化）
外部連携用のサーバー設定
Model Context Protocol（MCP）を利用すると、エージェントに独自のドキュメントリポジトリを参照させたり、外部のAPIや社内ツールを自律操作させたりできるようになります。これにより、Codexができることの幅が爆発的に広がります。設定するときは「[mcp_servers.<サーバーの識別名>]」という個別のサブテーブルを作成します。
セキュリティ上の重要注意：
MCPサーバーと連携するときに必要なパーソナルアクセストークンや秘密鍵などの認証情報は、絶対にプロジェクトのconfig.toml内にベタ書きしてはいけません！誤ってGitにプッシュして世界中に公開されてしまう事故を防ぐため、トークンを直接渡すのではなく「bearer_token_env_var」パラメータを使用し、OSのシェル環境変数を経由させて安全に参照させる書き方を徹底してください。
例えば、GitHubのAPIと連携させてリポジトリの操作をエージェントに行わせる場合のセキュアな記述方法は以下のようになります。実際の生トークンを一切ファイルに書き残さないのが、プロの開発者として大切なポイントですね。
GitHub連携MCPサーバーのセキュアな記述例：
[mcp_servers.github]url = "https://api.githubcopilot.com/mcp/"bearer_token_env_var = "GITHUB_PAT_TOKEN" # シェルの環境変数を安全にマッピングenabled_tools = ["create_branch", "open_pull_request"]default_tools_approval_mode = "prompt" # ツール呼び出し時は必ず開発者に承認を求める
エラーを防ぐ設定ファイルの移行
開発のシーンや予算に合わせて使用するモデルを切り替えられるプロファイル機能ですが、バージョン 0.134.0 以降において、記述方法に関する破壊的な仕様変更が行われました。古い書き方のままCodexを最新版にアップデートすると、起動時に親切なエラーを出すことなくクラッシュしてしまう致命的な問題が発生するので、正しい新方式へのマイグレーションを行いましょう。
古いレガシーな書き方（現在は動作しません）
以前はメインのconfig.toml内に直接、以下のようにインライン形式でネストしてプロファイルを書くことができました。しかし、現在のバージョンではこの書き方は完全にサポートが終了しています。[profiles.cost-save]model = "gpt-5.4-mini"
昔の記述が残ったままだと、「Error loading configuration: legacy profile config is no longer supported…」といったエラーメッセージを出して強制終了してしまいます。
正しい新方式へのマイグレーション手順
この起動クラッシュを回避して、最新環境へ綺麗に移行するための手順は以下の3ステップです。難しくないので一つずつやってみてくださいね。
- グローバル設定ファイル（~/.codex/config.toml）を開き、古いトップレベルキーの「profile = “…”」の行や、インラインの「[profiles.xxx]」テーブル配下の記述を完全に消去します。
- ホームディレクトリの「.codex」フォルダ内に、プロファイル名に応じた個別の設定ファイルを物理的に新しく独立したファイルとして作成します（例：
~/.codex/cost-save.config.toml）。 - 新しく作った個別ファイルの中に、ブラケットによるネスト構造（[profiles.xxx]など）は使わず、上書きしたいパラメータをフラットにそのまま記述します。
切り分けた個別ファイル（~/.codex/cost-save.config.toml）の記述例：
model = "gpt-5.4-mini"model_reasoning_effort = "low"
この新しく分離したプロファイルを適用してCodexを起動したいときは、コマンドを実行するときにターミナルで「codex --profile cost-save」という風に明示的に引数を渡してあげれば、自動的に該当の外部tomlファイルが読み込まれて適用されるようになります。すっきりして管理もしやすくなりましたね。
codex config.toml書き方のまとめ
ここまでOpenAI Codexのconfig.tomlの書き方について、基本構造から安全なセキュリティ設定、最新バージョンへの移行手順まで詳しく見てきました。快適で安全な自動コーディング環境を作るためには、この設定ファイルの正確な理解が本当に大切ですね。最初は難しく感じるかもしれませんが、一度構造を理解してしまえば自由自在にエージェントをコントロールできるようになりますよ。
最後に、トラブルを防いで上手に運用するための大切なポイントを振り返っておきましょう。
安全に運用するための3大チェックポイント
- 機密性の高いトークンやURL、認証に関するキーは、プロジェクトファイルではなく必ず個人のグローバル設定（~/.codex/config.toml）に環境変数経由で記述する
- リポジトリ固有のルールを有効にしたいときは、グローバル設定側で対象のプロジェクトを「trust_level = “trusted”」として必ず登録する
- バージョン0.134.0以降はプロファイルのインライン記述が使えないため、古い記述は削除して個別のプロファイル用ファイルへと物理的に切り分ける
適切な書き方のルールを守って設定を構築すれば、意図しないクラッシュやセキュリティリスクをきれいに排除できます。新しくなった設定ファイルの仕組みを上手に取り入れて、日々の開発ワークフローをより快適に、そして強力に進化させてみてくださいね。応援しています！
