如果你想让 Codex 成为真正服务于自己项目的本地自定义 Agent那 TOML、AGENTS.md 和优先级这三个词会是你绕不开的关卡。我最早以为把配置里的模型名改成 DeepSeek 就能直接跑结果命令行反复报错最后才明白接入点、项目指令、配置覆盖顺序这三样东西才是整个自定义体系的骨架。这篇文章记录的是我实际折腾两周后整理出来的完整思路适合已经装好 Codex 命令行工具、想进一步做本地化或第三方模型接入的开发者。不吹不黑照着做基本能跑通但更关键的是理解它背后的逻辑。1. 配置 Codex 之前先想清楚三件事很多人一上来就直接搜配置文件路径然后把参数抄一遍就完事。这样也不是不行只是遇到问题你会完全不知道从哪下手。我的建议是动手之前先把三件事弄明白Codex 默认在跑什么TOML、AGENTS.md、优先级分别管什么以及改坏了怎么快速回退。1.1 Codex 默认在跑什么Codex 默认情况下是一个偏向云端自动执行的终端编程助手。它启动后会自动读取你的配置连接模型服务然后在一个受控的沙盒环境里执行命令、读写文件、调用工具。你给它一句帮我修一下测试它会自己规划步骤、跑测试、看结果、改代码。在这个过程中有三个东西决定了它的行为模型从哪来默认走 OpenAI 官方接口模型名、接口地址、鉴权方式都在config.toml里。行为按什么规矩来它进入项目后会自动寻找AGENTS.md把它当作项目操作的说明书。冲突听谁的当全局配置、项目配置、会话里的临时要求之间出现冲突时有一套优先级规则决定最终结果。这三条线正好对应当前的标题TOML、AGENTS.md 和优先级。把它们拆开看配置工作就没那么玄乎了。1.2 TOML、AGENTS.md、优先级各干各的我刚接触时最大的误解是想用一份配置文件把什么都塞进去。后面发现这是三个不同层面的东西至少在心里要分成三层TOML 是接线图负责把请求送到正确的模型服务。改 provider、改 base_url、改模型名都是在这里完成。AGENTS.md 是操作手册负责告诉 Agent 这个项目有什么特殊规矩。比如测试命令是什么、哪个目录不能动、代码风格用什么。优先级是指挥规则负责在这些配置和指令交叉作用时决定谁说了算。比如你全局配了一个模型项目里又指定了另一个到底用哪个再比如根目录和子目录都有 AGENTS.mdAgent 听谁的这就是优先级问题。打个比方可能更好理解TOML 决定了你开车走的路线AGENTS.md 决定了你车上的驾驶规范优先级则是在交叉路口遇到交警时听交警的还是听红绿灯的。1.3 动手前先做好备份和最小验证这是我从一次惨痛教训里总结出来的。当时我为了接一个第三方模型把~/.codex/config.toml改得面目全非结果 Codex 连启动都报错我又记不清原来写了什么只能凭记忆重写浪费了大把时间。现在我的习惯是每次改配置之前先给整个配置目录做一次快照cp -r ~/.codex ~/.codex.bak.$(date %Y%m%d%H%M)如果你习惯用 dotfiles 管理配置文件也可以先提交一次 git commit。改完之后不要急着去跑大任务先开一个最简会话让它执行一个简单命令比如输出当前目录结构。这样能最快确认配置是否生效。2. 手写 config.toml把模型接入点彻底搞清楚config.toml是 Codex 的核心配置文件默认位置在~/.codex/config.toml。它的语法比 JSON 友好但注意它和 JSON 不一样没有花括号包住全部内容而是靠方括号来分组。这里我最常犯的错误就是写错层级的缩进和表名导致字段被放到了错误的位置。2.1 一份最基础的配置长什么样如果你是纯默认使用配置甚至可以短到只有两三行# ~/.codex/config.toml model gpt-5 model_provider openaimodel指定模型名model_provider指定模型走哪个 provider。所谓的 provider就是一个通道它告诉 Codex 该把请求发到哪个地址、用哪个鉴权环境变量。一旦你要接第三方模型或本地模型就得自己定义 provider。定义一个 provider 的通用写法是这样的[model_providers.custom] name 自定义服务名 base_url https://your-api-endpoint.example/v1 env_key CUSTOM_API_KEY wire_api chatname是人类可读的名字base_url是接口地址env_key告诉 Codex 从哪个环境变量里读密钥wire_api是通信协议类型。这里的wire_api要重点记住它有两个值chat和responses。Codex 本身默认偏向新的 responses 协议但很多第三方服务和本地模型只实现老的 chat completions 协议不把wire_api设成chat就会出现接口不存在之类的报错。2.2 接入 DeepSeek 这类第三方服务的完整写法现在很多人想把 Codex 接到 DeepSeek 这类 OpenAI 兼容模型上操作其实不复杂。我的配置文件里是这么写的model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后在你当前的 shell 环境里设置密钥export DEEPSEEK_API_KEYsk-你的密钥注意我特别在这一小节里把wire_api chat写了进去。因为 DeepSeek 官方接口目前走的是 chat completions 格式如果漏掉这一行Codex 可能会用默认的 responses 协议去请求最后你会看到路径不存在这种莫名其妙的现象。这个坑我踩过后来才发现问题根本不在网络而在协议不匹配。另外base_url的后缀/v1也很关键。有的服务商让你填https://api.deepseek.com不带/v1有的则要求带上。我的经验是凡是说自己兼容 OpenAI API 的绝大多数都要求/v1路径。拿不准的时候可以用 curl 直接看服务商文档里的示例。2.3 密钥别直接写进配置文件有一点想特别强调config.toml里不要写任何密钥明文。哪怕这个文件只在你自己的电脑上我也建议用env_key的方式。因为配置文件很容易被同步到网盘、git 仓库或者被某个截图带跑而 API Key 一旦泄露损失不可控。env_key的机制是Codex 在启动时从指定的环境变量里读取密钥而不是从配置文件里读。环境变量可以在~/.bashrc、~/.zshrc里设置也可以临时在终端里 export。对本地模型来说密钥可能并不需要真实值但 Codex 仍然需要一个环境变量存在否则会提示找不到密钥。这种时候你可以设置一个占位符比如export OLLAMA_API_KEYlocal-placeholder3. AGENTS.md 到底怎么写Agent 才会真听你的配置文件解决的是请求发去哪的问题而AGENTS.md解决的是项目该按什么规矩执行的问题。Codex 在进入一个项目目录时会自动查找这个文件并把里面的内容作为额外的系统指令注入到对话上下文里。3.1 为什么不用把项目规范写进 TOML有人会问既然 TOML 是配置为什么不把禁止修改 migrations 目录也写进去答案很简单TOML 能表达的是结构化的键值参数而 AGENTS.md 要表达的是自然语言规则。Agent 对自然语言指令的理解远比解析配置项要好。而且 AGENTS.md 可以跟着项目走你把这个目录发给同事或者放到新机器上规则依然有效。TOML 则会跟着用户主目录走是人的配置不是项目的配置。所以我的习惯是跟人走的放~/.codex/config.toml跟项目走的放项目根目录AGENTS.md。3.2 AGENTS.md 的存放位置和继承关系AGENTS.md 可以放在多个层级。我现在常用的结构是这样~/.codex/AGENTS.md全局偏好比如所有代码注释用中文默认使用 Python 3.11。项目根目录AGENTS.md项目级约定比如测试命令是 pytest tests/ -q不要动生成的代码文件。子目录AGENTS.md如果你在非常复杂的 monorepo 里可以在具体模块目录放一个更细的说明。它们的覆盖关系我的理解是越靠近当前工作目录的 AGENTS.md优先级越高。也就是说子目录里的规则会覆盖或补充项目根目录里的规则项目根目录会覆盖或补充全局规则。如果你发现一个指令老是没生效先看看是不是被更外层的 AGENTS.md 里的同话题规则给稀释了。对 Agent 来说多份规则同时存在时它可能不会丢弃任何内容而是把它们都当作参考。所以要避免在多个文件里写互相矛盾的话。3.3 写一份高质量 AGENTS.md 的实操模板我踩过最大的坑是把 AGENTS.md 写成论文。写一大堆正确的废话Agent 反而不知道该抓什么重点。后来我总结出一个比较好用的结构总体约定 常用命令 禁止事项。下面是我给一个 Python 项目写的示例# 项目指令 ## 总体约定 - 代码要求 Python 3.11 及以上使用类型注解。 - 注释和文档使用中文git commit 信息使用英文。 - 新功能必须包含对应测试。 ## 常用命令 - 安装依赖pip install -e .[dev] - 运行测试pytest tests/ -q - 代码格式化ruff format . ## 禁止事项 - 不要修改 migrations/ 目录下的文件。 - 不要提交 .env 文件到版本控制。 - 不要在未运行测试的情况下改动核心逻辑。这个模板的好处是短、直接、每条都可以执行。Agent 读取后能快速形成在这个项目里该怎么干活的预期。如果你写了一条很模糊的规则比如代码质量要高那 Agent 只能靠猜。不如写清楚测试覆盖率不能低于 80%。我从测试中发现AGENTS.md 里的指令应该尽量使用祈使句和明确条件少用形容词。因为模型对形容词的理解是有弹性的对具体动作的理解则更稳定。4. 优先级不是后写的覆盖先写那么简单现在来说标题里的第三个关键词优先级。这部分我觉得是最容易让人懵的。很多人以为配置的优先级就是谁写在后面听谁的实际情况要复杂一些。4.1 配置层级的先后关系先从大的层面试着梳理。Codex 的配置来源大致有这么几层命令行里显式传递的参数优先级最高。环境变量比如 API Key 的选择和变更。配置文件config.toml。内置默认值。什么意思呢如果你在启动 Codex 时显式指定了某个模型那么 config.toml 里的model字段就算写了别的也会被命令行参数压过。反过来如果 config.toml 里什么都没写Codex 就会用内置默认值。这个设计其实和很多命令行工具的惯例一致命令参数 配置文件 默认值。在排查问题的时候我会建议先确认当前会话到底有没有通过参数指定过什么。有时候是历史命令被 shell 自动补全带进来了就会悄悄改变实际生效的配置。4.2 最常见的问题出在 provider 覆盖我在本地实验时遇到过这么个情况config.toml 里明明把model_provider写成了本地服务但实际请求还是发去了默认的 OpenAI 地址。后来排查了半天发现是会话启动时我用了某个启动参数那个参数里指定了 provider 为 openai把文件里的配置覆盖掉了。这类问题在同时配置多个 provider 时非常常见。你有 openai、deepseek、ollama 三个 provider 躺在配置里只要model_provider没有明确指向或者某个隐藏参数把 provider 锁定了请求就会走错地方。我的排查经验是不要同时把多个 provider 全设为能用只留当前要用的那个其余的先注释掉。等跑通了再加回来。这样可以极大减少配置生效了但生效的不是我想要的这种问题。4.3 用 profile 或独立配置来管理多环境如果你确实需要经常在云端模型、第三方模型、本地模型之间切换建议不要反复注释代码块而是把多套配置拆成 profile 或者用环境变量隔离。Codex 本身支持通过命令行参数选择 profile 的用法不同版本参数名可能略有差异启动时可以用--help看下。核心思想是每一套环境一个独立配置块用的时候指定日常贵但强的模型官方服务。预算敏感的批量任务DeepSeek 这类第三方。完全离线的调试Ollama 本地模型。这样做最大的好处是你不会陷入改一行配置、跑一次验证、改错了再回滚的循环。优先级规则的真正意义不是让你研究出谁最优先而是让你主动选择当前场景下谁最优先。5. 把 Codex 接到本地模型Ollama 的完整实战前面讲了配置和指令现在说说真正的本地化。既然标题里有本地自定义 Agent这一步不能少。我目前最常用的本地模型运行时是 Ollama。选它没什么特别深刻的原因主要是它安装简单、跨平台而且直接提供 OpenAI 兼容的接口配 Codex 不需要额外写一层转换服务。5.1 完整配置步骤第一步安装 Ollama。装好后默认服务地址是http://127.0.0.1:11434。如果你访问那台机器的另一个端口记得把防火墙和监听地址一起确认下。第二步拉取一个适合编码的模型。我做过几次对比之后觉得从实用角度优先看 qwen2.5-coder 系列和 llama3.1 系列。以 qwen2.5-coder 14b 为例ollama pull qwen2.5-coder:14b第三步确认本地接口的 OpenAI 兼容地址。Ollama 启动后http://127.0.0.1:11434/v1就是 OpenAI 兼容端点。你可以先用 curl 验证curl http://127.0.0.1:11434/v1/models如果能返回模型列表说明接口是通的。这个验证步骤别跳过很多后面出现的连不上问题在这一步就能发现。第四步修改config.toml增加一个 local providermodel qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://127.0.0.1:11434/v1 env_key OLLAMA_API_KEY wire_api chat第五步在 shell 里设置占位密钥export OLLAMA_API_KEYlocal-placeholder然后启动一个最简会话让它做一些基础的文件操作。如果这一步通了再让它写一小段逻辑代码。不要一上来就丢一个重构整个项目的大任务给它先把链路确认稳固。5.2 本地模型常见的坑本地模型和云端模型在使用体验上有很大差异。最大的坑是上下文窗口和工具调用能力。有些模型参数写得很大实际推理时一旦塞入太多工具定义就开始出现漏调用、重复调用甚至直接终止执行的情况。我的建议是本地模型更适合做中等规模任务写单元测试、做代码解释、按规范改一个函数。不太适合让它做整个 monorepo 级别的自动重构。另外本地模型的推理速度和显存直接相关14B 模型在 24G 显存上表现尚可在 8G 显存上就会明显掉速。你要是手头硬件有限可以先跑 7B 甚至更小的模型不要盲目追求参数量。5.3 为什么 base_url 结尾要不要带 /v1 是个高频错误接 Ollama 时base_url要写http://127.0.0.1:11434/v1这个/v1很关键。如果你写成了http://127.0.0.1:11434Codex 会把请求发到 Ollama 的根路径路由对不上结果就是 404 或者路由不存在的错误。同理接 DeepSeek 时也要求/v1结尾。这个细节特别容易忽略因为 Web 上很多教程直接给了完整地址你复制过来是通的但你不知道自己实际上在改什么。一旦换一个没有/v1的服务商就开始瞎猜原因。6. 踩坑记录端点配置失败与沙盒执行错误怎么查最后这部分把我实际碰到的两个典型报错和排查思路完整记录下来。它们非常具有代表性。6.1 本地端点切换失败这类报错问题通常不在网络有一次我在调试自定义模型服务命令行直接弹出一串英文报错大意是切换本地端点失败处理 codex endpoint /responses 时出了问题。我当时的条件反射是去查网络通不通、Key 对不对折腾了半天都没用。最后才发现问题根本不在网络而是 Codex 默认在请求/responses这个新协议接口而我连的那个本地服务只实现了旧的/v1/chat/completions。解决办法就是前面提到的wire_api chat。这行一加上请求就切换成了 chat 协议报错马上消失。所以遇到端点类报错我的排查顺序固定是先确认base_url对不对用 curl 直连看看返回什么。再确认wire_api是否和服务端能力匹配。最后才去检查 Key 和环境变量。把网络放最后不是因为网络不会出问题而是大部分报错其实是协议不匹配和路径错误查网络纯粹浪费时间。6.2 agent execution terminated due to error的排查路径这个报错看起来非常吓人好像整个 Agent 都崩了。我遇到时第一反应是模型太弱或者是沙盒环境坏了。其实这类错误往往发生在 Agent 执行阶段而不是模型接入阶段。也就是说模型已经成功连上但在执行某个命令、调用某个工具时崩了。我的排查办法是把问题拆成两段看先用最小会话测试让 Agent 只做一件不涉及工具调用的事比如介绍一下这个项目如果这一步正常说明模型接入没问题。然后让 Agent 执行一个简单命令比如列出当前目录文件如果这一步崩了问题就在沙盒执行层。这时候可以试试降低请求上下文、换更稳定的模型或者把明确冲突的 AGENTS.md 指令简化。下面是我整理的一张速查表方便你在遇到类似问题时快速对照报错特征大概率原因排查顺序路径不存在或找不到 /responses服务端不兼容 responses 协议将 provider 的 wire_api 改成 chat401、403 鉴权失败API Key 没传对检查 env_key 对应的环境变量404 路由不存在base_url 漏了 /v1 或多了路径用 curl 访问 /v1/models 对比Agent 执行中途终止沙盒工具或代码解释器异常用无工具的最小会话隔离问题6.3 多用最小复现少用大项目验证这是我在整个配置实战里最想强调的工程习惯每次只改一个变量。无论是改模型、改 provider 还是改 AGENTS.md一次只动一处然后立刻用一个三五秒就能完成的会话任务验证。不要想着反正都改了一起看看行不行因为一旦出问题你根本无法判断是哪一处改动导致的。如果你在多个 provider 之间反复切换还经常出错我建议回到最简配置只留一个 provider、一个模型、一个 AGENTS.md。跑通了再一件一件加回来。这个过程虽然看起来慢但你节省的是排查问题的几倍时间。我自己现在把 Codex 日常场景固定成三套配置云端模型跑核心任务DeepSeek 做预算敏感的批量请求Ollama 完全离线调试。配置这东西没有标准答案但只要你把 TOML、AGENTS.md、优先级这三条线理清后面接任何新模型都不会再手忙脚乱。如果你也有类似的折腾经历欢迎把报错贴出来我们一起看看是哪一层优先级抢走了控制权。