1. 为什么我要折腾 Codex 的本地 Agent 配置Codex 这个工具刚上手的时候大多数人都是直接跑默认配置能对话、能补全、能改代码感觉已经够用了。但用久了就会发现一个问题默认行为太“通用”了。它不知道你项目的技术栈偏好不知道你团队的代码规范更不知道你希望它在什么场景下用哪个模型。每次开新会话都要重复交代一遍背景效率极低。我最初也是这么用的直到有一次在一个大型重构项目里Codex 反复给我生成不符合项目约定的代码风格改来改去浪费了大量时间。那时候我才意识到Codex 的本地自定义 Agent 与模型配置不是可选项而是必选项。它决定了你是在“用一个通用工具”还是在“用一个懂你项目的专属助手”。这篇文章要聊的核心就是围绕TOML 配置文件、AGENTS.md 文件以及配置优先级这三块内容把 Codex 本地 Agent 的自定义能力彻底讲透。适合已经装好 Codex、能正常跑起来、但还没深入配置过的朋友。如果你还在纠结安装问题那这篇内容可以先收藏等环境跑通了再回来对照操作。我自己的环境是 macOS 加 Windows 双平台都在用配置文件结构基本一致差异主要在路径上。下面所有操作和示例两个平台我都会标注清楚。2. Codex 本地 Agent 的整体配置架构2.1 配置文件到底放在哪里Codex 的本地配置核心是一个 TOML 格式的文件。TOML 这种格式这几年在开发者工具里越来越常见它的好处是可读性强、层级清晰、手写不容易出错。相比 JSON 没有那些烦人的引号和逗号问题相比 YAML 又不会因为缩进问题让人抓狂。默认情况下Codex 会在用户主目录下的配置文件夹里寻找这个文件。具体路径macOS / Linux~/.codex/config.tomlWindowsC:\Users\你的用户名\.codex\config.toml如果你不确定自己的配置目录在哪可以在终端里跑codex config path之类的命令来确认不同版本命令可能略有差异以你本地codex --help的输出为准。除了全局配置Codex 还支持项目级配置。也就是说你可以在项目根目录放一个.codex/config.toml这个文件里的配置只对当前项目生效。这个设计非常关键后面讲优先级的时候会详细展开。2.2 TOML 配置文件的整体结构一个完整的 Codex TOML 配置文件大致分为几个区块# 全局基础设置 model gpt-4o provider openai # 模型提供商配置 [model_providers.openai] base_url https://api.openai.com/v1 env_key OPENAI_API_KEY # Agent 行为配置 [agent] max_tokens 4096 temperature 0.7 # 项目级覆盖 [projects./path/to/your/project] model o1-preview这个结构看起来简单但每一块都有讲究。model和provider决定了默认用哪个模型、走哪个接口。model_providers区块定义了你可以切换的多个模型来源。agent区块控制 Agent 的行为参数。projects区块则允许你针对特定项目做覆盖。我建议刚开始配置的时候不要一次性把所有选项都写进去。先写最核心的model和provider跑通了再逐步加。配置这东西改一处测一处出问题了也好定位。2.3 AGENTS.md 是什么为什么它比 TOML 更重要如果说 TOML 是 Codex 的“硬件配置”那 AGENTS.md 就是它的“大脑说明书”。AGENTS.md 是一个放在项目根目录的 Markdown 文件Codex 在启动时会自动读取它把它作为系统提示词的一部分注入到对话上下文中。这意味着你可以在里面写任何你希望 Codex 知道的背景信息项目用什么语言、什么框架代码风格约定比如缩进用几个空格、命名用驼峰还是下划线哪些目录不要动常用的构建、测试命令团队特有的业务逻辑说明我实测下来AGENTS.md 对输出质量的影响比换模型还大。同一个模型有 AGENTS.md 和没有生成的代码质量差距非常明显。原因很简单模型再强它也不知道你项目的私有约定你不告诉它它只能猜。2.4 三层配置的优先级关系Codex 的配置优先级从高到低大致是这样的优先级配置来源作用范围典型用途1最高命令行参数当前会话临时切换模型、调试2项目级 TOML当前项目项目专属模型和参数3项目级 AGENTS.md当前项目项目背景和规范4全局 TOML所有项目默认模型和通用设置5最低内置默认值所有项目兜底这个优先级表是我踩了好几次坑之后总结出来的。最开始我以为 AGENTS.md 的优先级最高结果发现命令行参数能直接覆盖它。后来又发现项目级 TOML 会覆盖全局 TOML但不会覆盖命令行。理解这个层级关系是做好配置管理的前提。注意不同版本的 Codex 在优先级细节上可能有微调建议以你本地版本的官方文档为准。但“越具体越优先”这个原则是通用的。3. TOML 配置文件的核心参数详解3.1 模型选择与提供商配置模型配置是 TOML 文件里最核心的部分。Codex 支持多种模型提供商你可以通过model_providers区块定义多个来源然后在model字段里指定当前用哪个。model gpt-4o model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api chat [model_providers.local] name Local Model base_url http://localhost:11434/v1 env_key LOCAL_API_KEY wire_api chat这里有几个关键点需要解释base_url是接口地址。如果你用的是官方服务填官方地址如果你用的是兼容接口的第三方服务填对应的地址。这里要注意地址末尾的/v1不能少少了会报 404。env_key是环境变量的名字不是密钥本身。Codex 会去读这个环境变量来获取密钥。这样做的好处是密钥不会明文写在配置文件里安全性更高。我见过有人直接把密钥写在 TOML 里然后不小心把配置文件提交到了 Git 仓库后果很严重。wire_api指定通信协议常见的是chat。如果你用的是某些特殊接口可能需要改成responses或其他值。这个参数填错了会直接导致请求失败。3.2 Agent 行为参数的调优[agent]区块控制 Agent 的运行时行为几个关键参数[agent] max_tokens 8192 temperature 0.3 top_p 0.95 approval_policy on-request sandbox_mode workspace-writemax_tokens控制单次响应的最大长度。这个值设太小长代码生成会被截断设太大又可能浪费额度。我的经验是日常编码 4096 够用做大型重构或者生成完整文件时调到 8192 甚至更高。temperature控制输出的随机性。写代码场景建议设低一点0.2 到 0.4 之间比较合适这样生成的代码更稳定、更可预测。如果你用它来做创意类任务可以调到 0.7 以上。approval_policy决定 Codex 执行操作前是否需要你确认。可选值通常有always、on-request、never。我强烈建议新手用on-request这样它执行敏感操作前会问你一下避免误操作。sandbox_mode控制文件系统的访问权限。workspace-write表示只能写工作目录read-only表示只读danger-full-access表示完全放开。除非你非常清楚自己在做什么否则不要用最后一个。3.3 项目级配置的覆盖写法项目级 TOML 的写法和全局基本一致但只需要写你想覆盖的部分。比如全局用的是gpt-4o但某个项目你想用o1-preview# 项目根目录下的 .codex/config.toml model o1-preview [agent] temperature 0.2这样配置之后在这个项目里启动 Codex它会自动用o1-preview和更低的温度而其他项目不受影响。我自己的做法是全局配置放通用设置项目级配置只放差异项。这样维护起来最清晰不会出现“改了全局结果所有项目都受影响”的情况。3.4 配置文件的验证与调试改完配置文件后不要急着直接用。先跑一下验证命令确认语法没问题codex config validate如果命令不存在可以尝试启动 Codex 看它是否报错。TOML 语法错误通常会在启动时直接提示比如“unexpected token”或者“missing field”。调试配置的时候我常用的一个技巧是临时用命令行参数覆盖配置看看行为是否符合预期。比如codex --model gpt-4o-mini --temperature 0.1如果命令行参数生效了说明配置本身没问题可能是优先级或者文件路径的问题。如果命令行参数也不生效那就要检查 Codex 版本是否支持这些参数。4. AGENTS.md 的编写艺术与实战技巧4.1 AGENTS.md 的基本结构AGENTS.md 没有强制的格式要求它就是一个普通的 Markdown 文件。但根据我的经验结构清晰的 AGENTS.md 效果明显更好。因为模型读取它的时候清晰的结构能帮助它更快定位到关键信息。我推荐的结构是这样的# 项目背景 这是一个基于 React TypeScript 的前端项目使用 Vite 构建。 # 代码规范 - 缩进使用 2 个空格 - 组件文件名使用 PascalCase - 工具函数文件名使用 camelCase - 所有导出必须显式声明类型 # 目录说明 - src/components通用组件 - src/pages页面组件 - src/utils工具函数 - src/api接口封装 # 常用命令 - 开发npm run dev - 构建npm run build - 测试npm run test # 禁止事项 - 不要修改 src/legacy 目录下的文件 - 不要引入新的第三方依赖除非明确要求这个结构覆盖了模型最需要知道的几类信息项目是什么、规范是什么、目录怎么分、命令怎么跑、什么不能做。4.2 如何写出模型真正“看得懂”的指令写 AGENTS.md 最大的误区是写得太抽象。比如“请遵循良好的代码规范”这种话模型看了等于没看因为它不知道你所谓的“良好”具体指什么。正确的做法是具体、可执行、有例子。对比一下抽象写法具体写法遵循良好的命名规范变量用 camelCase常量用 UPPER_SNAKE_CASE类型用 PascalCase注意代码质量函数不超过 50 行圈复杂度不超过 10必须有错误处理写好注释每个导出函数必须有 JSDoc 注释说明参数和返回值具体写法虽然啰嗦但模型能准确执行。抽象写法看起来简洁但模型只能靠猜结果往往不符合预期。4.3 多项目场景下的 AGENTS.md 管理如果你同时维护多个项目每个项目都有自己的 AGENTS.md管理起来可能会有点乱。我的做法是建立一个基础模板包含通用的代码规范、注释要求、安全注意事项。然后每个项目在这个基础上补充项目特有的内容。比如基础模板里有“所有函数必须有错误处理”项目 A 补充“使用 try-catch 捕获异步错误”项目 B 补充“使用 Result 类型处理错误”。这样既保证了通用规范的一致性又保留了项目的灵活性。另外我建议把 AGENTS.md 纳入版本控制。这样团队成员共享同一份配置新人拉下代码就能获得一致的 Codex 体验。而且 AGENTS.md 的修改历史也能追溯方便回滚。4.4 AGENTS.md 与 TOML 的配合策略AGENTS.md 和 TOML 不是互斥的而是互补的。我的分工原则是TOML 管“怎么跑”模型选择、参数调优、接口配置、权限控制AGENTS.md 管“做什么”项目背景、代码规范、业务逻辑、禁止事项举个例子TOML 里配置temperature 0.2这是告诉 Codex“输出要稳定”AGENTS.md 里写“所有 API 调用必须有超时处理”这是告诉 Codex“具体要做什么”。两者配合好了Codex 的表现会有质的提升。我自己的项目里配置完这两块之后Codex 生成的代码几乎不需要怎么改就能直接用效率提升非常明显。5. 配置优先级实战从冲突到和谐5.1 优先级冲突的典型场景配置优先级这东西不遇到冲突是感受不到的。我遇到过几次典型冲突分享出来给大家避坑。场景一全局设了模型 A项目级设了模型 B命令行又指定了模型 C。结果用的是 C。这个符合预期命令行优先级最高。场景二全局 TOML 设了temperature 0.7项目级 AGENTS.md 里写了“输出要稳定”。结果温度还是 0.7因为 AGENTS.md 不控制参数它只是提示词。这个坑我踩过当时以为写了“稳定”就会自动降温实际上不会。场景三项目级 TOML 设了sandbox_mode read-only但全局设的是workspace-write。结果项目里是只读全局其他项目可写。这个符合“越具体越优先”的原则。5.2 如何设计一套不冲突的配置体系踩了几次坑之后我总结出一套自己的配置管理方法第一层全局 TOML 只放“绝对通用”的设置。比如默认模型、默认提供商、默认的 approval_policy。这些设置在所有项目里都适用不需要改。第二层项目级 TOML 只放“项目特有”的覆盖。比如某个项目需要用不同的模型或者需要更严格的沙箱模式。只写差异项不重复全局配置。第三层AGENTS.md 放“项目背景和规范”。这部分不涉及参数纯粹是给模型提供上下文。第四层命令行参数只用于“临时调试”。不要在日常使用中依赖命令行参数否则配置会变得很乱。按照这个分层我的配置文件一直很干净很少出现冲突。5.3 优先级调试的实用命令当你怀疑配置没生效时可以用这些方法排查# 查看当前生效的配置如果版本支持 codex config show # 查看配置文件的解析结果 codex config validate --verbose # 临时用环境变量覆盖 CODEX_MODELgpt-4o-mini codex如果config show不可用可以尝试在 Codex 启动后问它“你当前用的是什么模型”有时候它能从上下文里推断出来。这个方法不保证准确但可以作为参考。我常用的一个笨办法是故意在配置里写一个错误的值看 Codex 是否报错。如果报错了说明这个配置项被读取了如果没报错说明这个配置项可能被更高优先级的配置覆盖了或者根本没被识别。5.4 团队协作中的配置同步团队里每个人都有自己的本地配置怎么保证大家行为一致我的建议是把项目级 TOML 和 AGENTS.md 都提交到仓库。这两个文件是项目的一部分应该像代码一样被管理。新人拉下代码自动获得一致的配置。全局 TOML 不提交但提供模板。在仓库里放一个config.toml.example说明需要配置哪些项。新人复制一份到自己的配置目录填入自己的密钥即可。定期同步 AGENTS.md 的更新。项目规范变了AGENTS.md 也要跟着变。我建议把 AGENTS.md 的更新纳入代码审查流程确保每次修改都经过确认。6. 常见问题与排查技巧实录6.1 配置不生效的排查思路配置不生效是最常见的问题排查思路可以按这个顺序来第一步确认文件路径对不对。全局配置在~/.codex/config.toml项目配置在项目根目录的.codex/config.toml。路径错了配置自然不会生效。第二步确认文件格式对不对。TOML 对格式敏感少一个引号、多一个逗号都会导致解析失败。用codex config validate验证一下。第三步确认优先级对不对。如果全局和项目级都配了同一个项项目级会覆盖全局。如果你改的是全局但没生效检查一下项目级是不是也配了。第四步确认版本支持不支持。有些配置项是新版本才加的老版本可能不识别。检查一下你的 Codex 版本。6.2 模型切换失败的常见原因模型切换失败通常有这几个原因现象可能原因解决方法报错“model not found”模型名称拼写错误检查模型名称确认提供商支持该模型报错“unauthorized”密钥无效或未设置检查环境变量确认密钥正确报错“connection refused”接口地址错误检查 base_url确认服务可访问切换后行为没变化优先级冲突检查是否有更高优先级的配置覆盖我遇到最多的是密钥问题。有时候环境变量设了但终端会话没刷新导致 Codex 读不到。解决方法是重启终端或者用export重新设置。6.3 AGENTS.md 被忽略的情况AGENTS.md 被忽略通常是这几个原因文件位置不对。AGENTS.md 必须放在项目根目录放在子目录里 Codex 读不到。文件名大小写不对。有些系统对文件名大小写敏感agents.md和AGENTS.md可能被当成两个文件。建议统一用大写。文件内容格式有问题。虽然 Markdown 格式很宽松但如果文件里有特殊字符或者编码问题可能导致读取失败。建议用 UTF-8 编码保存。项目根目录识别错误。如果你在子目录里启动 Codex它可能找不到项目根目录的 AGENTS.md。解决方法是在项目根目录启动或者用--project-root参数指定。6.4 性能与并发相关的注意事项Codex 在高并发场景下可能会遇到性能问题。我实测下来几个关键点控制并发请求数。同时发起太多请求可能会触发限流。建议根据你的服务额度合理控制并发。合理设置超时时间。超时太短长任务会被中断超时太长失败请求会占用资源。我的经验是设 60 到 120 秒比较合适。注意上下文长度。AGENTS.md 内容太长会占用上下文窗口导致实际可用的对话空间变小。建议 AGENTS.md 控制在 2000 字以内只放最关键的信息。监控额度消耗。高频率使用会快速消耗额度建议定期检查使用情况避免超额。6.5 我的独家避坑清单最后分享几个我踩过的坑都是文档里不会写的坑一配置文件里的注释。TOML 支持注释但有些版本的 Codex 在解析时会把注释也读进去导致奇怪的问题。建议配置稳定后把注释删掉。坑二环境变量的作用域。在.bashrc里设的环境变量可能在某些终端里读不到。建议用.zshrc或者系统级的环境变量设置。坑三项目级配置的路径。项目级配置的路径是相对于项目根目录的不是相对于当前工作目录。如果你在子目录里操作路径可能会错。坑四AGENTS.md 的更新时机。Codex 只在启动时读取 AGENTS.md运行中修改不会生效。改完 AGENTS.md 后需要重启 Codex。坑五多版本共存。如果你同时装了多个版本的 Codex配置目录可能不同。建议统一用一个版本避免混乱。我个人在实际操作中的体会是Codex 的配置管理没有想象中那么复杂但也没有那么简单。核心就是理解 TOML、AGENTS.md 和优先级这三块然后把它们组合起来用。刚开始可能会觉得麻烦但配置一次之后后面所有项目都能受益。我现在开新项目第一件事就是配好这两块后面用起来省心太多了。