1. 为什么要在本地折腾 Codex 自定义 AgentCodex 这个工具刚出来的时候大部分人就是拿它当个命令行版的代码补全用敲个codex然后问两句就完事了。但真正把它用起来的人会发现默认配置下的 Codex 其实相当“保守”——它不知道你的项目结构不知道你的代码规范更不知道你团队里那些约定俗成的东西。每次开新会话都要重新交代一遍背景这谁受得了。所以本地自定义 Agent 和模型配置这件事本质上解决的是一个核心痛点让 Codex 从“通用助手”变成“懂你项目的专属助手”。而实现这个目标的路径就藏在两个关键文件里——AGENTS.md和config.toml。前者负责告诉 Codex“你是谁、你在什么项目里、该遵守什么规则”后者负责告诉 Codex“用哪个模型、走什么通道、参数怎么调”。这两个文件配合起来再加上对优先级规则的准确理解你就能在本地搭出一套完全可控的 Agent 工作流。不管你是想让 Codex 接入 DeepSeek 这类国产模型来降低成本还是想给不同项目配置不同的行为规范又或者是想在团队里统一 Agent 的执行标准这套机制都能覆盖。这篇文章适合三类人看第一类是刚装好 Codex、还在用默认配置瞎问的新手第二类是已经用过一段时间、但总觉得“差点意思”的中级用户第三类是在团队里负责搭建 AI 编码规范、需要统一管理 Agent 配置的开发者。我会从设计思路讲到具体配置再到实际踩过的坑尽量把每个环节都说透。2. Codex 本地 Agent 的整体设计思路拆解2.1 为什么是 TOML 而不是 JSON 或 YAMLCodex 选择 TOML 作为配置文件格式这个决定其实挺讲究的。JSON 写起来太啰嗦不支持注释你没法在配置里标注“这行是给 DeepSeek 用的”或者“这个参数调过之后效果更好”。YAML 虽然支持注释但缩进敏感一个 Tab 和空格的混用就能让你排查半天而且 YAML 的解析器在不同语言里行为不一致容易出幺蛾子。TOML 的好处在于语法清晰、支持注释、层级结构用[section]表示读起来像 INI 文件但比 INI 强大得多。对于 Codex 这种需要配置模型、Provider、Agent 行为等多个维度的工具来说TOML 刚好卡在“够用”和“不过度复杂”之间。你可以在一个文件里同时定义多个模型 Provider每个 Provider 下面挂不同的参数结构一目了然。实际用下来TOML 最舒服的地方是改配置的时候不用小心翼翼。你加一行注释、调一个参数、换一个模型名都不会影响其他部分的解析。这一点在频繁切换模型的场景下特别重要。2.2 AGENTS.md 的定位不是文档是行为契约很多人第一次看到AGENTS.md的时候以为它就是个说明文档写点项目介绍就完事了。但实际上这个文件在 Codex 的 Agent 体系里扮演的是“行为契约”的角色。它会被注入到每次会话的上下文里直接影响 Agent 的决策逻辑。这意味着你写在AGENTS.md里的每一句话都会成为 Agent 行为的约束条件。比如你写“所有代码必须使用 TypeScript 严格模式”那 Agent 在生成代码时就会默认带上strict: true。你写“禁止使用 any 类型”它就会尽量避免。你写“API 路由统一放在 src/app/api 目录下”它就不会把路由文件扔到别的地方。所以AGENTS.md的写法直接决定了 Agent 的“性格”。写得好的AGENTS.md能让 Agent 像一个熟悉项目的老员工一样干活写得差的就只是一堆废话Agent 看了跟没看一样。2.3 优先级机制谁说了算Codex 的配置体系里存在多层优先级这是很多人容易搞混的地方。简单来说当多个地方都定义了同一个配置项时Codex 会按照一定的顺序来决定用哪个值。这个顺序大致是命令行参数 项目级配置 用户级配置 默认值但实际情况比这个复杂一些因为AGENTS.md和config.toml的优先级关系不是简单的上下级。config.toml管的是“用什么模型、走什么通道”这类硬性配置而AGENTS.md管的是“在这个项目里该怎么干活”这类软性约束。两者是互补关系不是替代关系。不过当AGENTS.md里的指令和config.toml里的配置产生冲突时比如AGENTS.md说“用 GPT-4”但config.toml里默认模型设的是 DeepSeek那 Codex 会以config.toml为准。因为模型选择属于硬配置AGENTS.md里的描述更多是建议性质。理解这个优先级关系很重要否则你可能会遇到“明明在 AGENTS.md 里写了要用某个模型但实际跑起来还是用的另一个”这种情况。3. 核心文件配置与实操要点3.1 config.toml 的完整配置结构先来看一个典型的config.toml应该长什么样。以下配置基于常见实践整理具体字段名请以你使用的 Codex 版本为准# 默认使用的模型 Provider model_provider deepseek # 默认模型名称 model deepseek-chat # 模型推理时的温度参数 temperature 0.7 # 单次响应的最大 token 数 max_tokens 4096 [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat [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这个配置定义了三个 ProviderDeepSeek、OpenAI 和一个本地模型。model_provider字段指定默认用哪个model字段指定默认用哪个模型。每个 Provider 下面的base_url是 API 端点env_key是存放 API Key 的环境变量名wire_api指定通信协议类型。这里有个细节值得注意env_key不是让你直接把 API Key 写在配置文件里而是让你写一个环境变量的名字。Codex 运行时会去读这个环境变量来获取实际的 Key。这样做的好处是配置文件可以安全地提交到版本控制里不会泄露密钥。3.2 多模型切换的配置策略实际工作中你可能需要在不同场景下用不同的模型。比如日常编码用 DeepSeek 省钱遇到复杂推理任务切到 GPT-4处理敏感代码时用本地模型。这种需求可以通过配置多个 Provider 来实现。切换的方式有两种一种是在config.toml里改model_provider和model的值另一种是通过命令行参数临时指定。后者更适合频繁切换的场景因为不用每次都改文件。如果你经常需要在几个模型之间来回切可以考虑在config.toml里定义好所有 Provider然后通过命令行参数来覆盖默认值。这样配置文件只需要维护一份切换成本很低。还有一个技巧是给不同的项目目录配置不同的config.toml。Codex 会优先读取项目根目录下的配置文件如果找不到才会往上找用户级配置。这意味着你可以在每个项目里放一份独立的config.toml针对该项目的特点配置不同的模型和参数。3.3 AGENTS.md 的写法与内容组织AGENTS.md的写法直接决定了 Agent 在你项目里的表现。我见过很多人把这个文件写成项目 README 的翻版什么“项目简介”“安装步骤”“目录结构”都往里塞。不是说这些内容没用但它们的优先级应该排在后面。真正重要的是那些能直接影响 Agent 行为的指令。以下是我总结的一个AGENTS.md模板结构按优先级从高到低排列# AGENTS.md ## 项目概述 这是一个基于 Next.js 14 的全栈应用使用 TypeScript 严格模式。 ## 代码规范 - 所有组件使用函数式组件 Hooks - 禁止使用 any 类型必要时用 unknown 加类型守卫 - 样式统一使用 Tailwind CSS不写内联样式 - 导入顺序React 相关 第三方库 项目内部模块 ## 目录约定 - API 路由src/app/api/ - 组件src/components/ - 工具函数src/lib/ - 类型定义src/types/ ## 禁止事项 - 不要修改 package.json 中的依赖版本 - 不要删除现有的测试文件 - 不要在客户端组件中直接访问数据库 ## 常用命令 - 开发npm run dev - 构建npm run build - 测试npm run test这个结构的关键在于把行为约束放在最前面把背景信息放在后面。因为 Agent 在处理任务时会优先关注那些明确的指令性内容。你写得越具体、越可操作Agent 的执行就越准确。3.4 环境变量与密钥管理API Key 的管理是个容易被忽视但很重要的环节。直接把 Key 写在config.toml里是最不推荐的做法因为一旦这个文件被提交到 Git 仓库你的 Key 就泄露了。正确的做法是使用环境变量。在config.toml里通过env_key字段指定环境变量的名字然后在系统的环境变量里设置实际的值。不同操作系统的设置方式不同Linux 和 macOS 下可以在~/.bashrc或~/.zshrc里加一行export DEEPSEEK_API_KEYyour-api-key-hereWindows 下可以通过系统设置里的“环境变量”界面来添加或者用 PowerShell[Environment]::SetEnvironmentVariable(DEEPSEEK_API_KEY, your-api-key-here, User)设置完之后需要重启终端才能生效。验证是否设置成功可以用echo $DEEPSEEK_API_KEYLinux/macOS或echo %DEEPSEEK_API_KEY%Windows CMD。注意如果你在团队里共享config.toml确保文件里只写env_key的名字不写实际的 Key 值。每个团队成员在自己的机器上设置各自的环境变量。4. 完整实操流程与关键环节实现4.1 从零开始搭建本地 Agent 环境假设你现在什么都没装我们从第一步开始走一遍完整流程。第一步是安装 Codex CLI。根据你的操作系统选择对应的安装方式。macOS 用户可以用 HomebrewWindows 用户下载安装包或者用包管理器。安装完成后在终端里运行codex --version确认安装成功。第二步是创建配置目录。Codex 默认会从用户主目录下的.codex文件夹读取配置。如果这个文件夹不存在手动创建mkdir -p ~/.codex第三步是创建config.toml。把前面提到的配置模板复制进去根据你的实际情况修改 Provider 和模型名称。如果你只用 DeepSeek那就只保留 DeepSeek 的配置块。第四步是设置环境变量。把你申请到的 API Key 通过环境变量设置好然后重启终端。第五步是验证配置。运行codex进入交互模式随便问一个问题看是否能正常收到回复。如果报错检查 API Key 是否正确、网络是否通畅、base_url是否写对。第六步是在项目里创建AGENTS.md。进入你的项目根目录创建这个文件按照前面的模板结构填入你项目的信息。不需要一次写得很完美后续可以随时补充。4.2 模型参数调优的实操记录模型参数这块最常调的就是temperature和max_tokens。这两个参数直接影响 Agent 的输出质量和响应速度。temperature控制输出的随机性。值越低输出越确定、越保守值越高输出越多样、越有创造性。对于代码生成任务我一般建议设在 0.2 到 0.5 之间。太低会导致 Agent 只会用最常见的写法太高又容易生成不靠谱的代码。max_tokens控制单次响应的最大长度。设得太小Agent 可能话说到一半就被截断了设得太大又浪费 token 配额。对于代码补全场景2048 到 4096 通常够用。如果是让 Agent 生成完整的模块或文件可能需要调到 8192 甚至更高。以下是我在不同场景下的参数配置参考场景temperaturemax_tokens说明代码补全0.22048追求准确性和速度代码审查0.34096需要一定的分析深度架构设计0.58192需要创造性思维文档生成0.44096平衡准确性和可读性调试排查0.24096需要严谨的逻辑推理这些值不是固定的你可以根据自己的实际体验来调整。关键是要理解每个参数的作用然后有针对性地调。4.3 多项目配置隔离的实现方式如果你同时维护多个项目每个项目的技术栈和规范都不一样那就需要做配置隔离。Codex 的配置查找机制天然支持这一点它会从当前工作目录开始往上找config.toml和AGENTS.md找到最近的那个就用那个。所以你可以这样组织~/projects/ ├── project-a/ │ ├── AGENTS.md # 项目 A 的 Agent 规范 │ ├── .codex/ │ │ └── config.toml # 项目 A 的模型配置 │ └── src/ ├── project-b/ │ ├── AGENTS.md # 项目 B 的 Agent 规范 │ ├── .codex/ │ │ └── config.toml # 项目 B 的模型配置 │ └── src/ └── ~/.codex/ └── config.toml # 全局默认配置这样每个项目都有自己独立的配置互不干扰。全局配置作为兜底当项目级配置不存在时使用。提示项目级的.codex/config.toml建议加入.gitignore因为里面可能包含项目特定的 API Key 或敏感配置。AGENTS.md则可以提交到仓库让团队成员共享同一套 Agent 规范。4.4 验证配置是否生效的方法配置写完不代表就生效了你需要验证一下。最直接的方法是在 Codex 交互模式里问它一些和配置相关的问题。比如你可以在AGENTS.md里写一条“所有函数必须写 JSDoc 注释”然后让 Codex 生成一个函数看它是否自动带上了注释。如果带了说明AGENTS.md生效了。如果没带可能是文件位置不对或者格式有问题。验证模型配置是否生效可以问 Codex“你当前使用的是哪个模型”。虽然它不一定能准确回答因为这取决于实现方式但你可以通过观察响应速度和输出风格来间接判断。DeepSeek 和 GPT-4 的输出风格还是有明显差异的。还有一个更可靠的方法是查看 Codex 的日志输出。很多版本的 Codex 在启动时会打印当前加载的配置信息包括使用的模型和 Provider。如果你能看到这些信息就说明配置被正确读取了。5. 常见问题与排查技巧实录5.1 配置不生效的排查思路配置写了但没生效这是最常见的问题。排查的时候按照以下顺序来首先确认文件位置对不对。config.toml应该在~/.codex/目录下或者项目根目录的.codex/目录下。AGENTS.md应该在项目根目录下。文件名的大小写也要注意有些系统对大小写敏感。其次确认文件格式有没有语法错误。TOML 对格式要求比较严格少一个引号、多一个逗号都可能导致解析失败。可以用在线的 TOML 校验工具检查一下。然后确认环境变量是否设置成功。在终端里echo一下对应的变量名看有没有输出。如果没有输出说明环境变量没设置对需要重新设置并重启终端。最后确认优先级关系。如果你在多个地方都定义了同一个配置项Codex 会按照优先级来选择。项目级配置会覆盖用户级配置命令行参数会覆盖配置文件。检查一下是不是有更高优先级的配置覆盖了你想要的值。5.2 模型连接失败的常见原因模型连接失败通常有以下几个原因API Key 无效或过期是最常见的。检查一下 Key 是否复制完整有没有多余的空格。有些平台的 Key 有有效期过期了需要重新生成。base_url写错也很常见。不同的模型 Provider 有不同的 API 端点写错了就连不上。比如 DeepSeek 的端点通常是https://api.deepseek.com/v1注意末尾的/v1不能少。网络问题也需要考虑。如果你在公司内网或者有防火墙限制可能需要配置代理才能访问外部 API。这个具体怎么配取决于你的网络环境。模型名称写错也会导致连接失败。比如你写的是deepseek-chat但实际可用的模型名是deepseek-chat-v2那就对不上。去 Provider 的文档里确认一下正确的模型名称。5.3 AGENTS.md 被忽略的情况分析有时候你明明写了AGENTS.md但 Agent 的行为完全不受影响。这种情况通常是以下原因文件位置不对。AGENTS.md必须放在项目根目录下放在子目录里 Codex 是找不到的。如果你在子目录里运行 Codex它会往上找但只会找项目根目录那一层。文件内容格式有问题。AGENTS.md虽然是 Markdown 格式但 Codex 解析的时候可能对某些语法支持不好。比如嵌套很深的列表、复杂的表格、HTML 标签等可能导致解析异常。建议用最简单的 Markdown 语法来写。内容太长被截断了。AGENTS.md的内容会被注入到上下文里如果太长可能会超出模型的上下文窗口导致部分内容被截断。建议把最重要的指令放在文件最前面次要的放后面。Agent 没有正确加载文件。有些版本的 Codex 需要在启动时显式指定AGENTS.md的路径或者需要在配置里开启某个选项才会读取这个文件。查一下你使用的版本的文档确认是否需要额外配置。5.4 常见问题速查表问题现象可能原因解决方法启动时报配置解析错误TOML 语法错误用在线校验工具检查格式模型连接超时网络不通或 base_url 错误检查网络和 API 端点返回 401 错误API Key 无效重新生成并设置 KeyAgent 不遵守 AGENTS.md文件位置或格式问题确认文件在项目根目录且格式正确切换模型后没变化优先级被覆盖检查是否有更高优先级的配置响应被截断max_tokens 太小调大 max_tokens 值输出质量不稳定temperature 不合适根据场景调整 temperature环境变量读不到未重启终端重启终端或重新加载配置文件5.5 实操心得与避坑建议第一个心得是不要一次性把所有配置都写完。先配一个最简单的能跑通的版本确认没问题之后再逐步添加更多配置。这样出问题的时候容易定位。第二个心得是保留一份配置备份。每次改配置之前先复制一份改坏了可以快速回滚。我一般会在~/.codex/下放一个config.toml.bak改之前先cp config.toml config.toml.bak。第三个心得是AGENTS.md 要持续迭代。不要指望一次就写完美。用一段时间之后你会发现 Agent 在某些方面表现不好那就往AGENTS.md里加一条对应的约束。慢慢积累这个文件会越来越贴合你的项目需求。第四个心得是多模型配置要有主次。不要把所有模型都设成同等优先级要有一个默认的主力模型其他的作为备选。这样在主力模型不可用的时候可以快速切换。第五个心得是注意 token 消耗。AGENTS.md的内容会占用上下文 token如果写得太长每次会话都会消耗大量 token。建议控制在 2000 字以内只保留最关键的指令。6. 进阶技巧与扩展思路6.1 用脚本自动化配置切换如果你经常需要在不同模型之间切换手动改config.toml太麻烦了。可以写一个简单的 shell 脚本来自动化这个过程#!/bin/bash # switch-model.sh CONFIG_FILE$HOME/.codex/config.toml case $1 in deepseek) sed -i s/^model_provider .*/model_provider deepseek/ $CONFIG_FILE sed -i s/^model .*/model deepseek-chat/ $CONFIG_FILE echo Switched to DeepSeek ;; openai) sed -i s/^model_provider .*/model_provider openai/ $CONFIG_FILE sed -i s/^model .*/model gpt-4/ $CONFIG_FILE echo Switched to OpenAI ;; *) echo Usage: switch-model.sh [deepseek|openai] ;; esac这个脚本用sed命令直接修改配置文件里的model_provider和model字段。用的时候只需要./switch-model.sh deepseek就能一键切换。Windows 用户可以写一个对应的 PowerShell 脚本原理是一样的。6.2 团队协作中的配置管理在团队里推广 Codex 的时候配置管理是个绕不开的问题。我的建议是AGENTS.md提交到项目仓库作为项目规范的一部分。这样每个团队成员拉取代码后都能获得一致的 Agent 行为。config.toml不提交每个成员根据自己的环境和偏好来配置。但可以在仓库里放一个config.toml.example作为模板新成员复制一份改改就能用。API Key 通过环境变量管理不写入任何提交到仓库的文件。团队可以共用一个 Key也可以每人用自己的 Key取决于预算和管理方式。如果团队规模比较大可以考虑搭建一个内部的模型网关统一管理 API Key 和调用配额。Codex 的base_url指向这个网关就行团队成员不需要各自配置 Key。6.3 结合项目特点定制 Agent 行为不同类型的项目AGENTS.md的侧重点应该不同。以下是我总结的几种典型项目的配置要点前端项目要强调组件规范、样式方案、状态管理方式。比如“使用函数式组件”“样式用 Tailwind”“状态管理用 Zustand”。后端项目要强调 API 设计规范、数据库操作方式、错误处理策略。比如“RESTful 风格”“使用 Prisma 操作数据库”“统一错误码格式”。数据科学项目要强调代码可复现性、数据处理流程、可视化规范。比如“所有随机操作设置 seed”“数据清洗步骤写入 pipeline”“图表使用统一的配色方案”。基础设施项目要强调安全性、幂等性、回滚策略。比如“所有操作必须幂等”“变更前先备份”“禁止在生产环境直接执行”。把这些项目特定的约束写进AGENTS.mdAgent 就能在不同项目里表现出不同的“专业方向”。6.4 性能优化与响应速度提升Codex 的响应速度受多个因素影响以下是一些优化建议选择离你地理位置近的 API 端点。如果你在国内用国内的模型 Provider 通常会比用国外的快很多。这不是绝对的安全问题纯粹是网络延迟的考量。合理设置max_tokens。设得太大模型需要生成更多内容才能返回响应时间自然更长。根据实际需要设置一个合理的值。减少AGENTS.md的长度。上下文越长模型处理的时间越久。把不必要的内容删掉只保留核心指令。使用流式输出。如果 Codex 支持流式输出模式开启之后可以边生成边显示体感上会快很多。避免频繁切换模型。每次切换模型都可能需要重新建立连接有一定的开销。如果一段时间内主要用某个模型就保持那个配置不变。6.5 后续扩展方向这套本地 Agent 配置体系搭好之后还有很多可以扩展的方向。一个是接入更多的模型 Provider。除了 DeepSeek 和 OpenAI还有很多其他模型服务可以用。只要支持兼容的 API 格式就可以通过配置接入。另一个是给 Agent 添加工具能力。有些版本的 Codex 支持通过配置注册外部工具让 Agent 可以调用这些工具来完成更复杂的任务。比如调用一个代码格式化工具、运行测试脚本、查询数据库等。还有就是和 CI/CD 流程结合。把 Codex 的配置纳入项目的持续集成流程在代码审查阶段自动运行 Agent 检查确保代码符合规范。我自己在实际操作中的体会是这套配置体系最大的价值不在于“一次配好”而在于“持续调优”。你用得越多就越知道该怎么写AGENTS.md、该怎么调参数。刚开始可能觉得麻烦但一旦跑顺了效率提升是实实在在的。最后再分享一个小技巧把你觉得好用的配置片段单独存一个文件换项目的时候直接复制过去能省不少事。