Codex 插件开发实战：从 plugin.json 到公共市场，打包你的 AI 工作流
Codex 插件是什么
👍
Codex 插件（Codex Plugin）是 OpenAI 推出的 AI 工作流打包格式，类似于 npm 包，但内容是可安装到 Codex 和 ChatGPT 的 AI 工作流能力单元。
插件生态由四个层级组成，理解这四层是开发的前提：
#UMaNlEFRJphI text { white-space: pre; }#UMaNlEFRJphI .fb0 { stroke: var(--N900-FG, 0.15); }#UMaNlEFRJphI .fb0 {stroke: rgba(31,35,41, 0.15)}#UMaNlEFRJphI .fx0 { stroke-miterlimit: 10; }#UMaNlEFRJphI .fx0 {stroke-miterlimit: 10}#UMaNlEFRJphI .fa1 { fill: rgb(187, 191, 196); }#UMaNlEFRJphI .fa1 {fill: rgb(187, 191, 196)}#UMaNlEFRJphI .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#UMaNlEFRJphI .fx1 {font-style: normal}#UMaNlEFRJphI .fx2 { text-anchor: middle; }#UMaNlEFRJphI .fx2 {text-anchor: middle}#UMaNlEFRJphI .fx3 { dominant-baseline: central; }#UMaNlEFRJphI .fx3 {dominant-baseline: central}#UMaNlEFRJphI .fx4 { stroke: none; }#UMaNlEFRJphI .fx4 {stroke: none}#UMaNlEFRJphI .fc0 { fill: var(--text-caption); }#UMaNlEFRJphI .fc0 {fill: #646a73}#UMaNlEFRJphI .fa2 { fill: var(--text-link-disabled); }#UMaNlEFRJphI .fa2 {fill: rgb(187, 191, 196)}#UMaNlEFRJphI .fx5 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#UMaNlEFRJphI .fx5 {font-style: normal}#UMaNlEFRJphI .fx6 { text-anchor: start; }#UMaNlEFRJphI .fx6 {text-anchor: start}#UMaNlEFRJphI .fx7 { dominant-baseline: alphabetic; }#UMaNlEFRJphI .fx7 {dominant-baseline: alphabetic}#UMaNlEFRJphI .fc1 { fill: rgb(0, 0, 0); }#UMaNlEFRJphI .fc1 {fill: rgb(0, 0, 0)}#UMaNlEFRJphI .fx8 { font: 700 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#UMaNlEFRJphI .fx8 {font-style: normal}#UMaNlEFRJphI .fc2 { fill: rgb(152, 183, 198); }#UMaNlEFRJphI .fc2 {fill: rgb(152, 183, 198)}#UMaNlEFRJphI .fb1 { fill: var(--N900-FG, 0.15); }#UMaNlEFRJphI .fb1 {fill: rgba(31,35,41, 0.15)}#UMaNlEFRJphI .fb2 { fill: rgb(203, 205, 209); }#UMaNlEFRJphI .fb2 {fill: rgb(203, 205, 209)}#UMaNlEFRJphI .fa3 { fill: var(--bg-body); }#UMaNlEFRJphI .fa3 {fill: #fff}ABC12345层级作用可复用工作流的编写格式可安装、可分发的打包单元连接 GitHub/Slack 等外部服务的权限层扩展工具调用面或共享上下文的服务端层对应场景单仓库试验性逻辑跨团队共享工作流需要操作第三方工具自定义工具或数据源SkillPluginAppMCP 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 中调用：
在 ChatGPT Work 模式中调用：
$plugin-creator 会自动完成以下操作：
创建插件目录结构
生成必需的 .codex-plugin/plugin.json 清单
创建本地 marketplace 条目用于即时测试
如有 MCP 服务器，自动写入 .mcp.json 并在 plugin.json 中引用
生成的目录结构如下（仅 plugin.json 属于 .codex-plugin/ 目录，其余文件放插件根目录）：
SKILL.md 格式示例：
SKILL.md 由两部分组成：--- 包裹的 frontmatter（name 和 description 字段）+ 自然语言形式的工作流指令。指令写得越具体，Codex 执行结果越稳定。
plugin.json 核心字段全解析
plugin.json 是插件的唯一入口清单，必须放在 .codex-plugin/ 目录下。以下是一个完整的生产级配置示例：
关键字段说明：
mcpServers 的两种配置方式：
插件中的 Skill 如果需要调用 AI 模型，可以通过兼容 OpenAI SDK 格式的标准 API 接入，例如七牛云 Token Plan 提供了多模型统一接口，开发者无需为不同模型维护多套调用代码。
三种 Marketplace：本地开发 → 团队分发 → 公开发布
Codex 插件的三种分发模式对应三类 marketplace，开发阶段逐步从本地迁移到公共目录。
模式一：Personal Marketplace（默认）
配置文件位置：~/.agents/plugins/marketplace.json
适合个人本地测试，新建插件默认加入此 marketplace。配置示例：
JSON
注意：source.path 必须以 ./ 开头，路径相对于 marketplace.json 所在目录解析，而非 .agents/plugins/ 文件夹。
模式二：Repo/Team Marketplace
配置文件位置：
提交到仓库后，团队成员拉取代码即可访问同一套插件。支持三种插件来源：
•
"source": "local" — 本地目录（适合仓库内插件）
•
"source": "git-subdir" — 外部 Git 仓库子目录（适合跨仓库共享）
•
"source": "npm" — npm 包（适合版本化发布）
Git 子目录源示例：
代码块
JSON
"source": {"source": "git-subdir","url": "https://github.com/example/codex-plugins.git","path": "./plugins/repo-triage-plugin","ref": "main"}
JSON
Codex CLI 管理命令：
代码块
C#
# 添加 marketplace
codex plugin marketplace add owner/repo
codex plugin marketplace add ./local-marketplace-root
# 查看已安装
codex plugin marketplace list
# 更新插件
codex plugin marketplace upgrade
# 移除 marketplace
codex plugin marketplace remove marketplace-name
C#
安装后插件缓存于：~/.codex/plugins/cache/PLUGIN_NAME/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 等钩子：
代码块
Bash
Bash
钩子中可用的环境变量：
安全提示： 安装插件不会自动信任其 Hooks，用户需手动审核并授权 Hooks 执行权限。
MCP 服务器集成
.mcp.json 定义插件捆绑的 MCP 服务器，格式与标准 .mcp.json 相同：
代码块
JSON
{"mcpServers": {"issue-tracker": {"type": "http","url": "https://api.example.com/mcp/issues"}}}
JSON
MCP 服务器随插件一起安装，无需用户额外配置，是插件相对于独立 Skill 的核心能力扩展点。