Codexのconfig.tomlは、Codex CLIとIDE拡張（コード編集ソフトに入れて使う拡張機能）の「いつもの動き」を決める設定ファイルです。使うモデル、考える深さ、確認を求めるタイミング、ファイルを書き換えてよい範囲などを書いておけば、毎回オプションを付けなくても同じ条件で動かせます。自分用の設定は~/.codex/config.toml、プロジェクトごとの設定はリポジトリ（プロジェクトのフォルダ）の.codex/config.tomlに置きます。ただし、プロジェクトの設定が読み込まれるのは、そのプロジェクトを「信頼済み」にした時だけです（初めて開いた時に出る確認などで選べます）。
この記事は、OpenAIの公式資料（Config basics、Advanced Configuration、Configuration Reference、Agent approvals & security）を2026年10月22日に確認して作成しました。編集部はCodex CLI 0.163.0で、設定の読み込み順と、書き間違えた時の反応を16通り試しています。ふだんの設定に影響しないよう、Codexが設定を読む場所（CODEX_HOME）を一時フォルダに切り替えて試しました。試したのは設定の読み込みまでで、Codexに実際の作業をさせて結果を比べてはいません。企業向けの管理設定（requirements.toml）、Windowsでの動き、MCPサーバーの接続は実測していません。IDEや/permissionsの画面での操作、サンドボックスの保護やネット接続の実際の制限、trust_level = "untrusted"の実際の動きも試していません。これらは公式資料に基づいて説明しています。
Codexのconfig.tomlとは：既定の動きを決める設定ファイル
Codexは起動のたびに、どのモデルを使うか、作業の前にどこまで確認を求めるか、どのフォルダを書き換えてよいか、といった条件を決めてから動き出します。これらを毎回--modelや--sandboxのようなオプションで指定する代わりに、ファイルに書いておく場所がconfig.tomlです。
TOMLは、キー = 値の行を並べて書く設定用の書式です。[features]のように角かっこで囲んだ行は「表（テーブル）」の見出しで、その下に書いたキーはその表の中身になります。この仕組みは、あとの「よくある失敗」で大事になります。
公式のConfig basicsによると、CLIとIDE拡張は同じ設定を共通で読み込みます。設定できるのは、たとえば次のような項目です。
- 既定のモデルと、モデルの提供元
- 承認（実行前に確認を求めるか）とサンドボックス（読み書きできる範囲）
- 外部ツールをつなぐMCPサーバー
Codex全体の使い方をまだ押さえていない方は、先にCodexの使い方とできることとCodex CLIのインストールと初回設定を読んでおくと、この記事の設定がどこに効くのかをつかみやすくなります。
config.tomlの置き場所は3種類
自分で書くconfig.tomlの置き場所は、主に次の3つです。
| 種類 | 場所 | 向いている内容 |
|---|---|---|
| ユーザー設定 | ~/.codex/config.toml | どのプロジェクトでも使う自分の好み（モデル、考える深さ、通知など） |
| プロジェクト設定 | リポジトリ内の.codex/config.toml | そのリポジトリだけで変えたい条件（チームで共有したい既定値など） |
| プロファイル | ~/.codex/名前.config.toml | 用途ごとに切り替えたい組み合わせ（読み取り専用の点検用など） |
ユーザー設定 ~/.codex/config.toml
ふだん使う設定はここに書きます。~/.codexは、Codexが設定や履歴、ログイン情報を置くフォルダで、環境変数CODEX_HOMEで別の場所に変えられます（公式のAdvanced Configuration）。IDE拡張からは、右上の歯車からCodex Settings > Open config.tomlを選ぶと同じファイルを開けます。
プロジェクト設定 .codex/config.toml
リポジトリの中に.codex/config.tomlを置くと、そのプロジェクトで作業する時だけ値を上書きできます。Codexは、プロジェクトのいちばん上（既定では.gitがあるフォルダ）から、いま作業しているフォルダまでを順にたどり、途中にある.codex/config.tomlをすべて読み込みます。同じキーが複数あった時は、作業フォルダに近いファイルの値が優先です。
プロジェクト設定には、書いても無視されるキーがあります。ログイン情報の送り先を変えるopenai_base_urlや、モデルの提供元を決めるmodel_provider・model_providers、手元でコマンドを動かすnotify、プロファイルを選ぶprofile・profiles、計測データの送り先を決めるotelなどです。これは、リポジトリを開いただけで、認証情報の行き先や手元で動くコマンドが変わらないようにするための制限です。これらのキーはユーザー設定に書いてください（Advanced Configuration）。
管理者やシステムが置く設定
このほか、Unix系では/etc/codex/config.tomlがシステム全体の設定として読まれます。会社で管理されているパソコンでは、管理者がrequirements.tomlで「この値は使えない」という制約をかけている場合があります。たとえば、確認なしで動かすapproval_policy = "never"や、制限をすべて外すsandbox_mode = "danger-full-access"が禁止されているケースです。自分の設定が効かない時は、管理者の制約も疑ってください。
config.tomlが効く優先順位
同じキーが複数の場所に書かれている時、Codexは次の順に、上にあるものを優先します（Config basics）。
| 順位 | 設定の出どころ |
|---|---|
| 1 | コマンドのオプションと-c（--config）での上書き |
| 2 | プロジェクトの.codex/config.toml（作業フォルダに近いものが優先。信頼済みのプロジェクトだけ） |
| 3 | --profile 名前で選んだプロファイル（~/.codex/名前.config.toml） |
| 4 | ユーザー設定~/.codex/config.toml |
| 5 | サインイン中のワークスペース（チームや組織の単位）に向けて、クラウドから配られる既定値 |
| 6 | システム設定/etc/codex/config.toml（Unix系で、ある場合） |
| 7 | Codexに組み込まれた既定値 |
プロファイルは、ユーザー設定より上、プロジェクト設定より下に入ります。そのため、プロファイルのファイルには「ふだんと違う値」だけを書けば足ります。
1回だけ変える時は -c と専用オプション
ファイルを書き換えずに1回だけ値を変えたい時は、そのキー専用のオプションがあればそれを使い、専用のオプションが無いキーは-cで指定します。-cの値はTOMLとして読まれるので、文字列は引用符ごと渡します。
# 専用のオプション
codex --model gpt-6.1-sol
# 任意のキーを1回だけ上書き（値はTOMLとして読まれる）
codex -c model='"gpt-6.1-sol"'
codex -c sandbox_workspace_write.network_access=true入れ子のキーはmcp_servers.context7.enabled=falseのように点でつなぎます。TOMLとして読めない値は、そのまま文字列として扱われます。例にあるgpt-6.1-solは、公式資料でも「利用できる権限がある場合に使える」と書かれているモデルです。使えない場合は、自分のアカウントで使えるモデル名に置き換えてください。
config.tomlの読み込み順を編集部で試した結果
優先順位の表どおりに動くのかを、編集部の手元で確かめました。個人の設定に影響しないよう、空の一時フォルダをCODEX_HOMEに指定し、Gitで初期化した空の練習用フォルダの中で実行しています。値の変化は、各機能の現在の有効・無効を一覧で表示するcodex features listで、記憶機能memoriesの行を見て確かめました。モデルにはリクエストを送っていません。
| 試したこと | 結果 |
|---|---|
| 何も書いていない状態 | memoriesはfalse |
ユーザー設定に[features]とmemories = trueを書く | trueに変わった |
同じ状態で-c features.memories=falseを付ける | その回だけfalse。--disable memoriesでも同じ |
練習用フォルダの.codex/config.tomlにmemories = falseを書く（未信頼） | trueのまま。プロジェクト設定は読まれなかった |
| ユーザー設定でそのフォルダを信頼済みにする | falseに変わった。プロジェクト設定がユーザー設定より優先された |
信頼済みのまま-c features.memories=trueを付ける | true。コマンドの上書きがプロジェクト設定より優先された |
プロファイルの読み込みは、モデルに送られる前の指示を表示するcodex debug prompt-inputで確かめました。プロファイルを選ばない場合、信頼済みでGitで管理された練習用フォルダでは、サンドボックスはworkspace-writeでした。sandbox_mode = "read-only"だけを書いた~/.codex/lab.config.tomlを--profile labで選ぶと、read-onlyに変わりました。さらに-c 'sandbox_mode="workspace-write"'を付けると、workspace-writeに戻りました。最初のサンドボックスがworkspace-writeだった点は、公式資料にある「Gitで管理されたフォルダでは、書き込みと必要時の確認を組み合わせた設定をすすめる」という説明と合っています。承認の設定は、この方法では確かめていません。
書き間違えた時の反応も試しました。結果は「よくある失敗」の節にまとめています。
config.tomlでよく使う設定の書き方
公式資料が「よく変える設定」として挙げている項目から、最初に押さえたいものを並べます。ファイルの先頭、つまり最初の[...]の見出しより前に書くのがポイントです。
# ~/.codex/config.toml
model = "gpt-6.1-sol" # 既定のモデル（使えるモデル名に置き換える）
model_reasoning_effort = "medium" # 考える深さ
approval_policy = "on-request" # 実行前の確認の出し方
sandbox_mode = "workspace-write" # 読み書きできる範囲
web_search = "cached" # Web検索の方法（既定）
[features]
memories = true # 機能の有効・無効は [features] の下に書く承認とサンドボックスの組み合わせ
approval_policyは、Codexがコマンドを実行する前にどこで止まって確認を求めるかを決めます。現行の公式資料に載っている値は、必要な時だけ確認するon-request、確認しないnever、確認の種類ごとに許可と自動拒否を分ける{ granular = { ... } }です。sandbox_modeは、Codexが動かすコマンドがどこまで読み書きできるかを決めます。値には、読み取りだけのread-only、作業フォルダへの書き込みを許すworkspace-write、制限を外すdanger-full-accessがあります。
公式のAgent approvals & securityは、よく使う組み合わせを次のように整理しています。
| 使い方 | 設定 | 動き |
|---|---|---|
| 標準 | sandbox_mode = "workspace-write"とapproval_policy = "on-request" | 作業フォルダ内なら、読み書きもコマンド実行も確認なしで進める。フォルダの外への書き込みやネット接続の前には確認を求める |
| 安全に読むだけ | sandbox_mode = "read-only"とapproval_policy = "on-request" | 読み取りだけで動き、それを超える操作（書き込みなど）の前には確認を求める |
| CI（自動テストなど、人が見ていない実行）で読むだけ | sandbox_mode = "read-only"とapproval_policy = "never" | 読み取りだけで動き、確認は求めない |
workspace-writeでも、作業フォルダ内の.gitは読み取り専用として守られます。.agents、.codex、.awsも、フォルダとしてある場合は同じく守られます。git commitで確認を求められることがあるのはこのためです。ネット接続は既定で切られていて、workspace-writeで許可する時は[sandbox_workspace_write]の下にnetwork_access = trueを書きます。danger-full-accessを使ってよいとされているのは、コンテナなど、Codexの外側がすでに隔離されている環境だけです。
機能の有効・無効は [features] に書く
必要に応じて使う機能や試験中の機能は、[features]の表の中にtrue・falseを書いて有効・無効を切り替えます。書かなかった機能は既定値のままです。1回だけ試すならcodex --enable 機能名、止めるなら--disable 機能名が使えます。どの機能がいま有効かは、手元のCodex CLI 0.163.0ではcodex features listで一覧できました。lifecycle hooks（決まったタイミングで自分のスクリプトを動かす仕組み）も同じconfig.tomlに書けます。書き方と注意点はCodex hooksの記事で説明しています。
プロファイルで用途ごとに設定を切り替える
「ふだんは書き込みあり、点検の時だけ読み取り専用」のように用途ごとに条件を変えたい時は、プロファイルを使います。現行のCodexでは、プロファイルはconfig.tomlとは別のファイルとして作ります。
# ~/.codex/readonly.config.toml（ファイル名の「readonly」がプロファイル名）
sandbox_mode = "read-only"
approval_policy = "on-request"codex --profile readonly
codex exec --profile readonly "この変更を点検して"プロファイルのファイルには、[profiles.readonly]のような見出しを付けず、いちばん外側にキーを書きます。名前に使えるのは英数字、ハイフン、アンダースコアです。対話なしで動かすcodex execと組み合わせる場合は、codex execの使い方と権限の記事もあわせて確認してください。
古い [profiles.名前] の書き方は使えない
以前はconfig.tomlの中に[profiles.名前]という表を作り、profile = "名前"で選ぶ書き方がありました。公式資料によると、Codex 0.134.0以降はこの書き方を読みません。編集部の手元でも、config.tomlに[profiles.lab]を残したまま--profile labを付けると、「古い書き方をlab.config.tomlへ移して、[profiles.lab]の見出しを消すように」という趣旨のエラーで止まりました。古い記事の例をそのまま写すとこの状態になるので、見出しの下の値を別ファイルへ移してください。
プロジェクトのconfig.tomlが効かない時は「信頼済み」かを確かめる
プロジェクトの.codex/config.tomlを書いたのに効かない場合、まず疑いたいのは、そのプロジェクトが信頼済みになっていないことです。信頼していないプロジェクトでは、.codex/の中の設定、hooks、rules（コマンドの許可・禁止の決まり）がまとめて読み飛ばされます。手に入れたばかりのリポジトリに仕込まれた設定が、勝手に効かないようにするためです。
信頼の設定は、ユーザー設定に次のような形で書き込まれます。この行を自分で書くほか、プロジェクトを初めて開いた時に出る確認や、対話画面の/permissionsで信頼を選ぶこともできます。
# ~/.codex/config.toml
[projects."/Users/you/work/my-app"]
trust_level = "trusted"逆に、信頼していないことを明示したいプロジェクトにはtrust_level = "untrusted"を書けます。この場合、プロジェクトの設定は読まれません。さらにapproval_policyを明示していなければ、rulesで許可されたコマンド以外は、Codexが実行前に確認を求めるようになります。ただし、ユーザー設定などでapproval_policy = "on-request"をはっきり書いていると、そちらが優先され、この厳しい確認は効きません。信頼前は読まれず、信頼後に読まれるようになった手元の結果は、「config.tomlの読み込み順を編集部で試した結果」の節の表のとおりです。
config.tomlのよくある失敗と直し方
編集部が手元で再現した書き間違いと、公式資料で案内されている注意点を、症状ごとにまとめます。
見出しの下に書いたキーが別の表に入る
TOMLでは、[features]のような見出しを書くと、その後ろのキーは次の見出しが来るまですべてその表の中身になります。編集部が[features]の下にweb_search = "live"を書き足したところ、設定の読み込みでエラーになり、codex features listも動かなくなりました。web_searchが機能の切り替えとして読まれ、「trueかfalseが来るはずなのに、文字列の"live"が来た」という趣旨のエラーが出たためです。modelやapproval_policyのような外側のキーは、最初の見出しより前にまとめて書きます。
キーの綴りを間違えても、Codexはふつう何も言わずに動く
model_reasoning_effortをmodel_reasoning_efortと1文字落として書いた場合、ふだんの起動では、警告もエラーも出ずにそのまま動きました。書いたつもりの設定が効いていなくても、気付けないということです。--strict-configを付けて起動すると、「知らない設定項目がある」という内容のエラーと、該当する行と位置が表示されて止まりました。設定を書き換えた直後は、一度--strict-config付きで起動して確かめると安心です。手元のCodex CLI 0.163.0では、codex execに付けるとこのエラーで止まりました。一方、codex features listに付けると「このコマンドには使えない」というエラーになりました。
approval_policy = "untrusted" で起動しない
古い記事では、確認を厳しくする値としてapproval_policy = "untrusted"が紹介されていることがあります。現行のCodexではこの値は廃止されていて、編集部の手元でも「この設定はもうサポートされていないので削除するように」という趣旨のエラーで起動しませんでした。公式資料が案内する置き換えは2つです。
- 読むだけで、必要な時に確認を求めたい：
sandbox_mode = "read-only"とapproval_policy = "on-request" - コマンドごとに確認する厳しさを残したい：
approval_policyを書かずに、ユーザー設定の[projects."パス"]にtrust_level = "untrusted"を書く（approval_policy = "on-request"を書いていると、この厳しさは上書きされます）
設定が効いているか分からない時に見る所
次の順に確かめると、どこで値が変わっているかを絞り込めます。
- コマンドに
-cや--profile、--sandboxなどを付けていないか（いちばん優先される） - 作業フォルダから上にたどった所に
.codex/config.tomlがないか、そのプロジェクトは信頼済みか - キーが最初の見出しより前に書かれているか、綴りは正しいか（
--strict-configで確認） - 会社のパソコンなら、管理者の制約で使えない値になっていないか
Codex CLIには、インストールや設定、認証の状態をまとめて点検するcodex doctorもあります（手元の0.163.0で確認）。外部ツールの接続設定[mcp_servers]の書き方はCodexでMCPを使う記事、作業の前提を伝える指示書はAGENTS.mdの書き方の記事で扱っています。config.tomlは「どう動くか」、AGENTS.mdは「何を前提に仕事をするか」と分けると整理しやすくなります。
まとめ：config.tomlは小さく書いて、効いているかを確かめる
Codexのconfig.tomlは、まずユーザー設定にモデルや考える深さ、承認とサンドボックスのような「いつもの条件」だけを書くところから始めると迷いません。プロジェクトだけで変えたい値は.codex/config.tomlに書いてプロジェクトを信頼し、用途ごとに切り替えたい値は、名前.config.tomlのプロファイルに書きます。書き換えた後は、--strict-config付きで起動して間違いがないかを確かめましょう。1回だけ試したい値は-cで渡せば、ふだんの設定を壊さずに済みます。キーの一覧と最新の値は、公式のConfiguration Referenceで確認してください。
