Codex 配置体系完全指南：AGENTS.md、MCP 服务器与 Skills 的分层架构

Thu, 21 May 2026 09:00:00 +0800

你真的会配置 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 是 Codex 的"项目说明书"。它告诉 Codex 如何在当前代码库中工作。