你真的会配置 Codex 吗？#

很多人用 Codex 的方式是这样的：装好 CLI，登录账号，然后直接开聊。能用，但远远谈不上好用。

问题出在哪里？不是模型不够聪明，而是你没有给它足够的上下文。就像你雇了一个能力很强的开发者，但既不告诉他项目的技术栈，也不告诉他团队的代码规范，甚至连哪些文件不能碰都没说。他当然能写代码，但写出来的东西大概率不是你想要的。

Codex 的配置体系就是为了解决这个问题。它不是一堆散落的设置项，而是一套精心设计的分层架构。理解了这套架构，你就能把 Codex 从一个"能用的工具"变成一个"懂你项目的搭档"。

三种界面，一套配置#

OpenAI 为 Codex 提供了三种使用方式：CLI 命令行、VS Code 扩展、macOS 桌面应用。很多人以为它们是三个独立的产品，其实不是。它们共享同一套配置文件和技能系统。

也就是说，你在 CLI 里配置好的 AGENTS.md、MCP 服务器和 Skills，在 VS Code 扩展里同样生效。反过来也一样。这带来的好处是显而易见的：你不需要为每个界面重复配置，只需要维护一份配置就能覆盖所有使用场景。

三者的区别主要在交互方式上。CLI 最快、最灵活，适合终端重度用户。VS Code 扩展集成在编辑器侧边栏，适合习惯 IDE 工作流的开发者。桌面应用目前只有 macOS 版本，提供了一个独立的 Agent 工作空间。

我的建议是：日常开发用 CLI 或 VS Code 扩展就够了。桌面应用适合那些想把"Agent 工作"和"编辑器工作"分开的场景。

四层配置架构#

Codex 的配置体系可以分成四层，从上到下依次是：

第一层：AGENTS.md（指令层）。告诉 Codex 这个项目是什么、怎么工作、什么能做什么不能做。这是最核心的配置。

第二层：Skills（技能层）。把重复性的工作流程封装成可复用的剧本。比如代码审查、文档更新、测试编写，都可以变成一个 Skill。

第三层：config.toml（偏好层）。存放个人偏好和外部服务连接。MCP 服务器就配置在这一层。

第四层：Permissions（权限层）。控制 Codex 能做什么操作。自动模式、只读模式、完全访问模式，根据项目的安全需求灵活切换。

这四层的关系是层层叠加的。AGENTS.md 定义基础行为，Skills 提供扩展能力，config.toml 设置运行偏好，Permissions 划定安全边界。

AGENTS.md：少即是多#

AGENTS.md 是 Codex 的"项目说明书"。它告诉 Codex 如何在当前代码库中工作。

Codex 读取 AGENTS.md 的方式很特别：它从项目根目录开始，沿着目录树一路往下走到你当前所在的目录。在每一层目录中，它都会检查是否存在 AGENTS.md 文件（以及可选的 AGENTS.override.md 覆盖文件）。所有找到的文件会被拼接在一起，从根目录到当前目录依次叠加。

这种"沿目录树行走"的设计有一个巧妙之处：你可以在项目的不同子目录中放置不同的 AGENTS.md，实现细粒度的指令控制。比如在 src/ 目录下强调代码风格，在 tests/ 目录下强调测试覆盖率要求。

什么该写进 AGENTS.md#

一个好的 AGENTS.md 应该包含这些内容（控制在 10 条以内）：

  1. 这个项目是什么、给谁用的
  2. 真正重要的命令（开发、构建、测试、lint）
  3. “从这里开始"的指引（3 到 6 个 Codex 应该先读的文件）
  4. 架构概览（主要目录和边界）
  5. 硬性约束（比如"纯静态导出，不用 Server Actions”）
  6. 不明显的约定（命名规范、导入方式、生成代码的位置）
  7. “不要碰"的边界（密钥、生产环境配置）
  8. 你希望变更如何被验证（测试、类型检查、lint）
  9. 首选模型（如果有的话）
  10. 指向额外文档的链接

什么不该写进 AGENTS.md#

同样重要的是知道什么不应该放进去：

长篇大论的宣言。 如果你的 AGENTS.md 比 README 还长，那就是问题。保持简洁，让它可以在 30 秒内扫完。

代码风格指南。 链接到你的 eslint 或 prettier 配置就行，不要把规则直接粘贴进来。

密钥和令牌。 永远不要在 AGENTS.md 里放 API 密钥。用环境变量。

空洞的口号。 “写干净的代码"或"要乐于助人"这类话没有任何指导价值。要么给出具体标准，要么删掉。

如果你发现自己写了很多内容，考虑把详细指引拆分到 Skills 或独立的项目文档中。AGENTS.md 应该是一个精炼的导航地图，而不是一本百科全书。

一个实用的技巧：在 Codex 里运行 /init 命令，它会为你的仓库生成一个 AGENTS.md 起步模板。然后大胆删减，只保留真正能改善结果的内容。

MCP 服务器：给 Codex 装上外部能力#

MCP（Model Context Protocol）是 Codex 连接外部服务的机制。你可以把它理解为插件系统，但比传统插件更透明，你能清楚地看到每个 MCP 服务器在做什么。

MCP 服务器的配置写在 config.toml 中。配置文件有两个位置：全局配置在 ~/.codex/config.toml，项目级配置在 .codex/config.toml。项目级配置会覆盖全局配置中的同名项。

快速上手：添加 GitHub MCP 服务器#

最简单的方式是用 CLI 命令：

codex mcp add github -- npx -y @modelcontextprotocol/server-github

或者手动编辑 ~/.codex/config.toml：

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

然后设置环境变量：

export GITHUB_PERSONAL_ACCESS_TOKEN="你的令牌"

常见问题排查#

MCP 服务器不工作？通常就那么几个原因：

工具没出现。 大概率是配置文件放错了位置。检查你是放在全局配置还是项目级配置里，确认 Codex 读取的是哪个。

认证失败。 环境变量可能没设置或者过期了。用 echo $变量名 确认一下。有些 MCP 服务器读取环境变量有问题，这时候可能需要直接在配置文件中写死令牌（但千万别把配置文件提交到 git）。

命令找不到。 如果报 npx 或 uvx 找不到，说明缺少对应的运行时。npx 需要 Node.js，uvx 需要 uv。

服务启动了但工具调用失败。 先在 Codex 之外手动运行那个命令，确认它本身能正常工作。

配置优先级#

Codex 的配置优先级是一个栈，从高到低依次为：CLI 标志和显式配置、profiles、项目配置（从根目录到当前目录）、用户配置、系统配置、默认值。理解这个优先级很重要，它决定了当多个配置文件存在冲突时，哪个会生效。

Skills：把经验变成可复用的剧本#

如果一个工作流程是可重复的、多步骤的、或者搞错成本很高的，那就应该把它封装成 Skill。

Skills 存放在两个地方。项目级 Skills 在 .agents/skills/ 目录下，适合团队共享。用户级 Skills 在 ~/.codex/skills/ 目录下，适合个人的效率工具。

一个 Skill 长什么样#

每个 Skill 是一个目录，里面有一个必需的 SKILL.md 文件。文件用 YAML frontmatter 定义元数据，用 Markdown 写具体内容。

比如一个代码审查 Skill：

---
name: code-review
description: 审查代码中的 bug、风格问题和最佳实践
command: review
---

在 Markdown 正文中，你需要写清楚四件事：

做什么。 这个 Skill 的职责范围。比如"审查代码 diff 中的 bug、逻辑错误和安全问题”。

什么时候用。 触发条件。比如"在提交前想要第二双眼睛检查代码变更时”。

怎么工作。 具体的工作流程。比如"先读取文件，然后按优先级识别 bug、性能问题、安全风险、风格不一致"。

输出格式。 结果怎么呈现。比如"按严重程度分类：Critical、Warning、Nitpick，附上文件路径和行号"。

配置好之后，在 Codex 里直接用 /review @path/to/file 就能调用。

什么时候该写 Skill#

我的判断标准很简单：如果你发现自己在 Codex 里反复输入类似的指令，那就是该写 Skill 的信号。

常见的 Skill 候选场景：

  • 代码审查流程
  • 文档更新（代码改了之后同步更新 README）
  • 测试编写（为新函数生成单元测试）
  • 部署检查清单
  • 数据库迁移规范

Skills 和 AGENTS.md 的分工是：AGENTS.md 描述"这个项目是什么样的"，Skills 描述"在这个项目里怎么做事"。

与 Claude Code 和 Gemini CLI 的对比#

既然聊到了配置体系，不妨和另外两个主流 AI 编程工具做个对比。

AGENTS.md 和 Claude Code 的 CLAUDE.md 相比，最大的优势是简洁。CLAUDE.md 有复杂的记忆文件继承规则，多个配置文件之间的优先级关系让人头疼。AGENTS.md 就简单多了：沿目录树拼接，所见即所得。

和 Gemini CLI 的 GEMINI.md 相比，Codex 的 MCP 支持更成熟。Gemini 有免费额度优势，但在工具调用的可靠性上，Codex 表现更稳定。

从文档质量来看，Claude Code 的文档是最详尽的，Codex 的文档还在完善中。不过 Codex 的配置体系设计更直观，上手门槛更低。

实战建议#

基于这些分析，我给出几条实用建议：

从 /init 开始，然后大胆删减。 不要试图一开始就写出完美的 AGENTS.md。让 Codex 帮你生成一个起步版本，然后根据实际使用体验逐步精简。

MCP 服务器按需添加。 不要贪多。每多一个 MCP 服务器就多一份配置复杂度和潜在的故障点。只添加你真正需要的外部服务。

Skills 从高频操作开始。 先把你每天都会做的事情封装成 Skill，低频操作以后再说。

善用项目级和全局级的分离。 团队共享的配置放在项目仓库里，个人偏好放在全局配置里。这样既保证了团队一致性，又不牺牲个人灵活性。

定期审视配置。 随着项目演进，AGENTS.md 和 Skills 也需要更新。把配置维护纳入你的日常开发习惯中。

总结#

Codex 的配置体系不是一堆零散的设置文件，而是一套有层次、有分工的架构设计。AGENTS.md 定义项目上下文，Skills 封装工作流程，config.toml 管理偏好和外部连接，Permissions 控制安全边界。三个界面共享同一套配置，一次配置到处生效。

很多人把时间花在比较哪个 AI 编程工具更强上，却忽略了配置的重要性。一个被精心配置的 Codex，效果远好于一个默认配置的强大模型。花半小时把 AGENTS.md 写好，把常用的 Skill 建立起来，你会发现 Codex 的表现有质的提升。

工具的价值不在于它有多强大，而在于你有多会用它。

参考来源： How to Set Up OpenAI Codex (2026): AGENTS.md, MCP Servers, Skills, Config — Dmytro Chaban