Codex config.toml 設定：置き場所、優先順位、安全な例

Codex config.toml の最初の判断は、「どの key を書くか」ではなく「その設定をどの層が所有するか」です。個人の default は ~/.codex/config.toml、trusted project の共有 policy は .codex/config.toml、一度だけ試す値は CLI flag や --config、繰り返す CLI mode は profile に分けます。

OpenAI の Codex config、MCP、authentication、sandbox の文書は 2026 年 4 月 21 日時点で確認しています。コマンド例は手元の codex-cli 0.121.0 の help 出力に合わせています。

まず設定の置き場所を決める

Codex を subscription で使うのか API key で使うのかがまだ曖昧なら、先に Codex API key と subscription の違い を見てください。quota の問題なら Codex usage limits guide が別の入口です。

優先順位：どの設定が勝つか

現在の優先順位は強い順にこうです。

設定が効かないときは、ファイルそのものより先に、command alias、--config、selected profile、cwd、project trust を疑うべきです。

User config は個人 default だけにする

短い personal config から始めるのが安全です。

toml
#:schema https://developers.openai.com/codex/config-schema.json

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
allow_login_shell = false
cli_auth_credentials_store = "keyring"

この例は、default model、approval policy、workspace write、login shell の扱い、credential store を指定しています。API key や bearer token を直接書く例ではありません。auth.json には access token が含まれうるため、共有や commit は避けるべきです。

Project config は共有 policy に絞る

.codex/config.toml は、リポジトリが責任を持てる policy のために使います。

toml

#:schema https://developers.openai.com/codex/config-schema.json

approval_policy = "untrusted"
sandbox_mode = "workspace-write"
allow_login_shell = false

developer_instructions = """
Follow this repository's AGENTS.md.
Keep generated assets in documented project paths.
Do not commit credentials, auth state, or provider tokens.
"""

共有 project config に danger-full-access や approval_policy = "never" を入れるなら、かなり強い理由が必要です。danger-full-access は sandbox を無効にします。確認なしの policy と組み合わせると、高信頼の自動化 mode になります。

MCP と provider は helper から始める

MCP は先に CLI helper を使います。

bash
codex mcp add docs --env DOCS_TOKEN="$DOCS_TOKEN" -- node ./mcp/docs-server.mjs
codex mcp get docs --json

TOML を直接書く場合も secret は環境変数経由にします。

toml
[mcp_servers.docs]
command = "node"
args = ["./mcp/docs-server.mjs"]
env_vars = ["DOCS_TOKEN"]
startup_timeout_sec = 10
tool_timeout_sec = 60
required = true

openai_base_url は built-in OpenAI provider の送信先を変える設定です。subscription、API key billing、workspace policy の判断とは別です。ここを混ぜると、config の問題と請求経路の問題が見えなくなります。

Sandbox、approval、profiles

通常の開発なら、まず workspace-write と on-request が扱いやすい出発点です。review だけなら read-only。隔離された automation でなければ danger-full-access を default にしない方が安全です。

1回だけの変更は永続ファイルに書かず、コマンドで試します。

bash
codex --model gpt-5.4-mini
codex --sandbox read-only
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true

繰り返す CLI preset は profile にできます。

toml
[profiles.review]
model = "gpt-5.4"
sandbox_mode = "read-only"
approval_policy = "on-request"

bash
codex --profile review

ただし profiles は OpenAI 文書上 experimental で、IDE extension ではサポートされていません。CLI convenience として扱い、全 surface 共通の policy とは考えない方が安全です。

効かないときの確認順

ブラウザ操作や desktop permissions を扱うなら、config.toml だけで考えないでください。その領域は Codex Computer Use guide の方が近いです。

FAQ

Codex config.toml はどこにありますか？

user config は ~/.codex/config.toml です。trusted project は .codex/config.toml を持てます。system config は /etc/codex/config.toml です。

API key を config.toml に書いてよいですか？

共有 project config には書かないでください。environment variables、OS keyring、または適切な private secret 管理を使います。

project config が効かない理由は？

project trust、cwd、近い .codex/config.toml、selected profile、CLI flags、--config を確認してください。

--config はいつ使いますか？

1回だけ試す model、sandbox、nested key に使います。習慣化した値だけ user config や profile に移します。

danger-full-access は使えますか？

使えますが、すでに隔離されていて broad access が本当に必要な環境だけにしてください。shared repo の default には向きません。

公式 schema はどこですか？

https://developers.openai.com/codex/config-schema.json です。TOML の先頭に #:schema https://developers.openai.com/codex/config-schema.json を置くと editor が補助できます。