1. 为什么我要折腾 Codex 的本地 Agent 配置Codex 这个工具刚上手的时候很多人以为它就是个命令行版的代码补全敲个codex然后问它问题就完事了。但真正用进去之后你会发现它最值钱的地方其实是本地自定义 Agent 与模型配置这一层——也就是你能不能把 Codex 调教成一个懂你项目、懂你习惯、懂你技术栈的专属助手。我最初接触 Codex 的时候踩的第一个坑就是默认配置下它对我项目的目录结构一无所知每次都要手动把上下文贴进去效率极低。后来才搞明白Codex 提供了一套基于TOML 配置文件加AGENTS.md 项目说明文件的机制让你可以定义 Agent 的行为、绑定不同的模型、设置优先级甚至针对不同项目切换不同的配置方案。这套东西解决的核心问题是让 Codex 从通用问答工具变成项目专属 Agent。你可以在 TOML 里定义模型提供商、API 端点、默认模型、超时参数在 AGENTS.md 里写清楚项目的技术栈、目录约定、代码规范、常用命令。Codex 在启动时会按优先级依次加载这些配置最终拼出一个完整的运行时上下文。这篇文章适合谁看如果你已经在用 Codex CLI但还停留在每次手动喂上下文的阶段那这篇就是写给你的。如果你刚开始接触 Codex想从安装到配置一次搞明白也能跟着走。我会把 TOML 的字段含义、AGENTS.md 的写法、配置优先级规则、模型切换的实操步骤全部拆开讲并且把我踩过的坑和排查思路一并放出来。需要提前说明的是下面涉及的具体路径和字段名我是基于 Codex 常见版本的实践总结不同版本可能有细微差异你以自己本地codex --version和官方文档为准但整体思路是通用的。2. Codex 配置体系的整体设计与优先级逻辑2.1 三层配置结构全局、项目、会话Codex 的配置不是单一文件而是分层的。理解这个分层是后面所有操作的基础。我把它归纳成三层全局配置层位于用户主目录下的配置目录通常是~/.codex/config.tomlWindows 下是%USERPROFILE%\.codex\config.toml。这一层定义的是你所有项目共用的默认值比如默认模型、默认提供商、全局超时。项目配置层位于项目根目录下的.codex/config.toml或者项目级的AGENTS.md。这一层只对当前项目生效用来覆盖全局配置。比如你某个项目必须用某个特定模型就在这里改。会话/环境变量层通过命令行参数或环境变量传入的临时配置优先级最高只对当前这次会话生效。比如你临时想切个模型试试效果直接用命令行参数覆盖就行。为什么要这么设计因为实际工作中你的需求是分层的。你可能有 80% 的项目用同一套默认配置但剩下 20% 有特殊要求。如果只有一层配置你要么每次手动改要么每个项目复制一份完整配置维护成本极高。分层之后全局层管共性项目层管差异会话层管临时实验各司其职。2.2 优先级规则的底层逻辑优先级这件事说白了就是谁覆盖谁。Codex 的加载顺序是从宽到窄后者覆盖前者。我用一个表格把常见配置来源的优先级从低到高列出来优先级配置来源作用范围典型用途1最低内置默认值全局兜底保证不配置也能跑2全局 config.toml所有项目默认模型、通用参数3项目 .codex/config.toml当前项目项目专属模型与参数4项目 AGENTS.md当前项目项目上下文与行为约定5环境变量当前会话临时覆盖密钥、端点6最高命令行参数当前会话临时切换模型、调试这里有个容易搞混的点AGENTS.md 和 config.toml 不是同一类东西。config.toml 管的是机器怎么跑比如用哪个模型、连哪个端点、超时多少AGENTS.md 管的是Agent 怎么想比如项目用什么框架、代码风格是什么、有哪些禁忌。它们不冲突而是互补。但在优先级上AGENTS.md 里的某些指令性内容会覆盖 config.toml 里的默认行为设定因为它是更贴近具体项目的描述。提示不要试图用 AGENTS.md 去改模型参数那是 config.toml 的活。AGENTS.md 写的是自然语言的项目说明Codex 会把它作为系统提示的一部分注入。2.3 为什么用 TOML 而不是 JSON 或 YAML这个问题我被问过好几次。TOML 的优势在于可读性强、支持注释、层级清晰、解析严格。JSON 不支持注释你没法在配置里写这行是干嘛的YAML 虽然支持注释但缩进敏感一个空格错了就报错而且复杂嵌套时容易看花眼。TOML 的[section]语法天然适合配置文件的组织。比如你要配多个模型提供商每个提供商一个 section一目了然。而且 TOML 的类型系统比 YAML 严格不容易出现字符串被解析成布尔值这种坑。对于 Codex 这种需要频繁手改配置的场景TOML 是最优解。3. TOML 配置文件的核心字段与实操写法3.1 最小可用配置长什么样先给你一个能跑起来的最小配置放在~/.codex/config.tomlmodel gpt-4o provider openai [providers.openai] api_key_env OPENAI_API_KEY base_url https://api.openai.com/v1这几行的含义默认模型是gpt-4o默认提供商是openai提供商的密钥从环境变量OPENAI_API_KEY读取端点走官方地址。注意api_key_env这个字段——它填的是环境变量的名字不是密钥本身。这是安全设计避免你把密钥硬编码进配置文件然后不小心提交到仓库。我见过有人直接把 key 写进 config.toml结果推到公开仓库第二天 key 就被刷爆了。这个坑千万别踩。3.2 多提供商配置与模型切换实际工作中你往往不止用一个模型。比如日常用某个模型遇到复杂推理任务切另一个成本敏感时再切一个。Codex 支持在 TOML 里配多个提供商model gpt-4o provider openai [providers.openai] api_key_env OPENAI_API_KEY base_url https://api.openai.com/v1 [providers.deepseek] api_key_env DEEPSEEK_API_KEY base_url https://api.deepseek.com/v1 default_model deepseek-chat [providers.local] api_key_env LOCAL_API_KEY base_url http://localhost:8000/v1 default_model local-model配好之后切换模型有两种方式。一种是改model和provider字段另一种是命令行临时指定。我一般用后者做实验确认好用之后再写进配置。这里有个细节default_model是提供商级别的默认模型当你在顶层model里没指定、或者指定的模型在当前提供商下不存在时会回退到default_model。这个回退机制很实用但也很容易让人困惑——明明改了顶层 model 却没生效八成是提供商那边有默认值在兜底。3.3 超时、重试与并发参数网络请求相关的参数是配置里最容易被忽略但最影响体验的部分。默认超时往往偏短遇到大上下文或者慢端点就会频繁失败。我的常用配置[request] timeout_seconds 120 max_retries 3 retry_delay_seconds 2 stream truetimeout_seconds设 120 秒是因为有些复杂任务模型思考时间长设太短会中途断掉。max_retries 3配合retry_delay_seconds 2能扛住偶发的网络抖动。stream true开启流式输出你能看到模型逐字返回体验上不会觉得卡死。注意重试次数不是越多越好。如果端点本身有问题重试只会浪费时间。我一般设 3 次超过就说明是配置或网络问题该去排查而不是继续等。3.4 沙盒与执行权限配置Codex 作为 Agent有时候需要执行命令、读写文件。这部分权限控制很关键配错了要么啥都干不了要么风险失控。常见配置[sandbox] mode workspace-write allowed_paths [./src, ./tests] deny_paths [./secrets, ./.env]mode常见取值有只读、工作区可写、完全放行几种。我强烈建议默认用workspace-write只允许在项目目录内写并且用deny_paths明确排除敏感目录。这样即使 Agent 判断失误也不会把密钥文件改掉。我踩过的一个坑早期图省事把 mode 设成完全放行结果 Agent 在重构时把配置文件也顺手优化了导致环境变量全丢。从那以后我老老实实配deny_paths。4. AGENTS.md 的写法与项目上下文注入4.1 AGENTS.md 到底解决什么问题config.toml 解决的是怎么连模型AGENTS.md 解决的是模型怎么理解你的项目。它是一个放在项目根目录的 Markdown 文件Codex 启动时会自动读取把内容作为系统提示的一部分注入。为什么需要它因为模型再强也不知道你的项目约定。比如你的项目用 pnpm 而不是 npm用 vitest 而不是 jest目录结构是 feature-based 而不是 layer-based。这些信息如果不告诉模型它给出的建议就会水土不服。AGENTS.md 就是把这些隐性知识显性化。4.2 一份实用的 AGENTS.md 模板我用了大半年迭代出来的模板大概长这样# 项目说明 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 包管理pnpm禁止使用 npm/yarn - 测试vitest testing-library - 样式Tailwind CSS ## 目录约定 - src/features/ 按功能模块组织 - src/shared/ 跨模块复用代码 - src/lib/ 纯工具函数无副作用 ## 代码规范 - 组件用函数式禁止 class 组件 - 状态管理优先用 hooks复杂场景用 zustand - 所有导出函数必须有 JSDoc 注释 - 提交前必须跑 pnpm lint 和 pnpm test ## 常用命令 - 开发pnpm dev - 构建pnpm build - 测试pnpm test - 类型检查pnpm typecheck ## 禁忌 - 不要修改 package.json 里的依赖版本 - 不要动 src/legacy/ 目录那是待迁移代码 - 不要引入新的全局状态库这份文件的关键在于具体。不要写遵循最佳实践这种废话要写用 pnpm 不用 npm这种可执行的约定。模型看到具体指令才会照做看到空泛描述只会自由发挥。4.3 AGENTS.md 的层级与继承AGENTS.md 支持层级。你可以在项目根目录放一份在子目录再放一份。Codex 会从当前工作目录向上查找把找到的所有 AGENTS.md 合并。子目录的配置覆盖父目录的同名项。这个机制适合 monorepo。根目录的 AGENTS.md 写全局约定各个 package 目录下的 AGENTS.md 写该 package 的特殊约定。比如根目录说用 pnpm某个 package 说这个包用 npm 因为历史原因Codex 在那个 package 下工作时就会用 npm。提示层级不要超过三层否则合并逻辑会变得难以预测。我一般就根目录加一层子目录够用了。4.4 写 AGENTS.md 的三个经验第一用命令式而非描述式。写使用 pnpm 安装依赖比写项目使用 pnpm更有效因为前者是明确指令。第二把禁忌单独列一节。模型对不要做什么的敏感度低于要做什么单独列出来能提高遵守率。第三定期更新。项目演进了AGENTS.md 不更新模型就会按过时约定干活。我一般每个 sprint 结束 review 一次。5. 完整实操从零配置一个项目专属 Agent5.1 环境准备与安装确认先确认 Codex 装好了。不同平台安装方式不同我以常见的命令行安装为例codex --version能输出版本号就说明装好了。如果提示找不到命令检查 PATH 或者重新安装。Windows 桌面版的话确认安装包来源可靠装完在终端里同样用codex --version验证。安装完成后先跑一次codex进入交互模式随便问个问题确认能正常连通模型。这一步很重要因为后面配置出问题时你需要知道是本来能通现在不通还是从来没通过。5.2 创建全局配置在用户主目录创建配置目录和文件mkdir -p ~/.codex touch ~/.codex/config.toml然后把前面 3.1 节的最小配置写进去。设置环境变量export OPENAI_API_KEY你的密钥Windows 下用setx OPENAI_API_KEY 你的密钥然后重开终端生效。验证配置是否被读取跑codex后问它你当前用的是什么模型如果回答和你配置的一致说明全局配置生效了。5.3 创建项目级配置与 AGENTS.md进入你的项目根目录cd /path/to/your/project mkdir -p .codex touch .codex/config.toml touch AGENTS.md项目级 config.toml 里只写需要覆盖全局的部分。比如这个项目要用不同的模型model deepseek-chat provider deepseekAGENTS.md 按 4.2 节的模板填。填完之后在项目目录下跑codex问它这个项目用什么包管理器如果回答 pnpm说明 AGENTS.md 被正确注入了。5.4 验证优先级是否按预期工作这是最关键的一步。我设计了一个验证流程全局配置写model gpt-4o项目配置不写 model跑 codex 问模型应该回答 gpt-4o。项目配置写model deepseek-chat再跑应该回答 deepseek-chat。命令行加参数覆盖比如codex --model gpt-4o应该回答 gpt-4o。三步都符合预期说明优先级链路是通的。任何一步不对就去检查对应层级的文件路径和字段名。5.5 参数计算超时和重试怎么定超时和重试不是拍脑袋定的。我的计算方法先测正常请求的 P95 延迟。跑 20 次典型请求记录耗时取第 19 个的值。假设是 30 秒。那么timeout_seconds设为 P95 的 3 到 4 倍也就是 90 到 120 秒。这样既能容忍慢请求又不会在真挂掉时等太久。重试次数用可用性反推。假设单次请求成功率 95%重试 3 次后整体成功率是1 - 0.05^4 ≈ 99.99%。如果单次成功率只有 80%重试 3 次也只有1 - 0.2^4 99.84%这时候该去查为什么单次成功率这么低而不是加更多重试。6. 常见问题与排查技巧实录6.1 配置不生效的排查顺序配置改了没反应按这个顺序查排查项检查方法常见原因文件路径ls ~/.codex/config.toml路径拼错、目录不存在文件语法TOML 解析器验证引号不配对、section 重复环境变量echo $OPENAI_API_KEY没 export、拼写错误优先级覆盖逐层注释测试高层配置覆盖了低层版本差异codex --version字段名在新版本变了我遇到最多的是环境变量问题。尤其是 Windows 下setx之后没重开终端变量根本没加载。还有一次是密钥里带了空格复制的时候没注意排查了半天。6.2 模型切换后行为异常切了模型之后同样的 prompt 输出质量差很多或者格式完全不对。这通常不是配置问题而是不同模型对系统提示的响应方式不同。有的模型对 AGENTS.md 里的指令遵循度高有的需要更明确的格式约束。我的做法是换模型后先跑几个标准测试用例确认基本行为符合预期再投入实际使用。如果某个模型对 AGENTS.md 响应差就在项目配置里针对它单独调整提示策略。6.3 请求超时与连接失败超时和连接失败要分开看。超时是连上了但响应慢连接失败是压根没连上。超时的话先加timeout_seconds再考虑换端点。连接失败的话检查base_url是否正确、网络是否可达、密钥是否有效。我一般用 curl 直接测端点curl -X POST https://api.openai.com/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o,messages:[{role:user,content:hi}]}curl 能通但 codex 不通那就是 codex 配置问题curl 也不通那就是网络或密钥问题。这个二分法能快速定位。6.4 沙盒权限导致的执行失败Agent 想执行命令但被拦了报权限错误。先看sandbox.mode是不是太严再看allowed_paths有没有包含目标路径。我建议不要直接放开到完全权限而是精确添加需要的路径。比如 Agent 要写日志到./logs就把./logs加进allowed_paths而不是把整个项目放开。6.5 常见问题速查表现象可能原因解决方向提示找不到配置文件路径错误确认~/.codex/存在密钥无效环境变量未加载重开终端或检查 export模型不存在提供商不支持该模型查提供商文档或换模型输出被截断超时太短调大timeout_secondsAGENTS.md 没生效文件名或位置错误确认在项目根目录且拼写正确切换模型无效优先级覆盖检查高层配置请求频繁失败端点不稳定换端点或加重试执行命令被拒沙盒限制调整 mode 或 allowed_paths7. 我踩过的坑和几条实在建议配置这东西文档看一遍觉得懂了真上手还是各种问题。我把自己踩过的坑列几条你对照着避一避。第一条别把密钥写进配置文件。这个前面说过但值得再说一遍。用环境变量用环境变量用环境变量。重要的事说三遍。第二条改配置前先备份。我有次手抖把 config.toml 改坏了又没备份只能从头重写。现在我的习惯是改之前cp config.toml config.toml.bak出问题直接还原。第三条AGENTS.md 要短而精。我一开始写了两千多字结果模型反而抓不住重点。后来精简到几百字只留最关键的约定效果反而更好。上下文是有成本的别浪费在废话上。第四条优先级验证要形成习惯。每次改完配置跑一遍 5.4 节的三步验证。花两分钟省得后面排查半小时。第五条不同项目用不同配置别偷懒。我见过有人全局配置一套走天下结果在需要特定模型的项目里各种别扭。项目级配置就是干这个的该用就用。最后分享一个小技巧如果你不确定某个字段名对不对可以在 codex 里直接问它config.toml 里配置超时的字段叫什么它一般能答上来。这比翻文档快尤其是版本更新后字段名变了的时候。当然最终还是要以官方文档为准模型也可能记错。这套配置体系我用了大半年从最初的能跑就行到现在每个项目都有精细化的 Agent 配置效率提升是实打实的。核心就一句话把重复的上下文和约定固化到配置里让每次对话都从更高的起点开始。你把这套跑通之后会发现 Codex 完全不是刚上手时那个样子了。