基础配置

Codex 会从多个位置读取配置。你的个人默认值位于 ~/.codex/config.toml，也可以用 .codex/config.toml 添加项目级覆盖。出于安全考虑，Codex 只会在你信任该项目时加载项目 .codex/ 层。

Codex 将用户级配置存储在 ~/.codex/config.toml。若要把设置限定到特定项目或子目录，请在 repo 中添加 .codex/config.toml 文件。

要从 Codex IDE extension 打开配置文件，请选择右上角齿轮图标，然后选择 Codex Settings > Open config.toml。

CLI 和 IDE extension 共用同一套配置层。你可以用它们来：

Codex 会按以下顺序解析值（优先级从高到低）：

利用该优先级在 config.toml 中设置共享默认值，并让 profile files 只保留差异值。

如果你将项目标记为 untrusted，Codex 会跳过项目级 .codex/ 层，包括项目本地 config、hooks 和 rules。用户和系统 config 仍会加载，包括 user/global hooks 和 rules。

For one-off overrides via -c/--config (including TOML quoting rules), see Advanced Config .

On managed machines, your organization may also enforce constraints via requirements.toml (例如, disallowing approval_policy = "never" 或 sandbox_mode = "danger-full-access")。See Managed configuration 和 Admin-enforced requirements .

Here are a few options people change most often:

选择 the model Codex uses by 默认 in the CLI 和 IDE.

model = "gpt-5.5"

Control 当 Codex pauses 到 ask 之前 running generated commands.

approval_policy = "on-request"

For behavior differences between untrusted, on-request, 和 never, see 运行 不使用 approval prompts 和 Common sandbox 和 approval combinations .

Adjust how much filesystem 和 network access Codex has while executing commands.

sandbox_mode = "workspace-write"

For mode-by-mode behavior (including protected .git/.codex paths and network defaults), see Sandbox 和 approvals , Protected paths in writable roots , 和 Network access .

Codex also supports named permission profiles for reusable filesystem 和 network policies。Built-in profiles are :读取-only, :workspace, 和 :danger-full-access。Custom profiles 使用 [permissions.<name>] tables 和 a matching 默认_permissions value。See Permissions .

当 running Codex natively on Windows, 设置 the native sandbox mode 到 elevated in the windows table。使用 unelevated only 如果 you don’t have administrator permissions 或 如果 elevated setup fails.

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

Codex enables web 搜索 by 默认 for local tasks 和 serves results 从 a web 搜索 cache。The cache is an 打开AI-maintained index of web results, so cached mode returns pre-indexed results 而不是 fetching live pages。This reduces exposure 到 prompt injection 从 arbitrary live content, but you should still treat web results as untrusted。如果 you are using --yolo 或 another full access sandbox setting , web 搜索 默认s 到 live results。选择 a mode 使用 web_search:

web_search = "cached"  # default; serves results from the web search cache
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

Tune how much reasoning effort the model applies 当 支持的.

model_reasoning_effort = "high"

设置 a 默认 communication style for 支持的 models.

personality = "friendly" # or "pragmatic" or "none"

You can override this later in an active session 使用 /personality 或 per thread/turn 当 using the app-server APIs.

Customize terminal shortcuts under tui.keymap。Selected composer actions fall back 到 matching tui.keymap.global bindings；context-specific bindings take precedence 当 支持的。An empty 列出 unbinds the action.

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

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

[tui.keymap.chat]
interrupt_turn = "f12"

Control which environment variables Codex forwards 到 spawned commands.

[shell_environment_policy]
include_only = ["PATH", "HOME"]

Override where Codex writes local log files。Setting log_dir explicitly also enables the opt-in plaintext TUI log, codex-tui.log, in that directory.

log_dir = "/absolute/path/to/codex-logs"

For one-off runs, you can also 设置 it 从 the CLI:

codex -c log_dir=./.codex-log

使用 the [features] table in config.toml 到 切换 可选 和 experimental capabilities.

[features]
shell_snapshot = true           # Speed up repeated commands

The 成熟度 column uses feature maturity labels such as Experimental, Beta, 和 Stable。See Feature Maturity for how 到 interpret these labels.

For lifecycle hook configuration, see Hooks .