Codex Build Plugins：创建、测试和分发本地插件

适用场景

这篇手册适合想把 Codex 能力打包给团队复用的人。比如你已经写了一个好用的 Skill，想让同事也能安装；或者你希望把多个 skills、MCP 配置、应用集成和 hooks 放进同一个可管理的包。

如果你只是在一个仓库里反复做同一种事，先写 Skill。等它稳定、有多人使用需求，再升级为 Plugin。

Plugin 的最小结构

一个最小 Plugin 通常包含：

my-first-plugin/
  .codex-plugin/
    plugin.json
  skills/
    hello/
      SKILL.md

plugin.json 是插件清单，skills/ 里放可复用能力。后续你还可以加入 MCP、hooks、应用集成或 marketplace 元数据。

步骤 1：优先使用 plugin-creator

官方 Build plugins 文档推荐用内置 @plugin-creator skill 快速创建。它可以帮你生成必要的 .codex-plugin/plugin.json，也可以为本地测试创建 marketplace 入口。

你可以在 Codex 中这样描述：

@plugin-creator 请帮我创建一个本地 Codex plugin，包含一个用于生成发布检查清单的 skill，并生成本地 marketplace 配置。

生成后先不要急着分享，先检查 manifest、skill 描述和安装说明是否清楚。

步骤 2：手动创建 manifest

如果你想手动理解结构，可以先写一个最小 manifest：

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

命名建议：

• name 用稳定的 kebab-case。
• version 在功能变化时递增。
• description 写给安装者看，不要只写内部代号。
• skills 指向插件内的 skills 目录。

步骤 3：加入 marketplace

Codex 通过 marketplace 发现可安装插件。官方文档说明，仓库级 marketplace 常放在：

$REPO_ROOT/.agents/plugins/marketplace.json

个人 marketplace 常放在：

~/.agents/plugins/marketplace.json

一个最小入口可以写成：

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

注意 source.path 应该指向 marketplace 根目录内的插件位置，并保持相对路径清晰。

步骤 4：从 CLI 添加 marketplace

如果你希望 Codex 管理 marketplace 来源，可以使用官方 CLI 命令：

codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace list
codex plugin marketplace upgrade

GitHub 来源也可以通过 shorthand、Git URL 或指定 ref 添加。团队使用时建议固定版本或分支策略，避免未审查更新直接影响多人。

步骤 5：测试安装和调用

测试流程建议固定：

1. 重启 Codex。
2. 打开 Plugin 目录。
3. 切换到你的 marketplace。
4. 安装插件。
5. 新开线程调用插件能力。
6. 验证它是否加载了预期 skills 或 MCP 配置。

如果修改插件内容，更新 marketplace 指向的插件目录后再次重启 Codex。

步骤 6：工作区共享

官方文档说明，可以在 Codex App 中把你创建的插件分享给工作区成员或组。共享后，成员可以在 Shared with you 一类入口中找到它。

工作区共享适合内部团队；它不等同于公开发布。共享前要检查：

• 插件是否包含内部路径、账号或密钥。
• 安装说明是否足够清楚。
• 权限、认证和数据访问边界是否明确。
• 管理员是否允许 plugin sharing。

常见错误

不要把未稳定的个人 workflow 过早做成 Plugin。先用 Skill 快速迭代，稳定后再分发。

不要忽略 marketplace 元数据。安装者首先看到的是名称、描述、分类和策略。

不要把 secrets 写进插件目录。需要凭证时使用受控认证、环境变量或插件自己的安全配置。

小结

Build plugins 的核心流程是：先判断是否真的需要分发，再用 @plugin-creator 或手动 manifest 创建插件，放入 marketplace，重启 Codex 测试安装，最后再考虑工作区共享。Plugin 是团队复用能力的包装层，不是临时 prompt 的存放箱。