Codex 插件

概述

Codex 插件是可安装、可分发的能力包。一个插件可以只包含 Skills，也可以连接 MCP Server，还能附带 hooks、浏览器扩展和定时任务模板等特定宿主支持的组件。它解决的是一组能力如何被统一发现、安装、启用和更新。

截至 2026 年 8 月 19 日，ChatGPT 与 Codex 共用公共 Plugins Directory，同一个公开插件可以出现在两边支持的界面中。Codex 目前可在 ChatGPT desktop app 和 Codex CLI 中浏览插件，IDE extension 尚不支持插件。

组成关系

插件、Skill 和 MCP Server 的职责不同：

对象	负责内容	适用情况
Skill	指令、参考资料、脚本和固定工作流	现有工具足够，只需要告诉模型如何稳定完成任务
MCP Server	工具、数据、鉴权和服务端行为	需要访问外部系统或受控执行能力
Plugin	把 Skills、MCP 和元数据打包成可安装产品	需要安装、共享、升级或公开发布

只有一个仍在调整的个人工作流时，先写 Skill 更轻。需要把一组 Skills 交给团队安装，或把工作流和外部服务一起发布时，再做成插件。

支持入口

Desktop App

在 ChatGPT desktop app 中打开 Plugins Directory，可以从以下来源浏览插件：

• OpenAI 提供的插件
• 工作区管理员提供的插件
• 个人创建或共享的插件
• 本地和仓库 Marketplace

安装后需要新建 chat，新的会话才会加载插件内的 Skills 和工具。包含 Connector 的插件可能在安装时要求登录，也可能等第一次调用时再认证。

Codex CLI

在交互会话中打开插件浏览器：

/plugins

浏览器按 Marketplace 分组。可以查看详情、安装或卸载插件；选中已安装插件后按 Space 可启用或停用。安装完成后同样要启动新 session，当前 session 不会临时注入刚安装的组件。

使用 OpenAI API key 登录 Codex 时，也能管理一部分 OpenAI 筛选的插件。不过依赖特定 OAuth 流程的插件可能不可用，实际列表以当前插件浏览器为准。

插件结构

Codex 插件以 .codex-plugin/plugin.json 为必需入口。其他组件放在插件根目录，不放进 .codex-plugin/：

meeting-follow-up/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── meeting-follow-up/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
├── assets/
├── .app.json
└── .mcp.json

这些文件分别承担不同职责：

• .codex-plugin/plugin.json：插件身份、组件路径和安装界面元数据
• skills/：一个或多个可复用工作流
• hooks/hooks.json：Codex 生命周期 hook
• .app.json：已注册 MCP Server 的兼容映射
• .mcp.json：随插件分发的 MCP Server 配置
• assets/：图标、Logo 和截图

公开插件可以包含宿主专属能力。例如 hooks 只在 Codex 中运行，即使插件在 ChatGPT 和 Codex 的公共目录中使用同一个条目。

最小插件

一个只包含 Skill 的插件已经完整可用。先创建目录：

mkdir -p meeting-follow-up/.codex-plugin
mkdir -p meeting-follow-up/skills/meeting-follow-up

编写 .codex-plugin/plugin.json：

{
  "name": "meeting-follow-up",
  "version": "1.0.0",
  "description": "从会议记录中提取决定和后续事项",
  "skills": "./skills/"
}

name 应使用稳定的 kebab-case 名称。它既是插件标识，也是组件命名空间，发布后随意修改会被识别成另一个插件。

再编写 skills/meeting-follow-up/SKILL.md：

---
name: meeting-follow-up
description: 从会议记录中提取决定、负责人、后续事项和未决问题。
---

读取会议记录，按以下结构输出：

1. 已确认的决定
2. 后续事项、负责人和截止时间
3. 尚未解决的问题

Skill 的 description 要写清触发场景。描述太宽，Codex 会在无关任务中加载它；描述太窄，又可能到了该用的时候认不出来。

Plugin Creator

Codex 内置的 $plugin-creator Skill 可以生成目录、必需的 manifest 和本地 Marketplace 条目。一个具体的请求如下：

$plugin-creator 创建名为 meeting-follow-up 的插件。
加入一个 Skill，把会议记录整理为决定、负责人、后续事项和未决问题。
同时添加个人 Marketplace 条目，供本地安装测试。

生成完成后仍应手工检查：

• .codex-plugin/plugin.json 中的名称和组件路径
• 每个 SKILL.md 的触发描述与执行步骤
• .app.json 是否指向正确的 MCP 注册 ID
• Marketplace 的 source.path 是否能解析到插件根目录

脚手架只能保证结构起点，不能替插件决定权限、数据边界和验收标准。

本地市场

本地 Marketplace 是一个 JSON 目录，用于开发测试、仓库共享和私有分发。常见位置有两个：

• 仓库级：$REPO_ROOT/.agents/plugins/marketplace.json
• 个人级：~/.agents/plugins/marketplace.json

仓库级插件通常放在 $REPO_ROOT/plugins/。例如：

{
  "name": "local-repo",
  "interface": {
    "displayName": "Repository Plugins"
  },
  "plugins": [
    {
      "name": "meeting-follow-up",
      "source": {
        "source": "local",
        "path": "./plugins/meeting-follow-up"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

source.path 相对 Marketplace 根目录解析，不是相对 .agents/plugins/ 解析，并且本地相对路径要以 ./ 开头。这个位置写错时，目录文件本身仍是合法 JSON，但插件不会出现在可安装列表里。

Codex CLI 可以注册和管理 Marketplace：

codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

Git 来源还支持 --sparse，适合只拉取大型仓库中的插件目录。Codex 安装 Marketplace 插件后，会从 ~/.codex/plugins/cache/ 中的副本加载，不直接运行 Marketplace 源目录。

权限与数据

插件不会绕过宿主权限。能力通过 Codex 执行时，仍受当前 sandbox 和 approval policy 约束；Connector 和 MCP Server 还要遵守外部服务自己的认证与授权规则。

安装前需要分别审查几类风险：

• Skills 是否会引导 Codex 读取或修改超出预期的内容
• hooks 是否会在生命周期事件中自动执行命令
• MCP Server 会接收哪些数据、暴露哪些写操作
• Connector 请求哪些账号权限
• 外部服务的数据保留和隐私条款

卸载插件只删除当前 ChatGPT 或 Codex 环境中的插件包。已经建立的 Connector 连接不会自动断开，需要到 ChatGPT 的连接管理中另行处理。

分发边界

公共插件发布到 ChatGPT 与 Codex 共用的 Plugins Directory。仓库级和个人 Marketplace 则用于本地开发、团队共享或私有目录，两者不是公共发布流程。

工作区管理员可以把个人插件发布到工作区，并按角色控制可见范围。这仍不会把插件公开到公共目录。公开提交还需要准备发布者信息、隐私政策、测试用例，以及 MCP 插件所需的工具和鉴权审查材料。

Codex 插件与 Claude Code 插件虽然都能打包 Skill、MCP 和 hooks，但清单和 Marketplace 格式不同。Codex 使用 .codex-plugin/plugin.json，不能把 Claude Code 的 .claude-plugin/plugin.json 直接改个目录名就当作兼容包。

参考

• Plugins in ChatGPT and Codex
• Build plugins
• Plugin architecture
• Package your plugin