配置 Codex 时，最容易出问题的动作不是少写一个键，而是把别人的整份 config.toml 覆盖到自己机器上。这样一次改动可能同时换掉模型、provider、沙箱、审批、联网方式、feature flag 和 MCP；出错后，你看到的只是一句“无法启动”或“设置没生效”，却不知道是哪一层造成的。
更稳妥的顺序是：先确定这项设置应当属于个人、项目、profile 还是一次性命令；只改一个相关块；确认 Codex 能读取；最后再验证认证、网络或外部进程。个人默认配置通常在 ~/.codex/config.toml，受信任仓库可以使用项目内的 .codex/config.toml。Codex CLI 和 IDE 扩展共享这些配置层，具体位置与行为见 OpenAI 的 Config basics。
修改前只备份目标文件，不要为了恢复一个错误表就删除整个 ~/.codex。那个目录还可能保存认证、profiles、规则和其他仍然正常的状态。
先判断设置到底归谁
普通配置从高到低按以下顺序解析：
- CLI 参数和
--config临时覆盖； - 受信任项目中的
.codex/config.toml，离当前目录更近的层优先； --profile选中的独立 profile 文件；- 用户级
~/.codex/config.toml； - Unix 上可能存在的
/etc/codex/config.toml； - Codex 内置默认值。
这是官方 配置优先级 的当前顺序。于是，“我明明改了用户配置，为什么没变化”通常不是文件没保存，而是上方仍有 CLI、项目或 profile 值在覆盖。
可以先用下面的归属规则缩小范围：
| 你想改变的行为 | 建议放置位置 | 不应混入的内容 |
|---|---|---|
| 个人常用模型、推理强度、通知、个人 MCP | 用户级配置 | 仓库团队规则 |
| 某个仓库的执行边界和协作约定 | 受信任项目配置 | 个人 provider 与认证 |
| “只读检查”“深度审查”等可重复模式 | 独立 profile 文件 | 重复整份用户配置 |
| 临时试一个模型或开关 | CLI 参数、-c key=value | 长期默认值 |
| 公司不可绕过的限制 | 管理员 requirements | 依赖用户自觉的普通配置 |
项目配置还有一条硬边界：它不能覆盖机器本地的 provider、认证、profile 选择、通知和遥测类别，当前明确包括 model_provider、model_providers、profile、otel 等。完整名单应以最新 Configuration reference 为准。把这些键从项目文件搬到用户级，比反复调优先级更有效。
个人默认值不需要写成百科全书
一份能工作的起点可以只有几行：
tomlmodel = "gpt-5.6" model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached"
这里表达的是五个独立选择。示例模型并不是永久推荐；先确认你的客户端和账号当前能看到该模型。没有必要固定的值就省略，让当前版本使用自己的默认值。持久键越少，升级后越容易理解“为什么行为变了”。
approval_policy 决定何时暂停并请求批准，sandbox_mode 决定命令能触达哪些资源，它们不是同一个开关。官方把 workspace-write 加 on-request 作为风险较低的本地自动化组合；danger-full-access 加 never 则同时移除沙箱和审批边界，不适合作为普通省事配置。各模式的当前定义在 Sandbox：Configure defaults。
联网也应单独决定。当前顶层 web_search 支持 cached、indexed、live 和 disabled。旧的 [features] web search 开关已经弃用，看到旧模板能被 TOML 解析，不代表它仍是推荐写法。请按最新 Config basics 核对。
Profile 现在是独立文件
如果你经常在日常开发和只读审查之间切换，不要在主文件里维护两套重复表。可以创建：
toml# ~/.codex/read-only-review.config.toml model_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "read-only"
运行时选择：
bashcodex --profile read-only-review
profile 只写与基础用户配置不同的值。项目层和 CLI 参数仍然可以在它之上覆盖。需要特别注意版本迁移：Codex 0.134.0 及以后，--profile 不再读取主 config.toml 里的 [profiles.name]，顶层 profile = "name" 也不再支持。当前格式见 Advanced Config：Profiles。
MCP 配置正确，不等于 MCP 已经可用
本地 STDIO server 至少有三层事实：TOML 表存在、命令能启动、工具能工作。可以把启动信息写清楚：
toml[mcp_servers.docs] command = "docs-server" args = ["--mode", "read-only"] env_vars = ["DOCS_TOKEN"] startup_timeout_sec = 20 tool_timeout_sec = 60 enabled = true
远程 streamable HTTP server 则以 URL 为主，并通过环境变量名引用 token：
toml[mcp_servers.issues] url = "https://mcp.example.internal/mcp" bearer_token_env_var = "ISSUES_MCP_TOKEN" enabled = true
不要把真实 token 直接写进文章、项目文件或求助截图。OpenAI 的 MCP 文档 说明了 STDIO、streamable HTTP、OAuth、环境变量 header、tool allow/deny、timeout 和 required。
当前 CLI 通常可以先列出已解析的 server：
bashcodex mcp list codex mcp --help
支持 OAuth 的 server 还可使用 codex mcp login <server-name>。出现在列表里，只能证明定义被读取；它不能证明可执行文件存在、URL 可达、认证成功或某个 tool 的输入输出正确。
把“没生效”拆成六个检查点
不要从头重写文件。沿着最早未证明的一层继续：
- 文件：编辑的是本机实际读取的用户、项目或 profile 文件吗？
- TOML：当前客户端认识这些键吗？表的嵌套位置正确吗？
- 优先级：CLI、受信任项目或 profile 是否覆盖了用户值？
- 权限：sandbox 和 approval 的组合是否允许目标动作？
- provider：环境变量、认证主体、endpoint、model 和网络是否分别成立？
- MCP：定义、进程/HTTP、认证、tool 调用分别通过了吗？
近期 Codex CLI 提供 --strict-config 和 doctor，但命令是否存在取决于安装版本。先看：
bashcodex --version codex --help codex doctor --help
若本机帮助包含相应选项，可做一次只读检查：
bashcodex --strict-config doctor --summary
--strict-config 用于让未知字段直接报错，doctor 用于检查安装、配置、认证和运行环境。旧版本若没有这些入口，应使用它自己的 --help 和同版本参考，而不是继续粘贴新版本键。
按症状回到最早失败的一层
| 表现 | 优先检查 | 暂时不要做 |
|---|---|---|
| 只在一个仓库里设置无效 | 项目信任、就近 .codex/config.toml | 删除用户配置 |
| CLI 正常，IDE 报缺少 key | IDE 进程能否看到环境变量 | 把 token 写死进 TOML |
| unknown field 或启动解析失败 | 当前版本 reference、strict config | 同时升级并重写全文件 |
| 改了 model 却仍走旧路线 | model_provider、profile、CLI 覆盖 | 只反复改 model 字符串 |
| MCP 已列出但调用不到 | command/URL、认证、timeout、tool | 认为列表等于健康检查 |
| 工作电脑不允许高权限组合 | 企业 requirements.toml | 把禁止值换个本地层再写 |
在受管理的 Business 或 Enterprise 环境里，requirements.toml 可以限制 approval、permission profile、web search、MCP allowlist、plugin 和 feature。用户值与强制规则冲突时，客户端可以回退到允许值并提示。这个边界见 Admin-enforced requirements。这不是优先级技巧能绕过的问题。
最后把每次修改限制为一个可观察目标：选对层、备份、改一个块、解析、做低风险验证、失败则回到最早未证明的边界。这样做看似比复制模板多一分钟，却能避免同时排查模型、provider、权限、feature 和 MCP 的组合故障。
如果真正的问题是“该不该用 Codex”，而不是如何配置它，可以转到 Claude Code 与 Codex 的工作流比较。配置文件无法替你完成产品选择。
