1. 从一次模型不生效的排查说起如果你正在用 Codex 做本地 Agent 开发大概率遇到过这种场景明明在配置文件里写好了自定义模型启动之后却提示the gpt-5.6-sol model is not supported when using codex with a...或者干脆静默回退到默认模型日志里连个像样的报错都没有。更让人抓狂的是你改完 TOML 重启发现配置被某个中间层覆盖了改了个寂寞。这类问题的根源几乎都指向同一件事Codex 的配置体系是多层叠加的而大多数人只改了其中一层。Codex 本身支持本地自定义 Agent、自定义模型端点、项目级指令文件但它同时还有 CLI 参数、环境变量、全局配置、项目配置、以及某些第三方切换工具比如 ccswitch 这类的介入。这些层之间是有明确优先级的谁覆盖谁、谁生效谁被忽略不搞清楚就会一直在改了没用的循环里打转。这篇内容就是围绕这条链路展开的。我会把 Codex 本地自定义 Agent 的配置拆成三块来讲TOML 配置文件怎么写、AGENTS.md 到底管什么、以及多层配置的优先级怎么排。适合已经在用 Codex CLI 或桌面版、想接入自己的模型服务、或者被配置覆盖问题折磨过的开发者。读完你应该能做到知道每一层配置的作用边界知道改哪个文件才会真正生效知道遇到配置不生效时按什么顺序排查。先说一个我踩过的坑作为引子。早期我在项目根目录放了一个config.toml里面写了自定义 provider 和 model本地跑得好好的。后来团队引入了一个切换工具来管理多套环境结果那个工具在启动时往用户级目录写了一份自己的 TOML直接把我的项目级配置盖掉了。我花了两个小时才意识到问题不在我的配置写错了而在于我根本没搞清楚哪一层优先级更高。这个教训直接促成了后面这套排查方法论。2. Codex 配置的分层模型谁在什么时候读哪个文件2.1 三层配置的物理位置与加载时机Codex 的配置不是单一文件而是按用户级 → 项目级 → 运行时三层叠加的。理解这三层的物理位置和加载顺序是后面所有排查的基础。层级典型位置作用范围加载时机用户级用户主目录下的配置目录当前用户所有项目进程启动最先读取项目级项目根目录的配置文件仅当前项目进入项目目录后读取运行时CLI 参数、环境变量单次调用命令执行时覆盖前两者用户级配置是兜底默认值适合放你个人的通用偏好比如默认模型、默认 provider、日志级别。项目级配置是项目专属覆盖适合放这个项目特有的模型端点、Agent 定义、沙盒策略。运行时参数是临时覆盖适合做一次性实验比如临时换个模型跑个测试。关键在于后加载的层会覆盖先加载的层但覆盖是字段级的不是整文件替换。也就是说项目级配置里只写了 model那 provider 还是会沿用用户级的。这一点很多人误解成项目配置一写用户配置全废其实不是。2.2 为什么 Codex 要设计成多层而不是单文件这个问题值得展开说因为它直接决定了你该怎么组织配置。单文件配置看起来简单但在真实开发里会迅速失控你既想有一套个人通用设置又不想每个项目都复制一遍既想让团队共享项目配置又不想把个人密钥提交到仓库。多层模型解决的就是这个矛盾。用户级放我这个人怎么用项目级放这个项目怎么跑运行时放这次怎么试。三者职责清晰互不污染。我个人的习惯是用户级只放默认模型和日志偏好所有跟具体项目相关的 provider、Agent、沙盒设置全部下沉到项目级这样换项目时行为完全可预期。还有一个容易被忽略的点项目级配置是可以被版本控制的。把项目级 TOML 和 AGENTS.md 一起提交到仓库团队每个人拉下来就是一致的 Agent 行为。这比在群里发你把模型改成 xxx靠谱得多。但前提是配置里不能有个人密钥——密钥应该走环境变量这一点后面会专门讲。2.3 一个常见的认知误区改了 TOML 就一定生效吗不一定。这是我最想强调的一点。TOML 生效的前提是没有更高优先级的层覆盖它且没有被中间工具改写。举个具体例子。假设你在项目级 TOML 里写了[model] provider custom name my-local-model base_url http://localhost:8000/v1但如果你的启动脚本里带了--model gpt-5.6-sol这样的 CLI 参数那运行时层会直接覆盖掉 TOML 里的 nameprovider 也可能被重置。这时候你看到的报错就是the gpt-5.6-sol model is not supported——因为 CLI 参数赢了而那个模型在你的自定义端点上根本不存在。再比如某些切换工具会在启动时重写用户级 TOML。你以为改的是项目级实际生效的是被工具改过的用户级。这就是ccswitch 会覆盖 toml这类说法的由来。排查配置问题的第一步永远是确认当前生效的是哪一层。3. TOML 配置实战provider、model 与自定义端点3.1 最小可用配置的结构拆解先给一份能跑起来的最小 TOML然后逐字段解释为什么这么写。# 项目级配置示例 model_provider custom [model_providers.custom] name custom base_url http://localhost:8000/v1 env_key CUSTOM_API_KEY wire_api chat [model] provider custom name my-local-model这里有几个设计选择需要解释。model_provider是顶层字段指定默认用哪个 provider[model_providers.custom]定义了一个名为 custom 的 providerbase_url指向你的本地或自建模型服务地址env_key指定从哪个环境变量读密钥wire_api决定用哪种协议格式跟服务端通信。为什么密钥要走env_key而不是直接写在 TOML 里因为 TOML 很可能被提交到仓库。把密钥放环境变量配置文件就能安全地进版本控制。这是行业里非常成熟的实践几乎所有需要密钥的工具都这么做。wire_api这个字段容易被忽略但它很关键。不同的模型服务端支持的协议不一样有的走 chat completions 风格有的走 responses 风格。选错了会直接报错比如你看到failed while handling codex endpoint /responses这类提示八成就是 wire_api 跟服务端不匹配。先确认你的服务端支持哪种协议再填这个字段。3.2 自定义模型服务地址的接入要点接入自建模型服务时base_url是最容易出错的地方。常见错误有三类第一类是路径不完整。很多服务端的 OpenAI 兼容接口是挂在/v1下面的你只写到域名或端口请求就会 404。正确做法是写到/v1这一层让 Codex 自己拼后面的路径。第二类是协议不匹配。前面说的 wire_api 就是干这个的。如果你的服务端只实现了 chat completions却把 wire_api 设成了 responses请求格式对不上服务端会直接拒绝。第三类是网络可达性。本地服务如果只监听127.0.0.1而 Codex 跑在容器里那容器内的 localhost 指向的是容器自己不是宿主机。这种情况要么把服务监听地址改成0.0.0.0要么用宿主机的可达地址。这个坑在 Docker 环境里特别常见。提示改完 base_url 后先用 curl 手动打一次接口确认服务端能正常返回再让 Codex 去连。这样能把配置问题和服务端问题分开排查省大量时间。3.3 模型名称与 provider 的绑定关系[model]段里的provider和name是一对绑定关系。provider 指向你在[model_providers.xxx]里定义的某个 providername 是这个 provider 下具体的模型标识。这里有个细节name 必须是服务端认识的模型名。如果你在本地部署了一个模型服务端注册的名字是qwen-local那 TOML 里就得写qwen-local写别的名字服务端会返回模型不存在。很多人从别处抄配置模型名没改结果一直报模型不支持就是这个原因。另外provider 的 name 字段和[model_providers.xxx]的键名最好保持一致虽然技术上可以不同但保持一致能减少认知负担。我见过配置里 provider 键叫customname 字段却叫my-provider排查时自己都绕晕了。4. AGENTS.md被低估的项目级指令层4.1 AGENTS.md 和 TOML 的职责边界很多人把 AGENTS.md 和 TOML 混为一谈其实它们管的是完全不同的东西。TOML 管的是运行时配置——用哪个模型、连哪个端点、沙盒怎么开。AGENTS.md 管的是行为指令——Agent 在这个项目里应该遵守什么规则、用什么风格、注意哪些约束。打个比方TOML 是给车加油、设定导航目的地AGENTS.md 是给司机的一份行车规范。两者互不替代。你可以有完美的 TOML 配置但 Agent 行为完全不符合项目要求也可以有详尽的 AGENTS.md但模型端点没配好根本跑不起来。AGENTS.md 通常放在项目根目录Codex 进入项目时会自动读取。它的内容是自然语言写的指令比如这个项目用 TypeScript所有新代码必须带类型标注、提交前必须跑 lint、不要修改 migrations 目录下的文件。这些规则会作为上下文注入给 Agent影响它的决策。4.2 一份能真正约束 Agent 行为的 AGENTS.md 该怎么写写 AGENTS.md 最大的误区是写得太虚。请写出高质量代码这种话对 Agent 没有任何约束力。有效的指令必须具体、可判定、有边界。我一般按四块来组织项目背景一句话说清这是什么项目、技术栈是什么。让 Agent 有基本认知。硬性规则绝对不能做的事。比如不要引入新的第三方依赖、不要改动 public API 的签名。风格约定代码风格、命名习惯、注释语言。比如注释用中文、函数名用 camelCase。工作流要求改完代码要做什么。比如每次修改后运行测试、提交信息用约定式提交格式。举个具体的对比。虚的写法是注意代码质量实的写法是所有新增函数必须有 JSDoc 注释参数和返回值都要标注类型。后者 Agent 能直接执行前者它只能猜。注意AGENTS.md 里的规则不要和 TOML 里的配置冲突。比如 TOML 设了只读沙盒AGENTS.md 却要求 Agent 自动改文件那 Agent 会卡在权限上。配置层和指令层要协同不是各写各的。4.3 AGENTS.md 的加载优先级与覆盖规则AGENTS.md 也有层级。通常用户级可以有一份全局的项目级有一份项目专属的。加载时项目级会补充或覆盖用户级。这意味着你可以把通用规范放用户级把项目特有的约束放项目级。但要注意AGENTS.md 的覆盖和 TOML 的字段级覆盖不一样。指令是文本通常是叠加注入的项目级的内容会追加在用户级之后。所以如果两处写了矛盾的规则Agent 可能会困惑。我的做法是用户级只放极通用的偏好所有项目相关的规则一律放项目级避免冲突。还有一个实践细节AGENTS.md 不要写太长。上下文是有成本的一份几百行的 AGENTS.md 会挤占 Agent 处理实际任务的注意力。我一般控制在几十行以内只保留真正影响决策的规则。那些仅供参考的内容不如不写。5. 优先级实战当配置互相打架时怎么排查5.1 优先级从高到低的完整排序把前面散落的信息汇总成一张优先级表这是排查问题的核心工具。优先级来源覆盖能力典型场景最高CLI 参数覆盖所有下层临时换模型测试高环境变量覆盖配置文件注入密钥、切换端点中项目级 TOML覆盖用户级项目专属配置中项目级 AGENTS.md追加到用户级之后项目行为规范低用户级 TOML兜底默认个人通用偏好低用户级 AGENTS.md基础规范通用行为偏好记住一个原则越靠近这一次执行的层优先级越高。CLI 参数是单次执行的所以最高用户级配置是长期默认所以最低。排查时从高往低查先看有没有 CLI 参数和环境变量在捣乱再看项目级最后看用户级。5.2 一次完整的配置不生效排查链路回到开头那个场景。假设你改了项目级 TOML但模型没生效。按这个顺序查第一步看启动命令有没有带--model或--provider之类的参数。有的话先去掉参数再试。这一步能解决相当一部分问题。第二步检查环境变量。env | grep -i一下相关的变量名看有没有被 shell 或启动脚本设过。环境变量经常是隐形杀手因为它不在你改的文件里。第三步确认项目级 TOML 真的被读到了。可以在配置里加一个明显的、无害的字段比如改个日志级别看行为有没有变化。如果没变化说明这个文件根本没被加载可能是路径不对或文件名不对。第四步检查有没有中间工具改写了配置。某些切换工具会在启动时重写用户级 TOML这时候你改项目级也没用因为工具改的是用户级而用户级可能被工具设成了更高优先级。确认工具的行为必要时绕过它直接启动。第五步看日志。Codex 一般会输出它实际使用的 provider 和 model。如果日志里显示的还是旧值说明覆盖发生在日志输出之前如果日志显示新值但行为不对那问题在服务端。这套链路我用了很多次基本能定位 90% 以上的配置问题。核心思路就是从高优先级往低优先级逐层排除每层用可观测的手段确认它是否生效。5.3 中间工具覆盖 TOML 的识别与规避ccswitch 会覆盖 toml这类问题本质是中间工具在启动流程里插了一脚改写了配置文件或注入了环境变量。识别方法很简单在不用工具的情况下直接启动 Codex看配置是否生效。如果直接启动正常、用工具启动异常那问题就在工具。规避方式有几种。一是把关键配置放到工具不会碰的层比如 CLI 参数或环境变量让工具改不到。二是检查工具的配置看它是否有透传或不覆盖的选项。三是干脆不用工具自己写启动脚本管理多套环境——多套环境本质上就是多份项目级 TOML用目录区分即可不一定需要额外工具。我个人的选择是第三种。多环境管理用最朴素的方式每个环境一个目录目录里放各自的 TOML 和 AGENTS.md启动时 cd 进去。简单、可预期、没有隐藏行为。工具带来的便利往往抵不过它带来的排查成本。6. 自定义 Agent 的落地从配置到可复现6.1 把 Agent 定义固化进项目配置自定义 Agent 的价值在于可复现。你今天调好的一套行为明天、下个月、换台机器都应该一样。要做到这点Agent 的定义必须固化进项目配置而不是靠记忆或口头传递。具体做法是把 provider、model、沙盒策略写进项目级 TOML把行为规范写进项目级 AGENTS.md两者一起提交到仓库。新人拉下来配置就是一致的。这比写一份如何配置 Codex的文档靠谱得多因为文档会过期配置文件不会。这里有个细节如果项目里有多套 Agent比如一个负责写代码、一个负责 review可以用不同的配置目录区分或者用 CLI 参数在启动时选择。我倾向于用目录区分因为这样每套 Agent 的 AGENTS.md 也能独立互不干扰。6.2 沙盒与权限配置的注意事项沙盒配置是自定义 Agent 里最需要谨慎的部分。开得太松Agent 可能改坏文件开得太紧Agent 什么都干不了一直卡在权限提示上。我的经验是默认从只读开始按需逐步放开。先让 Agent 在只读模式下跑确认它能正确理解任务然后放开写权限但限定在特定目录最后如果需要执行命令再单独开命令执行权限。每一步都确认行为符合预期再往下走。还有一个坑沙盒配置和 AGENTS.md 里的指令要一致。如果 AGENTS.md 要求 Agent 自动改文件但沙盒是只读的Agent 会反复尝试然后失败日志里可能只显示更新 agent 沙盒之类的提示让人摸不着头脑。配置层和指令层的权限要对齐。6.3 验证配置生效的最小测试集配置写完怎么确认它真的生效了我一般跑三个最小测试第一个问 Agent 你当前用的是什么模型。如果它能正确回答你配置的模型名说明 model 配置生效了。第二个让它做一个需要写权限的小操作比如创建一个临时文件。成功说明沙盒写权限开了失败说明还是只读。第三个故意违反一条 AGENTS.md 里的规则看它会不会拒绝。比如规则说不要改 migrations你就让它改 migrations 下的文件看它是否遵守。遵守说明指令注入生效了。这三个测试跑通基本可以确认整套配置是可用的。之后再把配置提交团队其他人拉下来跑同样的测试就能保证一致性。7. 几个我反复踩过的坑和对应解法第一个坑是模型名抄错。从别人的配置里复制模型名没改服务端不认识报模型不支持。解法永远以服务端实际注册的模型名为准不确定就先查服务端的模型列表接口。第二个坑是wire_api 选错。服务端只支持 chat completions配置里写了 responses请求格式对不上。解法先确认服务端支持的协议再填这个字段。看到/responses相关的报错优先怀疑这里。第三个坑是环境变量残留。之前测试时设过一个环境变量忘了 unset导致新配置一直被覆盖。解法排查时先env | grep一遍相关变量确认没有残留。第四个坑是中间工具改写配置。工具在启动时重写了用户级 TOML项目级配置被绕过。解法不用工具直接启动对比确认问题来源然后决定是配置工具还是弃用工具。第五个坑是AGENTS.md 写太虚。规则不具体Agent 无法执行行为随机。解法每条规则都要可判定能写成必须做 X或禁止做 Y的就不要写成注意 X。第六个坑是沙盒和指令冲突。指令要求写沙盒是只读Agent 卡死。解法配置层和指令层的权限对齐改指令时同步检查沙盒设置。这些坑的共同点是它们都不是配置写错了而是配置之间的关系没理清。Codex 的配置体系是分层的、有优先级的、可能被外部改写的。理解这套关系比记住某个字段怎么写重要得多。最后分享一个我现在的习惯每次调整配置后都在项目里留一个CONFIG_NOTES.md记录这次改了什么、为什么改、验证结果是什么。看起来多余但下次再遇到配置不生效时翻一下这个文件往往能直接定位到是哪次改动引入的问题。配置管理这件事可追溯比聪明更重要。