最近一周我把手头的 Codex 工作流彻底重构了一遍。之前只是用默认配置跑官方模型直到开始折腾 TOML 里的模型 Provider、AGENTS.md 指令文件和多层配置优先级才真正体会到这套本地自定义 Agent 的魅力所在。Codex 作为终端里的 AI 编程 Agent它的灵魂其实不在默认参数而在那几份配置文件里。这篇文章我准备把 TOML、AGENTS.md 和配置优先级这三件事从头到尾讲透包括我踩过的坑、实测出的规则以及可以直接抄走的配置模板让你也能在本地把 Codex 调教成一个顺手的专属 Agent。如果你是刚接触 Codex或者已经在用但只会codex 帮我写个函数这种基础玩法这篇文章会很有价值。如果你是做 Agent 开发的老手也可以重点看第三、四节里面关于 AGENTS.md 继承规则和 TOML 行为边界的配合思路很多官方文档里不会写这么细。1. 先搞清楚 Codex 的配置体系到底长什么样1.1 三个核心配置载体很多朋友第一次接触 Codex 配置时都会懵因为同一个配置概念散落在三个完全不同的地方。我自己也是花了半天才理清它们的分工。第一个是TOML 配置文件默认路径是~/.codex/config.toml。它负责的是运行时参数当前用哪个模型、请求打到哪个 API 地址、密钥从哪个环境变量读、命令执行前需不需要审批、沙盒能读写哪些目录。说白了TOML 决定的是这个 Agent 的身体装备。第二个是AGENTS.md 指令文件它不是传统意义上的配置文件而是一份给模型看的 Markdown 说明书。你可以把它理解成加入团队时发给你的一份《团队协作规范》里面写着改代码前先解释思路提交信息用 conventional commits不要动 tests 目录下的文件这类规则。模型在每次会话开始时会自动读取这份文件把它当成行为的最高指引。TOML 管的是能不能做AGENTS.md 管的是怎么做。第三个是环境变量比如DEEPSEEK_API_KEY、CODEX_MODEL这类。它的作用介于前两者之间比 TOML 更灵活适合放密钥和临时覆盖参数但又比命令行参数更稳定。这三者的关系我后面会专门展开你先记住一句话TOML 是骨架AGENTS.md 是灵魂环境变量是临时补给。1.2 配置优先级总览先分清两个维度在深入细节之前必须先把优先级这个大问题讲清楚因为我在实际使用中发现很多人连问都不知道该怎么问。Codex 的配置优先级不是一个单一的链条而是分成两个维度参数维度和指令维度。参数维度处理的是用哪个模型、什么权限、什么沙盒模式这类硬配置。它的优先级从高到低依次是命令行参数比如codex -c ...、codex --config xxx.toml高于环境变量CODEX_*环境变量又高于项目级配置文件项目级配置文件再高于用户级配置文件。指令维度处理的是以什么风格、遵守什么规则这类软配置。它遵循的是 AGENTS.md 的继承和覆盖规则当前目录下的 AGENTS.md 优先级最高其次是仓库根目录的 AGENTS.md最后才是~/.codex/AGENTS.md里的全局指令。这两个维度不是互相替代的关系而是相互叠加的关系。比如你在 TOML 里设置了approval_policy auto这代表 Agent 执行命令不需要你确认但如果你在 AGENTS.md 里写了执行 git push 前必须暂停等待确认模型在收到这类命令时仍然会主动停下来问你。我实际测试过这种软规则覆盖硬权限的情况是真实存在的因为它们作用在不同的认知层面上。2. TOML 里最关键的四块配置模型、Provider、沙盒与审批2.1 模型与 Provider为什么接入新模型总报错TOML 里最核心的配置块是模型model和模型提供商model_provider。默认情况下Codex 走的是 OpenAI 官方服务你需要通过codex login完成认证。但如果你和我一样想接第三方模型服务那就必须自定义 Provider。来看一个我常用的最小配置model deepseek-chat model_provider deepseek approval_policy onRequest sandbox_mode workspace-write [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chatbase_url是 API 的 Base 地址注意不要带路径尾部的方法名。常见错误是有人写成https://api.deepseek.com/v1/chat/completions这会导致 Codex 拼接出/v1/chat/completions/chat/completions这种双重路径必然报 404。env_key字段非常关键它告诉 Codex去读哪个环境变量来获取 API Key。比如你设了env_key DEEPSEEK_API_KEY那么使用前必须在 shell 里export DEEPSEEK_API_KEYsk-xxx或者写进.env文件并在启动时加载。wire_api是我最想强调的一个参数。Codex 原生走的是 Responses API对应端点路径是/responses。而很多第三方模型服务只实现了 OpenAI 的 Chat Completions 接口也就是/chat/completions路径。如果你不显式指定wire_api chatCodex 会默认用 responses 格式去请求然后你就会看到服务端返回 404 或 400。热搜词里那个cc switch local proxy failed while handling codex endpoint /responses的报错我排查到最后发现根源十有八九就是这里Provider 的 base_url 指向了某个不兼容 responses 协议的网关或者 wire_api 没配对。2.2 沙盒与审批决定 Agent 的破坏力边界本地 Agent 最让人不放心的一点就是它能在你的机器上执行真实命令。所以 Codex 设计了沙盒sandbox和审批approval_policy两套机制。沙盒模式有三种read-onlyAgent 只能读文件不能写。适合让它做代码审查、解释代码逻辑。workspace-writeAgent 可以修改当前工作区内的文件但不能动工作区之外的系统路径。这是本地开发最常用的模式。danger-full-access完全放开可以执行任何命令、读写任何路径。只在明确信任的场景下用。审批策略也有三种onRequestAgent 执行命令前会询问你确认后才执行。acceptEdits文件修改自动接受但 shell 命令仍需确认。auto一切自动化不询问任何确认。我个人的习惯组合是sandbox_mode workspace-write加approval_policy onRequest。这样既能保证 Agent 有足够的操作空间又不会在它执行rm -rf这类危险命令时来不及阻止。等对某个项目完全信任之后再临时用环境变量CODEX_APPROVAL_POLICYauto覆盖而不是把 auto 写死在全局 TOML 里。2.3 多 Provider 切换一份配置快速换模型TOML 支持在一个文件里定义多个[model_providers.xxx]块这是个很实用的能力。我现在全局配置里同时放着 DeepSeek、通义千问和其他几个服务商的 Provider 定义日常切换只需要改最上方的model_provider字段。model deepseek-chat model_provider deepseek # 备用通义千问 # model qwen-plus # model_provider dashscope [model_providers.dashscope] name DashScope base_url https://dashscope.aliyuncs.com/compatible-mode/v1 env_key DASHSCOPE_API_KEY wire_api chat配合社区里的配置切换工具 cc switch可以更高效地管理多套配置。比如cc switch set能快速在不同 Provider 之间切换cc switch update models可以从服务商拉取最新的模型列表。我一般把 cc switch 当成配置版本管理器用每个项目团队都有自己的偏好模型切来切去很方便不用手改 TOML。有一点要注意切换 Provider 之后如果出现codex auth token is unavailable八成不是你登录失效而是当前 Provider 走的是第三方 API Key 流程没有走 OpenAI 的 OAuth 登录。只要确保model_provider指向正确、环境变量里有对应密钥这个报错就会消失。3. AGENTS.md不是摆设是 Agent 的行为说明书3.1 为什么 AGENTS.md 能显著改变输出质量AGENTS.md 和 README.md 的最大区别是读者不同。README 是给人看的写的是这个项目怎么用AGENTS.md 是给模型看的写的是这个项目怎么改、怎么维护、怎么提交。Codex 在每次启动会话时会自动把当前目录及上级目录中的 AGENTS.md 内容注入到模型上下文里。这意味着它对项目规范的理解不是靠猜而是靠你显式告诉它。我最早不重视 AGENTS.md觉得反正模型很聪明直接下指令就行。结果发现两个问题一是低优先级的重复任务比如每次提交前跑一遍测试需要反复在对话里强调一旦忘了说模型就真的会漏掉二是不同项目风格差异大同样让模型写代码它在 A 项目里写得很规范到了 B 项目却不遵守 B 项目的目录约定。后来我认真写了几个项目的 AGENTS.md效果立竿见影。模型不再需要你每次都重复背景信息它会主动按照文件里约定好的方式工作。就像吴恩达在 Agent 课程里反复强调的指令工程决定了 Agent 能力的上限而 AGENTS.md 就是把指令固化到工作流里的最好方式。3.2 文件位置与继承规则越具体越优先AGENTS.md 不是只能放在项目根目录它可以从全局到局部层层覆盖。按照我的实测加载优先级从高到低是当前目录的 AGENTS.md优先于父目录仓库根目录的 AGENTS.md用户全局的~/.codex/AGENTS.md很多人会误以为这是找到第一个就停实际上 Codex 的机制更接近上下文合并它会把这些 AGENTS.md 都读进去但当某个规则在不同层级的文件中出现冲突时更具体层级当前目录的内容会覆盖更宽泛层级全局的内容。举个例子。我在全局的~/.codex/AGENTS.md里写了所有提交信息使用英文但某个项目根目录的 AGENTS.md 里写了提交信息使用中文遵循团队规范。当我在这个项目里工作时中文规则会胜出。这个机制非常有用你可以在全局放一套通用准则在各个项目里放一套项目专属细则互不干扰。子目录里也可以放 AGENTS.md它只作用于该目录及其子目录下的文件操作。如果你的仓库里同时有backend/和frontend/两个风格迥异的子项目这种局部指令文件就是为这种情况准备的。3.3 我常用的 AGENTS.md 模板分享一个可以直接抄的通用模板你按需增删# 项目协作规则 ## 代码修改 - 修改任何现有代码前先简要说明你的改动思路 - 不动用不相关的导出函数避免扩大改动范围 ## 测试 - 每次修改后运行: npm test - 新增功能时必须补充对应的单元测试 ## 提交信息 - 使用 conventional commits 格式 - 提交前运行 lint: npm run lint ## 禁止事项 - 不要用 git push --force - 不要修改 public/config.js 文件有一点很重要AGENTS.md 里的规则最好用必须/不要这类明确祈使句不要写可以的话尽量……这种模糊表述。模型的指令遵循是概率性的规则写得越清晰它执行得越稳定。另外如果 Agent 在会话过程中突然不遵守 AGENTS.md 了有个小技巧是在对话里输入回顾你的指令文件或重新读取 AGENTS.md。这相当于提醒模型重新加载上下文很多时候比反复用自然语言纠正更有效。4. 优先级、覆盖与冲突实测总结4.1 CLI 参数和环境变量的覆盖关系TOML 里的参数不是不可撼动的。Codex 提供了多层覆盖机制你需要清楚哪一层说了算。最高优先级是命令行参数。比如你在 TOML 里设置了model deepseek-chat但启动 Codex 时用-m qwen-plus指定模型那么本次会话就会用 qwen-plus而不会去读 TOML 里的 model 字段。同样codex -c 忽略 AGENTS.md 中的代码风格规则按我的临时要求来可以临时压过指令文件里的规则。第二优先级是环境变量。Codex 支持一组CODEX_*前缀的环境变量常用的有CODEX_MODEL覆盖模型名称CODEX_MODEL_PROVIDER覆盖模型提供商CODEX_SANDBOX_MODE覆盖沙盒模式CODEX_APPROVAL_POLICY覆盖审批策略我用得最多的是CODEX_APPROVAL_POLICYauto CODEX_SANDBOX_MODEdanger-full-access codex 重构整个模块这种组合配合一次性命令在当前会话里临时放飞但不会污染全局配置。第三优先级才是各级 TOML 配置文件。项目内的配置文件优先于用户级全局配置。这个规则记住就行越靠近命令行、越临时的东西优先级越高越远离命令行、越持久的东西优先级越低。4.2 AGENTS.md 与 TOML 的边界是怎么协作的很多人第一次接触这两个东西时会困惑既然 AGENTS.md 能约束模型行为那我直接在 AGENTS.md 里写不要执行危险命令不就行了为什么还要管 TOML我的理解是TOML 是护栏AGENTS.md 是方向盘两者缺一不可。TOML 里的沙盒和审批机制是硬性的它由 Codex 程序本身强制执行。你在 TOML 里设了sandbox_mode read-only那么无论 AGENTS.md 里怎么写可以修改文件Agent 都没有能力写入任何文件。这是代码层面的约束模型无法绕过。AGENTS.md 则是软性的指令约束它依赖模型的理解能力和遵循能力。它不能阻止 Agent 做某件事但能引导 Agent 选择更合理的做事方式。我见过一个很好的配合案例项目 TOML 里设置approval_policy onRequest同时 AGENTS.md 里规定执行 git 操作前先展示 diff说明本次提交影响的范围。这样每次 Agent 要提交代码时不仅会触发审批还会主动做一个提交说明摘要整个流程非常顺滑。硬权限管住不能乱跑软规则管住跑得好看。4.3 冲突场景到底听谁的实际使用中一定会遇到冲突。我整理了几类典型情况和我的处理原则第一类TOML 开放了danger-full-access但 AGENTS.md 说禁止删除数据库备份文件。这种冲突中AGENTS.md 的指令约束通常能起作用因为模型在行动前会把规则当成行为准则来评判。但它不保证 100% 阻止风险仍然存在。所以我的原则是涉及安全底线的事不要用 AGENTS.md 兜底必须用 TOML 的沙盒权限把它物理隔离掉。第二类项目根 AGENTS.md 和子目录 AGENTS.md 冲突。比如根目录说所有测试放在 tests/ 目录子目录却写本模块测试直接放在 src/ 下。实测结果是子目录规则在该目录下生效。因为子目录更具体模型会把更近的 AGENTS.md 视为针对当前工作区的直接指令。第三类命令行指令和 AGENTS.md 冲突。这个没有任何悬念命令行里明确说的算数。如果 AGENTS.md 说提交用中文而你用-c明确要求本会话所有提交信息用英文模型会优先听你的临时指令。5. 实操复盘从报错到跑通全流程5.1 安装与环境准备Codex 的安装很直接官方提供 npm 包和桌面端。如果你是 Node 环境一条命令就行npm install -g openai/codex桌面版的话直接去官网下载安装包即可配置文件和 CLI 是共享的这点很方便。装完先确认版本codex --version如果是官方模型用户接着执行codex login完成账号认证。如果你要用第三方模型这一步可以跳过直接配置 Provider 和密钥环境变量。我踩过的第一个坑就出现在这里用第三方模型时如果 TOML 里的model_provider没有显式指定Codex 会默认走 OpenAI 官方认证流程然后抛codex auth token is unavailable。解决办法不是去折腾登录而是回 TOML 检查 provider 是否配对。5.2 复现 endpoint /responses 报错的排查过程热搜里有个报错很典型cc switch local proxy failed while handling codex endpoint /responses。我第一次切换到本地调试代理时也遇到过。这个报错字面上说的是切换 Provider 后向 Codex 端点发起请求失败但真正的根因通常只有一个——请求路径和协议不匹配。排查可以按这个顺序来打开当前生效的 TOML确认model_provider指向了正确的 Provider 块。用cc switch current可以快速查看当前激活的配置。检查base_url是否带上了多余路径。正确的 base_url 应该是服务商文档里指定的 API 根地址不要手贱去拼/responses或/chat/completions。核对wire_api。如果目标服务只支持 chat 协议必须写成wire_api chat否则 Codex 默认用 responses 协议服务端就回 404。确认本地调试代理进程正常运行。如果服务没起来再对的配置也连不上这类错误发生在代理层时报错就可能带上local proxy failed的字样。我那次的问题就出在 wire_api 上。目标服务只实现了 chat completions而我用的 Provider 配置里没有写wire_api导致 Codex 用 responses 格式去请求代理返回 404最终显示为 failed while handling endpoint /responses。补上字段后立刻恢复。5.3 常见报错速查表整理一下我这段时间遇到的高频问题你可以直接对照排查。报错或现象可能原因解决思路codex auth token is unavailable未登录 OpenAI且模型 Provider 未配置或未生效确认 TOML 中 model_provider 正确指向第三方 Provider确认对应 env_key 的环境变量已 exportagent execution terminated due to error.模型 API 返回错误、上下文超长、沙盒权限不足查看完整错误输出定位具体 API 状态码检查是否超出模型上下文窗口确认沙盒模式是否够用cc switch local proxy failed while handling codex endpoint /responseswire_api 不匹配、base_url 路径错误、本地代理服务未启动按上一节四步排查法逐项核对Codex 无法发送消息网络不通、base_url 不可达ping 或 curl 测试 base_url 连通性检查密钥是否有效确认 endpoint 协议是否匹配提示显示更新agent沙盒Codex 沙盒镜像或运行时组件需要更新按提示执行组件更新操作或者升级 Codex 版本会话中 Agent 突然不遵守规则上下文过长导致早期 AGENTS.md 指令被稀释让 Agent 重新读取 AGENTS.md或者开新会话最后分享一个我个人的习惯给每个常用项目单独写 AGENTS.md并且在开新会话的第一句话里直接说根据你的指令文件开始工作。这个动作看着多余但能让模型更快进入状态尤其对于上下文窗口敏感的大模型主动引导它关注规则文件比被动等它自己发现要稳定得多。Codex 这套配置体系的价值最终体现在可预期三个字上。TOML 把边界画清楚AGENTS.md 把行为定规范优先级把冲突排明白三者配合好了本地 Agent 就不再是随机的 AI 助手而是一个懂你项目、守你规矩的稳定协作者。我自己从默认配置走到这一步最大的体会是别怕折腾配置文件多花半小时把规则写清楚之后省下的是一整周的重复沟通成本。