从零搭建自己的Codex Plugin Marketplace的实践指南

2026-09-23 09:50:38 AI砖家

2026 年，AI 编码助手的竞争已经从"模型能力"卷到了"生态能力"。OpenAI Codex 在今年补齐了 skills 体系和插件市场（Plugin Marketplace）之后，插件成了在团队内分发工作流、工具链和最佳实践的标准载体。这篇文章不讲概念宣传，只讲一件事：如何从零搭建一个属于你自己（或你团队）的 Codex 插件市场，包括插件打包、市场清单编写、CLI 管理、分发策略和我踩过的坑。

一、先搞清楚：Marketplace 到底是什么

很多人第一次看到官方文档，会以为 Marketplace 就是"OpenAI 官方插件商店"。这是一个误解。

Marketplace 的本质，是一份 JSON 格式的插件目录清单。 Codex 读取这份清单，把里面列出的插件展示出来并安装。它可以是官方维护的，也可以是你自己写的——这是整个机制里最关键的一点。

Codex 可以从四个位置读取市场文件：

市场类型	位置	适用场景
官方精选市场	内置	直接使用 OpenAI 官方插件目录
仓库级市场	`$REPO_ROOT/.agents/plugins/marketplace.json`	团队共享，随项目仓库分发
个人市场	`~/.agents/plugins/marketplace.json`	只给自己用的私有工作流
Git 远程市场	通过 `codex plugin marketplace add` 登记	跨仓库、跨团队分发

值得一提的是，Codex 还兼容读取 $REPO_ROOT/.claude-plugin/marketplace.json 这种遗留格式——几大厂商的插件结构正在趋同，这意味着你在其他生态里积累的 skill，迁移成本比想象中低。

这套设计的意义在于：插件不是"挂个目录就算数"，而是有清单、安装缓存、启用状态三层管理，更接近真正可维护的软件分发方式。

二、插件解剖：一个插件的最小组成

一个完整的插件目录结构长这样：

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # 必需：插件清单（身份证）
├── skills/
│   └── my-skill/
│       ├── SKILL.md          # 必需：技能说明 + 元数据
│       ├── scripts/          # 可选：可执行脚本
│       └── references/       # 可选：文档和模板
├── apps/                     # 可选：ChatGPT app 集成
└── mcp.json                  # 可选：MCP server 配置

但真正能跑起来的最小插件只有三个文件：一个 plugin.json、一个 SKILL.md、一条 marketplace 条目。建议第一版就这样开始，先把流程跑通，再慢慢加 MCP、app 集成和图标资源——避免"还没验证流程值不值得复用，就先把打包发布全做了一遍"这个最常见的坑。

plugin.json：插件的身份证

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

几个要点：

name 用 kebab-case 且保持稳定。Codex 把它当作插件标识符和组件命名空间，后续版本升级不要改，否则市场无法识别为同一插件的迭代。
version 遵循语义化版本。市场依赖它判断是否提示用户升级。
所有路径必须相对于插件根目录，且以 ./ 开头。写成绝对路径或漏掉 ./ 是新手最高频的错误——本地能跑，安装时却报"无效清单"。

如果要面向展示层（比如让更多人浏览安装），还需要补充元数据：

字段	说明
`author` / `repository`	标识插件来源
`interface.displayName`	市场列表中展示的名称
`interface.category`	插件分类，影响浏览路径
`interface.capabilities`	能力标签数组
`mcpServers` / `apps` / `hooks`	指向对应组件配置文件

这种"字段指向文件"的设计让 manifest 保持精简，技能说明、工具配置拆到独立文件维护，多人协作改不同组件也不容易冲突。

SKILL.md：插件的大脑

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

Skill 就是一份带 frontmatter 的 Markdown：元数据告诉 Codex 这是什么、什么时候该调起它，正文是写给模型看的指令。写 skill 的质量直接决定插件好不好用——这是另一个大话题，本文不展开。

三、动手：从零搭一个插件

方式一：用内置的@plugin-creator（推荐）

官方推荐的第一方案不是手工建目录，而是直接用内置的 $plugin-creator skill。在 Codex 会话里直接调用它，它会帮你：

生成必需的 .codex-plugin/plugin.json 清单；
生成一个本地 marketplace 条目，方便立即测试。

如果你已经有现成的插件文件夹，也可以让 @plugin-creator 把它挂进本地市场，不必完全手写。

方式二：手动搭建（理解原理用）

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

然后分别写入上面展示的 plugin.json 和 SKILL.md 即可。没有编译步骤，改完文件装到本地就能测。

四、核心环节：搭建你自己的 Marketplace

插件做好了，下一步是把它"摆上货架"。前面说过，市场就是一份 JSON 清单，所以搭建市场 = 写一个 marketplace.json + 决定把它放哪。

4.1 个人市场：只给自己用

在 ~/.agents/plugins/marketplace.json 写入：

{
  "name": "my-personal-tools",
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-first-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity",
      "interface": {
        "displayName": "My First Plugin"
      }
    }
  ]
}

注意 source.path 是相对于市场根目录解析的（不是相对于 .agents/plugins/ 文件夹），必须以 ./ 开头。

4.2 仓库级市场：团队共享

把同样的文件放到 $REPO_ROOT/.agents/plugins/marketplace.json，插件本体放在仓库里（比如 $REPO_ROOT/plugins/ 下），随仓库一起提交。团队成员 clone 下来重启 Codex，就能在插件目录里看到你的市场——这是团队内部分发工作流最顺滑的方式。

4.3 重启生效

修改市场文件或插件内容后，重启 Codex 让本地安装读取新文件。然后打开插件目录（CLI 里输入 /plugins，或在 Codex App 的插件页），选择你的市场，就能浏览和安装里面的插件。

五、用 CLI 管理市场：codex plugin marketplace

当市场多了、来源变成远程 Git 仓库时，就该用 CLI 管理了。注意 codex plugin marketplace 是终端命令，不是会话里的斜杠命令，别敲混了。

添加市场

# GitHub 简写（最常用）
codex plugin marketplace add owner/repo
# 钉住某个 Git ref（分支 / tag / commit）
codex plugin marketplace add owner/repo --ref main
# 完整 Git URL + 稀疏检出（monorepo 场景）
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
# 本地市场根目录（调试用）
codex plugin marketplace add ./local-marketplace-root

市场来源可以是 GitHub 简写（owner/repo 或 owner/repo@ref）、HTTP/SSH 的 Git URL，或本地目录。--sparse PATH 只对 Git 来源有效，可以多次使用，适合插件仓库很大时只拉取需要的子目录。

重要认知：添加市场 ≠ 安装插件。 add 只是把这个"货架"登记下来，让它出现在插件目录的可选来源里，一个插件都还没装。

查看、升级、移除

codex plugin marketplace list                      # 列出所有已登记市场及解析根路径
codex plugin marketplace upgrade                   # 刷新全部市场快照
codex plugin marketplace upgrade marketplace-name  # 只刷新指定市场
codex plugin marketplace remove marketplace-name   # 移除市场

之后装插件在 /plugins 面板里选 Install 即可。

六、安装与启用的内部机制

理解 Codex 怎么存插件，对排查问题非常有帮助：

安装缓存路径：插件会被安装到
~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/
本地插件的 $VERSION 记为 local。Codex 从这个缓存路径加载已安装的副本，而不是直接从市场条目加载——所以你改了插件源文件，需要重启让缓存更新。
启用状态：每个插件的开启/关闭状态记录在 ~/.codex/config.toml 中，可以独立启用或禁用。
新线程生效：装完插件后，官方明确要求开一个新线程（new thread）再使用。然后在输入框描述任务，或输入 @<插件名或 skill 名> 点名调用。如果 @ 调不起来，先检查是不是没开新线程；带 app/MCP 的插件还要确认授权流程走完了。

七、进阶：让插件连接真实世界

纯 skill 插件只能编排 Codex 自身的行为。真正强大的插件是 skill + MCP 的组合：

MCP server：在插件里加 mcp.json 声明 MCP server 配置，让插件能连接外部工具和系统（数据库、内部 API、第三方服务）。
依赖声明：如果 skill 依赖某个 MCP，在 agents/openai.yaml 里声明依赖，Codex 会自动安装并接好线。
ChatGPT app 集成：需要真实对话环境调试 MCP-backed app 时，可以在 ChatGPT 设置里开启开发者模式创建 app，拿到 app ID 后通过 $plugin-creator 关联，验证插件与 app 之间的数据流转。这一步比纯命令行调试更接近上线后的真实体验，建议正式发布前至少完整走一遍。

八、分发策略：三种场景怎么选

场景	推荐方式
个人跨机器使用	个人市场 + Git 仓库托管，新机器上 `codex plugin marketplace add` 一条命令搞定
团队内统一工作流	仓库级市场（`.agents/plugins/marketplace.json` 随项目走），零配置分发
跨团队 / 社区分享	GitHub 仓库市场，用户 `add owner/repo` 即可；需要精细化分享时用 Codex App 的工作区共享功能

工作区共享的路径是：Codex App → 插件 → “由你创建” → 插件详情 → 共享，可以添加工作区成员或复制链接。注意这只在工作区边界内可见，不会发布到公共目录。

至于官方公共市场，目前 OpenAI 还没有开放自助提交通道（官方表示第三方提交即将到来），所以现阶段自建市场就是唯一且完全够用的分发方式。

九、踩坑记录与最佳实践

路径引用错误是第一大坑。plugin.json 里的 skills、marketplace.json 里的 source.path，全部要求相对路径 + ./ 前缀。提交前建议在干净目录里重新 clone 一遍仓库，模拟真实安装环境跑完整测试。
加市场和装插件是两步。marketplace add 之后别急着 @ 调用，还要在 /plugins 里 Install，再开新线程。
CLI 命令 vs 会话命令。codex plugin marketplace add 在终端敲，/plugins 在会话里敲，@plugin-name 在新线程里敲——三者别混。
name 一旦发布就不要改。版本可以升，名字不能动。
先用最小插件验证流程。一个 plugin.json + 一个 SKILL.md + 一条市场条目，跑通了再叠加 MCP 和 app。
善用 --ref 和 --sparse。给团队分发时用 --ref 钉住稳定 tag，甚至可以搭两个市场（stable / latest 指向不同 ref）实现发布通道；monorepo 用 --sparse 减少拉取量。

十、结语

Codex 的插件市场机制本质上回到了软件分发的第一性原理：一份清单 + 一个缓存 + 一个开关。没有花哨的审核后台，没有复杂的打包工具，JSON 和 Markdown 就是全部。

这也意味着门槛极低、自由度极高：今天下午你就可以把自己最顺手的那套工作流打成插件，写一份 marketplace.json，推到团队仓库里——从"口头相传的配置玄学"变成"一条命令装好的工程资产"。这大概就是插件生态对团队最大的价值。

以上就是从零搭建自己的Codex Plugin Marketplace的实践指南的详细内容，更多关于Codex Plugin Marketplace搭建指南的资料请关注脚本之家其它相关文章！