Codexのconfig.toml設定ガイド｜場所・優先順位・承認とサンドボックス・プロファイル【2026年10月】

Codex の設定は、ユーザーごとの ~/.codex/config.toml に書きます。リポジトリだけの設定は .codex/config.toml、場面ごとの設定セットは ~/.codex/<名前>.config.toml（プロファイル）に分けます。 VS Code などの IDE 拡張なら、右上の歯車から「Codex Settings」→「Open config.toml」で開けます。CLI と IDE 拡張は同じファイルを読みます（IDE の設定）。

2026年10月時点で、古い記事の書き方のままでは困る変更が2つあります。1つは、Codex 0.134.0 以降、config.toml の中の [profiles.<名前>] と profile = "<名前>" が読まれなくなったことです。もう1つは、approval_policy = "untrusted" が使えなくなり、書いたままだと Codex が起動しない場合があることです。この記事では、置き場所と優先順位から、よく変える設定、新しいプロファイルの書き方、設定が効かないときの確認手順までを順に説明します。

本記事の情報について：2026年10月12日に確認した OpenAI の開発者向けドキュメント（Config basics・Advanced Configuration・Configuration Reference・Sample Configuration・Agent approvals & security・Permissions・スラッシュコマンド）にもとづいています。Codex のドキュメントは developers.openai.com から learn.chatgpt.com に移っています。設定キーは版ごとに増減するため、手元の Codex を最新版にしたうえで読んでください。

やりたいこと別の早見表

設定したい内容から、書くキーと置き場所を引けるようにまとめました。MCP サーバーの接続は項目が多いため、Codex MCP設定ガイドで別にまとめています。

config.tomlはどこにある？置き場所と開き方

Codex の設定ファイルは、ユーザー設定 ~/.codex/config.toml が基本です。 ほかに、リポジトリごとの .codex/config.toml、Unix 系 OS のシステム全体の /etc/codex/config.toml、プロファイル用の ~/.codex/<名前>.config.toml があります（Config basics）。

~/.codex は環境変数 CODEX_HOME で変えられます。既定は ~/.codex で、同じフォルダに auth.json（ログイン情報。OS のキーチェーンに保存される場合もある）や、履歴の保存を有効にしたときの history.jsonl も置かれます（Advanced Configuration）。

開き方

• IDE 拡張（VS Code・Cursor など）：パネル右上の歯車アイコン →「Codex Settings」→「Open config.toml」
• CLI：ファイルが無ければ自分で作ります。macOS・Linux なら次の2行で作ってエディタで開けます

mkdir -p ~/.codex
code ~/.codex/config.toml   # VS Code がない場合は vi や nano など

Windows のアプリが使う場所は %USERPROFILE%\.codex です。WSL2 の中で CLI を動かしている場合は、Linux 側のホームの ~/.codex が使われ、両者の設定は共有されません（Windows での動かし方は CodexをWindowsで動かす方法 を参照）。インストールがまだなら、先に Codexのインストール方法 を済ませてください。

読み込みの優先順位は7層ある

同じキーが複数の場所に書かれているときは、上の層ほど優先されます。 公式ドキュメントが示す順番は次の7層です（Config basics）。

プロファイル（3）がユーザー設定（4）より上、プロジェクト設定（2）より下にある点に注意してください。たとえばプロファイルで model を変えても、リポジトリの .codex/config.toml に model が書かれていればそちらが使われます。

なお、企業の管理者は、配った要件ファイル（requirements.toml）で、使ってよい承認ポリシーなどを制限できます。ここで禁止された値は、上の層に書いても選べません（Configuration Reference）。

「プロジェクトの設定が効かない」3つの原因

リポジトリに .codex/config.toml を置いても効かないときは、ほとんどが次の3つのどれかです。

1. プロジェクトが信頼されていない：Codex は信頼済みのプロジェクトでだけ .codex/ の中身（設定、フック、ルール）を読みます。信頼されていないと、ユーザー設定とシステム設定だけで動きます
2. プロジェクト設定では無視されるキーを書いている：次のキーはプロジェクトの .codex/config.toml に書いても無視され、起動時に警告が出ます。openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url、otel（Advanced Configuration）。接続先や通知のように、リポジトリから勝手に変えられると困る設定はユーザー側でしか変えられない、と覚えておくと迷いません
3. もっと近い .codex/config.toml がある：Codex はプロジェクトのルートから作業フォルダまでの .codex/config.toml をすべて読み、作業フォルダに近いファイルを優先します。ルートは既定で .git のあるフォルダです。project_root_markers = [".git", ".hg", ".sl"] のように目印を変えられ、[] にすると今いるフォルダがルートになります

Codex は、作業フォルダを信頼するまで read-only で始まる場合があります。初回の案内で信頼できるほか（/permissions は権限モードの切り替えに使います）、ユーザー設定の [projects] にフォルダごとに書いておくこともできます（Agent approvals & security、Sample Configuration）。

# ~/.codex/config.toml
[projects."/Users/you/work/my-app"]
trust_level = "trusted"   # 信頼しない場合は "untrusted"

まず変える基本の設定

最初に決めるのは、モデル、推論の強さ、Web 検索、話し方の4つです。 どれもユーザー設定のトップレベル（[...] の見出しより上）に書きます。

# ~/.codex/config.toml
model = "gpt-6.1-sol"              # 公式の設定例の値。使えるモデルはプランで変わる
model_reasoning_effort = "medium"  # 推論の強さ
web_search = "cached"              # 既定値。"live" で最新のページを読む
personality = "pragmatic"          # 話し方。friendly / pragmatic / none

（値と既定は Config basics、Configuration Reference、Sample Configuration による）

推論の強さとモデルは使用量に直結します。重い設定を既定にすると、5時間あたりの枠や週の枠を早く使い切ります。枠の仕組みは Codexの使用量の確認方法と制限・リセットの仕組み で説明しています。

承認とサンドボックスの組み合わせ

Codex がどこまで自分で動いてよいかは、sandbox_mode（技術的にできる範囲）と approval_policy（いつ人に確認するか）の2つの組み合わせで決まります。 片方だけを見て設定すると、思ったより強い権限で動いたり、確認ばかりで進まなかったりします。

（Agent approvals & security、Configuration Reference。on-failure は非推奨です）

よく使う5つの組み合わせ

公式ドキュメントが挙げている組み合わせを、CLI のフラグと設定ファイルの書き方で並べると次のとおりです。

設定ファイルに書く場合の例です。

# ふだんの開発（Auto と同じ）
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false            # npm install などで通信が要るときだけ true
writable_roots = ["/Users/you/.pyenv/shims"]   # 作業フォルダ以外に書き込みを許す場所

workspace-write でも、.git/ と .codex/ は読み取り専用のままの場合があります。そのため git commit に確認が出ることがあります。会話中に Auto と Read Only を切り替えたいときは、スラッシュコマンドの /permissions を使います（スラッシュコマンド）。

approval_policy = "untrusted" は廃止された

以前の記事でよく見かける approval_policy = "untrusted" は、Codex と ChatGPT Work でサポートされなくなりました。書いたままだと、どちらのクライアントも起動しない場合があります（Agent approvals & security）。ユーザー設定、プロジェクト設定、プロファイルファイル、起動スクリプトのどこかに残っていないか探して消してください。

grep -rn "untrusted" ~/.codex/*.toml .codex/config.toml 2>/dev/null

移行先は目的で選びます。

• 読み取り専用で対話したい：sandbox_mode = "read-only" と approval_policy = "on-request" に置き換える（CLI なら codex --sandbox read-only --ask-for-approval on-request）
• コマンドの確認を厳しくしたい：approval_policy を書かずに、ユーザー設定の [projects."<パス>"] に trust_level = "untrusted" を書く。ただしこの場合はそのプロジェクトの .codex/ の設定も読まれなくなり、approval_policy = "on-request" を明示するとそちらが優先されます

同じく codex exec --full-auto も互換のために残っているだけの非推奨の書き方で、実行すると警告が出ます。今は codex exec --sandbox workspace-write と書きます。

ネットワークを許すときは送り先も絞る

network_access = true にすると、サンドボックス内のコマンドは自由に通信できます。送り先を絞りたい場合は、プロキシ機能 [features.network_proxy] でドメインごとに許可・拒否を書けます。

[sandbox_workspace_write]
network_access = true

[features.network_proxy]
enabled = true
domains = { "registry.npmjs.org" = "allow", "example.com" = "deny" }

このプロキシは、それ自体では通信を許しません。network_access が false なら何もせず、network_access が true でプロキシが無効なら通信は無制限になります（Agent approvals & security）。

新しい「権限プロファイル」はまだベータ

sandbox_mode の代わりに、ファイルとネットワークの許可を細かく書ける「権限プロファイル」（[permissions.<名前>] と default_permissions）も用意されています。組み込みの :read-only・:workspace・:danger-full-access から始めることもできます。ただし公式ドキュメントではベータ扱いで、sandbox_mode と組み合わせて使うことはできません。読み込んだ設定ファイルのどこかに sandbox_mode があるか、--sandbox を渡すと、従来の設定のほうが使われます（Permissions）。チームで使うなら、まずは sandbox_mode で運用を固めるのが無難です。

プロファイルで設定を切り替える（0.134.0以降の書き方）

プロファイルは、~/.codex/config.toml の上に重ねる差分のファイルです。 codex --profile deep-review と起動すると、ユーザー設定を読んだあとに ~/.codex/deep-review.config.toml が重なります。プロファイル名に使えるのは英数字・ハイフン・アンダースコアです（Advanced Configuration）。

# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"

codex --profile deep-review
codex exec --profile deep-review "この変更をレビューして"

プロファイルファイルには、トップレベルのキーをそのまま書きます。[profiles.deep-review] のような見出しの下に入れてはいけません。公式は、共通の設定は config.toml に置き、プロファイルのファイルには違う値だけを書けばよいとしています。

古い書き方からの移し方

Codex 0.134.0 以降、--profile は config.toml 内の [profiles.<名前>] を読みません。トップレベルの profile = "<名前>"（既定のプロファイルを選ぶ書き方）も使えなくなりました。古い書き方は次のように移します。

# 変更前：~/.codex/config.toml（0.134.0 以降は読まれない）
profile = "ci"

[profiles.ci]
model = "gpt-6-luna"
approval_policy = "never"

# 変更後：~/.codex/ci.config.toml
model = "gpt-6-luna"
approval_policy = "never"

移したら、config.toml から [profiles.ci] の見出しと中身、profile = "ci" の行を消します。既定でプロファイルを選ぶ書き方はなくなったので、使うときは毎回 --profile ci を付けます。

一時的に上書きする（-c / --config）

1回だけ設定を変えたいときは、ファイルを書き換えずに -c（--config）を使います。 専用のフラグ（--model など）があればそちらが先です。

codex --model gpt-6.1-sol
codex -c model_reasoning_effort='"high"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

キーは . でつなぎ、値は TOML として読まれます。TOML として読めない値はそのまま文字列として扱われます。文字列を確実に渡すなら、'"high"' のように引用符を二重にします（Advanced Configuration）。

そのほかのよく使う設定

モデルと権限以外で実務に効くのは、機能フラグ、渡す環境変数、ログ、通知、サブエージェント、スキルの6つです。

機能フラグ（[features]）

試験的な機能や、一部の機能のオン・オフは [features] で切り替えます。主なものと既定値は次のとおりです（Config basics）。

[features]
memories = true

1回だけ有効にするなら codex --enable memories です。複数あるときは --enable を繰り返します。既定のままでよいキーは書かないでおきます。

コマンドに渡す環境変数（[shell_environment_policy]）

既定では、名前に KEY・SECRET・TOKEN を含む環境変数も、Codex が実行するコマンドにそのまま渡ります。 ignore_default_excludes の既定が true で、自動の除外が効いていないためです。API キーなどを手元の環境変数に置いているなら、false にして除外を有効にします（Advanced Configuration）。

[shell_environment_policy]
inherit = "core"                  # "none" で空の環境から始める
ignore_default_excludes = false   # KEY / SECRET / TOKEN を含む変数を除外する
set = { MY_FLAG = "1" }

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

処理の順番は、自動の除外 → 自分で書いた除外 → set の値 → 許可リスト、です。古い exclude と include_only の配列も使えますが、同じ層で [shell_environment_policy.filters] と混ぜるとエラーになります。

ログ・通知・履歴

（Advanced Configuration、Configuration Reference）

サブエージェント（[agents]）とスキル（[[skills.config]]）

サブエージェント全体の設定は [agents] に書きます。同時に開けるサブエージェントの数を決める max_concurrent_threads_per_session（以前の max_threads も別名として使える）、サブエージェントの既定モデル default_subagent_model などがあります。役割ごとの定義は、[agents.<名前>] に description と config_file を書くか、~/.codex/agents/ や .codex/agents/ に1つずつ TOML ファイルを置きます（Configuration Reference）。

[agents]
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-6-luna"

# スキルを消さずに無効にする
[[skills.config]]
path = "/Users/you/.agents/skills/old-skill/SKILL.md"
enabled = false

サブエージェントは並列で動く分だけ使用量が増えます。上限を決めずに使い始めると、気づいたときには週の枠が残っていない、ということになりがちです。

Windows のサンドボックス

Windows では [windows] に sandbox = "elevated" を書く方式が従来の方法で、使える環境では [features] の prefer_mxc = true がすすめられています。unelevated は、管理者権限での準備ができず、組織の方針でも許されている場合だけに使います（Config basics）。

コピペ用テンプレート（個人・チーム・CI）

用途ごとに、最小限の設定を3つ用意しました。 モデル名は2026年10月時点の公式の設定例に合わせています。自分のプランで使えるモデルに置き換えてください。

個人の開発用（~/.codex/config.toml）

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "pragmatic"
file_opener = "vscode"

[sandbox_workspace_write]
network_access = false

[shell_environment_policy]
ignore_default_excludes = false

[agents]
max_concurrent_threads_per_session = 4

チームで共有するリポジトリ用（.codex/config.toml）

# リポジトリに置き、チームの全員が信頼済みにして使う
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

接続先（model_provider など）や通知（notify）はプロジェクト設定では無視されるので、ここには書きません。MCP サーバーの共有は Codex MCP設定ガイド の手順で [mcp_servers] を足します。コーディング規約などの文章での指示は AGENTS.md に分けます。

CI 用のプロファイル（~/.codex/ci.config.toml）

model = "gpt-6-luna"
approval_policy = "never"
sandbox_mode = "read-only"

codex exec --profile ci "テストが落ちている原因を調べて要約して"

CI で書き込みが必要なら sandbox_mode = "workspace-write" に変えます。never では人に確認する場面がないため、Codex は決めたサンドボックスの範囲の中でできるだけ作業を進めます。GitHub Actions で動かす方法は Codex CLIをGitHub Actionsで自動化する方法 にまとめています。

設定が効かない・起動しないときの確認手順

設定が効かないときは、「ファイルが読まれているか」「別の層に負けていないか」の順に確かめます。 次の順で見ていくと、たいていの原因が見つかります。

1. TOML として正しいか：引用符の閉じ忘れや、同じ見出し（[sandbox_workspace_write] など）の重複がないか。トップレベルのキーは最初の [...] 見出しより上に書く
2. Codex が最新版か：codex --version で版を確認し、古ければ更新する。ここに書いた設定キーには、新しい版で入ったものがある
3. 廃止された書き方が残っていないか：approval_policy = "untrusted"、[profiles.<名前>]、profile = "<名前>" を探して、この記事の移行先に直す
4. どの層の値が使われているかを見る：CLI で /debug-config を実行すると、設定の層と方針の診断が表示される。/status では、今のモデル、承認ポリシー、書き込める場所、残りのコンテキストが確認できる（スラッシュコマンド）
5. プロジェクトが信頼されているか：プロジェクト設定だけが効かないなら、[projects."<パス>"] の trust_level と、起動時の「無視されたキー」の警告を確認する
6. 管理者の制限ではないか：会社のアカウントでは、クラウド管理の既定値や要件ファイルで値が決められている場合がある。danger-full-access が選べないなどの症状なら、管理者に確認する

VS Code の拡張で設定が反映されないときは、ファイルを保存したあとで拡張を開き直してください。拡張ならではの設定や表示は CodexをVS Codeで使う で扱っています。

よくある質問

まとめ

• Codex の設定は ~/.codex/config.toml が基本。リポジトリ用は .codex/config.toml、場面ごとの差分は ~/.codex/<名前>.config.toml
• 読み込みは7層で、CLI のフラグ・-c が最優先。プロジェクト設定はプロファイルより強く、信頼済みのプロジェクトでだけ読まれる
• 権限は sandbox_mode と approval_policy の組み合わせで決まる。ふだんは workspace-write と on-request
• approval_policy = "untrusted" は廃止。読み取り専用なら read-only と on-request に置き換える
• 0.134.0 以降、プロファイルは別ファイルに書き、--profile で毎回選ぶ。[profiles.<名前>] と profile = は読まれない
• 秘密情報を含む環境変数を渡したくないなら、[shell_environment_policy] の ignore_default_excludes = false を忘れない
• 効かないときは /debug-config と /status で、どの層の値が使われているかを見る

Codex の全体像は OpenAI Codex CLI 完全ガイド、MCP サーバーの設定は Codex MCP設定ガイド を参照してください。

参考：

• https://learn.chatgpt.com/docs/config-file/config-basic
• https://learn.chatgpt.com/docs/config-file/config-advanced
• https://learn.chatgpt.com/docs/config-file/config-reference
• https://learn.chatgpt.com/docs/config-file/config-sample
• https://learn.chatgpt.com/docs/agent-approvals-security
• https://learn.chatgpt.com/docs/permissions
• https://learn.chatgpt.com/docs/cli/slash-commands