Codex CLI 的插件系统正在快速成型，/plugins 命令已经能按市场分组浏览、安装、启停插件，越来越多团队开始把内部工具链打包成可复用的 Codex 插件。但官方 Marketplace 的自助上架入口目前还处于"审核制"阶段，开发者需要先理解 manifest 结构、本地调试方式，再走完提交审核流程，才能让插件真正触达用户。这篇文章按照实战顺序梳理了从零搭建、本地测试、Git 市场分发，到官方审核上架的完整链路，并总结了几个容易踩坑的细节。
Codex 插件到底由什么组成
一个 Codex 插件本质上是把几种能力打包成可安装、可分发的单元。根据 OpenAI 官方文档，插件可以包含 skills（可复用的技能说明）、MCP-backed app（连接外部工具的服务）、生命周期 hooks，以及可选的浏览器扩展和定时任务模板。这些组件不是必须同时存在，一个只包含 skills 的轻量插件同样可以正常安装和使用。
理解每个组件的职责边界，是写出合格 manifest 的前提。下表梳理了 Codex 插件目录下四类核心组件的存放路径和作用：
| 组件 | 存放路径 | 作用 | 是否必需 |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
插件身份标识与元信息 | 必需 |
| skills | skills/<skill-name>/SKILL.md |
定义可复用的任务指令 | 可选 |
| MCP servers | .mcp.json |
配置外部工具服务连接 | 可选 |
| hooks | hooks/hooks.json |
声明生命周期钩子命令 | 可选 |
值得注意的是，如果插件只是团队内部复用的 SKILL.md 文件，不需要走完整的 manifest 流程——把文件直接放进 .agents/skills/ 目录，Codex 会自动发现，不需要插件清单。这也是很多团队从"内部脚本"过渡到"正式插件"之前的常见中间形态。
插件的能力边界比很多人预想的更广。除了 skills 和 MCP-backed app 这两个最常见的组件，官方文档还提到插件可以携带浏览器扩展所需的能力声明，以及可复用的定时任务模板，这意味着一个插件既能处理"用户主动触发"的交互式请求，也能承接"周期性后台执行"的自动化场景。选择哪些组件组合进同一个插件，本质上是在权衡安装体验和维护成本——组件越多，插件功能越完整，但对应的审核材料和测试用例也会相应增加，提交前最好先想清楚目标用户真正需要的是哪一层能力，而不是把所有组件都塞进同一个包里。
从 plugin.json 开始：插件清单文件详解
plugin.json 是插件的身份证，决定了 Codex 如何识别、加载和展示这个插件。一个最小可用的 manifest 只需要三个字段：
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}
name 字段建议使用稳定的 kebab-case 命名，后续版本升级不应该改变这个标识，否则市场无法正确识别为同一插件的迭代。version 遵循语义化版本号规范，市场依赖这个字段判断是否需要提示用户升级。所有 manifest 中引用的路径都必须相对于插件根目录，并以 ./ 开头，不能跳出插件根目录之外。
除了这三个基础字段，skills 也可以指向多个技能目录的数组，hooks、mcpServers、apps 字段则分别指向 hooks/hooks.json、.mcp.json、.app.json 对应的配置文件。这种"字段指向文件"的设计让 manifest 本身保持精简，具体的技能说明、工具配置都拆分到独立文件里维护，方便多人协作时并行修改不同组件而不产生冲突。
如果打算把插件提交到官方 Marketplace，还需要补充一组面向展示层的元数据。下表列出了发布阶段建议补全的关键字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| author / repository | 字符串 | 标识插件来源，建议与验证身份一致 |
| interface.displayName | 字符串 | 市场列表中展示的插件名称 |
| interface.category | 字符串 | 插件分类，影响用户浏览路径 |
| interface.capabilities | 数组 | 声明插件具备的能力标签 |
| mcpServers / apps / hooks | 对象 | 指向对应组件的配置文件 |
写 manifest 时最容易踩的坑是路径引用错误——比如 skills 字段写成绝对路径，或者遗漏开头的 ./，这会导致插件在本地能跑通，提交审核时却被判定为无效清单。建议在提交前用干净的目录重新克隆一遍插件仓库，模拟真实的安装环境跑一次完整测试。
本地脚手架与调试：让插件先跑起来
从零手写 manifest 效率不高，官方提供了内置的 $plugin-creator 技能来完成脚手架搭建，直接在 Codex CLI 里对话式生成：
codex "使用 $plugin-creator 脚手架生成一个名为 infra-monitor 的插件"
这条命令会自动生成 manifest、示例 skill 和本地市场条目，免去手写目录结构的繁琐工作。生成之后，插件已经可以在本地环境里直接安装测试，不需要先发布到任何远程仓库。
本地调试阶段，如果插件内的 skill 涉及调用不同厂商的大模型做对比测试，统一的 API 网关能显著减少环境配置的切换成本。我们在验证插件的 MCP server 能力时，通常会把 base_url 指向 API易 apiyi.com 提供的中转接口，一套 Key 就能在插件里切换调用不同模型，方便对比各家模型在同一段插件逻辑下的表现差异：
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
🎯 调试建议: Codex 插件开发过程中经常需要反复测试 MCP server 在不同模型下的响应质量。我们建议通过 API易 apiyi.com 平台统一管理多模型调用，避免为每个模型单独申请密钥、维护独立的调用逻辑，把精力集中在插件本身的功能打磨上。
除了手动搭建本地市场条目，也可以直接在 ~/.agents/plugins/marketplace.json（个人级）或仓库根目录的 .agents/plugins/marketplace.json（团队级）里声明本地插件路径，source 字段设为 local 即可指向本地目录，不需要推送到远程就能完成安装验证。
如果插件里包含需要 ChatGPT 开发者模式配合调试的 MCP-backed app，官方还提供了另一条路径：先在 ChatGPT 设置里开启开发者模式，创建一个 MCP-backed app 并拿到对应的 app ID，再通过 $plugin-creator 关联这个 ID，就能在真实的对话环境里验证插件与 app 之间的数据流转，这一步比纯本地命令行调试更接近上线后的真实体验，建议在提交审核之前至少完整走一遍。
Git 市场注册与团队内分发
插件在本地验证通过后，团队内部分发通常不需要等待官方审核，用 Git 仓库搭建一个市场源就足够。Codex CLI 提供了一组专门的市场管理命令：
| 命令 | 用途 |
|---|---|
codex plugin marketplace add owner/repo |
添加 GitHub 仓库作为市场源 |
codex plugin marketplace add owner/repo --ref v2.1.0 |
锁定特定分支或标签，控制灰度发布 |
codex plugin marketplace list |
查看已添加的市场列表 |
codex plugin marketplace upgrade |
拉取市场更新 |
codex plugin marketplace remove |
移除市场源 |
对于代码仓库体量较大的团队，还可以用 --sparse .agents/plugins 参数只拉取插件相关目录，避免整仓克隆拖慢安装速度。这种 Git 市场模式非常适合企业内部工具链——不需要经过公开审核，插件更新只需要推送新的 tag，团队成员执行一次 upgrade 命令即可同步。
从实践角度看，Git 市场模式还有一个隐藏优势：可以把插件的迭代节奏和团队内部的发布节奏解耦。业务代码可能一天多次合并，但插件作为对话式工具链的一部分，更新频率过高反而会打断使用者的心智模型。建议把插件版本和 tag 绑定在固定的发布窗口上，比如每周或每两周合并一次改动，既保证功能迭代速度，也不会让团队成员频繁地重新适应新的交互方式。
官方 Marketplace 提交审核全流程
官方 Marketplace 的自助上架入口截至目前仍未完全开放，OpenAI 文档明确标注这部分"即将推出"，现阶段面向公开用户的正式提交走的是插件提交门户的人工审核流程。提交前需要先完成身份验证——个人开发者需要完成 individual verification，以公司名义发布则需要完成 business verification，审核人员会核对发布身份与提交材料是否一致。
正式提交需要准备的材料清单如下：
| 材料类别 | 具体要求 |
|---|---|
| 插件基础信息 | 名称、描述、Logo、分类、相关 URL |
| MCP 服务器 | 公网可访问域名、CSP 策略、鉴权配置 |
| 演示账号 | 可直接登录，不要求 MFA 或邮箱二次验证 |
| 测试用例 | 恰好 5 个正向场景 + 3 个负向场景 |
| 工具标注 | readOnlyHint、openWorldHint、destructiveHint 需与实际行为一致 |
提交流程分为几个表单区块：Info（公开列表信息）、MCP（服务器与鉴权配置）、Skills（上传最终技能包）、Prompts（起始提示词示例）、Testing（测试用例）、Global（可用国家和地区），最后是 Submit 区块填写发布说明并完成政策确认。审核通过之后，发布时机由开发者自己在门户里选择，插件会同步出现在 ChatGPT 和 Codex 的统一插件目录中。
如果插件包含 MCP-backed app，还需要额外验证域名所有权，确保 MCP server 部署的域名和插件声明的域名一致。审核团队会重点检查工具返回结果是否包含多余的个人数据或密钥信息，这一点在设计工具输出格式时就应该提前规避，而不是等审核打回才修改。
版本管理与常见踩坑
插件上线之后，版本管理的细节直接影响用户的升级体验。市场依赖 version 字段判断是否有更新可用，所以严格遵循语义化版本号规范很重要——修复 bug 用 patch 版本号，新增能力用 minor 版本号，破坏性变更才升 major 版本号。
已安装的插件会缓存在本地路径 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/，排查"插件更新了但行为没变"这类问题时，先确认缓存是否已经刷新到新版本，往往比重新调试代码逻辑更快定位问题。企业环境下还会遇到 requirements.toml 强制的白名单策略，MCP server 需要名称和身份同时匹配，任何一项不一致都会导致服务被静默禁用，不会有明显报错提示，这类问题建议先在测试环境里跑一遍策略配置再上生产。
下表汇总了几个开发者反馈较多的踩坑点及应对方式：
| 常见问题 | 应对方式 |
|---|---|
| manifest 路径写成绝对路径 | 统一改为 ./ 开头的相对路径 |
| 隐式调用触发了非预期插件 | 使用 @plugin-name 显式指定插件 |
| 更新后行为未生效 | 检查本地插件缓存目录是否已刷新 |
| 企业策略下 MCP 静默失效 | 核对 requirements.toml 中名称与身份是否匹配 |
在正式提交官方审核之前，建议先跑一遍第三方的 codex-plugin-scanner 工具，它会从可安装性、维护状态、MCP 安全性、发布来源等维度给插件打分，尤其是要分发给企业客户的插件，提前发现问题比被审核打回更省时间。
另一个容易被忽略的细节是显式调用和隐式发现之间的差异。Codex 在没有明确指定插件的情况下，会根据上下文自动匹配最相关的技能，如果同一个工作区里安装了多个功能相近的插件，这种隐式匹配有可能选中的不是你预期的那一个。养成用 @plugin-name 显式声明的习惯，尤其是在团队共享的工作区里，能减少这类"插件互相打架"的排查成本。
Codex 插件开发常见问题（FAQ）
插件和单独的 SKILL.md 文件有什么区别？
SKILL.md 是插件里的一个组件，单独使用时不需要 manifest，放进 .agents/skills/ 目录即可被自动发现。插件则是把 skills、MCP server、hooks 等多个组件打包成一个带身份标识、可版本化管理的整体，适合需要正式分发和更新追踪的场景。
开发阶段需要多个模型账号做对比测试怎么办？
这是插件开发中经常遇到的实际问题，尤其是涉及模型选择或 prompt 调优的插件。与其为每个模型厂商单独开户、管理密钥，不如用 API易 apiyi.com 这类统一网关，通过一套 Key 调用主流模型完成 A/B 对比，把调试重心放在插件逻辑本身而不是账号管理上。
Git 市场分发和官方 Marketplace 上架能否共存？
可以。很多团队会先用 Git 市场做内部验证和小范围灰度，确认稳定后再走官方提交流程，两种分发方式互不冲突，manifest 结构也是通用的。
插件审核大概需要多长时间？
官方文档目前没有给出固定周期，只说明审核流程仍在持续建设和扩容中，也不支持加急处理。建议把审核周期算作项目排期里的不确定变量，提交前把材料一次性准备齐全，减少因材料补充导致的往返沟通，这是缩短整体上线时间最实际的办法。
写在最后
Codex 插件开发的核心难点其实不在代码本身，而在于理解 manifest 的规范要求和审核流程的材料准备——这些细节没有想象中复杂，但容易因为一个路径写法或者一个字段缺失而被打回重来。建议按照"本地脚手架验证 → Git 市场小范围分发 → 官方提交审核"的顺序推进，每一步都留出真实环境的测试时间。如果你的插件涉及多模型调用或需要频繁切换测试模型，API易 apiyi.com 提供的统一 API 中转能省去不少环境搭建的时间，让你把更多精力放在插件本身的打磨上。
