从零搭建自己的 Codex Plugin Marketplace：一份可落地的实践指南

从零搭建自己的 Codex Plugin Marketplace：一份可落地的实践指南

当你团队里第 N 个人问"那个代码评审的工作流你是怎么配的"时，你就该考虑把它做成插件，再搭一个属于自己的 Marketplace 了。

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

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

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

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

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

值得一提的是，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 遵循语义化版本。市场依赖它判断是否提示用户升级。
• 所有路径必须相对于插件根目录，且以 ./ 开头。写成绝对路径或漏掉 ./ 是新手最高频的错误——本地能跑，安装时却报"无效清单"。

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

这种"字段指向文件"的设计让 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 会话里直接调用它，它会帮你：

如果你已经有现成的插件文件夹，也可以让 @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 之间的数据流转。这一步比纯命令行调试更接近上线后的真实体验，建议正式发布前至少完整走一遍。

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

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

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

九、踩坑记录与最佳实践

十、结语

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

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

本文基于 2026 年 9 月的 Codex 插件机制撰写，插件生态迭代很快，建议以官方最新文档为准。