最近我一直在折腾 Codex 的本地自定义 Agent 和模型配置把config.toml、AGENTS.md和整套优先级关系摸了一遍。这篇东西不是官方文档的复述是我自己实测踩坑后整理出来的实战笔记。如果你准备把 Codex 接入自己的项目、想用本地模型跑 Agent或者只是好奇“为什么我的 Agent 就是不听话”这篇文章应该能给你一个可复现的答案。先说个前提Codex 的配置体系核心就两个文件——config.toml管“用什么模型、怎么连服务”AGENTS.md管“Agent 在项目里按什么规则干活”。两者配合好了Agent 就像个熟悉你团队规范的老同事配合不好它就像个每次都要重新教一遍的实习生。1. 配置体系全景Codex 到底读哪些文件1.1 两个核心文件的角色定位先解决一个基本问题Codex 启动时到底读哪些配置最常见的配置文件路径是~/.codex/config.toml这是全局配置。它决定了默认模型、上下文窗口、输出长度、第三方 provider 等机器级参数。这个文件相当于你的“全局偏好”所有项目共用。另一个就是AGENTS.md它可以放在全局~/.codex/AGENTS.md也可以放在具体项目根目录下。它用自然语言描述“这个项目里 Agent 应该怎么干活”比如测试用哪个框架、代码风格是什么、哪些文件不能动。项目目录下的AGENTS.md优先级更高会覆盖全局的同类规则。如果你用的是 Codex 桌面版或者 CLI 版本安装完成后第一次运行会在~/.codex下生成默认配置。我建议你不要急着改先跑通一个基础对话确认登录和网络层面没问题再开始动 TOML。因为很多新手上来就改配置结果发现 Agent 报网络错误或者认证错误就容易误判成“配置文件写错了”。基础版本的对话能力是一切自定义配置的前提。1.2 为什么特别关注 TOML 与 AGENTS.md 的组合如果你用过 ChatGPT 桌面版、Codex CLI或者很早期的codexnpm 包应该对这两类文件都不陌生AGENTS.md用自然语言描述项目规范和 Agent 行为边界。它描述的是“规则和意图”比如“测试请用 pytest”“提交前必须跑 lint”“不要修改公共 API 签名”。config.toml描述的是机器可读的偏好比如“默认模型用 gpt-5.2-codex”“禁用某个模型”“超时时间 120 秒”“上下文窗口设置成多少”。两者相辅相成但作用机制完全不同。AGENTS.md 负责“智能”它通过注入上下文引导 Agent 的行为config.toml 负责“纪律”它硬性决定模型和连接参数。如果你的 Agent 天天不听话不要急着怪模型笨先看看是不是这两份文件根本没写对——大部分情况下问题出在规则模糊或者配置优先级被覆盖。2. 本地自定义 Agent 与模型配置从零搭一套可复现的环境2.1 目录结构与安装基础我这边实测过几套方案最省心的是用官方 CLI 加本地配置的方式。下面是核心目录结构~/.codex/ ├── config.toml # 全局配置 ├── AGENTS.md # 全局 Agent 规则可选但强烈建议 └── projects/ └── my-agent-project/ ├── AGENTS.md # 项目级规则 └── config.toml # 项目级配置可选如果你用的是 Codex CLI 或者桌面版安装完成后第一次启动会在~/.codex下生成默认配置。有些版本会把你带入登录流程需要先完成认证后面才能调用云端模型。我的建议是先确认基础的对话、会话、模型调用都正常再动配置。这一步走不顺后面很容易混淆“配置问题”和“环境问题”。提示请使用官方渠道获取 Codex。设定自定义模型前先确保基础版本能正常对话再动 TOML 配置避免一出问题就怀疑配置文件。2.2 写一个能用的 config.toml我推荐用最小化配置起步跑通再逐步加参数。一个可以实际使用的例子model gpt-5.2-codex # 默认模型 model_context_window 200000 # 上下文窗口按模型实际支持值填 model_max_output_tokens 64000 # 单次输出上限 [experimental] # 有些版本支持实验性参数按需开启 [model_providers] # 如果你接入了第三方兼容网关或本地推理服务可以在这里注册几个字段我前面已经解释过这里补充两个容易踩坑的点model_context_window不一定要填模型的最大窗口。你可以按实际任务复杂度给 Agent 一个“受限窗口”这样它会更早开始整理上下文减少无效 token 消耗也更不容易中途把关键信息挤掉。比如日常代码问答 100k 就够长文档分析再上调。model_max_output_tokens这个值影响单次回复的长度。做代码生成、长文档任务时建议给大一点否则 Agent 会在生成中途被截断——那种“上半段思路清晰下半段突然重复或者戛然而止”的现象多半就是这个值太小。日常问答给默认值就够。如果后续想切换模型只需要改model字段大多数模型都可以共用同一套 TOML 模板。我这里强调“大多数”是因为某些模型可能有特殊参数要求比如需要单独设置reasoning_effort或者model_context_window的范围这时候你得在项目级 config.toml 里单独覆盖。2.3 AGENTS.md 该怎么写从规则到可执行AGENTS.md 的核心是让 Agent 在动手前知道边界和偏好。我常用的写法是分模块# 项目约定 ## 测试 - 所有测试使用 pytest不引入 unittest - 运行测试前需要先执行 make setup - 新增功能必须附带对应测试用例 ## 代码风格 - Python 代码遵循 PEP8使用 black 格式化 - 变量命名使用 snake_case常量使用 UPPER_CASE - 类型注解必须完整禁止写裸的 def func(x) 而不标注类型 ## Git 提交 - 提交信息使用 Conventional Commits 格式 - 提交前必须运行 make lint make test - 禁止直接 push 到 main 分支 ## 禁止事项 - 不要修改 schema.sql 中的已有字段类型 - 不要引入重量级第三方依赖如 pandas、numpy - 不要删除 tests/ 下的历史用例这样写的好处是每条规则都是可验证的Agent 能直接对应到具体命令或文件。比如“使用 black 格式化”Agent 可以直接执行black不需要猜测。明确写出“禁止事项”比只写“请谨慎修改”有效得多。大模型在开放指令下容易过度发挥明确边界能显著减少破坏性行为。中文描述完全没问题Codex 对中文的理解能力足够好但我个人建议命令、文件名、报错关键词保留英文原文减少歧义。比如make lint就写make lint不要写成“执行 lint 构建任务”。3. 模型配置优先级到底谁说了算3.1 优先级链路显式参数 项目级 全局 内置默认这是我这次实战中收获最大的一部分。Codex 的配置优先级并不是简单的“用户设置覆盖一切”而是有一套完整链路命令行或代码中显式指定最高 ↓ 项目级配置config.toml / AGENTS.md ↓ 全局配置~/.codex/config.toml / AGENTS.md ↓ Codex 内置默认值最低举个例子如果你在命令行里执行codex --model gpt-5.1-codex-mini那么哪怕项目级 config.toml 里写的是model gpt-5.2-codex最终实际生效的也是命令行指定的这个模型。再举个例子你全局配置里写了model gpt-5.2-codex但某个项目下的 config.toml 里写的是model gpt-5.1-codex那么这个项目里就会用gpt-5.1-codex。这就是为什么很多人发现“我明明改了全局配置怎么 Agent 还是用旧模型”——因为项目目录里可能有一份被遗忘的 config.toml。3.2 AGENTS.md 与 config.toml 的优先级关系AGENTS.md 和 config.toml 不是同一层级的文件它们的作用方式不同config.toml 优先级更高因为它直接决定“用什么模型跑推理”。这是硬约束。AGENTS.md 更接近软约束它会作为上下文注入给 AgentAgent 在生成回答时会参考这些规则但不保证 100% 遵守。这是行为约束。实操心得是重要的、硬性的约束比如“必须使用某个模型”“禁止调用某个 provider”放在 config.toml 里柔性的、策略性的约束比如“优先使用 pytest”“提交前跑 lint”放在 AGENTS.md 里。这和公司里“制度”与“文化”的分工有点像制度是红线文化是导向。制度违反就要处罚文化违反最多被提醒——但如果你希望 Agent 稳定地在红线内发挥两者都得有。3.3 多 Agent 场景下的模型隔离如果你像我一样同时维护多个 Agent 项目优先级机制就特别好用。假设你有两个项目docs-agent负责文档生成用轻量模型gpt-5.1-codex-mini节省成本。code-agent负责代码审查与重构用gpt-5.2-codex追求质量。实现方式很简单——每个项目目录下放各自的 config.toml# docs-agent/config.toml model gpt-5.1-codex-mini model_context_window 100000 model_max_output_tokens 32000# code-agent/config.toml model gpt-5.2-codex model_context_window 200000 model_max_output_tokens 64000这样两个项目互不干扰切换项目目录就等于切换 Agent 的“大脑”。比在同一个全局配置里反复改 model 字段要优雅得多也更适合直接用脚本批量切换。我在本地就是这么管理多个项目 Agent 的配合 direnv 之类的工具甚至可以做到进入目录自动加载对应环境变量。4. 实操过程与核心环节实现4.1 第一步确认当前生效配置改配置之前先搞清楚当前到底用的哪套配置。我建议按以下顺序排查执行codex --version确认 CLI 版本不同版本对 TOML 的支持程度有差异。有些老版本甚至不识别model_providers。打开~/.codex/config.toml检查全局配置是否存在、是否被注释。在主目录下执行codex --info或codex doctor部分版本支持查看当前生效的模型和配置来源。如果你发现改了 config.toml 但 Agent 行为没变大概率是以下原因之一配置文件路径不对Codex 读的是~/.codex/config.toml不是当前目录下的config.toml。项目级配置覆盖了全局配置你改的是全局但项目里有一份项目级配置。命令参数或环境变量里有显式指定优先级更高。比如你在 shell 里设置了CODEX_MODEL环境变量它可能直接覆盖配置文件。4.2 第二步切换到第三方模型或本地模型说实话Codex 目前对第三方模型的支持还在快速演进中。如果你确实需要接入其他模型我建议先看官方文档里对model_providers的定义再按格式填。下面这个是我实测可用的示例[model_providers.my_llm] name My Local LLM base_url http://127.0.0.1:8000/v1 env_key MY_LLM_API_KEY wire_api responses这段配置的含义是注册一个名为my_llm的 provider指向本地8000端口跑着的推理服务API 格式用 OpenAI 兼容协议。这样在model my_llm/模型名时就能调到本地模型。常见错误是wire_api填错。如果你本地服务用的是/chat/completions就填chat如果是/responses才填responses。填错了会直接报类似这样的错误cc switch local proxy failed while handling codex endpoint /responses.这个报错最近在社区里讨论很多很多人以为是网络问题其实就是 provider 协议不匹配。我一开始也卡在这里后来检查本地推理服务的 API 文档才发现是wire_api写错了。另外要注意base_url后面是否带/v1。很多 OpenAI 兼容协议的服务都需要/v1前缀比如http://127.0.0.1:8000/v1。不带/v1会导致路径拼接错误表现也是请求失败或者 404。4.3 第三步用 AGENTS.md 做一次真实项目演练我来演示一个实际例子。假设我有一个 Python 项目希望 Agent 帮我实现一个带缓存的 HTTP 客户端。我在项目根目录写了一份 AGENTS.md# HTTP 客户端项目 ## 技术栈 - Python 3.12 - httpx - pytest ## 任务约定 - 实现 cache.py 中的 CachedClient 类 - 使用 functools.lru_cache 做内存缓存 - 不引入 Redis 等外部依赖 - 所有方法必须有类型注解和 docstring - 测试文件放在 tests/ 目录命名 test_*.py然后启动 Agentcodex 请实现 CachedClient并补齐测试Agent 会读取项目根目录下的 AGENTS.md按约定实现代码、写测试、补类型注解。整个过程中它能自主判断“该不该加 Redis”因为它读到了“不引入外部依赖”这一条规则。如果没写这条很多模型会自作主张地引入 Redis 或者用requests而不是httpx。这个例子说明一件事AGENTS.md 不是摆设而是能让 Agent 的行为从“随机发挥”变成“按要求执行”的关键。它会显著提升输出的一致性尤其是在你同时使用多个模型时AGENTS.md 是拉齐行为差异的最好工具。4.4 第四步配置校验与常见报错排查最后一步也是最容易被忽略的改完配置后一定要验证。我一般这么做重新打开一个终端确保环境变量生效。因为有些环境变量在旧 shell 里不会自动刷新。直接运行codex看是否正常进入交互模式。故意问一个跟模型能力相关的问题比如“你是什么模型”看返回是否匹配预期。如果接了第三方 provider跑一个最短对话确认/responses或/chat/completions路径正常。如果出现下面这些报错可以参考我的排查经验报错信息可能原因处理方式codex auth token is unavailable未登录或 token 失效执行登录流程或检查环境变量中的 API Keyagent execution terminated due to error.模型输出超长/上下文超限/服务端异常调低model_max_output_tokens检查上下文窗口cc switch local proxy failed while handling codex endpoint /responses.provider 协议或本地代理配置不匹配检查wire_api和base_url确认代理服务正常Connection refused或timeout本地推理服务没起来或端口不对检查服务状态、端口占用、防火墙策略5. 常见问题与实操心得5.1 常见问题速查Q1改了全局 model为什么还是用旧模型检查项目目录下是否有config.toml或.codex/config.toml它在优先级上高于全局配置。另外检查启动命令是否带--model参数以及是否有CODEX_MODEL环境变量。Q2AGENTS.md 不生效Agent 还是乱来先确认 AGENTS.md 文件位置正确项目根目录或~/.codex。再看规则是否写得足够具体。不要写“请遵循最佳实践”这种空话要写“使用 black 格式化”“测试放在tests/目录下”这种可验证的指令。最后如果模型是特别小的本地模型它可能对长上下文的遵循能力较弱这时候建议用稍强一点的模型。Q3本地模型老是超时检查本地服务是否真的起了8000端口base_url是否带/v1以及模型上下文窗口是否设置过小。还有一个常见问题是本地服务并发能力不足Codex 同时发多个请求时会把服务打满建议把并发调低或者加大服务端资源。Q4配置里写中文注释可以吗可以。TOML 支持 UTF-8 注释中文没问题。但建议命令、路径、模型名保持英文。我自己在配置里是中文注释加英文键值混用读起来很清晰。Q5多个项目都需要自定义模型怎么管理最方便用项目级 config.toml 覆盖全局配置每个项目独立一套模型参数。配合脚本一键切换目录变量比每次手动改全局配置高效得多。5.2 我的几条独家心得配置版本化我会把~/.codex/config.toml和项目级AGENTS.md都放进 Git 仓库这样换机器或回滚配置都很方便。唯一要注意的是别把密钥、token 提交进去最好用环境变量引用。比如env_key MY_LLM_API_KEY然后在.env或 shell 配置里设置这个值。从最小配置开始不要一上来就堆几十个参数先跑通一个模型再逐步加model_providers、experimental等高级配置。很多人第一步就卡在 provider 配置上反而忽略了基础模型是否可用。日志是排查神器Codex 运行时的日志里会明确写出当前用的模型、provider、请求路径。遇到诡异问题先翻日志再看配置。我遇到过一次“改了配置但行为没变”的问题最后就是在日志里发现它读的是另一个目录下的配置文件。AGENTS.md 要“常驻”不只是项目初始阶段写一份随着项目演进要持续更新。比如某个依赖版本升级后规则里对应的命令也要同步调整。否则 AGENTS.md 会慢慢变成“过期的规范”Agent 反而被过时规则误导。善用[experimental]区域如果你在配置里看到[experimental]可以试着研究它里面的参数但别直接在生产环境启用。我一般先在测试项目里跑稳再复制到正式项目。6. 扩展把自定义 Agent 配置应用到团队协作这部分算是我最近正在尝试的方向。当你把 Codex 本地自定义 Agent 的配置整理清楚后其实完全可以推广到团队把统一的AGENTS.md模板放进代码仓库根目录所有成员 clone 之后自动生效。把config.toml的 baseline 版本提交到仓库团队成员只需复制到本地并改掉个人 token 相关的环境变量。用脚本一键初始化#!/bin/bash # init-codex.sh mkdir -p ~/.codex cp config.toml.example ~/.codex/config.toml cp AGENTS.md.example ~/.codex/AGENTS.md echo Codex config initialized.这样做的收益很明显新人入职不用再折腾半天配置老手也能保证自己的 Agent 行为和团队规范一致。我实际用过一段时间效果不错的。尤其对于多人协作的仓库AGENTS.md 一旦统一每个成员提交代码的风格都会收敛很多Code Review 的压力会小不少。不过也要提醒一句团队共用配置时别把所有成员都锁死在同一个模型上。基础模型可以统一但个人偏好比如输出长度、上下文窗口可以保留在各自的全局配置里通过优先级机制实现“团队规范 个人自由”的平衡。也就是说仓库里放 project-level 的config.toml只约束模型和必要的 provider 参数个人可以在~/.codex/config.toml里覆盖输出长度等无关紧要的偏好。我自己在实际折腾 Codex 的过程中最大的感受是配置本身并不复杂复杂的是搞清楚优先级和各类文件的作用边界。你花半小时读一遍官方文档不如花十分钟亲手把config.toml从默认改成自定义再写一份项目级AGENTS.md跑一个真实任务很多疑惑会立刻消失。如果这篇文章能帮你少走几条弯路我就很满足了。接下来你可以试着把默认模型切成gpt-5.2-codex再写一份针对自己项目的 AGENTS.md跑一个真实任务试试——你大概率会发现Agent 的“听话程度”比之前高了一个档次。