结论先说
- 旧版内联
[profiles.<name>]已正式废弃并触发启动报错。在新版 Codex CLI 中,不能再把多个场景区块堆在主~/.codex/config.toml里,也不能保留旧版顶层profile = "..."字段。 - 每个场景拆成独立的
<name>.config.toml文件。文件直接放在~/.codex/目录(Windows 为%USERPROFILE%\.codex\,自定义环境变量时为$CODEX_HOME/)下,原区块里的键提升为顶层键即可。 - 通过
--profile <name>(简写-p <name>)按需加载。运行时 Codex 会先读取基础config.toml,再把<name>.config.toml里的字段叠加覆盖上去,未重写的通用配置会自动沿用。 - 注意项目级配置和命令行参数的覆盖顺序。命令行显式传参(如
-c、--model)优先级最高,其次是受信任仓库里的.codex/config.toml,然后才是--profile指定的独立文件。 - 多场景高频切换跑深度审查需要充足订阅额度。若国内无外币卡或绑卡失败,可在本站自助开通 ChatGPT Plus 或高配额的 ChatGPT Pro,团队多人共用规范可了解 ChatGPT Business 团队定制。

图:本站根据 OpenAI Codex 官方文档:Advanced Configuration 整理的示意图
本文根据 OpenAI Codex 官方文档《Advanced Configuration》《Configuration Reference》《Command line options》整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 升级新版 Codex CLI 后启动报错,提示旧版
[profiles.*]或profile = "..."不再受支持的老用户; - 需要在日常开发、只读代码审查、自动化脚本等不同工作流之间一键切换模型、推理强度和权限策略的开发者;
- 希望厘清
config.toml、独立 Profile 文件、项目级配置和命令行参数到底谁覆盖谁的人。
一、为什么旧版 Profile 会报错:从内联区块到独立文件
早期版本的 Codex CLI 允许用户在单一 ~/.codex/config.toml 中通过 [profiles.review]、[profiles.fast] 等子表管理多套预设,并在顶层用 profile = "review" 指定默认项。随着权限配置文件、MCP 服务器、OpenTelemetry 和 TUI 选项越来越多,单一 TOML 文件动辄上百行,嵌套表头极易写错层级。
新版 Codex 改为独立 Profile 文件机制:主配置文件 ~/.codex/config.toml 只保留跨场景通用的基础配置(例如默认模型、通用 MCP 服务、界面通知),需要按场景切换的差异项则存为同目录下的 <name>.config.toml。只要主文件里还残留 [profiles.*] 区块或顶层 profile 字段,新版 CLI 就会直接报错拒绝启动,以此防止新旧规则静默冲突。
二、4 步完成迁移:把旧配置拆成 <name>.config.toml
动手前建议先对照完整配置字段手册 /guides/codex-config-toml-complete-guide,再按以下四步操作。
第 1 步:备份主配置文件
bash
cp ~/.codex/config.toml ~/.codex/config.toml.bak
Windows PowerShell 可执行:
powershell
Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.bak"
第 2 步:拆分旧版 [profiles.*] 区块
假设旧版 ~/.codex/config.toml 中有如下片段:
toml
# 旧版写法(新版会触发配置报错,切勿保留)
profile = "review"
[profiles.review]
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"
新建独立文件 ~/.codex/review.config.toml,把区块名去掉,原字段直接提升到文件顶层:
toml
#:schema https://developers.openai.com/codex/config-schema.json
# ~/.codex/review.config.toml
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"
第 3 步:清理主 config.toml 中的废弃字段
打开 ~/.codex/config.toml,彻底删除所有 [profiles.<name>] 子表(含其子项)以及顶层的 profile = "..." 行,只保留全局公共默认项。
第 4 步:通过 --profile 验证切换效果
bash
# 按名称加载 ~/.codex/review.config.toml
codex --profile review
# 简写形式同样有效
codex -p review
如果使用了自定义目录环境变量 CODEX_HOME,Codex 会自动去 $CODEX_HOME/review.config.toml 查找对应文件,无需手写绝对路径。

图:本站根据 OpenAI Codex 官方文档:Configuration Reference 整理的示意图
三、3 套高频实用场景模板与叠加优先级注意事项
下面 3 套独立文件命名与组合属于本站建议,可根据个人习惯增删字段(推理强度与模型切换细节可看 /guides/codex-switch-model-reasoning-effort):
| 文件名 | 定位 | 建议覆盖的关键字段 | 启动命令 |
|---|---|---|---|
review.config.toml | 严格只读审查 | 高推理强度 + 只读沙箱或只读权限配置 | codex -p review |
fast.config.toml | 日常小改动与问答 | 中低推理强度 + 工作区读写 + 常规审批 | codex -p fast |
ci.config.toml | 自动化批处理 | 关闭非必要通知 + 适配 codex exec 的策略 | codex -p ci exec "..." |
如果嫌每次敲 --profile 麻烦,本站建议在 ~/.zshrc 或 ~/.bashrc 中封装短别名,例如 alias cxr='codex --profile review'、alias cxf='codex --profile fast',终端里三个字母就能一键切入目标模式(常用启动参数速查见 /guides/codex-cli-commands-cheatsheet)。
使用多套 Profile 时,最容易踩的坑是误判覆盖优先级:
- 受信任项目的
.codex/config.toml优先级高于--profile。如果你在某个仓库里明明传了--profile review,但生效的仍是工作区读写,先检查仓库根目录的.codex/config.toml是否硬编码了同类字段。 - 命令行单次参数永远压过配置文件。例如
codex -p review -c model_reasoning_effort="medium"会先叠加review.config.toml,再把本次推理档位改成medium。 - 权限安全边界不可越过管理员策略。企业托管环境下,
requirements.toml锁定的沙箱和审批上限无法被任何独立 Profile 绕过(沙箱策略详见 /guides/codex-permissions-sandbox)。
订阅与账号准备提示:频繁使用高推理 Profile 做跨文件重构或审查,对五小时滚动限额与周配额要求更高(计算规则见 /guides/codex-usage-limits)。如果 Plus 额度经常见底,可在本站升级 ChatGPT Pro 充值 或选择高配额的 ChatGPT Pro 20x 档位;新号注册阶段遇到短信验证受阻,可查看 Codex 注册手机验证服务。
常见问题
问:为什么文件明明放进了 ~/.codex/,执行 codex --profile work 却提示找不到?
答:优先核对三点:一是文件名必须严格为 work.config.toml(不要漏掉 .config 或误写成 work.toml);二是检查当前终端是否设置了自定义 CODEX_HOME,导致 Codex 去了另一个目录找文件;三是确认文件扩展名在 Windows 下没有被记事本偷偷拼成 work.config.toml.txt。
问:每个 <name>.config.toml 都要把主 config.toml 的全部内容复制一遍吗?
答:不需要。独立 Profile 采用叠加机制,只需写入相对主配置文件有差异的那几行参数即可。把 MCP 服务器、通用主题等公共项留在主 config.toml,后续维护一处就能同步给所有 Profile。
问:国内没有外币信用卡,或者公司需要开票报销,怎么开通稳定跑 Codex CLI 的订阅?
答:可通过本站 AI 会员充值总览 选购 ChatGPT Plus或更高额度的 ChatGPT Pro,团队集中采购可咨询 ChatGPT Business 团队定制。支持支付宝、微信支付和 AlipayHK 付款,自助兑换无需交出账号密码,并可开具增值税发票;实时价格以页面显示为准,售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。
相关教程
参考资料
- OpenAI Codex 官方文档:Advanced Configuration — https://learn.chatgpt.com/docs/config-file/config-advanced
- OpenAI Codex 官方文档:Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
- OpenAI Codex 官方文档:Command line options — https://learn.chatgpt.com/docs/developer-commands
- OpenAI Developers 文档:Advanced Configuration — https://developers.openai.com/codex/config-advanced
0 条评论
还没有评论,来抢沙发~