1. 配置文件的三个层级与加载顺序动手前必须知道的 TOML 真相很多人第一次接触 Codex 本地自定义 Agent 时第一反应是打开默认的~/.codex/config.toml直接改模型。这个思路没错但如果你不知道这个文件在什么时候加载、被谁覆盖、能否按项目隔离后面就会踩到“改了配置但完全没生效”“这个项目用的怎么还是旧模型”之类的坑。Codex 的配置体系是我用过的 CLI 工具里比较典型的 TOML 三层结构全局配置、项目配置、本地覆盖。默认情况下你本机的配置文件在~/.codex/config.toml。如果你设置了CODEX_HOME环境变量那么这个路径会跟着变化。命令行的--config参数可以指定一个完全自定义的配置文件路径这在临时测试、CI 环境里非常有用。三层配置的规则大概是这样全局配置~/.codex/config.toml所有项目共享放默认模型、默认的 model_provider、默认的权限策略。项目配置项目根目录下的.codex/config.toml新版本支持按项目隔离适合团队统一某个仓库的模型和行为规范。本地覆盖/命令行参数优先级最高适合临时切换模型、调试 provider。实际测试下来Codex 加载配置的顺序是“先全局、再项目、后命令行”后面的配置会覆盖前面的同名配置项。也就是说你在全局把model配成了gpt-5项目里.codex/config.toml又写了model deepseek-chat那这个项目实际跑的就是deepseek-chat。命令行如果再跟一个-m参数那命令行说了算。提示别把环境变量和配置文件搞混。OPENAI_API_KEY、CODEX_HOME这类环境变量是在 shell 启动时注入的它们的生效时机比配置文件更早。如果同一个变量在配置文件的[env]块里也出现了实测下来 shell 里已导出的值优先级更高配置文件里的[env]更多是作为兜底。1.1 一个最小可用的初始配置先给一个最基础的配置骨架你在改任何高级参数之前先确保这个能跑通model gpt-5 model_reasoning gpt-5 model_reasoning_effort medium [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses这个配置干了几件事指定了默认模型和推理模型声明了 OpenAI 官方 provider通过env_key告诉 Codex 去哪里读取 API Key。注意我用的 key 是OPENAI_API_KEY这个变量必须在 shell 里已经存在否则 Codex 启动时会直接报“missing API key”。1.2 profile官方提供的配置隔离方案如果你想在同一个机器上维护两套 Codex 配置比如一套工作用、一套个人项目用不需要频繁改config.toml用profile是最干净的做法。配置里可以这样写[profiles.work] model gpt-5 model_reasoning_effort high [profiles.personal] model deepseek-chat [profiles.personal.model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后运行时用codex --profile personal启动或者设置环境变量CODEX_PROFILEpersonal。profile 里的配置会覆盖顶层同名配置这种“一个文件管多套环境”的方式比到处维护多个config.toml要省心得多。我自己的习惯是工作场景用work写开源项目用personal切换起来一条命令的事。2. 把 Codex 接到任意模型model_provider 与模型映射实战Codex 默认只连 OpenAI 官方服务但它的设计里有一个很关键的抽象层model_provider。这个字段相当于告诉 Codex “你要发请求的服务端点长什么样”把base_url、env_key、wire_api三样核心信息配好Codex 就能连接到任何兼容 OpenAI 接口的服务。2.1 三个核心字段的含义先逐个拆解这是很多人配置失败的重灾区base_urlAPI 服务的基础地址。注意这里有个特别容易踩的坑OpenAI 官方是https://api.openai.com/v1但很多第三方兼容服务只写了https://api.deepseek.com两者都能用但 Codex 拼接请求路径时行为不一样。我建议统一带上/v1这样路由前缀不容易 404。如果遇到“404 Not Found”或者“endpoint /responses 不存在”十有八九是这个路径没对齐。env_key指定从哪个环境变量读取 API Key。每个 provider 用独立的 key比如DEEPSEEK_API_KEY不要所有 provider 都共用一个OPENAI_API_KEY否则切模型的时候会莫名其妙鉴权失败。wire_api协议格式。OpenAI 官方现在推荐responses协议但大多数第三方兼容服务只实现了老的chat协议chat/completions。如果第三方服务只支持 chat 协议而你配成了 responsesCodex 启动时不会立刻报错真正发消息的时候才会报 “failed while handling codex endpoint /responses”。这个坑我在下一节排错里详细讲。2.2 用 DeepSeek 做例子完整接入配置热搜里“codex接入deepseek”出现频率很高我直接用这个例子演示。第三方模型普遍是 OpenAI 兼容接口接入步骤几乎一样。model deepseek-chat model_reasoning deepseek-reasoner model_reasoning_effort high [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat配置完成后在 shell 里导出密钥export DEEPSEEK_API_KEYsk-xxxx codex进交互界面后Codex 就会用deepseek-chat处理对话用deepseek-reasoner做深度推理。这里有一个容易忽略的点model_reasoning_effort有三个档位low / medium / high但它是否生效完全取决于上游模型是否支持这个参数。DeepSeek 的 reasoner 接受这个字段但有些开源模型的网关会直接忽略它不会有报错只是行为上没什么区别。2.3 model 与 model_reasoning 的分工逻辑Codex 会把“普通对话”和“深度推理”拆成两个模型位。model负责日常生成model_reasoning负责需要多步思考的任务。如果你只配置model不配置model_reasoningCodex 默认会用同一个模型处理所有任务。如果只配model_reasoning不配modelCodex 可能会报 config 解析错误。实际使用中我的建议是预算有限就两个都配同一个模型别让 Codex 因为缺少推理模型而频繁回退预算充足就把推理模型配成更强的版本日常对话用快一点的模型体验会有明显区别。这里“快”和“强”的取舍完全看你的场景写业务代码我倾向于快模型做架构设计、重构老代码我切到强推理模型。2.4 密钥管理的实操建议不要在config.toml里明文写 key。配置文件会进版本库、会分享给同事一旦泄露就是钱的问题。正确的做法是只写env_key然后通过 shell 的.zshrc、.bashrc、或者 direnv 这类工具注入环境变量。如果你用 Git 管理~/.codex目录记得把.env文件加进.gitignore。3. AGENTS.md用自然语言定义你的本地 Agent模型配置解决的是“Codex 用哪个脑子思考”的问题AGENTS.md 解决的是“Codex 按什么规矩干活”的问题。标题里的“本地自定义 Agent”说白了就是用 AGENTS.md 把 Codex 从一个通用助手塑造成符合你项目习惯的专属 Agent。3.1 全局 AGENTS.md 和项目 AGENTS.md 的分工Codex 支持两个层级的 AGENTS.md这一点和 config.toml 的层级思路是一脉相承的全局 AGENTS.md~/.codex/AGENTS.md定义你所有项目的通用偏好。比如“所有代码注释使用中文”“提交信息遵循 Conventional Commits”“不要修改测试文件除非用户明确要求”。这些规则应该在每个项目里都生效。项目 AGENTS.md项目根目录 AGENTS.md定义这个仓库特有的规则。比如“后端代码在app/目录下”“数据库迁移文件放在migrations/”“前端组件统一使用 TypeScript 泛型”。新版本的 Codex 还支持子目录级别的 AGENTS.md也就是说你可以在src/modules/下再放一个 AGENTS.md只约束那个目录里的代码。这个机制非常适合大型 monorepo每个子模块的代码风格差异很大时用子目录 AGENTS.md 做约束比在根目录堆一大堆规则要清晰得多。3.2 一份高效的 AGENTS.md 应该写些什么我见过很多人把 AGENTS.md 写成“你好请遵守以下规则”这种废话开头的文档一点用都没有。Codex 读 AGENTS.md 是把它当作额外的系统提示词上下文不是读给你看的。所以内容要具备可执行性每条规则都应该让 Agent 能直接判断对错。我的写法分五块项目角色一句话说清楚这个项目是什么技术栈是什么。让 Agent 先建立背景认知。目录地图告诉 Agent 哪些目录是核心业务、哪些是工具脚本、哪些是自动生成不要动。这能避免它乱改不该改的文件。硬性约束不许做什么。比如“不要运行npm install”“不要修改package-lock.json”“不要提交.env文件”。工作流偏好希望 Agent 完成任务时遵循什么顺序。比如“先读docs/architecture.md再动手”“每次修改后必须跑npm test”。示例代码风格贴一小段你觉得写得好的代码。Codex 的模式匹配能力很强给它一个“好例子”比给它十条抽象规则更管用。示例片段# Project: Payment Service You are working in a NestJS-based payment service. - Core business logic lives in src/domain/ - HTTP controllers live in src/api/ - Never modify files under generated/ - After changing a service, run npm test and make sure all tests pass - Use the existing logging format: logger.info(message, { ctx })3.3 AGENTS.md 和 config.toml 的边界这是很多人会混淆的一点。config.toml 管的是“模型、权限、沙盒、环境变量”AGENTS.md 管的是“上下文、规则、行为偏好”。两者不是二选一而是互补。比如“这个项目用哪个模型”应该写进 config.toml“这个项目不要动哪些目录”应该写进 AGENTS.md。如果你在 AGENTS.md 里写模型名在 config.toml 里写编码规范系统不会报错但维护起来非常拧巴。我见过最离谱的一个配置是用户把 API Key 直接写在 AGENTS.md 里理由是“让 Agent 自己读”。这个做法不仅有泄露风险而且完全没必要config.toml 的 env_key 机制就是干这个事的。记住AGENTS.md 永远不应该包含敏感信息。4. 优先级规则全解析冲突发生时听谁的配置项多了以后最头疼的问题就是优先级。Codex 文档里其实有明确的优先级顺序但我发现很多人根本没仔细看导致“我明明在这里改了配置为什么没生效”。这一节我把容易发生冲突的场景全部列出来按我的实测结果给一个可以直接参考的排序。4.1 配置来源的优先级排序从高到低整理如下来源优先级典型场景命令行参数最高codex -m model_name、codex --profile work环境变量高CODEX_PROFILE、CODEX_HOME、OPENAI_API_KEY项目级 config中.codex/config.toml中的 model 配置全局 config低~/.codex/config.toml中的默认配置内置默认值最低Codex 出厂自带的 model_provider 设置这个顺序决定了排查问题的思路如果某个配置没生效先从命令行参数查起再看环境变量是不是被设置了最后才怀疑项目级和全局配置写错了。4.2 模型选择优先级默认模型、快速模型与推理模型模型字段之间也有优先级关系。model是兜底模型model_reasoning是增强模型。当任务被 Codex 判定为“需要深度推理”时它会优先使用model_reasoning否则用model。这个判定机制不透明但你可以通过model_reasoning_effort的档位控制它的触发倾向。档位越高Codex 越倾向于把任务当作复杂任务处理代价是响应时间变长、token 消耗变大。我实测的一个经验model_reasoning_effort设成low时代码生成速度明显变快但复杂的跨文件重构容易“敷衍”设成high时简单问题也会被过度思考经常多写很多没必要的代码。日常开发建议用medium需要慢工出细活的时候临时用--config或者-m切换到 high。4.3 AGENTS.md 的优先级陷阱AGENTS.md 的优先级遵循“越靠近当前工作目录的指令越权威”的原则。也就是说子目录 AGENTS.md 会覆盖项目根目录 AGENTS.md 里的同名规则项目根目录会覆盖全局~/.codex/AGENTS.md。这个机制看起来合理但它有一个隐藏陷阱Codex 实际上是把所有匹配到的 AGENTS.md 内容都塞进上下文而不是简单“后者覆盖前者”。也就是说如果全局 AGENTS.md 里写了“禁止修改生成的代码”而某个子目录 AGENTS.md 写了“可以修改generated/目录下的模板文件”两条规则会同时存在Agent 可能会根据上下文强弱随机选择遵守哪一条。建议同一个规则只在一个层级定义。如果子目录确实需要例外在最靠近的 AGENTS.md 里写清楚“覆盖全局规则允许做 XX”用这种显式声明减少歧义。4.4 一个可复用的优先级自查表我把平时排查配置问题时用的清单整理成表格遇到“配置没生效”直接对照查症状第一检查项第二检查项第三检查项模型没切换codex -m参数CODEX_PROFILE环境变量profile 里的 model 字段API Key 不生效shell 是否导出同名 keyconfig.toml 里的 env_key 名字[env] 块是否写错AGENTS.md 规则不生效是否存在更高优先级 AGENTS.md内容是否是可执行指令是否因为太长被截断wire_api 报错provider 是否支持 responsesbase_url 路径是否带 /v1是否拼错协议类型5. 高频报错与排错思路从“无法发送消息”到“沙盒更新”配置写完了跑起来难免会遇到报错。我把这段时间在社区里看到的高频问题以及我自己排查过的几个典型案例整理在这一节。这部分内容的价值不在于报错本身而在于排查思路。5.1 codex 无法发送消息从密钥到网络层逐层排查“无法发送消息”是个非常笼统的报错很多人一看到就以为网络出问题了其实大部分时候是密钥和 base_url 的问题。我的排查顺序是固定的先看是不是密钥问题echo $DEEPSEEK_API_KEY确认变量存在。如果变量为空查~/.zshrc或.bashrc里的 export 语句新开的 shell 才会加载最新配置。再看 base_url 是否正确用 curl 直接打一下接口看看返回什么。比如 DeepSeek 的话curl https://api.deepseek.com/v1/models -H Authorization: Bearer $DEEPSEEK_API_KEY能返回模型列表说明网络层和鉴权都没问题。最后开 debug 模式codex --debug会输出完整的请求细节、HTTP 状态码和响应体。这一步能精确看到 Codex 到底往哪个 URL 发了什么请求。5.2 cc switch local proxy failed工具链切换配置失效的典型场景最近很多人在用 ccswitch 这类工具统一管理多个 AI CLI 的配置因为它们可以快速在 Claude Code、Codex 之间切换模型和服务商。我遇到的一个典型报错是启动 Codex 时提示 “failed while handling codex endpoint /responses”这个报错看起来像网络问题但排查下来其实是配置切换后前后两套配置残留导致的。原因通常是这三类wire_api 不匹配。切换工具时把 provider 的 wire_api 带过来了比如 Claude Code 的配置模板用的是chat协议Codex 不同版本默认期望responses两边没对齐发请求时 Codex 命中了一个不存在的/responses端点。base_url 路径没带 /v1。这是路由 404 的头号原因Codex 会在 base_url 后面拼具体路径你没带/v1它拼出来的地址自然不对。环境变量残留。切换配置后新 provider 的env_key改成读取DEEPSEEK_API_KEY但 shell 里还残留着上一个 provider 的OPENAI_API_KEY两个 key 在同一个环境里Codex 可能会选错。排查建议很简单先用env | grep -i api_key看看当前环境里到底有哪几个 key再检查切换后的配置里base_url和wire_api是否和实际服务端匹配。大部分“local proxy failed”类报错都能通过这两步定位。5.3 显示更新 agent 沙盒沙盒权限问题Codex 的沙盒机制是用来限制 Agent 对文件系统的访问的。启动时提示“更新 agent 沙盒”或者操作时提示没有权限写入通常和sandbox_mode配置有关。默认的沙盒模式是只读Codex 只能读取工作区内容不能写文件。如果你需要它改代码、创建文件得把沙盒模式调到允许写入sandbox_mode workspace-writeworkspace-write允许 Codex 在当前项目工作区内写文件但不允许碰工作区以外的目录比如家目录里的其他项目。如果你确认某个任务需要更大范围的权限Codex 也提供danger-full-access模式但我不建议日常使用一旦 prompt 注入或者指令错误后果不可控。“显示更新 agent 沙盒”这个提示还有一层含义是 Codex 的沙盒镜像或者版本过旧需要更新。这种情况一般直接运行安装脚本更新 Codex 本体正常情况下沙盒组件会跟着一起升级。5.4 排错方法论不要瞎试要有最小复现我发现很多人在排错时有个坏习惯看到一个报错就在配置文件里东改一下西改一下改完重启一遍不行再改别的。这种“瞎试”方法效率非常低因为多个变量同时变化后你根本不知道是哪个改动生效了。我的方法是二分回滚保留一份绝对能跑的配置比如官方默认配置在这个基础上只加一个自定义项跑一次看是否成功。如果失败回滚这个改动换下一个。这样每一步的因果关系都清晰。遇到复杂问题时再用codex --debug抓请求日志对照日志里的 URL、状态码、响应体来定位而不是靠猜。这份配置排查的经验比我一开始说的“记住优先级顺序”更值钱。因为优先级表是死的真实环境里配置来源的组合方式是无穷的只有掌握了“最小复现 分级排查”的方法才能在各种奇奇怪怪的报错面前不慌。我自己现在维护 Codex 配置的方式很简单所有配置文件纳入 Git 管理每次变更都提交每个项目单独写 AGENTS.md不依赖全局规则尽量用 profile 隔离不同场景避免在同一个 config.toml 里堆太多互相可能冲突的配置。这套组合拳打下来Codex 在本地真正变成了一个“知道这个项目该怎么干活”的专属 Agent而不是一个每次都要从零解释上下文的新实习生。