如果你已经装好了 Codex CLI别急着让它裸奔。真正能放大 Agent 生产力的不是提示词写得有多花哨而是把config.toml和AGENTS.md这两份文件吃透。我见过太多人本地跑 Agent模型一会儿用 A 一会儿用 B指令规则时灵时不灵最后发现全是配置加载顺序和优先级的问题。这篇文章我会用实际项目里的配置把 TOML、AGENTS.md 和优先级这三件事一次讲清楚让你改完配置心里有底。这篇内容适合三类人刚接触 Codex、想从零配置一个能用的本地 Agent 的开发者已经用了一段时间但始终没搞懂“为什么我改了配置不生效”的困惑用户以及想把 Codex 接到不同模型服务上、又不想每次手忙脚乱改文件的人。下面不废话直接进入正题。1. 先搞清楚 Codex 本地 Agent 的配置文件体系1.1 Codex 到底在找哪些文件Codex 的本地 Agent 行为和普通命令行工具不太一样它不是一个“启动时读一次配置”就完事的程序而是一个会动态读取多层配置的运行时系统。第一次接触的人往往会问配置到底放哪里答案是两个地方最核心用户级全局目录和项目本地目录。默认情况下Codex 会把用户级配置放在~/.codex/下面。你在这个目录里最常见到的文件是config.toml和AGENTS.md。config.toml是主配置文件负责模型选择、模型供应商、API Key 的环境变量绑定、沙箱行为、输出参数等AGENTS.md则是行为指令文件告诉 Agent 在干活时应该遵循什么规则、注意什么约束、优先采用什么风格。两者职责完全不同一个管“能不能跑”一个管“跑得好不好”。项目本地配置文件则更灵活。Codex 会从当前工作目录开始向上查找AGENTS.md也会优先读取项目目录下的.codex配置。这意味着你可以为不同仓库配置完全不同的行为而不是所有项目都套用同一套全局规则。1.2 文件加载顺序与合并规则配置系统的第一个坑就是加载顺序。Codex 的规则是先加载用户级全局文件再加载项目级文件最后用命令行参数做最终覆盖。如果同一个配置项在多个地方出现后加载的会覆盖先加载的但注意这里不是“整个文件覆盖”而是字段级覆盖。也就是说项目级config.toml里只写了一个model字段它不会抹掉全局配置里的其他字段只会覆盖model这一个值。AGENTS.md的加载顺序也类似但语义上要更小心。全局的~/.codex/AGENTS.md是基底规则项目根目录的AGENTS.md是针对当前仓库的补充规则。如果项目规则和全局规则冲突项目规则优先如果子目录里还有AGENTS.md子目录规则又会覆盖项目根目录规则。这种设计很像 Git 的.gitignore层级逻辑越具体的目录优先级越高。为什么这样设计因为 Agent 场景里你不可能为每一个小任务都显式传一大堆参数。合理的做法是把通用规范放在全局把仓库特有信息放在项目文件把临时调试参数放在命令行。Codex 要做的就是在你敲下命令的那一刻把所有这些信息合并成一个有效的上下文。1.3 为什么你的配置“时灵时不灵”很多人的第一反应是“Codex 是不是有 bug”。我排查过不少这类问题九成以上不是 bug而是下面几个原因。第一个原因是工作目录不对。Codex 的“项目”概念基于当前目录和向上查找的路径树。你在/home/user/project下运行它读的是/home/user/project/AGENTS.md你切到子目录/home/user/project/src它会继续找到父目录的AGENTS.md但如果你跑到/home/user/other那刚才的规则就全部失效了。这不是配置没生效而是位置不对。第二个原因是文件名大小写问题。Linux 下agents.md、Agents.md、AGENTS.md是三个完全不同的文件。Codex 只会读取约定好的精确文件名不要凭感觉改名。第三个原因是会话历史干扰。AGENTS.md虽然会在新会话启动时被读取但已经存在的会话可能还保留着旧指令的上下文。你改了AGENTS.md如果继续用老会话Agent 的行为可能看起来“没变”。这不是配置失效而是历史消息还在起作用。第四个原因是环境变量没刷新。如果配置里绑定了某个 API Key 的环境变量但你在当前终端没设置Codex 就找不到认证信息表现就是各种认证错误。新开终端、重启 Shell、确认变量是否导出这些操作比你想的更关键。2. TOML 配置文件逐项拆解模型与 Provider 的正确写法2.1 一份最小可用的 config.tomlToms Obvious Minimal LanguageTOML的语法非常直观但正因为简单很多人会忽略细节。下面这份配置是我实际使用的最小模板你把它放到~/.codex/config.toml就能让 Codex 跑起来。# 全局模型配置 model gpt-5 model_provider openai # 供应商定义 [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY这段配置做了三件事第一把默认模型指定为gpt-5第二声明使用名为openai的模型供应商第三定义该供应商的接口地址和 API Key 对应的环境变量名。这里要注意env_key的值是环境变量的名字不是 Key 本身。Codex 在需要调用模型时会自己从环境变量里读取OPENAI_API_KEY你千万不要把真正的密钥直接写进 TOML。如果你只是本地测试只配置这一层就够了。但如果你的项目用到了多个模型供应商或者在不同项目里要用不同模型这套结构就需要扩展。2.2 自定义模型 Provider 的套路很多第三方模型服务都兼容 OpenAI 的接口协议这意味着你不需要改一行业务代码只需要在config.toml里增加一个 provider 定义。以接入 DeepSeek 为例配置可以这样写[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY然后通过model_provider deepseek来切换。这里的核心在于base_url必须指向兼容 OpenAI 协议的/v1路径。很多人在这一步出错把地址写成了官网首页或者漏掉了/v1结果请求全部失败。另外不同服务在模型命名、上下文长度、速率限制上都可能不一样光配好 provider 还不够还要在具体项目里指定“用这个供应商下的哪个模型”这是下一节要说的内容。我的建议是把常用的几个供应商全部预置在全局config.toml里然后用项目级 TOML 去切换。这样全局文件只做“能力注册”项目文件才做“选型决策”逻辑清晰得多。2.3 影响 Agent 行为的常用配置项除了模型和供应商config.toml里还有一批参数会影响 Agent 的实际表现。挑几个我踩过坑的说。temperature控制随机性默认值通常够用但如果你在写代码生成类任务temperature设得太高容易让 Agent 编造 API建议保持低一点。top_p是另一种采样方式它和temperature二选一调整即可两个一起改会让行为更难预测。max_tokens控制单次响应的最大 token 数这个值设得不够会导致 Agent 话说到一半被截断表现在执行过程里就是“agent execution terminated due to error”。如果你需要 Agent 生成大文件或者长报告务必把max_tokens调大。沙箱相关配置同样值得关注。Codex 的本地 Agent 默认会在沙箱里执行命令你可以通过配置来控制工作区写入权限、网络访问等。这里有一个安全提醒不要把沙箱权限全部放开尤其是运行不可信代码时保持默认限制能避免很多灾难。2.4 TOML 语法雷区TOML 虽然简单但有几个雷区会直接导致解析失败。第一个是键名里的点号。写的model_providers.deepseek会被解析成二级表这没问题但如果你的供应商名字里带了点号比如model_providers.some.provider就必须用引号包起来否则 TOML 会把点号当成结构分隔符。第二个是字符串引号。base_url https://...里的双引号必须收尾匹配少一个引号整段配置报废。TOML 支持单引号和双引号单引号不会做转义适合写纯文本双引号支持转义适合写路径和 URL。第三个是注释。TOML 用井号开头注释但注意注释只能独占一行或跟在键值后面不能嵌套在键内部。很多人习惯在值的中间加注释比如model gpt-5 # 主模型这是允许的但不要写成model gpt-5 # 主模型那会变成值的一部分。每次改完config.toml我建议先用codex跑一次最简单的对话确认语法没问题再开始复杂任务。一条报错信息远比事后猜测省时间。3. AGENTS.md 规则文件让 Agent 按你的规矩干活3.1 AGENTS.md 的本质不是 README看到AGENTS.md这个名字很多人会下意识把它当成“项目的说明文档”。这是一个常见的误解。README 是给人看的告诉你这个项目是什么、怎么用AGENTS.md是给代码模型看的告诉它在修改代码、执行命令、生成文件时应该遵循什么工作模式。换句话讲AGENTS.md是 Agent 的“入职手册”。Codex 会在任务开始时自动读取相关规则把它和用户当前的对话、项目代码结构一起作为模型推理的上下文。所以你在里面写的每一句话都可能直接影响 Agent 的决策。举个实际例子。我维护的一个 Python 服务项目里AGENTS.md开头写了这么几条# 项目规则 - 本仓库使用 Poetry 管理依赖不要在 requirements.txt 中添加依赖。 - 所有新增函数必须带类型注解和 docstring。 - 运行测试请使用 poetry run pytest不要直接调用 pytest。 - 修改 models 模块前先阅读 docs/data-model.md。就这么几行Agent 的行为立刻变得守规矩不会随手生成requirements.txt不会跳过测试也不会在改数据库模型时乱撞。如果不写Agent 很可能会按自己训练数据里的通用习惯去操作结果就是风格跑偏。3.2 全局级与项目级指令怎么组织AGENTS.md同样有全局和项目之分。全局的~/.codex/AGENTS.md适合放“无论哪个项目都适用”的规则比如代码风格偏好、提交信息格式、禁用某些危险操作等。项目根目录的AGENTS.md适合放“只有这个仓库才适用”的特定信息比如技术栈、目录结构、构建命令、特殊约定等。这里有一个非常重要的经验全局指令要短项目指令要具体。全局文件如果写得太长每次对话都要塞进上下文既浪费 token 又干扰判断。我见过有人把几千字的规范塞进全局AGENTS.md结果 Agent 在每个简单任务里都在“回忆”这些规范反而忽略了用户的核心意图。项目级文件正好相反它不需要担心“通用性”可以放心地把仓库细节写进去。比如后端项目可以写“所有数据库迁移使用 Alembic”前端项目可以写“组件样式统一使用 Tailwind”。Agent 拿到这些信息之后生成的代码会更贴合项目实际。另外你可以在项目仓库里增加子目录级别的规则覆盖。比如src/api/AGENTS.md专门约束 API 层的开发规范tests/AGENTS.md约束测试写法。这样不同模块的 Agent 行为可以独立演进。3.3 高效编写 AGENTS.md 的五个原则第一用祈使句不要用描述句。写“运行测试使用poetry run pytest”比写“测试命令可能会用到 poetry”有效得多。Agent 不会猜你的意思它只按最明确的指令执行。第二明确边界。与其写“不要乱改代码”不如写“不要修改src/legacy/下的任何文件”。负面清单配合正面清单效果最好。第三给出示例。规则里写“所有接口错误必须返回统一格式”不如顺手贴一段统一的 JSON 结构。模型对示例的模仿能力远超对抽象描述的遵循能力。第四控制篇幅。一个AGENTS.md文件如果超过几百行Agent 的注意力会被稀释。优先级最高的规则放最前面越往后权重越低。第五把AGENTS.md当成代码维护。放进 Git 仓库跟着代码一起评审一起变更。规则过期比没有规则更可怕因为它会让 Agent 以错误的方式执行任务。4. 优先级实战模型、参数和指令到底听谁的4.1 优先级总览配置系统的核心问题永远是多个来源同时定义了同一个东西到底听谁的根据我的实测Codex 的优先级大致可以概括为命令行参数 项目级 TOML 全局 TOML 项目级 AGENTS.md 全局 AGENTS.md。但这里必须强调这不是一条铁律不同配置项的优先级可能有差异尤其是环境变量介入点很多。我用一张表总结最常见的覆盖关系配置项最高优先来源次高优先来源兜底来源模型选择命令行-m参数项目级 TOMLmodel全局 TOMLmodel模型供应商命令行--provider参数项目级 TOMLmodel_provider全局 TOMLAPI Key当前 Shell 环境变量provider 的 env_key全局密钥文件行为指令子目录 AGENTS.md项目根 AGENTS.md全局 AGENTS.md这张表的价值在于帮你在排查问题时快速定位先判断“这个值从哪来”再看“有没有更高优先级的地方覆盖了它”。4.2 实测一个多模型混合配置假设我手上有一个公司项目和一个个人项目。公司项目必须用官方模型个人项目想接 DeepSeek 来省成本。如果只靠全局config.toml就只能在每次切换时改文件非常痛苦。正确做法是全局config.toml里注册好两个 provider但默认模型保持官方模型在公司项目根目录放一个.codex/config.toml里面只写model gpt-5 model_provider openai在个人项目根目录放另一个.codex/config.tomlmodel deepseek-chat model_provider deepseek这样无论你什么时候进入对应目录Codex 都会自动加载项目级配置不需要手动改任何全局设置。命令行参数仍然拥有最高优先级临时要用别的模型直接在命令里加参数覆盖即可。这种“全局注册、项目选型、命令临时覆盖”的三层模型是我目前用过最舒服的结构。4.3 环境变量与密钥的优先级模型配置里密钥问题最容易让人栽跟头。Codex 会从多个位置读取认证信息但最终生效的只有一条链。首先要看 provider 定义里的env_key如果这个变量在当前环境里存在Codex 就会用它如果不存在Codex 会尝试默认的OPENAI_API_KEY或登录后的本地凭据。这就导致一个很隐蔽的问题你明明在两个 provider 里分别绑定了OPENAI_API_KEY和DEEPSEEK_API_KEY但 Shell 里两个变量都设置了Codex 可能会优先读取某个默认变量导致你以为在用自己的模型实际却调用了另一个端点。我的建议是不要同时在同一终端里导出两个 API Key除非你明确知道自己在做什么。更好的方式是按项目写.env文件配合 direnv 之类的工具在进入目录时自动加载对应变量。不同项目之间的环境彻底隔离比任何配置文件优先级都可靠。4.4 指令冲突时怎么仲裁AGENTS.md里的指令冲突更微妙。全局文件写“代码必须用 tabs 缩进”项目文件写“代码必须用 4 个空格缩进”这时候听谁的答案是听项目的。因为 Codex 在合并规则时后读取的具体层级规则会覆盖前面层级的同一条规则。但如果全局文件写“所有日志必须输出到 stdout”项目文件写“所有日志必须输出到文件”这两条规则并不直接冲突Agent 可能会两条都遵循结果出现日志双重输出。这种情况不能靠优先级解决只能靠你自己检查规则是否有交叉。我习惯在AGENTS.md里写一条总则如果本文件与全局规则冲突以本文件为准。虽然听起来像绕口令但对模型来说是很有用的消歧指令。5. 常见问题与排查技巧实录5.1 配置改了没生效第一步不是看配置每次有人问我“为什么改了config.toml没用”我的第一个建议都是先确认你当前所在目录有没有项目级配置在干扰。很多人改的是全局文件但项目目录里残留着一个旧的项目级config.toml它把你的新配置覆盖得干干净净。排查方法也很简单在项目根目录执行一次带调试信息的运行命令观察日志里实际加载的配置文件路径。如果 Codex 输出了~/.codex/config.toml之外的文件路径那多半就是项目级配置在起作用。另外改了配置后建议开一个新会话验证。老会话的历史上下文还存着旧的模型名和旧指令你很难判断到底是配置没生效还是历史消息把行为带偏了。5.2 auth token is unavailable 的常见解法这应该是 Codex 里出现频率最高的报错之一。看到 “codex auth token is unavailable”先不要慌按这个顺序排查。第一步检查是否设置了 provider 绑定的环境变量。比如model_provider openai那就确认OPENAI_API_KEY是否已导出。第二步检查变量名是否拼写正确。我见过有人把OPENAI_API_KEY写成了OPEN_AI_API_KEY就差一个下划线结果认证失败。第三步确认当前 Shell 环境是否真的继承了变量。有些终端工具不会自动同步.zshrc或.bashrc开新终端前记得source一下。如果用的是 Codex 自带的登录态可以重新执行一次认证流程。认证信息过期是常态尤其是本地 Agent 跑了一整天之后重新认证往往比修改配置更直接。5.3 agent execution terminated due to error 的定位思路这个报错看起来像 Agent 执行被终止但背后的原因五花八门。最常见的是沙箱里执行的命令非零退出比如 Agent 试图运行一个不存在的命令或者在权限不足的目录里写文件。其次是输出长度超限模型生成内容太多触发最大 token 限制执行被掐断。我的定位习惯是先缩小范围。让 Agent 只做一件事比如“只读取文件不要改任何东西”。如果这样还会报错基本可以排除业务逻辑问题往下先查环境变量和权限。如果只做一件事没问题那就说明是多个步骤组合时出错大概率与上下文长度或规则冲突有关。把任务拆分是规避这个报错最有效的方法。让 Agent 每完成一小步就检查一次而不是憋一个大动作。加上max_tokens调大一些能给模型更多缓冲空间。5.4 模型端点连接失败先检查 base_url很多人在配置自定义模型时把base_url写错了导致 Codex 在访问模型端点时报错。这类报错往往带有 endpoint 字样比如codex endpoint /responses相关错误。处理思路很固定先确认 base_url 是否是完整的 OpenAI 兼容地址再看末尾是否带/v1最后确认服务本身是否可用。还有一个隐蔽问题你的config.toml里可能同时存在多个 provider而当前model_provider指向的那个 provider其base_url已经过期或者写错。Codex 会忠实地照着base_url去请求哪怕它和一个已经能用的 provider 长得几乎一样。我见过有人把openai和deepseek的地址从中间某个位置开始就抄错了结果排查了半天。5.5 问题排查速查表症状可能原因检查点配置改了没生效项目级配置覆盖全局配置检查项目目录下.codex/config.toml和AGENTS.mdauth token is unavailable环境变量未设置或拼写错误env | grep API_KEY确认变量名agent execution terminated due to error命令非零退出、输出超长、权限不足拆分任务、调大max_tokens、检查沙箱权限端点请求失败 / /responses 报错base_url写错或多 provider 叠加核对地址、确认/v1后缀、一次只保留一个 provider模型行为漂移 / 时灵时不灵旧会话历史残留旧指令开新会话、重读AGENTS.md这张表不是标准文档而是我踩坑后提炼出的检查顺序。每次遇到问题照着走一遍大部分都能在十分钟内定位。最后再分享一个小技巧这套配置系统最反直觉的地方在于它更像一个分层路由系统而不是一个全局状态仓库。你会越来越清楚每一个配置项都有它最适合出现的层级。我的习惯是全局config.toml只放稳定的公共能力项目config.toml只放选型决策AGENTS.md只放规则约束而一次性的临时需求全部交给命令行参数。按这个思路把AGENTS.md纳入 Git 版本管理每次修改都跟着代码评审走长期下来收益非常明显。配置这件事前期多花一点时间想清楚优先级后面能省下无数个“为什么又变了”的下午。