Codex进阶使用指南：用 AGENTS.md 与 Skill 打造可复用的配置骨架

1. 为什么你的 Codex 用起来总像“一次性工具”很多人用 Codex 的方式还停留在“问一句、复制一段、关掉窗口”。下次遇到同类问题又得从头描述项目背景、技术栈、代码规范、测试命令。这种用法最大的问题不是效率低而是没有沉淀——你每次都在重新教它认识你的项目。Codex 进阶使用的核心思路是把重复出现的规则、流程、工具连接固化下来。具体来说有四层AGENTS.md项目级的长期规则文件Codex 进入这个目录就自动读取相当于给项目配了一份“协作说明书”。Skill可复用的工作流把“每次都要说一遍”的步骤封装成触发即用的能力。Plugin一组 Skill 和工具的打包分发单元适合团队或跨项目复用。MCP连接外部工具和实时数据的通道让 Codex 能访问你授权的资料库、API 或内部系统。这四层能力要真正跑起来前提是有一个稳定的模型接入通道。我实测下来用 TaoToken 统一管理 Key 和 API 地址可以避免在多个配置文件里反复改 base_url 和 token 的麻烦。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 下面会给出完整的 config.toml 和 settings.json 骨架。这篇文章适合已经会用 Codex 基本对话、但想让配置可复用、可迁移、可团队共享的开发者。读完你能拿到一套可以直接复制到本地的配置骨架并逐步验证 AGENTS.md、Skill、MCP 是否真正生效。2. 前置准备TaoToken 通道与本地环境在写配置文件之前先把接入通道理清楚。Codex 的配置文件通常涉及两个地方一个是模型提供方的 API 地址和密钥另一个是 Codex 自身的项目级配置。把这两者分开管理后面换模型或换项目时就不会互相干扰。2.1 获取 API Key打开 TaoToken 控制台创建一个 API Key。建议按用途分 Key比如“本地开发”“CI 测试”“团队共享”各一个方便后续排查和吊销。创建入口在控制台的 API Keys 页面。拿到 Key 之后不要直接写死在项目文件里。推荐用环境变量注入export TAOTOKEN_API_KEYsk-你的keyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key2.2 确认 API 地址TaoToken 的 API 基础地址是https://taotoken.net/api注意这里不带任何查询参数。所有模型请求都走这个 base_url具体路径由 Codex 客户端拼接。2.3 目录结构规划建议在项目根目录建立如下结构后面每一节都会往里面填内容your-project/ ├── AGENTS.md ├── .codex/ │ ├── config.toml │ └── skills/ │ └── review/ │ └── SKILL.md ├── .vscode/ │ └── settings.json └── src/.codex/放 Codex 专属配置.vscode/放编辑器侧配置两者职责不同不要混在一起。3. 可复制配置骨架config.toml 与 settings.json这一节是全文的核心交付。下面两份配置可以直接复制改掉 Key 和路径就能用。3.1 config.toml 完整骨架# .codex/config.toml # Codex 项目级配置模型通道 行为约束 [model] provider taotoken model gpt-4o base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY temperature 0.2 max_tokens 4096 [project] name my-codex-project root . agents_file AGENTS.md skills_dir .codex/skills [behavior] # 学习/审查类任务默认不直接改核心逻辑 default_mode suggest # 修改前先解释意图 explain_before_edit true # 修改后自动运行测试 run_tests_after_edit true test_command npm test [sandbox] # 默认只读写入需确认 read_only false allow_network true allowed_write_paths [src/, tests/, .codex/] [mcp_servers.local_docs] command npx args [-y, modelcontextprotocol/server-filesystem, ./docs]几个关键点说明api_key_env指向环境变量名而不是把 Key 明文写进文件。这样提交到 Git 时不会泄露。default_mode suggest让 Codex 默认只给建议不直接改代码。等你确认流程稳定后可以改成auto。allowed_write_paths限制写入范围避免 Codex 误改配置文件或依赖锁文件。3.2 settings.json 完整骨架{ codex.provider: taotoken, codex.baseUrl: https://taotoken.net/api, codex.apiKeyEnv: TAOTOKEN_API_KEY, codex.model: gpt-4o, codex.agentsFile: AGENTS.md, codex.skillsDir: .codex/skills, codex.autoRunTests: true, codex.testCommand: npm test, codex.explainBeforeEdit: true, codex.sandbox: { readOnly: false, allowNetwork: true, allowedWritePaths: [src/, tests/, .codex/] }, editor.formatOnSave: true, files.exclude: { **/.codex/cache: true } }settings.json 和 config.toml 有重叠字段这是故意的config.toml 给 Codex CLI 用settings.json 给编辑器插件用。两边保持一致避免在终端和编辑器里行为不同。3.3 参数对照表参数config.toml 键settings.json 键作用模型提供方model.providercodex.provider指定走 TaoToken 通道API 地址model.base_urlcodex.baseUrl统一为 https://taotoken.net/api密钥来源model.api_key_envcodex.apiKeyEnv指向环境变量不写明文默认模式behavior.default_mode无对应suggest / auto写入白名单sandbox.allowed_write_pathscodex.sandbox.allowedWritePaths限制可改目录测试命令behavior.test_commandcodex.testCommand修改后自动验证4. AGENTS.md让项目规则自动生效AGENTS.md 是 Codex 进阶使用里性价比最高的一环。它放在项目根目录Codex 启动时自动读取相当于每次对话都自带一份项目说明书。4.1 最小可用模板# 项目协作说明 ## 目标 这是一个 TypeScript 学习项目优先可读性和解释不追求炫技。 ## 常用命令 - 安装npm install - 开发npm run dev - 测试npm test - 检查npm run lint npm run typecheck ## 协作规则 - 学习练习默认使用提示模式不直接完成核心题目。 - 修改前先解释意图修改后运行相关测试。 - 不引入新依赖除非先说明必要性并获得同意。 - 保留我的注释和无关改动。 ## 完成定义 - 行为正确 - 测试通过 - 我能解释关键实现 - 记录一个边界情况和一个替代方案。4.2 验证 AGENTS.md 是否生效写完之后在项目目录里启动 Codex问一个和规则相关的问题请说明你当前读取到的项目规则以及默认协作模式是什么。如果配置正确Codex 会复述 AGENTS.md 里的“提示模式”“修改前先解释”等条目。如果它答不上来检查两点一是 AGENTS.md 是否在项目根目录二是 config.toml 里agents_file路径是否写对。4.3 常见写法误区不要把 AGENTS.md 写成百科全书。它应该只放每次都需要的规则。项目背景、架构文档这类内容放到单独的 docs 目录通过 MCP 或手动引用按需加载。规则文件越长模型越容易忽略其中某几条。5. Skill 与 MCP把重复流程固化下来AGENTS.md 解决“规则复用”Skill 解决“流程复用”MCP 解决“数据接入”。5.1 一个可用的 Skill 骨架在.codex/skills/review/SKILL.md里写--- name: code-review description: 对指定文件做分层代码审查先只读分析再给修改建议 trigger: 当用户说“审查这个文件”或“review”时触发 --- # 代码审查 Skill ## 步骤 1. 读取目标文件不修改。 2. 按正确性、边界、可读性、性能四类列出问题。 3. 每次只指出一个最高优先级问题。 4. 给提示不给完整实现。 5. 等用户修复后重新验证。 ## 输出格式 - 问题位置 - 问题类型 - 为什么影响正确性或可维护性 - 一个修改方向触发方式是在对话里说“审查 src/utils.ts”Codex 会按 SKILL.md 定义的步骤执行。5.2 MCP 接入本地文档config.toml 里已经配了一个 filesystem MCP指向./docs。启动后可以这样验证请通过 MCP 读取 docs/ 目录下的文件列表并总结每个文件的主题。如果返回了真实文件列表说明 MCP 通道打通。如果报错检查npx是否可用、路径是否存在、以及allow_network是否为 true。5.3 Skill、Plugin、MCP 的分工能力解决什么典型场景AGENTS.md项目规则复用每次对话都要遵守的约束Skill工作流程复用代码审查、论文阅读、错题归因Plugin一组能力的打包分发团队共享一套 Skill 工具MCP外部数据和工具接入读取私有文档、查询内部 API顺序建议先写 AGENTS.md再把重复三次以上的流程做成 Skill需要访问外部数据时再接 MCP最后才考虑打包成 Plugin。6. 验证请求与成功结果配置写完不算完要实际发一次请求确认整条链路通。6.1 最小验证请求在项目目录启动 Codex输入请读取 AGENTS.md列出当前项目的测试命令和默认协作模式。 然后通过 MCP 列出 docs/ 下的文件。预期结果应该包含测试命令为npm test默认模式为提示模式suggestdocs/ 下的真实文件列表6.2 用 curl 直接验证 API 通道如果怀疑是 Codex 配置问题而不是通道问题可以先用 curl 单独测 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }返回里有choices字段且内容为 OK说明 Key 和地址都没问题。这时候如果 Codex 还报错问题就在本地配置文件。6.3 验证 Skill 触发输入“审查 src/index.ts”观察 Codex 是否按 SKILL.md 的步骤走先只读、再分类列问题、每次只给一个。如果它直接开始改代码说明 Skill 没被加载检查skills_dir路径和 SKILL.md 的 frontmatter 格式。7. 本篇常见错误排查7.1 报错401 Unauthorized最常见原因是环境变量没生效。检查echo $TAOTOKEN_API_KEY如果为空说明当前终端会话没加载。重新 export 一次或者写进 shell 配置文件。注意 config.toml 里写的是api_key_env TAOTOKEN_API_KEY是变量名不是变量值别把 Key 直接填进去。7.2 报错base_url 拼接错误如果看到请求地址变成https://taotoken.net/api/v1/v1/chat/completions这类重复路径说明客户端自己又拼了一次/v1。把 config.toml 里的base_url确认为https://taotoken.net/api不要带尾部斜杠也不要手动加/v1。7.3 AGENTS.md 不生效三个检查点文件是否在项目根目录config.toml 里agents_file是否指向正确文件名启动 Codex 时的工作目录是否是项目根目录。在子目录启动会导致读不到。7.4 Skill 不触发SKILL.md 的 frontmatter 必须有name、description、trigger三个字段缺一个都可能加载失败。另外skills_dir要指向 skills 的父目录不是某个具体 Skill 目录。7.5 MCP 连接超时先确认npx能正常运行npx -y modelcontextprotocol/server-filesystem ./docs如果这条命令本身报错说明是 Node 环境问题跟 Codex 无关。如果命令能跑但 Codex 里连不上检查allow_network是否为 true以及路径是否是绝对路径或相对于项目根目录的正确路径。7.6 修改被沙箱拦截如果 Codex 提示无法写入某文件检查allowed_write_paths是否包含该目录。默认只允许src/、tests/、.codex/要改其他位置需要手动加进去。这是有意设计的保护不建议直接关掉沙箱。排查顺序建议先 curl 验通道再验 AGENTS.md再验 Skill最后验 MCP。逐层排除不要一上来就怀疑最复杂的部分。接入配置和 API Key 管理可以在 https://taotoken.net/api-keys 处理模型对话验证用 https://taotoken.net/chat 如果要把这套配置用于长期编码和 Agent 任务可以看 Coding Plan 页面 https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc Claude Code 相关配置参考 https://taotoken.net/claude-code 。