平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“从零搭建自己的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 会话里直接调用它，它会帮你：

1. 生成必需的 .codex-plugin/plugin.json 清单；
2. 生成一个本地 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 之间的数据流转。这一步比纯命令行调试更接近上线后的真实体验，建议正式发布前至少完整走一遍。

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

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

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

九、踩坑记录与最佳实践

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

十、结语

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

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

从实现思路看，总的来说，Codex适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。