---
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="/zh-Hant/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)
