一次配好 Codex：AGENTS.md、config.toml、Skills 与 MCP

2026年10月30日 更新：2026年10月30日 · 作者 Taylor Yang · #开发者工具 #智能体开发 #工作流程

把项目规则写进 AGENTS.md，把个人偏好存进 config.toml，再按需接 Skills 和 MCP，附 2026 年官方的精简建议和可直接改的模板。

💡 **这篇解决什么问题：**每开一个新会话，Codex 都像新来的员工，项目怎么启动、测试怎么跑、哪些目录不能动，都得重新交代一遍。这篇讲怎么用 AGENTS.md 存项目规则、用 config.toml 存个人偏好、用 Skills 和 MCP 扩展能力，一次配好，长期复用。也会讲清楚哪些旧教程的写法已经过时。

更多 Codex 文章：省点力 · Codex 小类

大家卡在哪里

一句话分工：稳定的偏好放进配置，项目背景放进文档。

一、AGENTS.md：写给 Codex 的项目入职手册

它是什么

三种放法

① 项目级：在 Codex 里运行 /init，会在当前目录自动生成一份 AGENTS.md，不用从空白文件开始写。生成后自己再补几句，比如：

本项目使用 pnpm
开发命令是 pnpm dev
测试命令是 pnpm test
不要修改 dist 和 generated 目录
所有接口请求都走 src/lib/api.ts

这几句很值钱，你不用每次重新教育 Codex。/init 只是搭个脚手架，真正有价值的是你写进去的项目规则。

② 全局级：在 Codex 主目录（~/.codex）里放一份 AGENTS.md，对所有项目生效。适合写你在所有项目里都希望它遵守的习惯，比如固定使用某类工具、用某种方式回答、优先查官方文档、调用特定 MCP、遵循统一代码风格、每次修改后都运行检查。

③ 子目录级：一个仓库里同时有前端、后端和多个服务，可以在对应子目录各放一份。根目录那份讲整个项目，子目录那份补充局部背景。Codex 进入某个子目录工作时，就知道自己在处理哪部分、有哪些特别要注意的地方。

短期、项目专属的要求放项目自己的 AGENTS.md，长期、通用的规则放全局文件，分工更清楚。

里面写什么

先写清项目里真正会影响执行的这些信息：

**写具体路径，别写笼统描述。**与其只写“代码在 src 目录”，不如写“前端页面放在 src/pages，接口请求放在 src/api，修改完以后先运行 npm run lint 和 npm test”。

写 AGENTS.md 的 6 条原则

  1. 保持简短、聚焦。OpenAI 看过的大多数 AGENTS.md 都不到 100 行。规则太多，Codex 反而不知道该优先关注什么；规则之间还有冲突的话，它会花很多时间判断该听哪一条。
  2. 让它能自己完成检查闭环。优先写清楚怎么检查：代码检查工具、相关测试、构建、看报错回去修。如果你发现每次都得手动告诉它怎么检查，就把办法写进去，比如运行命令确认能不能编译，或者截图看看页面实际长什么样。每写一项要求，就想清楚怎么检查它有没有做到，没有验证途径的要求，Codex 很难确认自己做对了没有。
  3. 从简单开始。先放最必要的：项目做什么、代码在哪里、怎么构建、怎么测试、最常用的几个命令。用一段时间后，再把那些你反复解释、每次解释都很啰嗦的东西补进去，比如团队习惯、特殊目录规则、某类功能的实现步骤。这样文件会一直贴近真实工作，不会变成一份看起来完整、实际上没人维护的文档。
  4. 持续更新。它犯了某个错误、总被同一个项目细节绊住，就把解决办法记下来。比如你看着 Codex 花了很久才推断出运行测试的命令，就把这条命令加进去，下次它会快很多。优先记录：经常用的命令、容易踩坑的地方、某类任务的特殊要求、能快速验证结果的方法。每补一条规则，都配上怎么检查。
  5. 主文件只放通用信息，细节拆到专门文档。AGENTS.md 每次都会进上下文，适合放项目做什么、代码在哪、怎么构建测试、最常用的工作方式。某类任务的详细步骤拆到其他 Markdown 文件里，比如 execplans.md（大型任务怎么规划）、frontend.md（前端任务的做法）、architecture.md（架构安排）、code-review-guidelines.md（团队审查标准，见 Codex 改代码不翻车：权限、分支、Diff、测试和 Code Review）。在 AGENTS.md 里加一个“任务专门文档”部分，写明什么任务看哪个文件。这叫逐步发现：先读简短总览，再按任务找具体资料，主文件就像一张目录。
  6. 定期审视每一条。见下一节。

2026 年的新提醒：给更强的模型松绑

OpenAI 在 2026 年 9 月发布的 Rethinking Skills and Prompts for GPT-6 Astra 里提醒：模型越来越强，过去需要手把手教的东西，现在很多不需要了。过去一年你为了让模型做对事，可能积累了大量指令，每次换模型都值得重新检查一遍。

写法例子效果
不好Before every edit, read architecture.md, database.md, and deployment.md.每次改动都读三份文档，烧上下文、拖慢速度
好Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.按场景指路，需要时才读

指向文档本身仍然有用，只要是按场景指路就行。文档本身也要保持更新。

The local tests use disposable fixtures and have no production access. Run them, fix failures caused by the requested change, and rerun affected tests without asking for approval at each step.

（本地测试使用一次性测试数据，没有生产环境权限。运行它们，修复由本次改动引起的失败，并重新运行受影响的测试，每一步都不用请求批准。）

这和前面的“检查闭环”冲突吗？不冲突。写清楚怎么检查（具体命令、截图方法）仍然有用；可以删掉的是“每次都必须先跑测试”这类督促语气。如果仓库里的说明也会被其他人、其他模型（比如 Sol、Luna）使用，就要考虑他们还需不需要这些提醒。

三份可以直接改的模板

模板一：Next.js + pnpm

# AGENTS.md

## 项目说明
这是一个 Next.js 项目，使用 pnpm。

## 常用命令
- 安装依赖：pnpm install
- 本地开发：pnpm dev
- Lint：pnpm lint
- 测试：pnpm test
- 构建：pnpm build

## 修改规则
- 不要改数据库 schema，除非用户明确要求。
- 不要新增依赖，除非说明理由。
- 修改前先读 README 和 package.json。
- 完成后必须说明改了哪些文件，以及运行了哪些命令。

这类文件本质上是给 AI 的项目 SOP。用久了你会发现，真正拉开差距的不是某一次 prompt 写得多漂亮，而是项目有没有沉淀出一套稳定规矩。

模板二：Python 小项目

最简版只要 4 行：

# 项目规范
- 语言：Python 3.11+
- 代码风格：PEP 8
- 测试框架：pytest
- 注释：中文注释

新手更完整的版本：

# AGENTS.md

## 项目说明
这是一个 Python 项目，主要用于练习小游戏开发。

## 开发规范
- 使用 Python 3.11+
- 代码保持简单，优先可读性
- 新增功能时同步更新 README
- 修改代码后尽量运行测试或启动程序验证

## 交互偏好
- 先解释修改思路，再改代码
- 涉及删除文件、重构目录、安装依赖时先询问
- 回复使用中文

## Codex 特定配置
- 权限模式：自动审查（关键操作需确认）
- 默认模型：qwen3.6-plus（或 gpt-5.5）
- 技能路径：./.codex/skills（如有）

注意：最后“Codex 特定配置”这一段只是写给模型看的文字说明。权限模式、默认模型真正生效，要在 config.toml 或界面里设置（见下文）。

模板三：英文版

# Project Guide for Codex

## Commands
Install: pnpm install
Dev: pnpm dev
Test: pnpm test
Lint: pnpm lint
Build: pnpm build

## Rules
Do not edit dist/
Do not edit generated files
Keep changes minimal
Run tests after touching business logic
Use existing components before creating new ones

## Architecture
API clients live in src/lib/api
Shared UI components live in src/components
Route pages live in src/pages
Auth logic lives in src/auth

## Before finishing
Explain changed files
Mention tests run
Mention tests not run

二、config.toml：存你的个人偏好

放在哪里，怎么打开

配置优先级（从高到低）

  1. 命令行参数和 --config 覆盖；
  2. 项目配置 .codex/config.toml，从项目根目录到当前工作目录，越近越优先（仅限受信任项目）；
  3. 用 --profile 名称 选中的配置档（~/.codex/名称.config.toml）；
  4. 用户配置 ~/.codex/config.toml；
  5. 登录的工作区由云端下发的默认配置；
  6. 系统配置（Unix 上是 /etc/codex/config.toml）；
  7. 内置默认值。

公司管理的电脑上，组织还可能用 requirements.toml 强制限制，比如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"。所以网上教程里的某些配置，你那边可能根本不生效。

最常改的几项

# 默认模型
model = "gpt-5.6"

# 推理强度
model_reasoning_effort = "high"

# 审批策略：需要更高权限时才停下来问
approval_policy = "on-request"

# 沙箱：可以改当前工作区，不能随意写到外面
sandbox_mode = "workspace-write"

# 沟通风格：friendly / pragmatic / none
personality = "friendly"

终端快捷键（tui.keymap）：

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

设成空列表就是解绑这个操作。

命令环境变量（shell_environment_policy）：控制哪些环境变量会传给 Codex 运行的命令。

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

这里有个容易误会的点：ignore_default_excludes 默认是 true，也就是默认不会自动过滤名字里带 KEY、SECRET、TOKEN 的变量。想让它自动过滤，要设成 false。

日志目录：

log_dir = "/absolute/path/to/codex-logs"

显式设置 log_dir 后，还会在该目录生成纯文本的 codex-tui.log。只想临时用一次，可以：

codex -c log_dir=./.codex-log

排查故障时日志很有用，见 Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错。

网页搜索：确认当前版本的配置

现在用顶层的 web_search 设置：

web_search = "cached"      # 默认：从搜索缓存返回结果
# web_search = "indexed"   # 只有搜索索引放行时才访问外部网页
# web_search = "live"      # 抓取最新网页数据（等同于 --search）
# web_search = "disabled"  # 关闭网页搜索
开启网页搜索，查找关于 Next.js 15 的最新文章，并把当前文章放到页脚。

profiles：一键切换工作状态

同一份配置可以定义多个配置档。比如建一个 fast，用最快的模型和较低的推理强度，专门处理追求速度的任务。启动时加上 --profile fast 就能用。配置档文件是 ~/.codex/fast.config.toml，按官方建议，共用的默认值放在 config.toml，配置档文件只写和默认不同的那几项。

功能开关 [features]

开关默认成熟度作用
appstrue稳定启用 App（连接器）集成
goalstrue稳定持久目标和自动继续（见 Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度）
hookstrue稳定生命周期 hooks（hooks.json 或内联 [hooks]）
fast_modetrue稳定启用 Fast 模式和 service_tier = "fast"
memoriesfalse实验启用记忆功能
multi_agenttrue稳定子智能体协作工具
personalitytrue稳定沟通风格选择
remote_plugintrue稳定远程插件目录
shell_snapshottrue稳定给 shell 环境拍快照，加快重复命令
shell_tooltrue稳定默认的 shell 工具
unified_exectrue（Windows 除外）稳定统一的 PTY 执行工具
web_searchtrue已弃用旧开关，改用顶层 web_search
web_search_cachedfalse已弃用旧开关，未设置时对应 web_search = "cached"
web_search_requestfalse已弃用旧开关，未设置时对应 web_search = "live"

终端通知

打开后，Codex 在后台完成任务会弹一条提醒。长时间后台任务很省心，不用一直盯着终端；但有人嫌它打断操作，同时跑的任务一多，提示音和弹窗一起响也会很吵。按自己的习惯开关。

接国内模型（第三方模型）

国内不少平台提供 OpenAI 兼容的 API，改一下配置和环境变量就有机会让 Codex 用国内模型。先说清楚：OpenAI 兼容不等于 Codex 一定能用。

在 App 设置里打开配置文件，改成：

model = "qwen3.6-plus"
model_provider = "bailian"

[model_providers.bailian]
name = "bailian"
env_key = "BAILIAN_API_KEY"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"

然后在本地设置环境变量 BAILIAN_API_KEY（Windows：右键“此电脑” → 属性 → 环境变量），完全退出 Codex 再打开；还提示找不到，就重启电脑。

验证有没有生效：

用中文写一个 Python 脚本，打印"Hello 国内大模型"，然后运行它。

能理解中文指令、生成代码、成功运行，就说明配置生效了。

不要只凭模型名称判断能否接入。确认所选模型支持平台当前的 Responses API，再用上面的最小任务验证；可用模型和版本以服务商控制台为准。

能跑就用，跑不起来就换平台。再提醒一次：第三方模型地址和权限配置别照搬，先对照官方当前参数。

三、自定义提示：把常说的话存起来

每次改完代码都想让 Codex 补单元测试、并尽量少改无关代码？不用每次打一遍，存成提示文件：

  1. 打开 Codex 主目录，建一个 prompts 文件夹；
  2. 放一个 Markdown 文件，比如 add_test.md，内容见下；
  3. 退出并重新启动 Codex CLI；
  4. 在输入框里键入 prompts，就能看到 add_test.md，选中后 Codex 会把里面的完整要求带进当前会话执行。

add_test.md 的内容：

为所有发生改动的文件生成单元测试。
使用项目现有的测试运行器，并尽量把代码差异控制到最小。

自定义命令的重点：把经常重复说的话提前写好，以后直接调用。

四、Skills：把重复的工作流打包

它是什么

Skill 本质上是存成 Markdown 文件的提示词，还可以打包资源文件和脚本。最适合的场景是某个特定工作流的指导，或者使用某些应用时的指导。

装太多 skill 的问题

每个 skill 都带一个名称和描述，会加载进模型上下文，让它知道什么时候用。现在很多人默认往项目里塞一大堆 skill，问题就来了：

写好 skill 的 4 条建议（OpenAI 官方）

常用的创建方式是调用 $skill-creator 这个 skill，它的指导最近已经更新，专门规避这些常见问题。

① 描述尽量短，但要说清什么时候用。

写法描述
不好Create and validate Postgres schema migrations. Use when working with databases, queries, models, or persistence.
好Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout.

不好的写法会让模型一碰到数据库相关的东西就用它，好的写法只在处理迁移时才用。

② 渐进披露。读 skill 本身就占上下文，会让对话更快走到压缩，还会带进来不适用的指导。有多个工作流的 skill，根文档写成一个最小的“路由”，指向配套的文档和脚本，让模型知道去哪找，不强迫它读当下用不上的东西。

③ 别写成详细菜谱。很多 skill 写得像精确到每一步的行程单。模型现在更能理解细微差别和模糊情况，过度具体的指导以前有用，现在反而会拖后腿。

④ 考虑别人用的是什么模型。仓库里的 skill 也会指导其他贡献者的 agent，他们可能用不同模型。对 Sol 或 Luna 有用的指导，可能会把 GPT-6 Astra 限制得太死。

去哪里装，装哪些

想看一个完整的“自己写 skill”案例，Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度 里有 $harness-author 的完整例子：把规划长任务的流程做成 skill，再根据复盘结果持续调优。

五、MCP：给 Codex 接上外部工具

它是什么

MCP 是一种协议，用来把模型和额外的工具、上下文连起来。Codex 支持两种接入方式：**标准输入输出（stdio）**和 HTTP。接上之后，Codex 就能连设计工具、任务管理系统、监控平台和第三方服务，先拿资料再动手。Codex 负责理解需求、安排调用，具体数据由 MCP 服务提供。

常见用法

在 AGENTS.md 里可以列出希望 Codex 使用的 MCP 服务器。MCP 的相关设置同样可以写进 config.toml，让 Codex 启动时就带着这些能力。

用纸杯蛋糕订单理解 MCP 的调用流程

下面用一个示例订单服务说明流程。假设 cupcake MCP 可以查询“谁订了多少个纸杯蛋糕”；服务名、顾客和订单内容只是示例，实际接入要按自己服务的接口配置。

  1. 先保存项目文件，再退出当前会话。重启不会替你回滚已经写入磁盘的代码。
  2. 运行 codex mcp add ...（参数按服务说明填），回车后就添加了一个名为 cupcake MCP 的全局 MCP 服务。
  3. 打开 config.toml，能看到对应的配置已经写进去了。也可以直接手动编辑 config.toml 添加，但多数人用 codex mcp add 更方便，也不容易写错格式。
  4. 新开一个会话，输入：“在 agents.md 页面底部添加一个区块，用来获取 Rachel 的纸杯蛋糕订单。”
  5. 让 Codex 调用订单查询工具，再把返回值接到页面中。假设服务返回“Rachel，7 个大理石纸杯蛋糕，到店自取”，就逐项检查页面是否准确显示这些字段，而非让模型自行补全订单。

整个过程是三步：**理解任务 → 判断需要哪些外部能力并调用 MCP → 把拿到的结果用到真正的代码修改里。**换成实际工作，返回的可以是设计稿、工单、文档内容或系统状态。

Context7：别让 Codex 只靠旧知识写代码

模型的预训练资料有知识截止时间，框架和接口一直在变。Context7 能提供各种框架的最新文档，安装同样用 codex mcp add。

例如，要在 agents.md 页面加一个输入框，让用户提交简短提示词并生成自己的 agents.md，可以让 Codex 先通过 Context7 查 Responses API 的当前用法，再实现表单和请求逻辑。

团队自己的内部文档也可以做成 MCP 接进 Codex，开发就能跟着实际实现更新，不用一直照着过时资料写代码。

不想每次提醒它查 Context7？写进全局 AGENTS.md：

只要开发功能涉及外部库或 API，就先去 Context7 查找相关文档。

什么时候不必上 MCP

大型任务的计划、进度这类信息，也可以通过 MCP 提供，但一个模型方便读取、还能提交进 Git 的 Markdown 文件往往就够用：跟着项目一起保存，团队成员都能看、能改、能复用。具体做法见 Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度。

Windows 上 MCP 服务出问题比较常见，排查见 Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错。

总结

真正实用的定制，靠的是把稳定的偏好放进配置、把项目背景放进文档，提示词不用越写越长。

按需查阅的官方文档

相关阅读