给 Codex 装上外挂：0 基础也能看懂的插件开发入门

给 Codex 装上外挂：0 基础也能看懂的插件开发入门

适合读者：刚听说 Codex 插件，只会一点点编程基础，想知道插件到底能帮 Codex 做什么的新手。
阅读目标：读完后，你应该能分清 Codex 插件和 VS Code 插件，理解plugin.json、Skill、MCP Server 的作用，并看懂一个“代码审查小助手”插件的最小结构。

你有没有想过，让 Codex 不只是帮你写代码，还能按照团队规范检查代码、自动生成测试、读取项目文档、调用外部工具，甚至像一个熟悉公司祖传代码的老员工一样干活？

当然，先别急着让它接管全公司。饭要一口一口吃，插件也要一个一个写。

Codex 插件的本质，是给 Codex 安装一套可复用的工作技能包。它不是让界面更花哨，也不是给编辑器多加几个按钮，而是让 Codex 在特定任务中更懂流程、更会调用工具、更适合团队反复使用。

目录

• 一、什么是 Codex 插件
• 二、开发前需要了解什么
• 三、Codex 插件的基本结构
• 四、第一个实战：代码审查小助手插件
• 五、插件开发的核心概念
• 六、小白踩坑指南
• 七、学习路线
• 八、总结

一、什么是 Codex 插件

一句话解释：

Codex 插件是用来扩展 Codex 工作能力的可复用工作流包。

它和 VS Code 插件不是一类东西。VS Code 插件更像给编辑器加按钮、菜单、语法高亮、侧边栏；Codex 插件更像给 AI 程序员发一套专用工具箱和工作手册。

一个 Codex 插件可以把这些东西组合起来：

所以，Codex 插件的目标不是“让界面更炫”，而是“让 Codex 做事更专业、更稳定、更符合团队流程”。

比如你们团队有固定代码审查规范。每次你都手动提醒 Codex：“先看业务逻辑，再看边界条件，再看安全问题，最后给修改建议。”
说一次可以，说十次就有点像重复念咒。插件可以把这套流程固化下来，让 Codex 每次都按同一套规矩办事。

二、开发前需要了解什么

先把几个词说清楚，不然后面容易迷路。

1. Codex 是什么

小白版：Codex 可以理解为一个会读代码、改代码、运行工具、帮你完成开发任务的 AI 编程助手。
专业版：Codex 是面向软件工程任务的 AI 代理环境，可以结合工作区文件、终端命令、工具调用和上下文来协助完成开发工作。

2. Plugin 是什么

小白版：Plugin 就是技能礼包，把工作手册、工具配置和素材打包起来。
专业版：Codex 插件是带有.codex-plugin/plugin.json清单的可安装扩展包，用于组织 Skills、MCP 配置、应用集成和资源。

3. Skill 是什么

小白版：Skill 是写给 Codex 的操作说明书。你告诉它“遇到代码审查任务时，先做什么，再做什么”。
专业版：Skill 通常用SKILL.md描述特定任务的流程、约束、工具使用方式和输出规范。

4. MCP 是什么

小白版：MCP 像给 Codex 接了一根数据线，让它能连接外部工具。
专业版：MCP 是一种让模型访问工具、上下文和外部服务的协议，可以扩展 Codex 的可操作范围。

5. plugin.json 是什么

小白版：plugin.json是插件的户口本，Codex 先看它，才知道这个插件叫什么、在哪里、有什么内容。
专业版：plugin.json是 Codex 插件清单文件，通常位于.codex-plugin/plugin.json，用于声明插件名称、版本、描述和相关能力入口。

为什么要用插件管理这些东西？因为团队工作流不能只靠口头传承。插件能把“我们平时怎么做代码审查、怎么写测试、怎么整理文档”变成可复制、可安装、可维护的规则。

三、Codex 插件的基本结构

一个简化版插件目录可以长这样：

my-plugin/ .codex-plugin/ plugin.json skills/ review-code/ SKILL.md .mcp.json assets/ icon.png

逐个拆开看：

其中最重要的是.codex-plugin/plugin.json。没有它，Codex 就不知道这是一个插件。它就像插件的户口本：名字、版本、说明、入口，都从这里开始认。

skills/目录则是插件真正有“工作经验”的地方。你可以放多个 Skill，比如review-code、write-tests、summarize-docs。每个 Skill 负责一种明确任务。

.mcp.json不是每个入门插件都必须写。只有当你需要让 Codex 连接额外工具时，才会用到它。比如数据库查询、浏览器控制、内部系统接口等。

四、第一个实战：代码审查小助手插件

我们做一个适合新手的插件：代码审查小助手。

目标很简单：让 Codex 审查代码时，按照固定顺序执行：

1. 先理解代码功能；
2. 再检查潜在 bug；
3. 再检查命名和结构；
4. 再检查安全风险；
5. 最后给出修改建议。

1. plugin.json 示例

{"name":"code-review-helper","version":"0.1.0","description":"A simple Codex plugin for structured code review.","skills":"./skills/"}

逐行解释：

• name：插件名字，建议用小写和连字符，别起名叫“我的超级无敌插件”；
• version：版本号，0.1.0表示早期试用版；
• description：一句话说明插件做什么；
• skills：告诉插件技能文件夹在哪里。

不同 Codex 版本或插件校验规则可能会要求更完整的清单字段。入门时先理解它的角色：声明插件身份和能力入口。

2. SKILL.md 示例

目录可以这样放：

skills/ review-code/ SKILL.md

SKILL.md内容可以很短：

# Code Review Helper When reviewing code, follow these steps: 1. Understand the purpose of the code. 2. Check for bugs and edge cases. 3. Check readability and naming. 4. Check security risks. 5. Give clear improvement suggestions.

这就像你给 Codex 递了一张小纸条：

兄弟，别上来就改代码。先看懂，再动手。

Skill 的价值不在于写得长，而在于写得清楚。模糊的 Skill 会让 Codex 自由发挥，清晰的 Skill 会让它更稳定地按流程工作。

五、插件开发的核心概念

1. Plugin：插件包

小白版：把一套工作能力打包成一个可以安装的礼包。
专业版：Plugin 是 Codex 可识别的扩展单元，用于组织清单、技能、工具配置和资源。

2. Manifest：插件清单

小白版：插件说明书，告诉 Codex“我是谁”。
专业版：Manifest 通常指.codex-plugin/plugin.json，用于声明插件元数据和入口。

3. Skill：任务技能

小白版：写给 Codex 的工作流程卡片。
专业版：Skill 用 Markdown 描述特定任务的执行步骤、约束和输出要求。

4. MCP Server：外部工具连接器

小白版：给 Codex 接上的外接机械臂，让它能碰到更多工具。
专业版：MCP Server 向模型暴露工具、上下文或外部服务能力，让 Codex 在授权范围内调用。

5. App integration：应用集成

小白版：让 Codex 和外部应用打配合。
专业版：应用集成用于把 Codex 工作流与特定服务、产品或应用能力连接起来。

6. Local testing：本地测试

小白版：先在自己电脑上试试，别一上来就发给全组。
专业版：本地测试用于验证插件结构、Skill 表达和工具配置是否按预期工作。

7. Distribution：分发和复用

小白版：把插件分享给别人装。
专业版：分发是将插件通过本地路径、团队仓库或插件市场机制交付给其他用户使用。

六、小白踩坑指南

新手最容易犯的错，就是第一天写插件，第二天想统治硅基文明。建议先从一个小功能开始，比如代码审查、测试生成、文档整理。能稳定做好一件事，比“什么都想做但都做得飘”强得多。

七、学习路线

适合 0 基础小白的路线可以这样走：

1. 了解 Codex 基本使用方式：知道它怎样读文件、改代码、运行工具。
2. 学习 Markdown：Skill 主要靠清晰说明驱动，Markdown 是基本功。
3. 学习 JSON：看懂plugin.json配置。
4. 理解插件目录结构：知道清单、技能、工具配置分别放哪。
5. 写第一个简单 Skill：比如固定代码审查流程。
6. 把多个 Skill 打包成插件：例如审查、测试、文档整理。
7. 学习 MCP：让 Codex 调用外部工具。
8. 学习测试、版本管理和团队分发：让插件能被别人稳定使用。
9. 尝试复杂插件：代码审查插件、测试生成插件、项目文档助手、Bug 复现助手。

这条路线的重点不是炫技，而是逐步把“你脑子里的流程”变成 Codex 能反复执行的规则。

八、总结

Codex 插件开发的核心，不是把界面做得多漂亮，也不是一上来接十几个工具。它真正解决的问题是：如何把可复用的工作流程交给 Codex，让它按你的规矩做事。

如果 Codex 是一个 AI 程序员，那么 Skill 就是你塞给它的工作手册，MCP Server 是你给它接上的外部工具箱，Plugin 则是把这些东西打包成可安装、可复用、可分发的技能礼包。

刚开始不要追求“大而全”。先做一个代码审查小助手，或者一个测试生成小助手。等你能把一个小流程写清楚、跑稳定，再慢慢加工具、加场景、加团队规范。

说白了，Codex 插件不是为了炫技，而是让 AI 不只是“会写代码”，而是“按你的规矩写代码”。