2026 Codex Plugins 插件教程：创建、安装、plugin.json 与 Marketplace

先看结论：个人工作流先做 Skill，要分发再做 Plugin

只在一个仓库或自己电脑使用的步骤，优先从本地 Skill 开始；需要把多个 Skills、连接器、MCP 配置、Hooks 或品牌资源作为一个可安装包交给别人时，再创建 Plugin。

最快的创建方法是调用内置 @plugin-creator（Codex 中也可用 $plugin-creator），让它生成必需的 .codex-plugin/plugin.json 和本地 Marketplace 条目。普通用户在 ChatGPT 网页 Work mode、ChatGPT 桌面 App 的 Work mode / Codex，或 Codex CLI 的 /plugins 中浏览安装；IDE 扩展与移动端当前不提供 Plugin 浏览器。

Codex Plugins 在哪里能用：网页、桌面 App、CLI、IDE 不一样

如果你搜的是“VS Code 如何安装 Codex 插件”，目标其实是 OpenAI 的 IDE Extension，请转到Codex VS Code 扩展安装与不显示排查。本页讨论的是可组合 Skills、连接器、MCP 和 Hooks 的 Codex Plugin 包。

Codex Plugin、Skill、MCP、Hook 和 IDE 扩展怎么选

一个 Plugin 可以只包含一个 Skill，也可以同时声明多个 Skills、MCP Server、Apps 和 Hooks；但它并不会替代这些组件本身。先看Codex Skills 教程、MCP 配置教程和Hooks 教程，再决定哪些组件应该打包。

Codex Plugin 目录结构：只有 plugin.json 放进 .codex-plugin

每个 Plugin 的必需入口是根目录下的 .codex-plugin/plugin.json。Skills、Hooks、资源和配置文件都放在 Plugin 根目录，不要塞进 .codex-plugin/：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── review-pr/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
├── assets/
│   ├── icon.png
│   └── logo.png
├── .mcp.json
└── .app.json

plugin.json 的三个职责是标识插件、指向组件、提供安装页元数据。一个完整但仍易审计的示例：

{
  "name": "team-review",
  "version": "0.1.0",
  "description": "Bundle repeatable code review workflows.",
  "author": {
    "name": "Example Team",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/team-review",
  "repository": "https://github.com/example/team-review",
  "license": "MIT",
  "keywords": ["review", "quality"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "hooks": "./hooks/hooks.json",
  "interface": {
    "displayName": "Team Review",
    "shortDescription": "Repeatable review workflows",
    "developerName": "Example Team",
    "category": "Developer Tools",
    "capabilities": ["Read", "Write"],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png"
  }
}

最小清单只需要稳定的 kebab-case name、版本、描述，以及你实际包含的组件路径。不要为了“看起来完整”声明不存在的 MCP、Apps、Hooks 或能力；安装者应能从 manifest 和仓库内容判断真实边界。

方法一：使用 @plugin-creator 创建 Codex Plugin

官方当前推荐用内置 Creator 完成脚手架与本地 Marketplace 接线。给它清楚的目标、组件、作用域和测试方式，例如：

$plugin-creator

创建一个名为 team-review 的 Codex Plugin：
- 包含 review-pr Skill
- 只读取当前仓库，不连接外部服务
- 生成 .codex-plugin/plugin.json
- 添加 repo-scoped marketplace 条目
- 不添加 Hook 和 MCP Server
- 完成后验证目录与 JSON

1. 先限定能力

   明确是一个 Skill、多个 Skills，还是还需要 App、MCP 与 Hook。没需要的组件不要默认生成。

2. 选择 Marketplace 作用域

   团队仓库使用 repo Marketplace；只有自己使用时选 personal Marketplace。

3. 逐文件审核

   检查 manifest 路径、Skill 触发描述、MCP 域名、Hook 命令、资源与法律链接。

4. 在测试项目安装

   刷新或重启桌面 App，在 Plugins Directory 选择对应来源，再用新会话验证。

如果 Plugin 连接一个 ChatGPT Developer mode App，先在 ChatGPT 的 Settings → Security and login 启用 Developer mode，再在 Plugins 页面创建 App，取得以 plugin_asdk_app 开头的 ID；Creator 会生成 .app.json 并从 manifest 的 apps 字段引用。不要把别人的 App ID、OAuth 回调或凭证复制进自己的包。

方法二：手动创建最小 Plugin

如果只是把一个已经稳定的 Skill 包装成 Plugin，最小步骤并不复杂：

mkdir -p my-first-plugin/.codex-plugin
mkdir -p my-first-plugin/skills/hello

my-first-plugin/.codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

my-first-plugin/skills/hello/SKILL.md：

---
name: hello
description: Greet the user and ask how you can help.
---

Greet the user warmly and ask what outcome they want.

先运行 JSON 解析和目录检查，确认 skills 指向真实目录，再把 Plugin 接入 Marketplace。Plugin 名称应长期稳定；随意改名会改变标识与缓存路径。版本应在发布内容变化时更新，不能只改文件却让安装者继续看到旧版本。

Codex Marketplace 是什么：它是 JSON 目录，不等于官方审核

Marketplace 是一个列出 Plugin 来源、安装策略和展示分类的 JSON catalog。桌面 App 可读取官方目录、项目目录和个人目录；项目默认位置是 $REPO_ROOT/.agents/plugins/marketplace.json，个人默认位置是 ~/.agents/plugins/marketplace.json。

{
  "name": "team-plugins",
  "interface": { "displayName": "Team Plugins" },
  "plugins": [
    {
      "name": "team-review",
      "source": {
        "source": "local",
        "path": "./plugins/team-review"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}

• source.path 相对 Marketplace 根目录解析，不是相对 .agents/plugins/ 目录；本地路径应以 ./ 开头并保持在 Marketplace 根内。
• 一个 Marketplace 可以包含一个或多个 Plugins，不需要每个 Plugin 单独建目录文件。
• policy.installation 可表达 AVAILABLE、INSTALLED_BY_DEFAULT 或 NOT_AVAILABLE；policy.authentication 决定安装时或首次使用时认证。
• Git 来源可以固定 ref 或 sha。团队生产使用应固定可追溯版本，而不是永远追随未知的 main。
• npm 来源不会运行 lifecycle scripts，但仍要核对包、版本、registry 和依赖来源；Registry URL 不应嵌入凭证。

用 CLI 添加和维护 Marketplace

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-name

--sparse 只适用于 Git Marketplace。list 会列出 Codex 正在考虑的目录与解析根路径，是排查“文件存在但 Plugin 不显示”的第一批证据。CLI 命令负责管理 Marketplace 来源；本地 Plugin 的安装测试仍以 ChatGPT 桌面 App 或 CLI Plugin 浏览器的当前能力为准。

如何安装、启用、停用和卸载 Codex Plugin

ChatGPT 网页或桌面 App

1. 进入支持的 Work mode 或桌面 Codex，打开 Plugins。
2. 切换 OpenAI、工作区或 Personal 来源，搜索并打开详情。
3. 检查发布者、组件、权限、连接器和外部服务，点击加号安装。
4. 如果需要连接器，核对授权域名和 scopes 后再登录。
5. 安装完成后开启新聊天或新 Codex 会话，再显式用 @ 选择 Plugin / Skill，或直接描述任务。

Codex CLI

codex
/plugins

CLI 浏览器按 Marketplace 分组。打开详情后可安装或卸载；在已安装 Plugin 上按 Space 可切换启用状态。安装后重新开启会话，避免拿旧会话的能力列表判断“安装失败”。

桌面 App 会把 Marketplace Plugin 安装到类似 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/ 的缓存目录；本地 Plugin 的版本为 local。App 加载的是已安装缓存副本，不是你正在修改的源目录，所以更新本地 Plugin 后需要刷新目录、重新安装或重启 App，再用新会话验证。

Repo、Personal、Workspace 分享与公开发布的区别

在桌面 App 的 Plugins → Created by you 中可以打开详情并 Share 给工作区成员或群组。工作区分享不会自动把 Plugin 发布到公共目录；未登录该工作区的账号不能访问。管理员可以通过 requirements.toml 的 features.plugin_sharing = false 禁用分享。

安装 Codex Plugin 前的 12 项安全审查

1. 核对发布者、官网、仓库和 Marketplace 来源，不只看显示名称。
2. 检查 .codex-plugin/plugin.json 声明的 Skills、MCP、Apps、Hooks 与资源是否真实存在。
3. 阅读所有 SKILL.md，特别关注自动发布、删除、支付、凭证和权限变更指令。
4. 逐条审核 hooks/hooks.json 与脚本；Hook 是本地可执行代码。
5. 查看 .mcp.json 的命令、远程域名、工具列表与认证方式。
6. 连接器 OAuth 只授予任务需要的账号、工作区和最小 scopes。
7. 确认隐私政策、服务条款、数据保留和跨境处理主体。
8. Git 来源固定 ref 或 sha，并核对更新差异后再升级。
9. npm 来源核对 registry、包作用域、版本和依赖，不从带凭证的 URL 安装。
10. 首次使用在测试仓库和低权限账号中进行，保留审批提示。
11. 不要向 Plugin、网页或聊天提供 ChatGPT Session、Cookie、密码、私钥和恢复码。
12. 不再使用时卸载 Plugin，并单独撤销连接器 OAuth、Token 或外部服务权限。

Codex host 的 Sandbox 与 Approval 仍会约束通过 Plugin 运行的能力，但它们不能证明第三方服务可信。Marketplace 可发现性也不是官方背书；repo 或 personal Marketplace 完全可能包含组织自己维护或来源不明的代码。

Codex Plugin 不显示、未找到、安装后不生效：10 步排查

1. 确认当前入口支持 Plugins

   网页必须在 Work mode；桌面 App 使用 Work mode 或 Codex；IDE 扩展和移动端当前没有 Plugin 浏览器。

2. 确认来源已被发现

   运行 codex plugin marketplace list，检查 Marketplace 名称、根路径、Git 快照和本地默认目录。

3. 解析 marketplace.json

   确认 JSON 有效、plugins[] 存在、source 类型正确、path 以 ./ 开头并相对 Marketplace 根解析。

4. 检查 Plugin 必需入口

   源目录必须含 .codex-plugin/plugin.json；只有该文件属于 .codex-plugin/，组件应在根目录。

5. 核对 name、version 与组件路径

   名称使用稳定 kebab-case；skills、hooks、apps、mcpServers 和资源路径都应指向真实文件。

6. 刷新 Marketplace 或重启 App

   Repo / personal Marketplace 新增或修改后重启桌面 App；Git 来源可先运行 marketplace upgrade。

7. 重新安装本地缓存副本

   App 加载 cache 中的安装副本，不会自动执行你刚修改的源目录；更新后刷新、重装或重启。

8. 开启新聊天或新 CLI 会话

   已安装的 Skills 和工具通常在新会话进入能力列表，旧会话看不到不等于安装失败。

9. 检查启用状态与工作区策略

   CLI 中已安装 Plugin 可按 Space 开关；桌面状态存入配置。管理员也可能限制安装、分享或默认 Plugin。

10. 分离组件故障

    Plugin 可见但 Skill 不触发时检查 description；MCP 失败检查传输与认证；Hook 被跳过检查信任；连接器失败检查 OAuth 与权限。

Codex Plugins 创建与安装常见问题

Codex Plugin 是什么？

它是可安装的能力包，可以组合 Skills、连接器、MCP Servers、浏览器能力、Hooks、定时任务模板与展示资源。必需入口是 .codex-plugin/plugin.json。使用定时任务模板前，先分清 网页 Scheduled、桌面 Automations、聊天续跑与 CLI cron。

Codex Plugin 和 VS Code 插件是同一个吗？

不是。VS Code Marketplace 的 OpenAI Codex Extension 是编辑器入口；Codex Plugin 是在 Work mode、桌面 Codex 或 CLI Plugin 浏览器中安装的能力包。

如何创建 Codex Plugin？

最快方法是使用 @plugin-creator 或 $plugin-creator，明确名称、组件与 repo / personal Marketplace。也可手动创建根目录、.codex-plugin/plugin.json 和至少一个 Skill。

plugin.json 放在哪里？

固定放在 Plugin 根目录下的 .codex-plugin/plugin.json。Skills、Hooks、assets、.mcp.json 和 .app.json 应保留在 Plugin 根目录。

Codex Plugin 怎么安装？

在 ChatGPT 网页 Work mode、桌面 App 的 Work mode / Codex 中打开 Plugins，或在 Codex CLI 输入 /plugins。选择 Marketplace、检查详情、安装，然后开启新会话。

Codex Marketplace 是官网吗？

Marketplace 是 JSON 插件目录这一机制，不必然代表 OpenAI 官方目录。它可以来自官方、工作区、Git 仓库或个人本地文件；来源和审查级别必须分别核对。

为什么安装后 Plugin 不生效？

常见原因是使用了不支持的 IDE / Chat mode、Marketplace 路径错误、manifest 缺失、组件路径无效、App 仍加载旧缓存、Plugin 被停用，或安装后没有开启新会话。

Plugin 与 Skill 应该先做哪个？

先把单一工作流做成 Skill 并验证。需要分发、版本化、组合多个 Skills，或加入连接器、MCP 与 Hooks 时再包装为 Plugin。

安装 Plugin 会自动信任 Hooks 吗？

不应这样假设。Hook 是可执行代码，应在启用前审核当前定义、脚本和来源；Codex 的 Hook 信任、Sandbox、Approval 与组织策略仍然适用。

Plugin 不用了只关掉开关就够吗？

临时不用可以停用；彻底移除应卸载 Plugin，并单独撤销它连接过的 OAuth、Token 或第三方服务权限。隐藏 UI 不会自动取消外部授权。