GPT Codex 中文指南

主题

Codex Plugins、Skills、MCP、AGENTS.md 有什么区别？一张表讲清配置优先级与使用场景 ​

更新时间：2026年8月4日

安装 Codex 后，最容易让新手卡住的不是命令，而是配置名越来越多：AGENTS.md、Skills、MCP、Plugins、Hooks、config.toml 到底分别做什么？Bing 头部教程常把它们全部塞进“Codex 保姆级教程”，结果读者知道了名词，却不知道应该选哪一个。

最短答案是：

  • 提示词：这一次任务要做什么；
  • AGENTS.md：这个仓库长期应该遵守什么；
  • Skill：某一类任务每次应该按什么流程做；
  • MCP：Codex 需要连接哪个外部数据或工具；
  • Plugin：把 Skills、MCP、工具和资源组合成一个可安装能力包；
  • config.toml：模型、权限、MCP、Hooks 等运行设置放在哪里；
  • Hook：在生命周期节点自动执行或强制检查什么。

国内开发路径

需要 Codex 国内版、中文开发工作流或高额度 GPT 编程模型，可以了解第三方平台 ZeoGPT。它不是 OpenAI 官方产品。无论使用哪种扩展机制，都不要把 API Key、Cookie、生产数据和私有凭据写进公开配置。

一张表看懂 Codex 配置机制 ​

机制解决的问题典型作用域是否连接外部服务是否适合版本控制
当前提示词本次任务目标与边界当前任务否通常否
AGENTS.md仓库长期规则仓库或子目录否是
Skill可复用任务流程用户或仓库可声明依赖，但本身不是连接是
MCP外部工具与实时数据用户、项目或客户端配置是配置可版本控制，密钥不可
Plugin打包分发多种能力安装级可能插件源码可以
config.toml运行参数与扩展配置用户或项目可配置 MCP视范围而定
Hook生命周期自动动作用户、项目或管理层可能是，但需谨慎

这几种机制不是互相替代，而是不同层级。一个成熟工作流往往会组合使用。

什么时候只写当前提示词 ​

只对当前任务有效的要求，直接写在提示词里：

text
只修改 docs/blog 下新建的一个 Markdown 文件。
不要覆盖已有文件，不要部署。
完成后运行 npm run docs:build，并返回文件路径。

不要为了一个临时任务修改 AGENTS.md 或创建 Skill。持久化配置越多，后续冲突越难排查。

提示词需要目标、范围、约束、验证和交付，可以参考 Codex 提示词、Goal 与模板大全。

AGENTS.md：仓库长期规则 ​

AGENTS.md 适合写对这个仓库长期有效的内容：

  • 技术栈与目录边界；
  • 安装、构建、测试命令；
  • 代码风格和命名约定；
  • 禁止修改的文件；
  • 安全、审查和交付要求；
  • 子目录的特殊规则。

例如：

markdown
## Repository Instructions

- Use VitePress and keep existing URLs stable.
- Do not overwrite existing blog files.
- Run `npm run docs:build` and `npm run docs:qa` after content changes.
- Never commit API keys or Vercel credentials.

AGENTS.md 不应该写一次性标题、某个临时 Bug 的细节或真实密钥。完整写法见 Codex AGENTS.md 项目规则教程。

Skill：重复任务的标准流程 ​

Skill 适合“每次遇到这类任务，都按同样步骤执行”的场景：

  • SEO 文章发布；
  • 代码审查；
  • Bug 修复；
  • 数据分析；
  • 文档或 PPT 生成；
  • 发布前 QA。

Skill 的核心是 SKILL.md，包含名称、触发说明、步骤、边界和验收标准。它可以引用脚本和参考资料，但不等于 MCP，也不应把所有仓库规则重复一遍。

安装、创建和调用方法见 Codex Skills 保姆级教程。

MCP：连接外部工具和实时数据 ​

MCP（Model Context Protocol）用于让 Codex 访问外部能力，例如：

  • GitHub issue、PR 和仓库数据；
  • 数据库或内部知识库；
  • 浏览器自动化；
  • 设计稿与文档系统；
  • 第三方 API；
  • 本地工具服务。

MCP 解决的是“Codex 怎样获得工具”，不是“任务应该按什么步骤做”。同一个 GitHub MCP 可以被代码审查 Skill、发布 Skill 和 issue 分析 Skill 复用。

配置时要保护 Token 和私有地址。连接失败、启动超时或工具为空时，参考 Codex MCP 服务器连接失败排查。

Plugin：可安装的能力组合包 ​

Plugin 比单个 Skill 更大。一个 Plugin 可以组合：

  • 一个或多个 Skills；
  • MCP 配置；
  • 工具与命令；
  • 应用或连接器；
  • 参考资料和静态资源；
  • 展示元数据。

适合做 Plugin 的场景是：你希望把一整套能力分发给多个用户或团队，而不是只维护一个 SKILL.md。例如“GitHub PR 助手 Plugin”可以包含 PR 审查 Skill、GitHub MCP、评论命令和规则模板。

如果只有一个小流程，先写 Skill；如果需要安装、分发和组合多种能力，再做 Plugin。

config.toml：运行参数和扩展配置中心 ​

config.toml 常用于设置：

  • 默认模型与推理强度；
  • 审批和沙箱策略；
  • MCP server；
  • 功能开关；
  • Hooks；
  • 项目或用户级运行偏好。

它不适合承载长篇操作说明，那是 AGENTS.md 或 Skill 的工作。配置示意：

toml
model = "<MODEL_ID>"
model_reasoning_effort = "medium"

[mcp_servers.example]
command = "<MCP_COMMAND>"

字段和层级会变化，使用前核对 Codex 官方配置参考。不要把真实 Token 贴进公开教程、Git 仓库或问题截图。

Hooks：自动执行与机械约束 ​

Hook 适合在固定生命周期节点触发动作，例如：

  • 工具调用前检查风险；
  • 文件修改后运行格式检查；
  • 任务结束时生成报告；
  • 阻止某类命令；
  • 记录合规审计信息。

Hook 比提示词更机械，配置错误也可能阻塞所有任务。只有当规则必须自动执行、单靠说明不够时才使用 Hook。普通“请运行测试”优先写在 AGENTS.md 或 Skill 中。

三个组合案例 ​

案例一：VitePress SEO 发布 ​

  • AGENTS.md：旧 URL 不删除、配置不随意删改、构建命令固定；
  • Skill：查重、写稿、内链、发现入口、QA、返回 URL；
  • MCP：需要实时搜索或外部数据时提供连接；
  • Hook：发布前强制检查密钥和构建状态；
  • Plugin：把整套 SEO 流程分发给多个站点维护者。

案例二：GitHub PR 代码审查 ​

  • 当前提示词：指定这次 PR、重点模块和交付格式；
  • AGENTS.md：仓库测试命令和禁止变更；
  • Skill：按严重程度、证据、测试、回滚输出；
  • MCP：读取 GitHub PR、评论与状态；
  • Hook：阻止含密钥文件被输出。

案例三：数据库迁移 ​

  • AGENTS.md：数据库规范和禁止直连生产；
  • Skill：备份、迁移、验证、回滚步骤；
  • MCP：连接受控测试数据库；
  • Hook：拒绝对生产环境执行破坏性命令；
  • 当前提示词：本次迁移表、时间窗与责任人。

选择流程：只问五个问题 ​

  1. 只对这一次有效吗？ 是，用提示词。
  2. 对整个仓库长期有效吗？ 是，用 AGENTS.md。
  3. 是一套需要重复执行的步骤吗？ 是，用 Skill。
  4. 需要外部实时数据或动作吗？ 是，用 MCP。
  5. 需要把多种能力打包给别人安装吗？ 是，用 Plugin。

必须机械执行的生命周期检查，再考虑 Hook；模型、权限和 server 参数放 config.toml。

配置冲突时怎么排查 ​

当 Codex 行为与预期不一致，按“当前任务到管理层”的顺序找来源：

  1. 当前提示词是否明确覆盖了旧要求；
  2. 当前目录与父目录是否有不同 AGENTS.md；
  3. 使用了哪个 Skill，Skill 是否与仓库规则冲突；
  4. 项目与用户 config.toml 是否设置不同；
  5. Plugin 是否带入额外 Skill、MCP 或 Hook；
  6. 组织管理策略是否覆盖本地配置；
  7. 用 /status、/debug-config、/skills、/mcp verbose 查看实际状态。

AGENTS.md 单独不生效时，看 作用域、优先级与规则冲突教程。

安全底线 ​

  • Skill、AGENTS.md 和 Plugin 源码中不写真实密钥；
  • MCP 的 Token 使用受控环境变量或密钥管理；
  • 不安装来源不明、要求高权限的 Plugin；
  • Hook 中的删除、上传和网络命令必须人工审查；
  • 项目配置进入 Git 前检查是否包含私有地址；
  • 新能力先在公开或脱敏项目中验证；
  • 任何自动化修改后都检查 Diff 与测试。

FAQ ​

Skills 和 MCP 可以一起用吗 ​

可以。Skill 定义流程，MCP 提供外部工具。例如“PR 审查 Skill”可以调用 GitHub MCP 读取 PR 数据。

AGENTS.md 和 Skill 内容重复怎么办 ​

把长期仓库规则保留在 AGENTS.md，把任务步骤保留在 Skill。Skill 可以引用规则，但避免复制两份造成更新不一致。

Plugin 一定比 Skill 强吗 ​

不是。Plugin 更适合组合与分发，复杂度也更高。一个清晰的单任务流程用 Skill 更容易维护。

config.toml 能代替 AGENTS.md 吗 ​

不能。config.toml 主要是结构化运行设置，AGENTS.md 是仓库开发与验证说明。

为什么 /plugins 或 /skills 看不到 ​

可能是版本、产品入口、功能开关、安装范围或组织策略不同。先更新 Codex，用 /status 和 codex features 核对，不要假设所有客户端功能一致。

相关教程 ​

本文依据 2026年8月4日 OpenAI Codex 官方仓库、公开文档和 Bing 当前搜索结果整理。扩展机制仍在快速变化，最终以本机命令、实际界面和官方文档为准。

独立中文教程站，不是 OpenAI 官方网站。产品信息请以官方资料为准。

© 2026 gpt-codex.com · 关于本站 · 编辑规则 · 隐私声明