最近我一直在折腾 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 更接近软约束，它会作为上下文注入给 Agent，Agent 在生成回答时会参考这些规则，但不保证 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 第一步：确认当前生效配置

改配置之前，先搞清楚当前到底用的哪套配置。我建议按以下顺序排查：

1. 执行codex --version，确认 CLI 版本，不同版本对 TOML 的支持程度有差异。有些老版本甚至不识别model_providers。
2. 打开~/.codex/config.toml，检查全局配置是否存在、是否被注释。
3. 在主目录下执行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`

然后启动 Agent：

codex "请实现 CachedClient，并补齐测试"

Agent 会读取项目根目录下的 AGENTS.md，按约定实现代码、写测试、补类型注解。整个过程中它能自主判断“该不该加 Redis”，因为它读到了“不引入外部依赖”这一条规则。如果没写这条，很多模型会自作主张地引入 Redis 或者用requests而不是httpx。

这个例子说明一件事：AGENTS.md 不是摆设，而是能让 Agent 的行为从“随机发挥”变成“按要求执行”的关键。它会显著提升输出的一致性，尤其是在你同时使用多个模型时，AGENTS.md 是拉齐行为差异的最好工具。

4.4 第四步：配置校验与常见报错排查

最后一步，也是最容易被忽略的：改完配置后一定要验证。我一般这么做：

1. 重新打开一个终端，确保环境变量生效。因为有些环境变量在旧 shell 里不会自动刷新。
2. 直接运行codex，看是否正常进入交互模式。
3. 故意问一个跟模型能力相关的问题，比如“你是什么模型”，看返回是否匹配预期。
4. 如果接了第三方 provider，跑一个最短对话，确认/responses或/chat/completions路径正常。

如果出现下面这些报错，可以参考我的排查经验：

5. 常见问题与实操心得

5.1 常见问题速查

Q1：改了全局 model，为什么还是用旧模型？

检查项目目录下是否有config.toml或.codex/config.toml，它在优先级上高于全局配置。另外检查启动命令是否带--model参数，以及是否有CODEX_MODEL环境变量。

Q2：AGENTS.md 不生效，Agent 还是乱来？

先确认 AGENTS.md 文件位置正确（项目根目录或~/.codex）。再看规则是否写得足够具体。不要写“请遵循最佳实践”这种空话，要写“使用 black 格式化”“测试放在tests/目录下”这种可验证的指令。最后，如果模型是特别小的本地模型，它可能对长上下文的遵循能力较弱，这时候建议用稍强一点的模型。

Q3：本地模型老是超时？

检查本地服务是否真的起了8000端口，base_url是否带/v1，以及模型上下文窗口是否设置过小。还有一个常见问题是本地服务并发能力不足，Codex 同时发多个请求时会把服务打满，建议把并发调低或者加大服务端资源。

Q4：配置里写中文注释可以吗？

可以。TOML 支持 UTF-8 注释，中文没问题。但建议命令、路径、模型名保持英文。我自己在配置里是中文注释加英文键值混用，读起来很清晰。

Q5：多个项目都需要自定义模型，怎么管理最方便？

用项目级 config.toml 覆盖全局配置，每个项目独立一套模型参数。配合脚本一键切换目录变量，比每次手动改全局配置高效得多。

5.2 我的几条独家心得

1. 配置版本化：我会把~/.codex/config.toml和项目级AGENTS.md都放进 Git 仓库，这样换机器或回滚配置都很方便。唯一要注意的是别把密钥、token 提交进去，最好用环境变量引用。比如env_key = "MY_LLM_API_KEY"，然后在.env或 shell 配置里设置这个值。
2. 从最小配置开始：不要一上来就堆几十个参数，先跑通一个模型，再逐步加model_providers、experimental等高级配置。很多人第一步就卡在 provider 配置上，反而忽略了基础模型是否可用。
3. 日志是排查神器：Codex 运行时的日志里会明确写出当前用的模型、provider、请求路径。遇到诡异问题，先翻日志，再看配置。我遇到过一次“改了配置但行为没变”的问题，最后就是在日志里发现它读的是另一个目录下的配置文件。
4. AGENTS.md 要“常驻”：不只是项目初始阶段写一份，随着项目演进要持续更新。比如某个依赖版本升级后，规则里对应的命令也要同步调整。否则 AGENTS.md 会慢慢变成“过期的规范”，Agent 反而被过时规则误导。
5. 善用[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 的“听话程度”比之前高了一个档次。