1. 从“降智”说起Codex 用户绕不开的一道坎如果你最近在用 Codex 做开发辅助大概率遇到过这种情况前几天还聪明得能帮你重构整个模块突然某一天开始回答变得又短又敷衍代码质量断崖式下跌甚至开始胡编 API。社区里管这个叫“降智”。我第一次遇到的时候以为是网络波动重启了好几次换了几个不同的入口结果都一样。后来才慢慢摸清楚这事儿跟网络关系不大核心问题出在系统提示词和配置文件这两个地方。Codex 是 OpenAI 推出的一套代码智能体工具链支持 CLI、IDE 插件和桌面版多种形态。它的工作方式跟普通的对话式 AI 不太一样——它会在你的项目目录下读取AGENTS.md这类上下文文件同时依赖config.toml来管理模型选择、provider 配置和认证信息。一旦这些文件出了问题或者系统提示词被某种机制“压缩”了模型的表现就会明显退化。这就是“降智”最典型的来源。这篇文章适合三类人看第一类是刚装好 Codex、还没搞明白配置文件怎么写的第二类是已经用了一段时间、突然发现效果变差想排查原因的第三类是想通过修改系统提示词来稳定输出质量、把 Codex 调教成顺手工具的。我会从原因定位讲到具体的配置修改把config.toml、AGENTS.md、系统提示词这几个关键点全部拆开说清楚每一步都给到可以直接抄的配置和命令。2. 降智到底降在哪里核心原因逐层拆解2.1 模型选择与账号权益的隐性关联很多人以为降智是模型本身变笨了其实更常见的情况是你实际调用的模型跟你以为的不是同一个。Codex 在config.toml里有一个model字段如果你没显式指定它会走默认值。而默认值会随着版本更新、账号类型、甚至登录方式的不同而变化。社区里有人反馈过the gpt-5.6-sol model is not supported when using codex with a chatgpt account这类报错本质上就是模型名和账号权益不匹配。判断自己的账号是否被“标记”其实有个简单办法在 Codex 里跑一个稍微复杂点的重构任务观察它是否会在中途突然简化输出。如果连续几次都是前两轮正常、第三轮开始敷衍那大概率不是账号问题而是上下文被截断或者系统提示词被覆盖了。真正的账号权益问题通常表现为直接报错或者拒绝服务而不是“变笨”。2.2 config.toml 加载失败引发的连锁反应config.toml是 Codex 的核心配置文件位置通常在用户目录下的.codex/文件夹里。这个文件一旦格式有问题Codex 会直接报chatgpt cant load config.toml, so this thread cant resume或者请修复 config.toml:model provider openai not found。很多人看到这个报错第一反应是重装其实完全没必要九成情况是 TOML 语法写错了比如少了个引号、缩进用了 Tab、或者 provider 名字拼错了。我踩过的一个坑是在 Windows 上用记事本编辑config.toml保存的时候自动加了 BOM 头导致 Codex 解析失败。后来换成 VS Code 并确认编码为 UTF-8 无 BOM 才解决。这个细节网上很少有人提但确实是高频问题。2.3 系统提示词被“稀释”的机制Codex 的系统提示词不是一成不变的。它会根据你当前的项目结构、AGENTS.md的内容、以及对话轮次动态组装。当对话变长早期的系统提示词可能被挤出上下文窗口模型就“忘记”了自己应该遵循的编码规范。这就是为什么很多人感觉“聊着聊着就变笨了”。解决思路有两个方向一是通过AGENTS.md把关键约束固化到项目级别让每一轮都能重新加载二是精简系统提示词把最重要的规则放在最前面。后面我会给出具体的模板。2.4 网络与重试机制导致的假性降智codex exceeded retry limit, last status: 429 too many requests这个报错说明请求被限流了。限流状态下Codex 可能会降级使用更小的模型或者返回缓存结果表现出来就是“降智”。这种情况跟配置无关纯粹是请求频率问题。解决办法是降低并发、增加重试间隔或者在config.toml里调整超时参数。3. config.toml 深度解析从零写一份不会报错的配置3.1 文件位置与基础结构不同系统下config.toml的位置不一样系统默认路径WindowsC:\Users\你的用户名\.codex\config.tomlmacOS~/.codex/config.tomlLinux~/.codex/config.toml如果目录不存在手动创建即可。一个最小可用的配置长这样model gpt-5.6-sol provider openai [providers.openai] api_key 你的key base_url https://api.openai.com/v1注意provider字段的值必须和下面[providers.xxx]的名字完全一致大小写敏感。我见过有人写成OpenAI结果报provider openai not found排查了半天。3.2 模型字段的正确写法与常见错误model字段最容易出问题。Codex 支持的模型名是固定的几个写错了会直接报model is not supported。截至我写这篇文章时常用的有gpt-5.6-sol、gpt-5.6等。如果你用的是第三方兼容接口模型名要按对方的文档来写。一个实用技巧在config.toml里加一行注释记录你上次修改的时间和原因方便回滚。# 2025-01-15 从 gpt-5.6 切换到 gpt-5.6-sol解决长上下文降智 model gpt-5.6-sol3.3 provider 配置与多环境切换如果你需要在不同 provider 之间切换比如公司内网和本地开发可以配置多个 providerprovider openai [providers.openai] api_key sk-xxx base_url https://api.openai.com/v1 [providers.local] api_key local-key base_url http://localhost:8080/v1切换的时候只改第一行的provider值就行。这里有个坑base_url结尾不要带斜杠否则某些版本会拼出双斜杠导致 404。3.4 认证信息的安全管理直接把api_key写在config.toml里方便但有风险尤其是多人共用机器的时候。更稳妥的做法是用环境变量[providers.openai] api_key ${OPENAI_API_KEY} base_url https://api.openai.com/v1然后在系统里设置OPENAI_API_KEY环境变量。Codex 会自动读取并替换。这样配置文件可以放心提交到私有仓库不会泄露密钥。4. AGENTS.md 与系统提示词工程让 Codex 稳定输出4.1 AGENTS.md 是什么为什么它比 config.toml 更重要AGENTS.md是放在项目根目录下的上下文文件Codex 每次启动时会自动读取它把里面的内容作为项目级系统提示词注入。跟config.toml管“怎么连”不同AGENTS.md管的是“怎么干”。它决定了 Codex 在你这个项目里遵循什么编码规范、用什么技术栈、避免哪些操作。我实测下来一个写好的AGENTS.md能把降智概率降低至少一半。因为它保证了每一轮对话都带着完整的项目约束不会因为上下文变长而丢失关键信息。4.2 一份可直接复用的 AGENTS.md 模板# 项目上下文 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 包管理pnpm - 测试Vitest ## 编码规范 - 所有函数必须有显式返回类型 - 禁止使用 any必要时用 unknown 加类型守卫 - 组件文件使用 PascalCase工具函数使用 camelCase - 提交前必须通过 eslint 和 tsc --noEmit ## 禁止操作 - 不要修改 package.json 里的依赖版本 - 不要删除现有的测试用例 - 不要引入新的全局状态管理库 ## 常用命令 - 开发pnpm dev - 构建pnpm build - 测试pnpm test这个模板的关键在于“禁止操作”这一节。Codex 有时候会“自作聪明”地帮你升级依赖或者删掉它认为没用的代码明确写出来能有效避免。4.3 系统提示词的分层设计思路系统提示词不是越长越好。我的经验是分三层第一层是全局约束放在AGENTS.md最前面比如“你是一个严谨的 TypeScript 工程师所有输出必须可编译”。第二层是项目特定规则比如上面模板里的编码规范。第三层是任务级指令这个在每次对话时临时给不写进文件。分层的好处是全局和项目级的规则稳定不变任务级的灵活调整。这样即使对话很长前两层也会因为文件重新加载而保持生效。4.4 系统提示词工程和 Skill Agent 的区别社区里经常有人问这两个概念的区别。简单说系统提示词是“告诉模型怎么做事”Skill Agent 是“给模型一套可调用的工具”。前者影响输出风格和质量后者影响能力边界。降智问题主要靠系统提示词解决因为大部分降智是风格退化而不是能力缺失。如果你发现 Codex 连基本的文件读写都做不了那才需要检查 Skill Agent 的配置。5. 实操全流程从安装到调优的完整记录5.1 安装与首次配置Windows 桌面版的安装比较简单下载安装包后一路下一步。CLI 版本需要先装 Node.js 18然后npm install -g openai/codex codex --version首次运行codex会引导你登录。如果登录失败提示codex auth token is unavailable检查一下系统时间是否准确时间偏差超过几分钟会导致 token 校验失败。这个坑我踩过调了半天以为是网络问题。登录成功后手动创建~/.codex/config.toml把前面给的模板填进去。然后在项目根目录创建AGENTS.md。这两步做完基础环境就好了。5.2 验证配置是否生效跑一个简单的测试任务codex 读取当前目录的 package.json告诉我项目用了哪些依赖如果它能正确读取并回答说明配置没问题。如果报config.toml相关错误按第 3 节的排查表逐项检查。5.3 降智复现与对比测试想确认自己是不是真的遇到降智可以做一个对比测试。准备一个中等复杂度的任务比如“把这个 200 行的工具函数拆分成三个模块保持原有测试通过”。分别在配置修改前后跑一次对比输出质量。我自己的测试结果是修改前 Codex 会在第二轮开始省略错误处理修改后能完整输出所有边界情况。差异非常明显。5.4 参数调优与性能平衡config.toml里还有几个可选参数值得调参数作用建议值timeout请求超时秒数120max_retries最大重试次数3temperature输出随机性0.2temperature调低能让输出更稳定适合代码场景。但别调到 0否则会变得死板遇到需要创意的时候反而不好用。0.2 是我试下来比较平衡的值。6. 常见问题速查与避坑指南6.1 报错信息与对应解决方案报错原因解决cant load config.toml语法错误或编码问题用 VS Code 检查 TOML 语法确认 UTF-8 无 BOMprovider openai not foundprovider 名字不匹配检查provider字段和[providers.xxx]是否一致model is not supported模型名写错或账号不支持换成文档里列出的模型名auth token is unavailable系统时间偏差或登录过期校准时间重新登录429 too many requests请求频率过高降低并发增加重试间隔6.2 那些文档里不会写的坑第一个坑Windows 路径里的反斜杠。在config.toml里写路径要用正斜杠或者双反斜杠单反斜杠会被当成转义字符。第二个坑AGENTS.md的文件名必须全大写agents.md在某些版本里不识别。第三个坑如果你同时装了 CLI 和 IDE 插件它们可能读的是不同的配置文件改完一个记得同步另一个。6.3 降智自查清单遇到效果变差时按这个顺序排查检查config.toml是否能正常加载有没有报错确认当前使用的模型名是否正确查看AGENTS.md是否存在于项目根目录观察对话轮次是否超过 10 轮后开始退化检查是否有 429 限流报错对比同一任务在不同配置下的输出质量这个清单我贴在显示器边上每次出问题照着走一遍基本五分钟内能定位。6.4 长期维护建议配置文件不是写完就不管了。每次 Codex 版本更新后建议重新跑一遍验证任务确认配置仍然兼容。AGENTS.md也要随着项目演进更新比如换了测试框架、加了新的代码规范都要同步进去。我习惯每个月花十分钟检查一遍这两个文件能省下大量排查降智的时间。最后分享一个我自己的习惯把每次修改config.toml和AGENTS.md的原因、时间、效果记录在一个CHANGELOG.md里。看起来麻烦但当你三个月后遇到类似问题翻记录比重新排查快得多。这个习惯让我从“每次降智都抓瞎”变成了“五分钟定位、十分钟解决”。