Codex config.toml 不是一个随便粘贴模板的文件。个人默认值放在 ~/.codex/config.toml，可信仓库策略才放 .codex/config.toml，临时实验用命令覆盖，密钥不要写进共享项目。
Codex config.toml 最先要解决的不是“复制哪段配置”，而是“这个设置应该归谁管”。个人默认值放在 ~/.codex/config.toml，可信仓库策略放在 .codex/config.toml，只试一次的模型或权限变化用命令行覆盖，重复使用的 CLI 模式再放进 profile。
不要把 API key、bearer token 或 auth.json 写进共享项目配置。OpenAI 的 Codex 配置、MCP、认证和沙盒文档已按 2026 年 4 月 21 日重新核对。
先决定配置层，而不是先打开文件
| 你要改什么 | 优先放哪里 | 原因 |
|---|---|---|
| 默认模型、审批习惯、通知命令、凭据存储偏好 | ~/.codex/config.toml | 这是你的个人习惯，不应该跟着仓库走 |
| 仓库说明、保守沙盒、团队共用 MCP 名称 | 可信项目里的 .codex/config.toml | 这是项目策略，应该被代码审查看到 |
| 临时模型、临时沙盒、某个嵌套 key | CLI flag 或 --config | 只影响这一次，不污染长期文件 |
| review、fast edit 这类重复 CLI 模式 | [profiles.<name>] | 需要显式 --profile 选择，适合个人预设 |
| 新 MCP server | 先用 codex mcp add | helper 更不容易写错 TOML，也更容易处理 env |
如果你还没分清 ChatGPT 订阅和 API key 该走哪条路线，先看 Codex API Key 和 ChatGPT 订阅怎么选？先看计费路由。如果问题其实是额度或限制，可以继续看 OpenAI Codex 用量限制：Plus、Pro 5x/20x、Business Credits 和 API Key 怎么看。
优先级：冲突时到底谁赢
当前 Codex 配置优先级从强到弱是：
| 顺位 | 层级 | 结果 |
|---|---|---|
| 1 | CLI flags 和 --config | 单次命令可以覆盖下面所有文件 |
| 2 | --profile <name> 选中的 profile | 命名预设覆盖普通文件默认值 |
| 3 | 项目 .codex/config.toml | 只在可信项目里生效；离当前目录最近的可信项目配置优先 |
| 4 | 用户 ~/.codex/config.toml | 你的个人默认层 |
| 5 | 系统 /etc/codex/config.toml | 机器或组织级默认值 |
| 6 | 内置默认值 | 上面都没设置时才使用 |
所以“我改了 config.toml 但没生效”通常不是 Codex 忽略文件，而是别的层级正在赢。先查当前命令有没有 alias、--config 或 --profile，再查当前目录和项目 trust 状态。
个人配置：只放跟你有关的默认值
个人配置适合放模型、审批策略、沙盒偏好和本机凭据存储方式。保持短小比复制完整模板更稳。优先放默认模型、常用审批习惯和本机认证方式，不要把只对某一个仓库生效的策略塞进用户层。
好的个人配置有两个特点：一是能减少你每次启动 Codex 的重复选择，二是不会把 token 写死，也不会默认给整台机器开过宽权限。
项目配置：写共享策略，不写私人状态
项目配置应该保守。它可以告诉 Codex 这个仓库的规则、默认沙盒和项目专用说明，但不应该保存你的私密路由、账号 token 或本机路径。
尤其不要把 danger-full-access 和 approval_policy = "never" 当成共享默认值。danger-full-access 会关闭沙盒；如果再不提示确认，就等于把高信任自动化放进仓库策略。只有在隔离、可丢弃、明确授权的环境里，这类设置才有意义。
MCP、模型和 provider：示例要短，密钥要间接
配置 MCP 时，优先用 codex mcp add 这类 helper，让 Codex 帮你生成更不容易写错的 TOML 结构。
如果确实要直接写 TOML，secret 也应该通过环境变量或系统凭据存储间接注入，而不是直接写进共享文件。
模型默认值也一样：稳定长期使用再写进文件，只试一次就用命令。
openai_base_url 可以让内置 OpenAI provider 走代理、网关或特定 endpoint，但这只是请求路由，不等于自动改变订阅、API 计费或 workspace 政策。
沙盒、审批和 profile
日常本地开发通常从 workspace-write + on-request 开始：Codex 能改当前工作区，但高风险动作仍会停下来确认。代码审查或只读排查可以用 read-only。共享项目里要谨慎使用宽权限。
Profile 适合重复使用的 CLI 预设，例如把 review、fast edit 或只读排查分成几个命名模式。真正执行时，再显式加 --profile <name>。
注意：OpenAI 当前把 profiles 标为 experimental，并说明 IDE extension 不支持它。也就是说，profile 是 CLI 便利功能，不是所有 Codex 表面的通用策略。
配置没生效时按这个顺序查
| 先查什么 | 具体看什么 |
|---|---|
| 当前命令 | alias、flag、--config、--profile |
| 当前目录 | pwd、仓库根目录、子目录里的 .codex/config.toml |
| 项目 trust | 项目没被信任时，项目配置会被跳过 |
| TOML 语法 | 字符串引号、数组、表名、schema hint |
| key 是否还支持 | 官方配置参考和本机 codex --help |
| MCP server | codex mcp get <name> --json |
| 认证状态 | auth.json、keyring、环境变量 |
如果你的问题是桌面控制、浏览器权限或应用交互，不要把它全塞进 config.toml。那是另一条权限路径，应该单独看对应的能力和授权说明。
FAQ
Codex 配置文件到底在哪？
用户配置默认是 ~/.codex/config.toml。可信项目可以有 .codex/config.toml。系统级默认可以是 /etc/codex/config.toml。
API key 应该写进 config.toml 吗？
不要写进共享项目配置。API key、bearer token 和 auth.json 应该放在环境变量、系统凭据存储或其它私密 secret 管理位置。
为什么项目里的 .codex/config.toml 没生效？
先查项目是否 trusted，再查当前目录、是否有更近的项目配置、是否选了 profile，以及命令里是否有 --config 或 flag 覆盖。
什么时候用 --config？
临时实验、一次性模型、临时沙盒变化、嵌套 key 测试都适合 --config。如果这个值变成长期习惯，再移到用户配置或 profile。
danger-full-access 可以用吗？
可以，但只应出现在已经隔离、可丢弃、明确需要宽权限的环境里。普通个人仓库或共享项目不应该把它当默认值。
官方 schema 在哪里？
当前 schema 是 https://developers.openai.com/codex/config-schema.json。支持 schema hint 的编辑器可以在 TOML 顶部加入 #:schema https://developers.openai.com/codex/config-schema.json。