发布日期：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 会自动完成以下操作：

  1. 创建插件目录结构

  2. 生成必需的 .codex-plugin/plugin.json 清单

  3. 创建本地 marketplace 条目用于即时测试

  4. 如有 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 管理命令：

# 添加 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

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

模式三：公共 Plugin Directory

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

  1. interface 字段完整（displayName、shortDescription、longDescription、category、privacyPolicyURL 必填）

  2. 所有 [TODO: ...] 占位符已替换（官方 scripts/validate_plugin.py 会拒绝含占位符的清单）

  3. 通过 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 获取最新规范。

延伸阅读

  • OpenAI Codex 插件开发官方文档：https://developers.openai.com/plugins/build/plugins

  • Codex plugin-json-spec 完整字段规范：https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md

  • LinSkills 技能生态（含可复用 Skill 包下载）：https://linskills.qiniu.com/

  • 七牛云 AI Token Plan（多模型统一管理）：qiniu.com/ai/plan