config.toml 配置指南

config.toml 是 Codex 的机器可读配置文件。它决定默认模型、推理强度、沙箱和审批策略，也可以注册 MCP 服务器、保存命令行之外的常用选项。它不替代 AGENTS.md：前者控制工具行为，后者提供项目规则和工作上下文。本页按“位置 -> 信任 -> 优先级 -> 字段 -> 验证 -> 诊断 -> 安全边界”的顺序展开。Codex CLI、桌面应用和账号能力会持续更新，模型名、实验开关和部分 profile 语法可能变化。每次排查时都以本机 codex --help、子命令帮助和官方 Config Reference 为最终依据。

先记住四条规则

用户配置通常位于 CODEX_HOME/config.toml；未设置 CODEX_HOME 时，CODEX_HOME 默认是用户主目录下的 .codex。
项目配置位于仓库或项目目录的 .codex/config.toml，只有项目处于可信状态时才会加载。
越具体、越接近当前启动命令的设置通常优先级越高；命令行覆盖只影响这次运行。
配置可以放宽行为，但不能把不可信项目变成可信项目，也不能替代人工审查、凭据隔离和备份。

1. 配置文件在哪里

1.1 用户级配置

用户级配置是个人默认值，适用于当前用户启动的多个项目：

Unix/macOS:  ~/.codex/config.toml
Windows:     %USERPROFILE%\\.codex\\config.toml
自定义目录:   $CODEX_HOME/config.toml

例如 Windows PowerShell：

$env:CODEX_HOME
Join-Path $HOME ".codex"
Test-Path (Join-Path $HOME ".codex\\config.toml")

例如 macOS 或 Linux：

printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"
ls -la "${CODEX_HOME:-$HOME/.codex}/config.toml"

文件不存在时可以创建。首次编辑前先备份已有文件，避免把登录、历史、MCP 或个人设置一并覆盖：

cp ~/.codex/config.toml ~/.codex/config.toml.bak

Copy-Item "$HOME\\.codex\\config.toml" "$HOME\\.codex\\config.toml.bak"

用户级配置适合放：

个人常用的 model 和 model_reasoning_effort；
默认的 sandbox_mode、approval_policy；
自己管理的 MCP 服务器；
自己的 profiles 或 profile 文件；
通知、日志和模型提供方等机器级设置。

不要把 API key、OAuth 刷新令牌、SSH 私钥或数据库密码写进配置文件。需要凭据时使用 Codex 支持的登录机制、环境变量或系统密钥存储，并检查文件权限。

1.2 项目级配置

项目级配置通常是：

<项目根目录>/.codex/config.toml

它适合表达“这个项目的默认行为”，例如项目只允许只读分析，或该项目需要一个特定模型。项目文件可能进入 Git，因此任何提交者都能影响它；只写团队确实需要共享、且不会泄露环境信息的设置。

# <repo>/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false

项目配置不是“无条件自动执行的项目脚本”。Codex 会先判断工作区是否可信；不可信时会跳过项目 .codex/ 层，包括其中的配置、hooks 和 rules。这样可以避免 clone 一个陌生仓库就被它的配置主动放宽权限。判断项目是否可信时，不要只看仓库名。确认来源、提交者、依赖和构建脚本，检查是否含有可疑的 AGENTS.md、hooks、安装脚本或要求外发数据的指令。只有在你完成检查后才接受信任提示。

1.3 系统级配置

受管理环境还可以提供系统级配置，用来给一台机器或一组用户设定基线。Unix 环境常见位置是：

/etc/codex/config.toml

实际支持的位置、Windows 的等价位置以及是否启用系统层，取决于当前 Codex 版本和安装方式。不要因为某个目录存在就假设 Codex 会读取它；使用官方 Config Reference 和启动日志确认。系统级配置适合管理员设定组织基线，例如禁止完全访问、统一默认模型提供方或限制遥测出口。它不应保存个人令牌。系统管理员还可以通过设备策略、容器、网络防火墙和文件权限提供比 TOML 更高层的约束。

2. 信任条件和项目边界

2.1 为什么项目层需要信任

项目配置是仓库内容的一部分，而仓库内容可能来自不可信来源。假设项目配置可以无条件设置通知命令、遥测端点、模型服务地址或高权限行为，那么一次打开陌生项目就可能把数据发送到外部服务。因此 Codex 对项目层设置增加信任门槛，并对部分机器级字段直接忽略。 “不信任项目”并不等于不能阅读项目。通常仍可以在只读沙箱中检查文件、查看 Git 状态和分析代码；只是项目本地配置、规则和 hooks 不会作为可信行为加载。

2.2 哪些设置不应由项目控制

即使项目被信任，也不要把下面这些设置交给来自仓库的配置：

model_provider、model_providers、openai_base_url、chatgpt_base_url；
notify、otel、外部日志或遥测出口；
profile、profiles 等影响全局配置选择的设置；
认证、账号、密钥、代理和本机路径；
会让工具访问整个文件系统或关闭所有审批的设置。

官方会忽略部分机器级键在项目本地 .codex/config.toml 中的值，并可能输出警告。看到“配置写了却没生效”时，先检查它是否属于项目层禁用字段，而不是重复修改文件。

3. 配置优先级

3.1 一张实用的优先级图

实际合并细节会随版本和入口变化，但排查时可以先按下面的原则理解：

层级	来源	作用范围	典型用途
1	命令行专用选项、`-c/--config`	当前进程	临时试验一个值
2	当前可信项目层	当前项目	项目共享默认
3	`--profile` 选中的配置	当前进程或 profile	切换一整套个人设置
4	用户级 `config.toml`	当前用户	跨项目默认
5	系统级配置	机器或组织	管理员基线
6	内置默认值	所有未设置场景	最终兜底

不要把这张表理解成“所有键都严格按同一套合并算法覆盖”。有些键只能在用户层设置，有些专用命令行选项会在解析阶段生效，有些表是合并而不是整表替换。遇到行为差异，应以启动时的诊断信息和当前版本文档为准。一个键发生冲突时，先问四个问题：

这是不是专用命令行参数直接指定的？
当前项目是否可信，项目层是否真的被加载？
是否通过 --profile 选择了另一份配置？
该键是否属于只允许用户级的机器级设置？

3.2 根键和表的 TOML 顺序

TOML 中，根键必须放在表声明之前。把根键写到 [mcp_servers.foo] 后面，可能会让它被解释为表内字段或触发解析错误。

# 正确：根键先写
model = "gpt-5.5"
approval_policy = "on-request"

[features]
memories = false

# 容易出错：model 已经处在 features 表中
[features]
memories = false
model = "gpt-5.5"

同一个表或同一个键不要重复定义。字符串必须用引号，布尔值只能写 true 或 false，数组和内嵌表要使用合法 TOML 语法。

4. 常用顶层字段

4.1 `model`

model 设定默认模型：

model = "gpt-5.5"

可用模型会随账号、入口和版本变化。不要照抄过时模型名；在会话中用 /model 查看可用列表，或使用当前 CLI 支持的模型帮助。模型选择不是权限边界：更强模型仍然受沙箱、审批、网络和账号限制约束。模型选择建议与任务匹配：简单改名、格式化和批量机械操作可以选择更快的模型；跨模块重构、复杂调试和安全审查通常需要更强模型或更高推理强度。不要把“最强”配置成全局默认后忘记等待时间、成本和上下文规模。

4.2 `model_reasoning_effort`

model_reasoning_effort 控制支持推理的模型投入多少推理资源：

model_reasoning_effort = "medium"

常见值包含 minimal、low、medium、high，部分模型支持 none 或 xhigh。可选值不是所有模型通用，当前模型不支持时会报错或回退。建议从 medium 开始，简单任务降到 low，复杂设计和难定位的 bug 再提高。推理强度会影响延迟、额度和输出深度，但不会替你验证结果。无论强度多高，都应阅读 diff、运行测试并检查外部副作用。

4.3 `approval_policy`

审批策略控制 Codex 何时请求人工批准：

approval_policy = "on-request"

常见策略如下：

值	含义	适合场景
`untrusted`	对不被视为安全的操作更谨慎地请求批准	陌生项目、首次检查
`on-request`	沙箱内常规操作自动进行，越过边界时请求批准	日常开发
`never`	不请求审批，但仍受沙箱和其他系统边界限制	可复现的 CI 或隔离环境

never 不是“拥有全部权限”。只读沙箱配 never 仍然不能写入文件；工作区可写配 never 仍可能不能访问工作区之外或网络。不要把 never 和真实生产目录、真实密钥、未审查仓库一起使用。命令行等价写法：

codex --ask-for-approval on-request
codex -a untrusted

4.4 `sandbox_mode`

sandbox_mode 设定文件系统和网络的粗粒度边界：

sandbox_mode = "workspace-write"

常见模式：

值	能力	推荐用途
`read-only`	只读分析，写入和其他越界动作需要额外处理	审查陌生代码、生成方案
`workspace-write`	允许工作区和指定可写根目录写入	日常开发
`danger-full-access`	移除大部分本地沙箱限制	隔离容器或一次性虚拟机

在 Git 工作区中，Codex 常见默认是工作区可写；非 Git 目录可能默认只读。默认行为可能因平台和启动入口改变，使用 /status 或当前版本帮助确认。命令行等价写法：

codex --sandbox read-only
codex -s workspace-write

4.5 `web_search`

web_search 控制网页搜索工具：

web_search = "cached"

常见值：

cached：使用缓存或预索引结果，通常是更保守的默认；
live：允许实时网页搜索，结果更新但更容易接触提示注入和不可信内容；
disabled：禁用网页搜索。

需要实时信息时可以使用：

web_search = "live"

实时网页不是可信指令来源。不要因为页面要求复制密钥、执行下载脚本、关闭沙箱或改变配置就照做。搜索结果只作为资料，代码变更仍需要本地验证。某些完全访问或专用搜索参数可能改变搜索模式，以当前版本帮助为准。

4.6 `writable_roots`

writable_roots 用于在工作区可写模式下额外声明允许写入的目录。字段名称、是否支持以及路径解析方式应以当前 Config Reference 为准；常见配置形态如下：

sandbox_mode = "workspace-write"
writable_roots = [
  "/tmp/codex-build",
  "/workspaces/shared-cache",
]

Windows 路径示例：

sandbox_mode = "workspace-write"
writable_roots = [
  "C:\\Users\\you\\AppData\\Local\\Temp\\codex-build",
]

使用时遵循三条原则：目录先创建并确认归属；只加入构建缓存、临时输出等必要路径；不要把整个用户主目录、根目录、云盘同步目录或包含密钥的目录加入列表。writable_roots 是沙箱允许范围的补充，不是审批策略，也不是把路径加入后就能绕过操作系统 ACL。建议先打印规范化路径，再启动 Codex：

realpath /tmp/codex-build

[System.IO.Path]::GetFullPath("C:\\Users\\you\\AppData\\Local\\Temp\\codex-build")

4.7 工作区网络设置

工作区可写通常不代表默认可以联网。需要联网安装依赖时，显式配置并缩小范围：

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

网络打开后，安装脚本、依赖包、远程 API 和实时网页都成为新的输入边界。优先使用锁定版本、包管理器校验和公司代理；安装完成后关闭网络或恢复为 false。不要把网络访问误当作“只允许访问某个域名”，域名白名单需要更细粒度的权限配置或外部防火墙。

5. MCP 配置

5.1 MCP 是什么

MCP 服务器向 Codex 暴露工具或资源，例如文档查询、数据库只读检索或内部工单系统。MCP 的权限与 Codex 本身的沙箱、审批并不自动等价：MCP 服务器进程可能拥有它自己的文件、网络和凭据权限。只连接你审查过的服务器。先确认启动命令、包来源、环境变量、网络目标、日志位置和服务器实际能做的操作，再决定是否启用。

5.2 一个 stdio MCP 示例

常见 TOML 结构如下，具体字段以当前版本 MCP 配置参考为准：

[mcp_servers.docs]
command = "npx"
args = ["-y", "@example/docs-mcp", "--readonly"]
enabled = true
startup_timeout_ms = 10000
tool_timeout_ms = 30000

[mcp_servers.docs.env]
DOCS_BASE_URL = "https://docs.example.com"

使用绝对路径可以减少 PATH 差异：

[mcp_servers.local_tools]
command = "/usr/local/bin/my-docs-mcp"
args = ["--readonly"]
enabled = true

不要把令牌直接写在 args 或 TOML 中：

# 不要这样做
# args = ["--token", "sk-live-真实密钥"]

如果服务器需要凭据，使用 Codex 支持的环境变量注入方式或独立凭据存储，并确认日志不会打印环境变量。

5.3 MCP 调试顺序

MCP 不工作时按这个顺序缩小范围：

用 codex --help 和当前文档确认表名、字段名和传输方式。
在终端单独运行服务器命令，确认它能启动并输出预期协议内容。
确认 command 在 Codex 进程的 PATH 中可见，工作目录和 Node/Python 版本一致。
先设置 enabled = false 启动 Codex，确认基础配置正常，再单独启用一个服务器。
查看 Codex 的 MCP 状态或日志，区分启动失败、握手失败、工具超时和权限拒绝。
用只读、无真实数据的请求验证工具，确认服务器没有越权写入或外发。

多个 MCP 服务器应逐个加入。一个服务器的崩溃、超时或恶意工具不应阻塞整个工作流，也不应因为“方便”给所有服务器共享同一个高权限令牌。

6. profiles 与配置文件复用

6.1 profile 的用途

profile 适合保存几套个人配置，例如只读审查、日常开发和隔离自动化。常见做法是在 CODEX_HOME 下创建独立文件：

~/.codex/review.config.toml
~/.codex/build.config.toml

# ~/.codex/review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "untrusted"
web_search = "cached"

# ~/.codex/build.config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

启动时选择：

codex --profile review
codex exec --profile build "运行测试并总结失败原因"

profile 文件仍然是机器级个人配置，不要提交到项目仓库，也不要把它当作项目可信声明。若多个 profile 之间差异很大，文件中明确写全关键安全字段，避免继承关系变化后出现意外放宽。

6.2 旧版 `[profiles]` 语法

不同版本对 [profiles.name]、顶层 profile 和独立 <name>.config.toml 文件的支持可能不同。新版本可能要求使用独立 profile 文件，并不再读取旧的嵌套写法。升级后发现 profile 不生效时，执行：

codex --help
codex --profile review --help

不要同时在项目配置中设置 profile 来强迫每个人使用某套个人配置。项目可以共享安全的默认值，profile 选择应由启动者明确完成。

7. 命令行覆盖

7.1 专用参数

临时试验优先使用专用参数：

codex --model gpt-5.4-mini \
  --sandbox read-only \
  --ask-for-approval untrusted

常见快捷方式包括 -m、-s 和 -a，但以 codex --help 为准。会话内也可能提供 /model、/permissions 和 /status 等命令；它们通常只影响当前会话。

7.2 `-c` / `--config`

没有专用参数时，可以用 -c 或 --config 指定键值：

codex -c web_search='"live"'
codex -c model_reasoning_effort='"high"'
codex -c mcp_servers.docs.enabled=false

-c 的值按 TOML 解析，不是 JSON。字符串需要 TOML 双引号；上例外层单引号只是让 shell 把整段作为一个参数。在 PowerShell 中也要留意引号：

codex -c 'web_search="live"'
codex -c 'mcp_servers.docs.enabled=false'

命令行覆盖不会改写 config.toml。验证完成后，如果确实要长期使用，再把最小必要值写入合适层级。不要把包含令牌的完整命令复制到聊天记录、Issue 或 shell 历史。

7.3 覆盖后的验证

用三个层次确认覆盖确实生效：

codex -c sandbox_mode='"read-only"'

进入会话后：

/status

再用普通 codex 启动一次，确认配置已恢复原值。若两次结果一样，检查参数位置、子命令继承方式和当前 CLI 版本，而不是直接把用户配置改成更宽松的值。

8. 一份安全的起步配置

下面是适合个人开发机的保守示例。模型名请替换为当前账号可用的值：

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "cached"

[sandbox_workspace_write]
network_access = false

[features]
# 只显式设置你确认需要的开关；实验功能名称以当前版本为准。
memories = false

对陌生项目使用更严格的项目配置：

# <repo>/.codex/config.toml
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "untrusted"
web_search = "disabled"

需要生成构建产物到工作区之外时，先创建专用临时目录，再只加入它：

sandbox_mode = "workspace-write"
writable_roots = ["/tmp/codex-build"]

不要把下面这组配置作为日常全局默认：

# 高风险示例，仅适用于已隔离且可销毁的环境
sandbox_mode = "danger-full-access"
approval_policy = "never"

命令行的 --yolo 或 --dangerously-bypass-approvals-and-sandbox 同样属于高风险组合。本机、生产机和存有个人凭据的环境不要使用。

9. 配置验证

9.1 先验证 TOML，再验证 Codex 行为

TOML 语法正确不等于 Codex 认识所有字段。验证应分两步：

python - <<'PY'
import pathlib
try:
    import tomllib
except ModuleNotFoundError:
    import tomli as tomllib
p = pathlib.Path.home() / ".codex" / "config.toml"
with p.open("rb") as f:
    data = tomllib.load(f)
print("TOML parsed:", p)
print("top-level keys:", ", ".join(sorted(data)))
PY

如果不希望依赖 Python，使用你组织批准的 TOML 校验器。不要用正则表达式判断嵌套表是否正确。然后检查 Codex 本身：

codex --version
codex --help
codex

在会话中执行：

/status

重点核对模型、推理强度、沙箱、审批、网络和工作区目录。配置文件中的未知字段可能被忽略、警告或在新版本中变成错误，必须关注启动输出。

9.2 用无害动作验收

不要用删除文件或发送真实请求验证权限。可以使用临时目录和无敏感数据的测试：

mkdir -p /tmp/codex-config-check
cd /tmp/codex-config-check
printf 'check\n' > input.txt
git init
codex --sandbox read-only --ask-for-approval never

在只读会话中请求读取 input.txt，再请求创建测试文件。预期前者可以完成，后者会被沙箱拒绝或要求升级权限。退出后删除测试目录前确认路径：

pwd

验证 MCP 时只调用只读工具，并使用测试账号。验证实时搜索时不要让它执行页面中的命令。

9.3 检查只改了一个文件

配置通常在用户目录而不在项目 Git 中；项目配置则要审查 diff：

git diff --check
git status --short
git diff -- .codex/config.toml

检查文件权限和秘密扫描结果。不要因为 git diff 没有显示用户级配置就认为它没有生效；确认 CODEX_HOME 和 /status 才是关键。

10. 错误诊断

配置文件完全没有生效

按顺序确认：

路径是否是实际的 CODEX_HOME/config.toml；
文件名是否确实为 config.toml，没有隐藏的 .txt 后缀；
TOML 是否能被解析；
是否启动了不同的 Codex 二进制或不同用户；
是否被 --profile、-c 或专用参数覆盖；
当前工作区是否不可信，导致项目层被跳过。

项目层值没有生效

先查看项目根目录和当前工作目录是否正确，再确认项目信任状态。然后检查字段是否属于项目禁区，例如模型提供方、通知、遥测、profile 等。最后用一个不会放宽权限的普通字段测试，避免把排查变成安全降级。

报“未知字段”或“无效值”

模型、推理档位、features 开关和 profile 语法都可能版本相关。执行：

codex --help
codex exec --help

逐项删除最近增加的字段，直到基础配置能启动，再按官方参考逐项加回。不要为了消除错误把字段名随意改成看起来相似的名称。

`-c` 报 TOML 或 shell 错误

字符串值是否有 TOML 双引号？外层 shell 是否把参数拆开？嵌套字段是否使用点号？先用布尔值测试：

codex -c mcp_servers.docs.enabled=false

再测试字符串：

codex -c model='"gpt-5.5"'

模型不可用或被拒绝

模型可能不属于账号、入口或当前地区，也可能已经弃用。用 /model 查看可选模型；不要只根据旧文章中的模型名编辑配置。若切换模型后推理强度无效，选择该模型支持的档位。

MCP 启动失败

先单独运行 command，再核对 PATH、Node/Python 环境、参数、超时和环境变量。把服务器设为 enabled = false 后确认 Codex 本身能启动。若服务器能启动但工具失败，区分协议握手、工具权限、网络和业务 API 错误，分别处理。

网络搜索或依赖安装失败

web_search = "live" 只影响搜索工具，不等于所有 shell 命令都能联网。workspace-write 下网络也可能默认关闭，需要检查 [sandbox_workspace_write]。公司代理、防火墙、证书和包管理器配置仍然可能阻断请求。

配置修改后仍表现为旧值

关闭并重新启动会话，确认没有复用旧进程。检查 profile、命令行覆盖、环境变量和项目层。用 /status 记录有效值，比较“普通启动”和“带覆盖启动”的差异。

11. 安全边界

不要把配置当成信任系统

approval_policy = "never" 只是不弹审批；它不验证提示内容，也不阻止恶意依赖、网页提示注入或 MCP 工具执行危险操作。danger-full-access 更不会自动识别“安全命令”。权限越宽，人工审查和环境隔离越重要。

保护凭据和外发数据

不要让 Codex 读取包含令牌的目录，也不要把 .env、SSH 目录、浏览器配置、云凭据目录加入 writable_roots。实时搜索、MCP、通知和遥测都可能把上下文或元数据送到外部系统；确认数据去向、保留期和访问主体。

生产环境和自动化

生产目录优先使用 read-only，发布动作由独立 CI 或人工审批完成。CI 若使用 approval_policy = "never"，应在一次性容器中运行，使用最小权限令牌、固定依赖和出站网络限制。不要把全局 danger-full-access 写入开发机配置后再期待每个项目都安全。

项目配置的提交策略

提交 .codex/config.toml 前检查：没有密钥、个人路径、内部域名、通知命令和未经团队批准的权限放宽。团队共享配置应倾向：read-only 或 workspace-write、on-request、关闭不需要的网络，并在项目 README 中说明如何验证和回滚，而不是偷偷依赖个人机器状态。

12. 速查表

需求	配置或命令	注意
设置默认模型	`model = "..."`	模型以 `/model` 实际列表为准
调整推理	`model_reasoning_effort = "medium"`	支持档位随模型变化
工作区内开发	`sandbox_mode = "workspace-write"`	网络不一定默认开启
只读审查	`sandbox_mode = "read-only"`	可配 `approval_policy = "never"` 做安静分析
出圈时询问	`approval_policy = "on-request"`	不等于允许越界
关闭网页搜索	`web_search = "disabled"`	不影响其他网络工具
临时改一个值	`codex -c key=value`	值按 TOML 解析
查看有效设置	会话内 `/status`	以当前会话为准
切换 profile	`codex --profile name`	profile 文件在 `CODEX_HOME`
增加可写目录	`writable_roots = ["..."]`	只加入最小必要目录
注册 MCP	`[mcp_servers.name]`	先审查命令、凭据和网络

小结

config.toml 的正确用法不是把所有开关都打开，而是让配置层级和安全边界清晰：用户级放个人默认和机器级设置，可信项目层放项目共享行为，系统层提供组织基线，命令行用于一次性试验。模型和推理决定“用多少能力”，沙箱和 writable_roots 决定“能碰哪里”，审批决定“什么时候问人”，web_search 和 MCP 决定“哪些外部信息或工具进入流程”。遇到不生效时，不要先放宽权限。先确认 CODEX_HOME、项目是否可信、优先级、字段是否被项目层禁止、TOML 是否有效，以及 /status 显示的实际值。配置验证通过后仍要审查 diff、测试结果、网络请求和凭据边界。参考资料：参考/codex/18-config.md、参考/codex/30-models.md、参考/codex/15-permissions.md。动态字段和默认值以本地 Codex 版本及官方 Config Reference 为准。

​config.toml 配置指南

​先记住四条规则

​1. 配置文件在哪里

​1.1 用户级配置

​1.2 项目级配置

​1.3 系统级配置

​2. 信任条件和项目边界

​2.1 为什么项目层需要信任

​2.2 哪些设置不应由项目控制

​3. 配置优先级

​3.1 一张实用的优先级图

​3.2 根键和表的 TOML 顺序

​4. 常用顶层字段

​4.1 model

​4.2 model_reasoning_effort

​4.3 approval_policy

​4.4 sandbox_mode

​4.5 web_search

​4.6 writable_roots

​4.7 工作区网络设置

​5. MCP 配置

​5.1 MCP 是什么

​5.2 一个 stdio MCP 示例

​5.3 MCP 调试顺序

​6. profiles 与配置文件复用

​6.1 profile 的用途

​6.2 旧版 [profiles] 语法

​7. 命令行覆盖

​7.1 专用参数

​7.2 -c / --config

​7.3 覆盖后的验证

​8. 一份安全的起步配置

​9. 配置验证

​9.1 先验证 TOML，再验证 Codex 行为

​9.2 用无害动作验收

​9.3 检查只改了一个文件

​10. 错误诊断

​配置文件完全没有生效

​项目层值没有生效

​报“未知字段”或“无效值”

​-c 报 TOML 或 shell 错误

​模型不可用或被拒绝

​MCP 启动失败

​网络搜索或依赖安装失败

​配置修改后仍表现为旧值

​11. 安全边界

​不要把配置当成信任系统

​保护凭据和外发数据

​生产环境和自动化

​项目配置的提交策略

​12. 速查表

​小结