1. 项目概述与配置思路拆解最近 Codex 在开发者圈子里热度一直没下去我也从命令行重度用户一路折腾到本地自定义 Agent越用越觉得它的可玩性被大多数人低估了。很多人装上 Codex 就直接用默认配置跑遇到模型不听话权限弹窗烦人换项目还要手改配置这类问题就觉得它就是个玩具。其实 Codex 真正值钱的地方在于它有一套完整的本地配置体系——TOML 配置文件管模型和运行参数AGENTS.md 管 Agent 的行为规范再加上一套贯穿始终的优先级规则。只要你把这套东西盘顺了它就是一个完全为你定制的本地编码 Agent而不是 OpenAI 附赠的一个默认角色。这篇文章不聊那些花哨的提示词技巧就聊最基础也最容易被忽略的本地配置实战config.toml 怎么写得明白AGENTS.md 怎么编排才听话模型和配置之间的优先级到底怎么算。适合两类人看一类是刚接触 Codex、装了也跑通了但想深入定制的开发者另一类是准备在团队内推广 Codex、需要统一 Agent 行为和模型管理规范的技术负责人。通篇是基于我实际踩坑记录的实战总结不是官方文档翻译你照着做基本能复刻出来。先说整体配置架构。Codex 的本地配置由两条线组成一条是 config.toml负责Agent 用什么模型、以什么权限运行、连哪个模型服务端点另一条是 AGENTS.md负责Agent 在哪个目录、面对什么项目、遵守什么规则、优先看什么文件。两条线不冲突config.toml 是引擎参数AGENTS.md 是行为指令两者叠加才构成一个完整的自定义 Agent。我实际用下来有个很深的体会大多数人卡住的不是某个配置项不会写而是不知道多个配置来源冲突时到底听谁的。Codex 的优先级机制比想象中严格下一节我把整个文件体系和加载顺序拆开讲理解了这个后边的配置才有意义。1.1 Codex 到底解决什么问题Codex 是 OpenAI 推出的终端编码代理它能理解你项目里的代码结构自己读写文件、执行终端命令、跑测试、修 bug甚至帮你提交 Pull Request。跟那些只能在聊天窗口里给代码片段的工具不同Codex 是真正跑在你自己项目环境里的 Agent它能直接操作工作区文件能调用沙盒执行命令能根据执行结果自动调整下一步动作。换句话说它是你的编程搭档不是你的词典。但默认情况下Codex 只走官方模型链路配置也相对固化。对于个人开发者来说默认配置勉强够用一旦你开始做本地自定义 Agent比如想把模型切换到更经济的第三方服务、想给不同项目预置不同的编码规范、想让 Agent 在提交代码前自动跑一整套检查和格式化就必须动 TOML 配置和 AGENTS.md 了。这两个文件就是 Codex 从能用到好用的分水岭。1.2 为什么需要本地自定义配置我说几个真实场景你对照看看自己是不是也有这类需求。场景一我在做开源项目的时候每天要跟 Codex 交互几十次每次都手动指定指令很烦。我更希望它自动读取项目里的 AGENTS.md知道这个仓库要求测试覆盖率不低于 80%提交前必须跑 gofmt 和 golangci-lint遇到 panic 要先看日志再改代码。这些规则如果靠聊天时现说Agent 大概率会漏。场景二团队里几个人都在用 Codex每个人本地模型配置五花八门有的人用了默认模型有的人走着走着模型配额就超了。如果团队统一维护一份 config.toml 模板把模型、超时时间、权限策略都定好新成员克隆配置就能用Agent 的行为差异一下就缩小了。场景三个人开发者对成本敏感默认的官方模型虽然强但高频使用价格不低。Codex 允许配置自定义模型提供方你可以接入 OpenAI 兼容的第三方模型服务把高性价比模型作为日常默认只在复杂重构时才临时切到更强模型。要做到这一切靠的就是 config.toml 里那套 provider 配置和模型优先级逻辑。这就是本地自定义 Agent 的价值把 AI 编码工具从一个对话窗口改造成一个懂你项目规矩的工具人。1.3 配置体系的整体架构我对 Codex 配置体系的理解可以概括成一张三层图不用画图工具想象一下就够——最底层是用户级配置文件位于用户主目录下的 .codex 目录里面有全局 config.toml 和全局 AGENTS.md中间层是项目级配置放在仓库根目录的 .codex 子目录里主要放项目独有的平台配置最上层是你日常操作时传入的命令行参数。这三层不是各管各的而是按照具体优先于抽象的原则层层覆盖命令行参数最大能覆盖项目级配置项目级配置次之能覆盖用户级配置用户级配置兜底提供所有项目的默认行为。在模型这一项上同样的覆盖逻辑也成立。命令行指定 --model 会覆盖 config.toml 里 model 字段的值而 config.toml 里的 model 又决定了默认模型。如果你配置了多个 model_providerCodex 还会按 provider 内部预设的模型列表去做兜底选择这个过程也有一套固定优先级。把整体架构理清后你会发现 Codex 的配置哲学并不复杂能让你在一个地方统一设默认值也允许你在更具体的层级上临时覆盖。2. 环境准备与文件体系认知动手写配置之前先把环境和文件体系摸清楚。很多人配置文件写得很漂亮结果 Codex 根本不读原因多半是放错了位置或者文件名写错了。这里我把整个安装到文件定位的过程完整过一遍。2.1 安装 Codex 并确认版本Codex 的安装方式很简单官方推荐用 npm 全局安装只要机器上有 Node.js 环境就行。装完之后命令行输入 codex --version 确认安装成功。需要注意版本差异不同版本的 Codex 对 TOML 配置项的支持程度不完全一样比如早期版本就不支持某些 provider 字段。我建议直接装最新稳定版省得踩配置项没反应的坑最后发现是版本太老不识别这个字段。安装完成后首次启动会让登录并完成认证。这一步走完它会在用户目录下生成 .codex 目录以后的配置文件都会放在这里。如果你要做的只是官方默认模型调优到这一步就可以开写配置了如果要接第三方模型就得准备好 API 密钥和 Base URL。2.2 配置文件的三种存在位置Codex 的配置不只有一份它按照作用范围分成三个层级。理解这三个层级是搞清优先级问题的前提。第一层是用户级配置固定存放在 ~/.codex/config.toml。这一层配置对所有项目生效适合放通用行为默认模型、日志级别、审批策略、沙盒模式等。绝大多数人只需要维护这一个文件。第二层是平台级配置存放在 ~/.codex/config.toml 之外的平台特定文件不同平台位置略有差异主要用于存储与平台绑定的一些默认值。这一层绝大多数用户碰不到但你要知道它的存在避免后续排查时摸不着头脑。第三层是项目级配置放在仓库目录的 .codex/config.toml 里。这一层允许你把配置跟着仓库走提交到 Git 后全团队都能共享同一套 Agent 参数。项目级配置适合覆盖用户级配置中的特定值比如某个项目必须用特定模型、必须开启完整沙盒等。需要特别强调项目级配置的优先级高于用户级配置。我见过不少人改了项目里的 config.toml但发现不生效一查发现用户级配置里的 model 字段把项目级的值顶掉了——其实顺序正好反了项目级应该更高。出现这种困惑的根源是没有完整搞懂加载顺序。记住自己的优先级口诀命令行参数 项目级配置 用户级配置 内置默认值。2.3 认识 config.toml 与 AGENTS.mdconfig.toml 和 AGENTS.md 是 Codex 本地自定义的两大核心文件。config.toml 负责运行参数AGENTS.md 负责行为指令二者的关系可以类比成汽车的仪表盘参数和司机手册。config.toml 里主要定义模型名称、模型提供方model_provider、沙盒模式sandbox_mode、审批策略approval_policy、网络超时model_timeout、输出令牌上限model_max_output_tokens等。这些参数决定 Agent 用什么引擎、以什么权限跑、能做到多激进。AGENTS.md 则是给 Agent 看的说明文件Codex 在进入工作目录时会自动读取项目里的 AGENTS.md把它作为行为约束注入到对话上下文中。你可以在里面写代码风格、测试要求、禁止事项、项目架构说明等。它不像 config.toml 那样有严格的键值语法更像是给 Agent 的规范笔记。这两个文件一个管能不能做一个管怎么做是 Codex 自定义配置的一体两面。实际操作中config.toml 写得越稳Agent 运行越省心AGENTS.md 写得越具体Agent 行为越可控。3. config.toml 模型与优先级配置实操这一节是本文的重头戏。我把 config.toml 的语法、核心字段、第三方模型接入方式以及优先级规则串起来讲清楚。你手头打开一个编辑器边看边写就行。3.1 TOML 语法速览与易错点TOML 是一种为配置文件设计的格式核心语法就是键值对用中括号定义表结构。Codex 的 config.toml 完全遵循 TOML 规范所以你有必要先避开几个高频错误。第一个错误字符串不加引号。TOML 里基本字符串必须用双引号包起来不少人习惯性写成 model gpt-5配置文件解析直接报错。正确写法是 model gpt-5。第二个错误注释搞错符号。TOML 支持 # 注释但有些人在行尾写 // 注释这种写法会导致配置解析失败。注意TOML 不支持 // 注释风格。第三个错误数组混用类型。TOML 数组要求元素类型统一写 [gpt-5, 123] 这种混合数组会报错。Codex 配置里数组用得不多但万一用到保持统一。第四个错误嵌套表缩进混乱。TOML 不靠缩进区分层级靠表名路径。比如 [model_providers.deepseek] 和 [model_providers] 是两种不同的节点缩进只是给人看的不是语法的一部分。很多人看着缩进整齐以为没问题结果表路径写错了。整份配置文件的骨架可以长这样# ~/.codex/config.toml model gpt-5 model_provider openai [approval_policy] mode on-request [model_providers.deepseek] name deepseek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat上面这段基本结构先记住后面我会逐字段拆解。注意表路径 [model_providers.deepseek] 里的 deepseek 是写在这里的 key后面引用它会用到这个名字。3.2 核心配置项逐条解读先看 model 字段。这一项设置默认模型名称可以是官方模型比如 gpt-5、gpt-4o也可以是你在 model_providers 里定义的自定义提供方下的模型名。使用优先级最高的是命令行参数比如 codex --model gpt-5其次是 config.toml 里的 model最后是 Codex 内置的默认模型。再看 model_provider 字段。它指定当前默认使用的提供方。如果没有单独配置Codex 会使用内置的 openai 作为提供方。一旦你设置了自定义提供方而且把 model_provider 指过去Codex 就会用该提供方对应的 base_url、API key 和协议来完成请求。这一项和 model 共同决定了Agent 到底在和谁说话。接着是 sandbox_mode 和 approval_policy。sandbox_mode 控制 Agent 对文件系统的访问权限常用的有 workspace-write只能写当前工作区、sandbox只能写沙盒目录、full-access不限制写权限。approval_policy 则控制命令是否需要人工审批可选项有 on-request要求时必须审批、auto-write自动批准写操作但执行命令仍需审批等。我自己的经验是日常开发用 workspace-write on-request 最稳既不伤系统目录又能保留对危险命令的控制权。只在自己的个人工具项目里我才会临时用 full-access 跑自动化批处理。3.3 接入第三方模型提供方配置Codex 允许通过 model_providers 定义自定义模型服务商支持 OpenAI 兼容协议。这一步是很多人最关心的我就以接入 DeepSeek 为例完整跑一遍。在 config.toml 里追加一段[model_providers.deepseek] name deepseek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat这里每个字段的作用分别是name 是对外显示的名称base_url 是 API 服务的基地址env_key 指定从哪个环境变量读取 API 密钥wire_api 表示协议类型写 chat 表示走 Chat Completions 协议。配置完成后在环境变量里设置 DEEPSEEK_API_KEY然后切换默认模型model deepseek-chat model_provider deepseek这样 Codex 就会走 DeepSeek 的 API 来完成对话。第一次切换时记得 codex 重新启动一个新会话确保配置重新加载。这里的关键点是 wire_api 的选择不同厂商可能不完全一致有的是 chat 兼容有的是 responses 协议。接第三方模型时先查清楚对方 API 兼容哪一种再决定 wire_api 写什么这个错误排查起来最浪费时间的。3.4 模型与环境级别的完整优先级规则我把 Codex 的优先级规则整理成了一张速查表你直接对照着用。需求场景高优来源低优来源说明本次会话用什么模型命令行 codex --model xxxconfig.toml 的 model 字段命令行永远最高多项目共用一套配置还是项目独立项目级 .codex/config.toml用户级 ~/.codex/config.toml项目级覆盖用户级用哪个提供方的 APIconfig.toml 的 model_provider 字段内置默认 openai显式指定优先Agent 行为规范冗余时听谁的子目录 AGENTS.md项目根目录 AGENTS.md具体目录优先这里最容易被忽略的是model 和 model_provider 的组合关系。如果 model 指定成 deepseek-chat但 model_provider 还是 openai那 Codex 会尝试在 openai 的模型列表里找 deepseek-chat结果自然是模型不存在。反过来model_provider 设成 deepseekmodel 写 gpt-5则 API 请求发到 DeepSeek 服务端同样报错。所以这两个字段必须配套设置优先级规则也只能在配套的前提下生效。4. AGENTS.md 分层规则编写指南config.toml 调完之后Codex 的肉身就搭好了AGENTS.md 则负责注入灵魂。这一节讲清楚 AGENTS.md 的工作原理和编写方法这是本地自定义 Agent 行为控制的核心。4.1 AGENTS.md 为什么会生效很多第一次接触的人会疑惑AGENTS.md 就是个 Markdown 文件Codex 凭什么读它、又为什么能够影响模型行为原理并不神秘。Codex 在启动时会自动扫描当前工作目录把它找到的 AGENTS.md 内容注入到发送给模型的上文context中。模型在拿到用户指令前其实已经看到了这份背景说明因此后续生成代码时指令文件里的约束就会持续影响它的行为。这些约束不是法律但大模型在上下文里会显著倾向于遵循只要约束写得清楚、不与用户显式指令冲突效果非常明显。我自己测试过同一个任务在没放 AGENTS.md 时Codex 会按照默认习惯写代码放了 AGENTS.md 并写明所有函数必须在注释中标注复杂度之后它后续生成的所有函数都老老实实带上了复杂度注释。这说明 AGENTS.md 确实能够把 Agent 的行为调教到一个预设轨道上。4.2 全局、项目、子目录三层怎么排AGENTS.md 也可以分层放置这与 config.toml 的层级机制异曲同工。全局的 AGENTS.md 放在 ~/.codex/AGENTS.md它描述用户在所有项目里都希望 Agent 遵守的通用习惯比如代码注释使用中文不要修改未要求改动的文件。项目根目录的 AGENTS.md 在仓库根目录它描述这个项目特有的规则比如测试用 pytest 而不是 unittest新功能必须加测试用例。子目录里的 AGENTS.md 可以进一步覆盖根目录的规则适用于局部模块有特殊约束的情况。优先级也很直白子目录 AGENTS.md 覆盖根目录 AGENTS.md根目录覆盖全局。如果你的项目默认走 pytest某个子模块却是遗留的 unittest 代码你就在那个子目录放一个 AGENTS.md写上This directory uses pytest-style tests, do not use unittest效果立竿见影。这个分层的设计理念跟我前面说的配置优先级完全一致都是让更具体的声明获得更高优先级。4.3 从普通说明到 Agent 规则的语言转化很多技术负责人会犯一个典型错误把 AGENTS.md 写得像一份团队 Wiki全是背景介绍和长篇大论。这确实好看但 Agent 处理起来效率低而且容易抓不住要点。AGENTS.md 的目标读者是模型不是人类同事所以语言组织方式必须适配模型避免歧义。我推荐的小技巧是使用明确祈使句 正例示范的组合。比如不要写The project uses a modular architecture, you should try to keep consistency模型对should try这类模糊表述很不敏感要写REQUIRED: New modules must follow src/ directory structure. Example: src/parser/tokenizer.ts模型看到 REQUIRED 加示例执行准确率会明显提升。另一个实用做法是把禁止清单分类列出。模型的注意力机制对分条目的短句更敏感一条禁令占一行效果最好。比如# Project Rules - 禁止直接修改 lockfile 文件除非重构依赖关系 - 提交前必须运行 make test - 新功能必须包含测试用例 - 不要修改非任务相关文件 - 使用中文写注释代码内标识符保持英文这套写法比长篇散文有效得多。注意AGENTS.md 虽然以 md 结尾但本质是配置文件不是给人读的文档内容贵精不贵多精简的规则反而更稳定地被遵循。5. 完整实操本地自定义 Agent 配置全过程讲了这么多理论回归实战。这一节给你呈现一份完整的、可以照抄的本地自定义 Agent 配置全过程从场景设定到每一步的验证结果全部走一遍。5.1 我与配置目标假设你在做一个 Python 后端服务项目内部规范如下代码风格用 ruff 检查测试用 pytest提交前必须跑 make check所有公共函数必须有 docstring。你希望 Codex 在这个项目里表现得像个熟悉团队规范的老手而不是一个只会写通用代码的 AI。同时你希望默认模型使用某个第三方更经济的模型提供方假名为 ExampleAI你已经在服务商后台拿到了 API Key只有明确需要更强推理时才临时切换官方大模型。放着这两个目标我们开始配置。5.2 配置过程与验证第一步在项目根目录创建 .codex/config.toml写项目级配置内容如下# .codex/config.toml model example-ai-fast model_provider exampleai [model_providers.exampleai] name exampleai base_url https://api.example-ai.example/v1 env_key EXAMPLEAI_API_KEY wire_api chat [approval_policy] mode on-request第二步在仓库根目录创建 AGENTS.md写下团队规则上文示例即可。注意两个文件各管一摊config.toml 决定 Agent 用哪个模型、以哪种权限跑AGENTS.md 决定 Agent 遵循哪些编码行为。第三步验证配置是否生效。在 .codex 目录里运行 codex确保当前工作目录在项目内随便问一个问题比如这个项目的入口文件是哪个。如果 Codex 能正确返回入口路径说明它已经读取了项目结构和 AGENTS.md。如果返回结果明显没有遵循项目规则检查 config.toml 是否有 TOML 语法错误、AGENTS.md 是否放在了正确的位置。第四步验证模型切换。先按默认模型跑一个任务然后使用 codex --model gpt-5 强制切换官方模型执行同一个任务对比两者输出。此时你会体会到层级优先级在真实工作中怎么起效不写参数时听 config.toml 的写了 --model 参数时命令行覆盖全局。我实测后的建议是先用小任务验证模型连通性再慢慢上真实业务代码不要一上来就让 Agent 做大重构配置错了连报错信息都听不懂排查成本反而高。5.3 多项目并存时的切换方案现实中你不会只维护一个项目。如果每个项目都要一套独立的模型和规则全堆在用户级配置里会乱成一锅粥。正确做法是坚持项目级配置优先每个仓库自带 .codex/config.toml 和 .codex/AGENTS.mdAGENTS.md 也可以直接放仓库根目录看团队习惯用户级只放兜底配置。这样切换项目时你甚至不需要手动改任何全局配置只要 cd 到对应仓库目录启动 Codex它就会自动加载该仓库的配置。我的工作流是用户级 config.toml 只写日志级别、鉴权信息、默认模型这一层抽象东西具体项目的模型选择、权限策略、规则文件全部下沉到项目里跟着 Git 走。这既方便协作又能保证各项目互不污染。我见过有人把多项目并存简单理解为多份 config.toml 轮换覆盖但这会污染全局状态而且容易出现残留配置影响下一个项目。真正干净的方案就是让配置的作用域尽量收窄——能用项目级解决的绝不动用户级。6. 常见问题与排查技巧实录最后这部分是踩坑记录我按问题出现的频率排列每一条都是实际遇到并验证过解决思路的可以直接当成排查手册。6.1 配置不生效 / 模型选择不对症状一改了 config.toml 的 model 字段重启 Codex 后依然是原来的模型。排查方向先确认你改的是不是实际生效的那一份配置。用户在多个项目目录下工作容易改完项目里的 config.toml 却忘了用户级还有一份高优先级配置在覆盖。用 codex --version 确认版本必要时可以用 codex --debug 输出详细的加载日志直接看到每个配置项的最终来源。还有一个容易被忽略的问题Codex 启动后配置就固定了如果你在一个已打开的会话里修改 config.toml它不会自动重载必须重新启动会话。遇到改了没反应先别怀疑配置本身先重启一次。6.2 连接异常与鉴权失败症状二切换了自定义 provider 后请求报错提示网络连接失败或鉴权失败。排查方向第一步检查环境变量里的 API Key 是否设置且拼写正确第二步检查 base_url 是否正确很多自定义服务的地址要精确到 /v1 路径多加或少加一个斜杠都会导致请求路径错误第三步确认 wire_api 是否与厂商协议匹配。我遇到过一种比较隐蔽的情况config.toml 里 env_key 换了个名字但当前终端会话没有 export 新变量旧变量还在Codex 读到了旧值鉴权自然失败。这种情况清理环境变量后重启终端问题就消失了。6.3 沙盒与审批策略问题症状三Agent 明显需要写文件但一直提示权限不足或者反过来Agent 自动改动了不该改的文件。排查方向两种现象都是 sandbox_mode 没配对。只希望你检查当前 session 的沙盒模式设置是否过于严格或过于宽松。如果提示权限不足把 sandbox_mode 从 sandbox 调整为 workspace-write如果 Auto 改动范围过大尽快收紧到 sandbox 或workspace-write并把 approval_policy 调整为on-request。这类问题往往在写自动化脚本批量改文件时最容易暴露。我的经验是高风险的批量操作前先手动提交一遍当前改动再让 Agent 动手过度授权后还有后悔药。6.4 冷门但真要命的问题最后说几个不那么常见但一旦遇上就让人抓狂的小问题。一个是大小写不一致。模型名称和 provider 名称的大小写必须和配置完全一致CODE 的大小写不一致会导致配置读取但目标找不到对象。另一个是全局与项目配置残留互相污染。我见过有人几个月前在某项目里配过一次 model_provider之后其他项目里模型一直莫名其妙用错排查到最后才发现是项目级配置文件残留。遇到难以理解的配置行为一份份检查所有 .codex/config.toml比盯着一份看半天强。最后是 AGENTS.md 写了很多规则但 Agent 不响应。原因通常是规则写得像散文全是背景描述而缺少明确的祈使句。把关键规则提出来、单独成句、加上 REQUIRED 或 MUST 这类强约束标记模型遵循度会显著上升。写在最后个人实际配置心得折腾完这一整套 Codex 本地自定义配置我最深的感受是工具链的深度远比第一眼看上去要深而每一层配置都是让你离顺手更近一步的代价。我自己的最后配置形态是用户级 config.toml 里只放最少的通用项项目级配置按需覆盖AGENTS.md 精简成不超过二十行的强制规则清单。这样做的收益是——我可以在不同类型的项目之间无缝切换Codex 会自动带上对应项目的人格而我也几乎不需要再在对话里反复交代上下文。如果你正准备开始配置自己的 Codex我的建议是先别急着抄一份完整配置而是用最小配置跑通一个任务理解每个字段的实际效果再逐步叠加。这样即使哪天配置写乱你也能很快定位到哪一行引发了问题。最后分享一个小技巧把 AGENTS.md 的规则写完之后多问 Codex 一句你记住了哪些项目规则让它把理解复述一遍。这一招能在真正投入复杂任务前就及时修正指令文件中的歧义和冲突省下后面大量的返工时间。