1. 从一次配置翻车说起为什么本地 Agent 值得折腾前阵子帮朋友调一个本地代码助手他上来就问我“为什么我改了模型配置重启之后又变回去了”我让他把目录结构发过来一看问题一目了然——他在项目根目录放了一份配置又在用户目录放了一份两份内容冲突而他又没搞清楚哪份优先级更高。这种场景我见过太多次了几乎每个刚接触 Codex 本地自定义 Agent 的人都会踩一遍。Codex 这套东西的核心价值说白了就是让你把 AI 能力“焊”进自己的开发流程里而不是每次打开网页复制粘贴。它支持本地自定义 Agent意味着你可以定义自己的角色、行为边界、调用哪些模型、走什么参数。而承载这些定义的文件主要就是两类TOML 配置文件和AGENTS.md 行为描述文件。前者管“用什么模型、走什么参数”后者管“这个 Agent 是谁、该怎么干活”。这篇文章适合三类人看一是刚装完 Codex、想搞清楚配置文件到底放哪的新手二是已经能跑起来、但被优先级和覆盖规则搞晕的进阶用户三是想基于 Codex 搭一套团队内部 Agent 规范的开发者。我会把 TOML 的结构、AGENTS.md 的写法、两者的优先级关系以及我实际踩过的坑全部摊开讲清楚。你照着做基本能少走两三个晚上的弯路。2. Codex 本地 Agent 的整体设计与配置思路2.1 为什么要用 TOML 而不是 JSON 或 YAML很多人第一反应是配置嘛JSON 不香吗YAML 不也挺流行我一开始也这么想直到我在一个项目里写了三百多行嵌套 JSON改一个缩进错一位整个文件直接报错排查了半小时。TOML 的好处在于它对人类友好——支持注释、层级清晰、不需要靠缩进表达结构写错了也容易定位。Codex 选 TOML 作为主配置格式我认为核心考量有三点。第一可读性优先。Agent 配置往往需要频繁调整模型名、温度值、超时时间这些参数TOML 的key value形式一眼就能看懂。第二注释友好。你可以在配置里直接写# 这个模型用于代码补全别乱改团队协作时非常实用。第三解析稳定。TOML 的类型系统比 YAML 严格不会出现yes被解析成布尔值这种坑。实际配置时一个典型的 TOML 文件大概长这样# 全局默认模型配置 [model] provider openai name gpt-4o temperature 0.2 max_tokens 4096 # 代码补全专用配置 [model.completion] name gpt-4o-mini temperature 0.0 max_tokens 1024 # Agent 行为配置 [agent] name code-reviewer instructions_file AGENTS.md timeout 120这里有个细节值得说temperature在代码场景下我一般设 0.0 到 0.3 之间。为什么因为代码生成需要确定性温度太高模型会“发挥创意”给你写出能跑但不符合项目规范的代码。而max_tokens要根据你的实际任务设补全场景 1024 够用整文件重构就得拉到 4096 甚至更高。2.2 AGENTS.md 到底解决什么问题TOML 管的是“机器参数”AGENTS.md 管的是“人的意图”。这两者分工明确但很多人会混淆。我见过有人在 TOML 里写一大段自然语言描述 Agent 性格结果模型根本不认——因为 TOML 是结构化配置不是给模型读的提示词。AGENTS.md 的本质是一份行为契约。它用 Markdown 格式描述这个 Agent 的角色、职责边界、输出规范、禁止事项。Codex 在启动 Agent 时会把这份文件的内容作为系统提示的一部分注入。所以它写得好不好直接决定 Agent 干活靠不靠谱。一份合格的 AGENTS.md 通常包含这几个部分角色定义这个 Agent 是谁负责什么工作流程接到任务后按什么步骤执行输出规范代码风格、注释要求、提交信息格式禁止事项哪些操作绝对不能做上下文说明项目背景、技术栈、依赖关系我自己的习惯是AGENTS.md 控制在 200 到 500 行之间。太短了模型抓不住重点太长了会挤占上下文窗口反而影响实际任务的处理质量。这个度需要根据项目复杂度调。2.3 优先级设计的底层逻辑配置文件散落在不同位置到底谁说了算这是最容易翻车的地方。Codex 的优先级设计遵循一个原则越靠近当前工作目录的配置优先级越高。这跟 Git 的.gitignore层级、ESLint 的配置继承是一个思路。具体来说优先级从高到低大致是项目根目录下的.codex/config.toml项目根目录下的AGENTS.md用户主目录下的~/.codex/config.toml系统级默认配置为什么这么设计因为项目级配置应该能覆盖个人偏好。比如你个人习惯用某个模型但当前项目要求统一用另一个模型项目配置就该赢。反过来如果项目没特殊要求就回落到你的个人配置。这个逻辑听起来简单但实际用起来很多人会忘记自己什么时候在用户目录改过东西导致“明明项目里配了却不生效”。提示每次改完配置建议用codex config show之类的命令确认最终生效的是哪份配置别靠猜。3. TOML 配置核心细节与实操要点3.1 模型配置的字段拆解与参数选择TOML 里最核心的就是模型配置块。我把常用字段和我的推荐值整理成一张表方便你对照字段作用推荐值说明provider模型提供方openai / 兼容接口决定走哪套 APIname模型名称gpt-4o / 自定义必须与提供方一致temperature随机性0.0-0.3代码场景宜低max_tokens最大输出1024-8192按任务复杂度调timeout超时秒数60-180网络差就调高top_p采样范围0.9-1.0一般不用改这里重点说temperature和max_tokens的取舍。温度值我实测下来代码补全用 0.0 最稳代码审查用 0.2 能发现更多边界问题而写文档注释可以放到 0.5。max_tokens不是越大越好设太大模型可能生成冗余内容设太小又会截断。我的经验是单函数补全 512多函数重构 2048整文件生成 4096。还有一个容易忽略的字段是timeout。默认值往往偏短遇到复杂任务模型思考时间长直接超时失败。我一般设 120 秒起步网络环境差就拉到 180。这个值调高不会影响正常速度只在慢的时候兜底。3.2 多模型配置与场景切换实际项目里一个 Agent 往往需要多个模型配合。比如补全用轻量模型省钱复杂推理用大模型保质量。TOML 支持通过子表定义多个模型配置[model] provider openai name gpt-4o temperature 0.2 [model.fast] name gpt-4o-mini temperature 0.0 max_tokens 1024 [model.reasoning] name o1-preview temperature 1.0 max_tokens 8192然后在 AGENTS.md 里说明什么场景用哪个。这里有个坑子表的provider会继承父表如果你要换提供方必须在子表里显式写一遍。我一开始没注意结果fast配置一直走的是父表的 provider排查了半天。场景切换的另一个技巧是用环境变量覆盖。Codex 支持读取CODEX_MODEL这类环境变量优先级高于 TOML。这在 CI 环境里特别有用——本地开发用大模型流水线里用便宜模型不用改配置文件。3.3 配置文件的组织与版本管理配置文件该不该进 Git我的答案是项目级配置进个人级配置不进。项目根目录的.codex/config.toml和AGENTS.md应该提交到仓库这样团队每个人拉下来就是统一行为。而~/.codex/config.toml里往往有你的个人偏好甚至密钥绝对不能提交。密钥管理是另一个重点。TOML 里不要直接写 API Key用环境变量引用[model] provider openai api_key_env OPENAI_API_KEY这样配置文件可以安全地进版本库密钥通过环境变量注入。我在团队里推这套做法之后再也没出现过密钥泄露到仓库的事故。注意如果你在 TOML 里直接写了密钥记得加到.gitignore并且用git log检查历史提交里有没有残留。4. AGENTS.md 编写实战与行为控制4.1 角色定义怎么写才有效AGENTS.md 的开头通常是角色定义。很多人写成“你是一个 helpful assistant”这种写法基本没用因为太泛了。有效的角色定义要具体到职责、领域、风格。我常用的模板是这样的# Agent: 代码审查助手 ## 角色 你是一名资深后端工程师专注于 Python 和 Go 项目的代码审查。 你的职责是发现逻辑错误、性能隐患、安全漏洞而不是重写代码。 ## 工作流程 1. 先通读变更文件理解改动意图 2. 逐文件检查标注问题行号 3. 按严重程度排序输出阻断 / 警告 / 建议 4. 对每个问题给出修复方向但不直接改代码 ## 输出规范 - 使用中文 - 每个问题格式[级别] 文件:行号 - 问题描述 - 阻断级问题必须说明后果这个模板的关键在于边界清晰。“不直接改代码”这一条很重要否则模型会越权把审查变成重写反而引入新问题。4.2 输出规范与格式约束输出规范是 AGENTS.md 里最实用的部分。你希望 Agent 输出什么格式就在这里写死。比如要求 JSON 输出、要求特定 Markdown 结构、要求代码块标注语言都可以在这里约束。我踩过的一个坑是没写输出语言结果模型中英文混着来看着很难受。后来我在所有 AGENTS.md 里都加了一条“所有输出使用中文代码和专有名词除外”。这一条看似简单效果立竿见影。另一个技巧是用示例代替描述。与其写“输出要简洁”不如直接给一个期望输出的例子。模型对示例的遵循度远高于抽象描述。我通常会在 AGENTS.md 里放两三个输入输出示例模型照着模仿格式稳定性提升明显。4.3 禁止事项与安全边界禁止事项这块很多人不重视直到出事才后悔。我建议至少写清楚这几类文件操作边界能不能删文件、能不能改配置、能不能执行命令网络访问边界能不能调用外部接口、能不能上传代码数据边界能不能读取敏感目录、能不能输出密钥行为边界能不能自动提交、能不能自动部署比如我会写## 禁止事项 - 禁止执行任何删除操作包括 rm、git reset --hard - 禁止读取 .env、credentials 等敏感文件 - 禁止在输出中回显任何 API Key 或密码 - 禁止自动 git commit 或 git push这些约束不是万能的模型偶尔还是会越界但有了明确规则出问题时至少能追溯是配置没写还是模型没遵守。5. 优先级冲突排查与常见问题实录5.1 配置不生效的排查路径“我改了配置怎么没生效”是最高频的问题。我的排查顺序是这样的确认文件位置codex config path看它实际读的是哪个文件确认优先级项目级是否覆盖了用户级确认语法TOML 有没有解析错误用codex config validate确认缓存有些版本会缓存配置重启或清缓存确认环境变量环境变量优先级最高检查有没有被覆盖这五步走下来九成问题能定位。我遇到过一次特别隐蔽的项目里有个.codex/config.toml但它是空的结果它把用户级配置整个覆盖了导致所有个人设置失效。空文件也是文件也会参与优先级计算这个坑值得记住。5.2 常见问题速查表现象可能原因解决方法模型配置不生效项目级覆盖用户级检查项目根目录配置AGENTS.md 没被读取路径写错或文件名大小写确认instructions_file指向输出格式混乱规范描述太抽象改用示例约束频繁超时timeout 太短调到 120-180 秒密钥报错环境变量未注入检查 shell 配置多模型切换失败子表未写 provider子表显式声明 provider5.3 我踩过的三个真实坑第一个坑是配置合并的直觉错误。我以为项目配置和用户配置会“合并”结果实际是“覆盖”。项目里只写了模型名没写温度我以为会继承用户的温度设置结果用了默认值。后来才明白同层级是覆盖不是合并要合并得显式写全。第二个坑是AGENTS.md 的编码问题。有次在 Windows 上编辑保存成了 GBK 编码Codex 读取时中文全乱码Agent 行为完全跑偏。后来统一用 UTF-8 保存问题消失。这个坑在跨平台协作时特别容易遇到。第三个坑是优先级和符号链接。我在用户目录用软链接指向项目配置以为能统一管理结果 Codex 解析时按真实路径算优先级导致行为不符合预期。软链接在配置管理里要慎用容易让优先级判断变得反直觉。6. 团队协作场景下的配置规范6.1 统一配置与个人偏好的平衡团队里每个人习惯不同有人喜欢低温严谨有人喜欢高温发散。统一配置不能一刀切我的做法是项目级定底线个人级调偏好。项目级配置规定必须遵守的部分比如模型提供方、安全边界、输出语言个人级配置调温度、超时这些不影响协作的参数。具体实现上项目级 TOML 只写强制项个人级写可选项。因为项目级优先级高它没写的字段会回落到个人级正好实现“底线统一、偏好自由”。6.2 配置变更的评审流程配置文件也是代码改动应该走评审。我们团队的做法是.codex/目录的改动必须有人 review尤其是 AGENTS.md 的修改。因为 AGENTS.md 直接影响 Agent 行为改错一行可能导致整个团队的 Agent 输出异常。评审时重点看三样安全边界有没有放松、输出规范有没有破坏、模型参数改动有没有理由。我见过有人为了“让 Agent 更聪明”把温度调到 1.0结果代码质量直线下降这种改动就该在评审时拦下来。6.3 新人上手的配置清单新人入职我一般给一份配置检查清单确认~/.codex/config.toml存在且密钥通过环境变量注入确认项目根目录有.codex/config.toml和AGENTS.md运行codex config validate确认无语法错误跑一个测试任务确认 Agent 行为符合预期检查.gitignore有没有排除个人配置这份清单走一遍基本能避免新人常见的配置问题。我带的几个新人按这个流程走第一天就能正常用起来不用我反复救火。7. 模型接入与扩展配置的进阶玩法7.1 接入第三方兼容接口Codex 支持接入兼容 OpenAI 接口规范的第三方服务。配置上主要是改provider和base_url[model] provider openai-compatible base_url https://your-endpoint/v1 name your-model api_key_env CUSTOM_API_KEY temperature 0.2这里的关键是base_url要指向兼容接口的/v1路径name要填服务方文档里给的模型标识。我试过几个不同的兼容服务大部分能直接跑少数需要在 AGENTS.md 里调整提示词风格因为不同模型对指令的遵循度不一样。7.2 多 Agent 协作的配置拆分复杂项目里一个 Agent 不够用往往需要多个角色配合。比如一个负责写代码一个负责审查一个负责写文档。这时候配置可以按角色拆分.codex/ config.toml # 全局配置 agents/ coder.toml # 编码 Agent 配置 reviewer.toml # 审查 Agent 配置 writer.toml # 文档 Agent 配置 AGENTS.md # 默认行为 agents/ coder.md reviewer.md writer.md每个 Agent 有自己的 TOML 和 MD通过命令行参数或环境变量切换。这种拆分方式让职责清晰调优时互不干扰。我做过一个项目三个 Agent 各司其职整体效率比单 Agent 高不少。7.3 配置的版本演进与兼容Codex 版本更新时配置格式偶尔会变。我的经验是升级前先备份配置升级后跑验证。有次升级后某个字段名变了旧配置直接报错幸好备份了能快速回滚。另外团队里最好锁定一个 Codex 版本避免有人升级有人没升级导致行为不一致。我们在package.json或类似的地方固定版本号升级走统一流程。8. 性能调优与资源控制8.1 上下文窗口的合理利用AGENTS.md 和项目上下文都会占用 token。如果 AGENTS.md 写得太长留给实际任务的上下文就少了。我的做法是核心规则前置细节后置并且定期精简。一般控制在 300 行以内超过就考虑拆分或删减。还有一个技巧是用include机制把不常用的规则放到单独文件按需引入。这样默认上下文精简需要时再加载。8.2 超时与重试策略超时和重试要配合设置。超时太短会频繁失败太长会卡住流程。我的配置是超时 120 秒重试 2 次重试间隔 5 秒。这样偶发的网络抖动能自动恢复真出问题也不会无限等待。重试要注意幂等性。如果 Agent 执行的是写操作重试可能导致重复写入。所以我在 AGENTS.md 里明确要求写操作前先检查状态避免重试造成副作用。8.3 资源占用的监控本地跑 Agent 会占 CPU 和内存尤其是大模型推理。我一般用系统自带的监控工具看资源占用发现异常就调max_tokens或换轻量模型。长期高占用说明配置有问题该优化了。9. 我个人的几条实操心得配置这东西文档看十遍不如自己踩一遍坑。我折腾 Codex 本地 Agent 这段时间最大的体会是优先级规则一定要亲手验证别靠记忆。我因为记错优先级浪费过整整一个下午。第二个心得是AGENTS.md 要当代码一样维护。它有版本、有评审、有测试。我现在的习惯是每次改完 AGENTS.md跑一组固定任务看输出有没有变化确认符合预期再提交。第三个心得是配置越简单越好。一开始我什么都想配结果文件臃肿排查困难。后来精简到只留必要的反而稳定。配置的复杂度应该匹配项目的复杂度别过度设计。最后一个技巧把常用的配置片段存成模板新项目直接复制改。我维护了一套自己的模板涵盖编码、审查、文档三种场景新项目五分钟就能配好省下大量重复劳动。这套模板我用了大半年迭代了十几版现在基本能覆盖八成场景。