config.toml 常用配置速查

Codex CLI 的用户级配置文件默认位于 ~/.codex/config.toml；如果设置了 CODEX_HOME 环境变量，则位于 $CODEX_HOME/config.toml。文件使用 TOML 语法，顶层键写在所有表头之前。

本文只列常用项，键名与取值按 openai/codex 仓库 commit 4517871 的源码核对；不同版本或不同模型支持的取值可能不同，完整参考请见文末的官方链接。

常用顶层键

键	作用	取值 / 默认值
`model`	选择模型	模型 ID，例如源码模型目录中的 `"gpt-5.5"`；以账号实际可用模型为准
`model_provider`	选择模型提供方	内置的 `openai`，或 `[model_providers]` 中定义的名称
`approval_policy`	命令执行前的审批策略	`"untrusted"`、`"on-request"`（默认；旧别名 `"on-failure"`）、`"never"`；`granular` 需用表结构配置
`sandbox_mode`	沙箱模式	`"read-only"`（默认）、`"workspace-write"`、`"danger-full-access"`
`model_reasoning_effort`	推理强度	`"none"`、`"minimal"`、`"low"`、`"medium"`、`"high"`、`"xhigh"`、`"max"`、`"ultra"`、`"persistent"`
`model_reasoning_summary`	推理摘要详细程度	`"auto"`（默认）、`"concise"`、`"detailed"`、`"none"`
`model_verbosity`	输出详细程度	`"low"`、`"medium"`（默认）、`"high"`
`web_search`	联网搜索模式	`"disabled"`、`"cached"`（默认）、`"indexed"`、`"live"`
`project_doc_max_bytes`	项目指令总字节上限	默认 `32768`（32 KiB）
`notify`	需要通知时执行的外部命令	字符串数组，例如 `["say", "done"]`
`log_dir`	日志目录	设置后会启用纯文本 TUI 日志
`instructions`	自定义系统指令	字符串；作为基础指令使用，谨慎修改

approval_policy 的 granular 模式需要配合一张表来分别控制各类审批；日常使用 "on-request" 即可。model_reasoning_effort 的可用档位由模型决定，不是每个模型都支持最高档。

一个偏保守的示例

# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"
model_reasoning_summary = "auto"
model_verbosity = "medium"
web_search = "cached"
project_doc_max_bytes = 32768

[sandbox_workspace_write]
# 默认不允许联网；需要时再打开
network_access = false
# 在主工作区之外额外允许写入的绝对路径
writable_roots = ["/Users/you/shared-libs"]

workspace-write 默认只允许写入当前工作区以及系统临时目录。writable_roots 用于追加可写目录；network_access = true 会放开沙箱内的联网能力，应结合审批策略一起考虑。

用 `-c` 临时覆盖

命令行覆盖适合一次性试验，不会改动配置文件：

codex -c model_reasoning_effort="low"
codex -c sandbox_mode="read-only" -c approval_policy="on-request"
codex exec -c model_verbosity="high" "解释这个仓库的构建流程"

覆盖值的写法是 键=值，字符串需要加引号。嵌套键可用点号，例如 -c sandbox_workspace_write.network_access=true。

用独立配置文件切换场景

--profile（短选项 -p）会在基础用户配置之上叠加 $CODEX_HOME/<名称>.config.toml。它读取的是独立文件，不是 config.toml 里的 [profiles.<名称>] 表：

codex -p review

对应的 ~/.codex/review.config.toml 可以只写差异项，例如更保守的沙箱与审批组合。这样比在同一个文件里反复改注释更清晰。[profiles] 表属于另一套配置机制，不会由这个 CLI 参数读取。

排错提示

配置写错时，Codex 可能直接报错退出；先用最小配置逐项加回，比盯着整份文件更快。
启动时加 --strict-config，遇到当前版本不认识的键会直接报错，适合在升级后检查遗留配置。
不确定某个键是否生效，可用 /status 查看当前会话的配置与用量，或用 /debug-config 查看配置层与来源。