---
title: "构建自己的插件"
description: "区分 skill、plugin、marketplace 的职责，并用最小分发单元安全发布第一版 Codex plugin。"
verifiedAt: "2026-05-07"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Codex plugin 是分发单元，用来把 skills、MCP 配置、app integration 或其他能力打包给别人安装。它不是“把一段 prompt 包起来”。

新手最常见的错误，是本来只需要本地 skill，却一上来做 plugin、marketplace 和发布目录。

> [!TIP]
> 自己用先写 skill；团队复用再考虑 plugin；需要 Codex 发现和安装一组 plugin，才需要 marketplace。

<Cards>
  <Card title="Build plugins" href="https://developers.openai.com/codex/plugins/build">
    查看官方 plugin manifest、目录结构和 marketplace 说明。
  </Card>
  <Card title="Plugins" href="https://developers.openai.com/codex/plugins">
    理解 plugin 的安装、管理和使用方式。
  </Card>
  <Card title="Skills" href="/docs/codex/official/03-extensions/09-skills-reuse">
    如果只是复用流程，先做 skill。
  </Card>
</Cards>

## 三个概念

```mermaid
flowchart LR
    Skill["Skill<br/>工作方法"]
    Plugin["Plugin<br/>分发包"]
    Marketplace["Marketplace<br/>发现和安装目录"]

    Skill --> Plugin
    Plugin --> Marketplace
```

Skill 解决：

- Codex 在某类任务上应该怎么做。
- 触发条件、步骤、输出和验证。

Plugin 解决：

- 把一组能力打包给别人安装。
- 可以包含 skills、MCP、hooks、app mappings 等。

Marketplace 解决：

- Codex 从哪里发现 plugin。
- 团队或个人如何维护可安装清单。

## 什么时候该做 plugin

适合：

- 能力已经被反复使用。
- 有清楚名称、说明、输入边界和使用场景。
- 安装后别人能直接在 Codex 里发现。
- 需要一起分发 skill、MCP 或其他配置。
- 愿意维护版本、兼容性和变更记录。

不适合：

- 只是一次性 prompt。
- skill 还没跑稳。
- 只服务当前仓库的临时任务。
- 还没想清楚权限和外部依赖。
- 只是为了目录看起来更工程化。

## 第一版应该尽量小

第一版 plugin 建议只包含一个稳定 skill。

最小结构：

```text
my-plugin/
  .codex-plugin/
    plugin.json
  skills/
    my-skill/
      SKILL.md
```

说明必须写清：

- 插件解决什么任务。
- 什么时候应该调用。
- 什么时候不应该调用。
- 是否需要 token、MCP、外部网络或账号。
- 安装后如何确认生效。

不要第一版就塞多个 skills、多个 MCP servers 和复杂 hooks。包越大，排错越难。

最小 manifest 放在 `.codex-plugin/plugin.json`：

```json
{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable workflow for one stable Codex task.",
  "skills": "./skills/"
}
```

`name` 使用稳定 kebab-case。Codex 会把它当成 plugin identifier 和 component namespace。

## Marketplace 怎么放

Marketplace 是 JSON catalog，不是 plugin 本身。常用位置：

| 范围 | 文件 |
| --- | --- |
| Repo marketplace | `$REPO_ROOT/.agents/plugins/marketplace.json` |
| Personal marketplace | `~/.agents/plugins/marketplace.json` |

本地 repo marketplace 的最小条目：

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

`source.path` 必须相对 marketplace root，并以 `./` 开头。修改 marketplace 或 plugin 后要重启 Codex；local plugin 会被安装到 Codex cache 中，Codex 读取的是安装后的副本，而不是你刚编辑的源目录。

也可以用 CLI 添加 marketplace：

```bash
codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name
```

## 发布前检查

发布前确认：

- plugin name 稳定。
- version 清楚。
- description 能触发正确任务。
- 不包含密钥、token、私有 URL。
- 外部依赖写明。
- 禁止事项写明。
- 关闭 plugin 后不会留下全局副作用。

如果插件会调用外部系统，还要说明权限、数据流和审计方式。

## 安装后怎么验证

本地验证不要只看文件存在，要在 Codex 里确认：

- `/plugins` 能看到对应 marketplace。
- plugin details 能展示名称、说明和 category。
- 安装后 bundled skills 能被调用。
- 需要认证的 app 或 MCP 会在 install 或首次使用时提示。
- 禁用 plugin 后，相关能力不再触发。

如果插件包含外部 app、MCP server 或 hooks，还要单独确认权限提示和失败路径。安装 plugin 只是让 workflow 可用，Codex 现有 approval settings 仍然生效，外部服务仍受自己的认证和隐私策略约束。

## 推荐流程

1. 先写本地 skill。
2. 在真实任务中跑多次。
3. 记录误触发、缺上下文和失败点。
4. 用 plugin creator scaffold plugin。
5. 本地 marketplace 安装测试。
6. 换干净环境复验。
7. 再放进团队 repo marketplace。

每一步都要可回滚。不要把未稳定能力分发给团队。

## 常见坑

- marketplace 路径写错。
- 修改后忘记重启或刷新 Codex。
- description 太泛，导致误触发。
- 把敏感配置打进插件。
- 缺少版本和变更记录。
- 安装说明只适用于作者机器。
- skill 和 plugin 职责混在一起。

Plugin 的目标是分发稳定能力，而不是提前包装不稳定流程。

## 官方资料

- [Plugins](https://developers.openai.com/codex/plugins)
- [Build plugins](https://developers.openai.com/codex/plugins/build)
- [Agent Skills](https://developers.openai.com/codex/skills)
- [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
