Codex 插件开发实战：从 plugin.json 到公共市场，打包你的 AI 工作流-平芜编程栈

、> 发布日期：2026-08-10 | 适用版本：Codex v0.117.0+（Plugin 支持版本）| 话题：OpenAI Codex 插件开发

Codex 插件系统由 OpenAI 于 2026 年 3 月 27 日正式推出，是一种将可复用 AI 工作流打包为可安装、可分发单元的机制；与仅作用于单一仓库的 Skill 不同，插件能同时捆绑 Skills、App 集成连接器和 MCP 服务器配置，实现跨项目、跨团队的能力共享。截至 2026 年 7 月 9 日，插件已成为 ChatGPT 和 Codex 跨产品发现工作流能力的主要方式，Cisco、NVIDIA、Ramp、Rakuten 等企业均已在生产环境中部署。本文完整覆盖从第一行配置到公共市场发布的全流程，包括 plugin.json 字段规范、marketplace.json 三种模式、@plugin-creator 快速脚手架、Hooks 与 MCP 集成，以及常见开发问题解答。

Codex 插件是什么

Codex 插件（Codex Plugin）是 OpenAI 推出的 AI 工作流打包格式，类似于 npm 包，但内容是可安装到 Codex 和 ChatGPT 的 AI 工作流能力单元。

插件生态由四个层级组成，理解这四层是开发的前提：

层级	作用	对应场景
Skill	可复用工作流的编写格式	单仓库试验性逻辑
Plugin	可安装、可分发的打包单元	跨团队共享工作流
App	连接 GitHub/Slack 等外部服务的权限层	需要操作第三方工具
MCP Server	扩展工具调用面或共享上下文的服务端层	自定义工具或数据源

一个插件可以同时包含Skills、Apps 和 MCP Servers——这是插件相对于单独 Skill 的核心价值。

根据 OpenAI 官方文档，Codex v0.117.0 是首个支持插件系统的版本，插件公共目录（Universal Plugin Directory）与 ChatGPT 共享，发布一次即可在两款产品中被发现。

什么时候该从 Skill 升级到 Plugin

官方建议的判断逻辑是：“还在一个仓库内迭代时，用 Skill；需要跨项目复用、分享或打包多项能力时，用 Plugin。”

以下场景明确适合构建插件：

团队统一 PR 审查流程，需要部署到多个仓库
将同类技能（如 API 文档生成 + 测试生成 + 变更日志）捆绑为一个安装包
需要连接外部系统（Slack 通知、GitHub Issues 同步），走 App/MCP 集成
准备发布到 Codex 公共市场或企业内部 Marketplace

不适合构建插件的场景：一次性任务、高度依赖本地环境的个人偏好配置。

快速上手：用 $plugin-creator 生成插件骨架

OpenAI 内置了$plugin-creator技能作为官方脚手架工具，无需手动创建目录和配置文件。

在 Codex CLI 中调用：

$plugin-creator

在 ChatGPT Work 模式中调用：

@plugin-creator create a plugin for [描述你的工作流需求]

$plugin-creator会自动完成以下操作：

创建插件目录结构
生成必需的.codex-plugin/plugin.json清单
创建本地 marketplace 条目用于即时测试
如有 MCP 服务器，自动写入.mcp.json并在 plugin.json 中引用

生成的目录结构如下（仅plugin.json属于.codex-plugin/目录，其余文件放插件根目录）：

my-plugin/ ├── .codex-plugin/ │ └── plugin.json # 唯一必须文件 ├── skills/ │ └── repo-triage/ │ └── SKILL.md ├── hooks/ │ └── hooks.json ├── assets/ │ ├── icon.png │ └── logo.png ├── .app.json └── .mcp.json

SKILL.md 格式示例：

--- name: repo-triage description: 自动分类新 Issue，打标签并分配到对应 Milestone。 --- 检查新 Issue 的标题和描述，根据关键词判断属于 bug / feature / docs 类别， 为其打上对应标签，并将 feature 类 Issue 关联到当前 Sprint Milestone。

SKILL.md 由两部分组成：---包裹的 frontmatter（name 和 description 字段）+ 自然语言形式的工作流指令。指令写得越具体，Codex 执行结果越稳定。

plugin.json 核心字段全解析

plugin.json是插件的唯一入口清单，必须放在.codex-plugin/目录下。以下是一个完整的生产级配置示例：

{"name":"repo-triage-plugin","version":"1.0.0","description":"自动分类 Issue、生成 PR 摘要，标准化团队代码审查流程。","author":{"name":"Your Team","email":"dev@example.com","url":"https://example.com"},"skills":"./skills/","mcpServers":"./.mcp.json","apps":"./.app.json","hooks":"./hooks/hooks.json","interface":{"displayName":"Repo Triage Plugin","shortDescription":"Issue 分类与 PR 审查自动化","longDescription":"自动对新 Issue 打标签、分配 Milestone，并在 PR 提交时生成结构化摘要，减少重复劳动。","category":"Productivity","capabilities":["Read","Write"],"privacyPolicyURL":"https://example.com/privacy","defaultPrompt":["帮我对最新的 Issue 进行分类","生成本次 PR 的变更摘要"],"brandColor":"#10A37F","composerIcon":"./assets/icon.png","logo":"./assets/logo.png"}}

关键字段说明：

字段	类型	说明
`name`	string	kebab-case 格式，作为插件命名空间
`version`	string	严格遵循 semver（如`1.0.0`）
`skills`	string	相对路径，指向 SKILL.md 所在目录
`mcpServers`	string/object	引用`.mcp.json`文件路径，或直接内联服务器对象
`interface.defaultPrompt`	array	最多 3 条，每条上限 128 字符，作为启动建议
`interface.privacyPolicyURL`	string	必须为`https://`开头的绝对 URL，公开发布时必填

mcpServers 的两种配置方式：

// 方式 1：引用外部文件{"mcpServers":"./.mcp.json"}// 方式 2：直接内联服务器对象{"mcpServers":{"my-server":{"type":"http","url":"https://api.example.com/mcp"}}}

插件中的 Skill 如果需要调用 AI 模型，可以通过兼容 OpenAI SDK 格式的标准 API 接入，例如七牛云 Token Plan 提供了多模型统一接口，开发者无需为不同模型维护多套调用代码。

三种 Marketplace：本地开发 → 团队分发 → 公开发布

Codex 插件的三种分发模式对应三类 marketplace，开发阶段逐步从本地迁移到公共目录。

模式一：Personal Marketplace（默认）

配置文件位置：~/.agents/plugins/marketplace.json

适合个人本地测试，新建插件默认加入此 marketplace。配置示例：

{"name":"local-dev-plugins","interface":{"displayName":"本地开发插件库"},"plugins":[{"name":"repo-triage-plugin","source":{"source":"local","path":"./plugins/repo-triage-plugin"},"policy":{"installation":"AVAILABLE","authentication":"ON_INSTALL"},"category":"Productivity"}]}

注意：source.path必须以./开头，路径相对于 marketplace.json 所在目录解析，而非.agents/plugins/文件夹。

模式二：Repo/Team Marketplace

配置文件位置：<repo-root>/.agents/plugins/marketplace.json

提交到仓库后，团队成员拉取代码即可访问同一套插件。支持三种插件来源：

"source": "local"— 本地目录（适合仓库内插件）
"source": "git-subdir"— 外部 Git 仓库子目录（适合跨仓库共享）
"source": "npm"— npm 包（适合版本化发布）

Git 子目录源示例：

"source":{"source":"git-subdir","url":"https://github.com/example/codex-plugins.git","path":"./plugins/repo-triage-plugin","ref":"main"}

Codex CLI 管理命令：

# 添加 marketplacecodex plugin marketplaceaddowner/repo codex plugin marketplaceadd./local-marketplace-root# 查看已安装codex plugin marketplace list# 更新插件codex plugin marketplace upgrade# 移除 marketplacecodex plugin marketplace remove marketplace-name

安装后插件缓存于：~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/，本地插件的$VERSION值为local。

模式三：公共 Plugin Directory

ChatGPT 和 Codex 共享一个通用公共目录，发布一次在两个产品均可被发现。发布前需确保：

interface字段完整（displayName、shortDescription、longDescription、category、privacyPolicyURL 必填）
所有[TODO: ...]占位符已替换（官方scripts/validate_plugin.py会拒绝含占位符的清单）
通过 OpenAI 插件提交门户提交审核

生产级插件：Hooks 与 MCP 集成

生命周期 Hooks

hooks/hooks.json允许在特定事件触发时执行自定义脚本，目前支持SessionStart等钩子：

{"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"python3 ${PLUGIN_ROOT}/hooks/session_start.py","statusMessage":"加载插件上下文..."}]}]}}

钩子中可用的环境变量：

变量	说明
`PLUGIN_ROOT`	已安装插件的根目录路径
`PLUGIN_DATA`	插件可写数据目录
`CLAUDE_PLUGIN_ROOT`	`PLUGIN_ROOT`的兼容别名
`CLAUDE_PLUGIN_DATA`	`PLUGIN_DATA`的兼容别名

安全提示：安装插件不会自动信任其 Hooks，用户需手动审核并授权 Hooks 执行权限。

MCP 服务器集成

.mcp.json定义插件捆绑的 MCP 服务器，格式与标准.mcp.json相同：

{"mcpServers":{"issue-tracker":{"type":"http","url":"https://api.example.com/mcp/issues"}}}

MCP 服务器随插件一起安装，无需用户额外配置，是插件相对于独立 Skill 的核心能力扩展点。

常见问题

Q：Codex 插件和 ChatGPT 插件是同一套体系吗？
是的。自 2026 年 7 月 9 日起，Codex 和 ChatGPT 共享统一的插件目录（Universal Plugin Directory）。开发者发布一个公共插件后，两款产品的用户均可发现和安装，无需分别适配。

Q：plugin.json 中 skills 字段路径如何写？
skills字段的值是相对于插件根目录（即.codex-plugin/plugin.json所在目录的父目录）的路径字符串，通常写为"./skills/"。该路径是对默认组件发现规则的补充，而非替代——即使不写skills字段，Codex 也会扫描标准位置的 SKILL.md。

Q：插件开发调试时，如何避免影响生产环境的 personal marketplace？
建议在仓库根目录创建.agents/plugins/marketplace.json（Repo Marketplace），将开发中的插件注册在此，仅对本仓库生效，不污染~/.agents/plugins/marketplace.json中的个人配置。

Q：一个插件能包含多少个 Skill？
官方文档未设置数量上限，但建议每个插件围绕一个工作流主题组织，避免将无关功能打包在一起——过于宽泛的插件会降低interface.defaultPrompt的准确性，影响用户发现体验。

Q：不会写代码，能开发 Codex 插件吗？
可以。Skill 的核心文件 SKILL.md 使用自然语言编写指令，无需编程基础。对于只包含 Skills 的简单插件，借助$plugin-creator脚手架和自然语言描述即可完成基础插件的创建与本地测试。

小结

Codex 插件系统于 2026 年 3 月上线，同年 7 月成为 ChatGPT 和 Codex 跨产品工作流能力的主要分发形式，标志着 AI 编程工具从"个人辅助"向"团队工作流标准化平台"的演进。据 OpenAI 公开信息，截至 2026 年 6 月的"Codex for Every Role"发布活动，插件已覆盖 62 款主流商业应用的开箱集成，Cisco、NVIDIA、Ramp 等企业已在生产环境采用。

对开发者而言，插件开发的门槛远低于传统工具插件：核心文件只有plugin.json和若干SKILL.md，$plugin-creator脚手架可在一次对话中生成完整骨架，而团队分发只需提交一个marketplace.json文件到仓库。

本文内容基于 Codex v0.117.0+ 及 2026 年 8 月 OpenAI 官方文档，插件 API 仍在持续更新，建议参考 developers.openai.com/plugins/build/plugins 获取最新规范。