Config basics

概要

Codex の設定は複数の場所から読まれる。個人の既定は ~/.codex/config.toml、プロジェクト固有の上書きは .codex/config.toml。セキュリティのため、project の .codex/ レイヤーはそのプロジェクトを信頼したときにだけ読み込まれる。

仕様

設定ファイルの場所

user レベル: ~/.codex/config.toml
プロジェクト／サブフォルダにスコープする場合: リポジトリ内の .codex/config.toml
IDE extension から開くには、右上の歯車アイコン → Codex Settings > Open config.toml
CLI と IDE extension は同じ設定レイヤーを共有する

優先順位

優先度の高いものから順に解決される。

CLI フラグと --config の上書き
project の config ファイル .codex/config.toml。プロジェクトルートから現在の作業ディレクトリまでの順で、近いものが勝つ。trusted なプロジェクトのみ
--profile profile-name で選んだ profile ファイル（~/.codex/profile-name.config.toml）
user config ~/.codex/config.toml
system config（存在すれば）。Unix では /etc/codex/config.toml
組み込みの既定値

プロジェクトを untrusted にすると、project-local の config・hooks・rules を含む project スコープの .codex/ レイヤーをスキップする。user / system の config は引き続き読み込まれ、user / global の hooks と rules も読み込まれる
管理されたマシンでは、組織が requirements.toml で制約を強制することがある（approval_policy = "never" や sandbox_mode = "danger-full-access" を禁じるなど）

よく変える設定

設定	内容
`model`	CLI と IDE で既定に使うモデル
`approval_policy`	生成されたコマンドを実行する前に確認するタイミング
`sandbox_mode`	コマンド実行時のファイルシステム／ネットワークアクセスの範囲
`default_permissions` / `[permissions.<name>]`	再利用可能な filesystem / network ポリシー（permission profile）
`[windows].sandbox`	Windows ネイティブ実行時のサンドボックスモード
`web_search`	web search のモード
`model_reasoning_effort`	モデルの reasoning effort
`personality`	対応モデルでの既定のコミュニケーションスタイル
`[tui.keymap]`	ターミナルのショートカット
`[shell_environment_policy]`	spawn したコマンドへ転送する環境変数
`log_dir`	ローカルログの出力先

補足:

Windows ネイティブでは [windows] sandbox = "elevated" が推奨。管理者権限が無い、または elevated のセットアップが失敗する場合にのみ unelevated を使う
web_search の値
- "cached"（既定）: web search cache から結果を返す
- "indexed": 検索インデックスがリクエストを gate する場合にのみ外部 web アクセスを許す
- "live": web から最新データを取得する（--search と同じ）
- "disabled": web search ツールを切る
- キャッシュは OpenAI が保守する web 結果のインデックス。任意のライブコンテンツからの prompt injection への露出を減らすが、web の結果は依然として untrusted として扱うべき
- --yolo などの full access sandbox 設定を使っている場合、web search の既定はライブ結果になる
personality は "friendly" / "pragmatic" / "none"。セッション中は /personality で、app-server API 利用時はスレッド／ターン単位で上書きできる
tui.keymap: composer の一部のアクションは対応する tui.keymap.global のバインドにフォールバックする。対応している場合はコンテキスト固有のバインドが優先される。空リストでそのアクションのバインドを外す
shell_environment_policy.ignore_default_excludes の既定は true で、これは KEY / SECRET / TOKEN を名前に含む変数の自動フィルタをスキップする。自動フィルタを効かせたい場合は false にする
log_dir を明示的に設定すると、そのディレクトリで opt-in の平文 TUI ログ codex-tui.log も有効になる

feature flags

config.toml の [features] テーブルで任意機能・実験的機能を切り替える。

キー	既定	Maturity	説明
`apps`	true	Stable	app（connector）連携
`goals`	true	Stable	永続化された goal と自動継続
`hooks`	true	Stable	`hooks.json` またはインライン `[hooks]` のライフサイクル hook
`fast_mode`	true	Stable	Fast mode の選択と `service_tier = "fast"` の経路
`memories`	false	Experimental	Memories
`multi_agent`	true	Stable	subagent 協調ツール
`personality`	true	Stable	personality の選択コントロール
`remote_plugin`	true	Stable	リモートの plugin カタログ
`shell_snapshot`	true	Stable	シェル環境をスナップショットして繰り返しコマンドを速くする
`shell_tool`	true	Stable	既定の `shell` ツール
`unified_exec`	Windows を除いて `true`	Stable	PTY ベースの統合 exec ツール
`web_search`	true	Deprecated	旧来のトグル。トップレベルの `web_search` 設定を使う
`web_search_cached`	false	Deprecated	未設定時に `web_search = "cached"` に対応づく旧トグル
`web_search_request`	false	Deprecated	未設定時に `web_search = "live"` に対応づく旧トグル

この表はよく使うユーザー向けフラグの一覧であり、内部機能や開発中の機能をすべて挙げたものではない
feature キーを省略すると既定のままになる

feature の有効化

config.toml の [features] 配下に feature_name = true を追加する
CLI からは codex --enable feature_name。複数なら codex --enable feature_a --enable feature_b
無効化は config.toml でキーを false にする

設定

model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"
personality = "friendly"
web_search = "cached"

[windows]
sandbox = "elevated"

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

codex -c log_dir=./.codex-log