OpenAI Codex Plugins 导读：插件目录、安装方式与本地打包入门

Posted March 27, 2026 by XAI 技术团队 ‐ 15 min read

OpenAI 在 Codex 官方文档中提供了 Plugins 页面，专门说明：怎样把一套可复用的工作流、技能说明和外部工具整合成一个可安装的插件，再让 Codex 在不同项目里复用它。

上图：官方文档展示的 Codex 插件目录。它更像一个“工作流商店”或“能力目录”，而不是只给工程师看的配置页。

如果你平时主要把 Codex 当作“会写代码、会改代码的 AI 助手”，那这篇文章可以把官方文档翻成更容易理解的话：Codex Plugin 可以把你常用的一套能力打包起来，像安装软件包一样给自己、给团队、给不同项目重复使用。

说明：本文根据 OpenAI 官方 Codex / Plugins 文档整理，保留关键配图、命令和结构，但会用更适合普通用户理解的方式重新组织，不是逐段全文照搬。

先记住这 6 个结论

Codex Plugin 本质上是一个“可安装的工作流包”，不是单独一条 prompt，也不是旧时代那种“网页插件”概念。
一个插件里可以打包三类东西：skills、可选的应用集成、以及 MCP 服务器配置。
普通用户最常见的入口有两个：Codex App 里的插件目录，以及 CLI 里的 /plugins。
如果你只是给自己当前仓库用，很多时候先写本地 skill 就够了，不一定要上来就做成 plugin。
如果你想复用到多个项目，或者分享给团队，plugin 才开始体现价值。
截至当前官方文档，面向公众的官方 Plugin Directory 自助发布还在 “coming soon” 阶段，也就是机制已经成形，但公共发布入口还没有完全开放。

Codex Plugin 到底是什么

官方文档给出的定义很直接：插件是可安装的 bundle，用来封装可复用的 Codex 工作流。

你可以把它理解成一个“打包盒子”，里面可以装：

Skills：告诉 Codex 应该怎么完成某类工作流的说明文件。
Apps：可选的应用或连接器映射。
MCP servers：插件需要用到的远程工具或共享上下文。

换句话说，如果你有一套固定流程，比如：

读 GitHub issue 后自动整理任务拆分
连上 Slack / Notion / Linear 再做跨工具协作
调用某个 MCP 服务去查资料、执行操作、补上下文

那么这些东西就不必零散地拼在一起，而是可以做成一个 Codex Plugin，后面重复安装、重复复用。

普通用户平时怎么用插件

1. 在 Codex App 里找插件

官方文档提到，由 OpenAI 筛选维护的插件会出现在 Codex 的插件目录里。如果你只是想“装现成的，不想自己折腾目录结构”，这通常是最简单的入口。

这里的重点不是“插件多不多”，而是 Codex 开始把技能、工具链和外部服务统一成一个安装面板。对普通用户来说，这意味着以后很多常见工作流不必再从零手写配置。

2. 在 CLI 里用 `/plugins`

如果你主要在终端里用 Codex，官方给出的入口是：

codex
/plugins

上图：官方文档里的 CLI 插件界面示例。你可以直接在命令行界面里浏览和安装插件。

这也说明一件事：Codex 的插件能力不是只给图形界面准备的。 如果你的工作流本来就在终端里，插件一样能装、一样能切换。

自己做本地插件，最快的路是什么

先用 `@plugin-creator`

官方文档给出的第一推荐方案不是手工建目录，而是直接使用内置的 @plugin-creator skill。

上图：官方文档展示的 @plugin-creator。它的作用是帮你快速 scaffold 一个本地插件。

它至少能帮你做两件事：

生成必需的 .codex-plugin/plugin.json
按需要创建一个本地 marketplace 条目，方便你测试这个插件

如果你已经在别的生态里有现成插件，或者你手头已经做了一个本地插件，官方文档也建议通过 @plugin-creator 把它接到本地 marketplace 里，而不是完全手写。

也可以手动把本地插件挂进 marketplace

如果你不想用 @plugin-creator，也可以手工配置。本地安装的核心概念不是“直接指向某个文件夹”，而是先有一个 marketplace 清单，再让 Codex 从这个清单里加载插件。

官方文档给了两种常见方式：

Repo marketplace：写在当前项目里，适合团队一起用
Personal marketplace：写在用户主目录里，适合只给自己用

上图：官方文档里的本地 marketplace 示例。除了官方目录外，你也可以加载自己的本地插件目录。

Repo marketplace 和 Personal marketplace 有什么区别

Repo marketplace

适合这种场景：

这个插件就是为当前仓库服务的
你想把插件随仓库一起管理
团队成员拉下仓库后也能看到同样的插件入口

官方文档建议把 marketplace 文件放在：

$REPO_ROOT/.agents/plugins/marketplace.json

插件目录常见放法是：

$REPO_ROOT/plugins/my-plugin

一个简化后的示意配置可以写成这样：

{
  "name": "local-repo",
  "interface": {
    "displayName": "My Local Repo Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Personal marketplace

适合这种场景：

这是你自己的私人工作流
你想跨多个项目复用
你不想把插件内容提交到某个具体仓库里

官方文档建议把个人 marketplace 放在：

~/.agents/plugins/marketplace.json

插件目录常见放法是：

~/.codex/plugins/my-plugin

无论是哪一种 marketplace，文档里都强调了几个规则：

source.path 应该是相对 marketplace 根目录的路径
路径应当以 ./ 开头
每个插件条目都应该带上 policy.installation、policy.authentication 和 category

你改完插件内容后，通常还需要更新对应目录并重启 Codex，这样本地安装才能拿到新版本。

marketplace 在 Codex 里是干什么的

很多人第一次看官方文档，会误以为 marketplace 就是“官方插件商店”。其实不完全是。

更准确地说，marketplace 是一份 JSON 插件目录清单。Codex 可以读取它，再把里面列出的插件展示出来并安装。

官方文档提到，Codex 可以从三类地方读取 marketplace：

官方 curated marketplace，也就是内置的官方插件目录
仓库级 marketplace：$REPO_ROOT/.agents/plugins/marketplace.json
个人级 marketplace：~/.agents/plugins/marketplace.json

插件装上之后，Codex 会把它安装到本地缓存目录。文档给出的缓存路径是：

~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/

对于本地插件，$VERSION 会被记成 local。另外，每个插件的启用/停用状态会记录在：

~/.codex/config.toml

这套设计的意义是：插件并不是零散地“挂一个目录就算数”，而是有一层清单、安装和启用状态管理，这样更接近真正可维护的软件分发方式。

一个 Codex Plugin 目录长什么样

官方文档给出的规则非常明确：只有 .codex-plugin/plugin.json 是必需的入口文件，其他内容都可以按需加。

一个最典型的目录大概是这样：

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

这里最值得注意的一点是：

.codex-plugin/ 目录里只放 plugin.json
skills/、assets/、.app.json、.mcp.json 都放在插件根目录

这套组织方式很“工程化”，但它的好处是清楚：入口、功能、资源、扩展配置分层明确，不容易越做越乱。

`plugin.json` 里通常写什么

如果你只是做一个最小可用插件，完全可以先从这种极简版本开始：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "A reusable workflow bundle",
  "skills": "./skills/"
}

这里的几个重点：

name：插件的稳定标识，官方建议用 kebab-case
version：插件版本
description：一句话说明这个插件干什么
skills：指向你打包进来的技能目录

如果插件更完整，还可以继续加这些信息：

发布者信息：author、homepage、repository、license、keywords
组件入口：mcpServers、apps
安装界面展示信息：interface

而 interface 下面又常见这些字段：

displayName、shortDescription、longDescription
developerName、category、capabilities
websiteURL、privacyPolicyURL、termsOfServiceURL
defaultPrompt、brandColor
composerIcon、logo、screenshots

如果你把它类比成一个 App 商店条目，这些字段就很好理解了：它们不是让插件“能运行”的最低要求，而是让插件“更适合被安装和展示”的元数据。

想做第一个插件，最小步骤是什么

官方文档建议从“只打包一个 skill”开始，而不是一上来就接一堆外部服务。

最小流程可以概括成三步：

新建插件目录，并创建 .codex-plugin/plugin.json
在 skills/<skill-name>/SKILL.md 里写一个技能说明
通过本地 marketplace 把它加载进 Codex

你甚至可以把第一版理解成：

一个 plugin.json
一个 SKILL.md
一个 marketplace 条目

先跑通，再慢慢加 .mcp.json、.app.json 和图标资源。

这种路径很合理，因为它避免了最常见的问题：还没验证流程值不值得复用，就先把打包、发布、图标、元数据全做了一遍。

什么时候该用 plugin，什么时候只用 skill

官方文档在这里给出的建议其实非常实用，可以直接翻译成一句话：

先本地，后打包；先验证，后分发。

更适合先用本地 skill 的情况

你只是在当前仓库里试一个工作流
这个行为非常个人化、项目化
你还在实验，不确定是不是值得长期保留

更适合做成 plugin 的情况

你想在多个项目、多个仓库里重复使用
你想把 skills、MCP 配置和 app 集成统一装进一个包
你想给同事、团队或者 marketplace 提供一个稳定版本

所以对大多数普通用户来说，一个很稳妥的路线是：

先写本地 skill
觉得好用以后，再升级成 plugin
等需要跨项目、跨团队分发时，再认真补齐 marketplace 和界面元数据

普通用户可以怎样理解这件事

如果把这页官方文档放回真实使用场景里，Codex Plugins 的意义大概可以概括成三层：

对使用者来说：以后越来越多现成工作流会变成“可安装项”，而不是零散说明文档。
对重度用户来说：你常用的一套技能、工具和连接器，终于可以被打成一个有结构的包。
对团队来说：同样的 Codex 使用方式可以标准化，而不是每个人都各写一份 prompt 和配置。

这也是为什么官方在文档里一直强调 marketplace、manifest、install policy、display metadata 这些词。它想做的不是“再加一个提示词功能”，而是把 Codex 的能力逐步变成可分发、可安装、可管理的插件生态。

目前还没完全开放的部分

如果你已经在想“那我怎么把自己的插件公开发布到官方目录里”，官方文档目前给出的答案还是比较克制：

添加到官方 Plugin Directory：coming soon
自助发布和管理：coming soon

也就是说，本地插件、私有插件、仓库内插件的路径已经很清楚了；真正面向公开市场的完整发布流程还在逐步开放。

资料来源

OpenAI Developers: Plugins – Codex