Codex 外掛開發 | 建立、測試與分發 | 擴充與自動化

本頁面面向外掛作者。如果你只是想在網頁版 ChatGPT Work，或桌面 App 的 ChatGPT Work / Codex 中瀏覽、安裝和使用外掛，請先看外掛。如果你仍然只是在單個儲存庫或個人工作流程裡迭代，一個本機技能往往就足夠了。只有當你希望把這個工作流程分享給團隊、把連接器、MCP 設定或生命週期鉤子一起打包，或釋出成穩定的可安裝包時，再考慮做成外掛。

一個外掛可以包含技能、由 MCP server 支援的 App，或同時包含兩者。如果外掛需要連線服務，或通過 MCP server 公開工具，請參閱建置 App。

完整的公開範例可參考 Figma、Notion 和 Build web apps。

使用 `@plugin-creator` 建立外掛

最快的方式是直接使用內建的 @plugin-creator 技能。

它會自動生成必須的 .codex-plugin/plugin.json 清單檔案，也可以順手生成一個本機外掛市場條目，方便你立即測試。如果你已經有一個外掛目錄，也可以繼續用 @plugin-creator 把它接到本機外掛市場中。

建立並本機測試由 MCP server 支援的 Developer mode App 外掛

如果要本機測試包含由 MCP server 支援的 App 的外掛，也可以使用 plugin-creator skill。外掛仍需要本機外掛資料夾和清單，但 App 本身從 ChatGPT Developer mode 啟動。

首先在 ChatGPT 中啟用 Developer mode：

開啟 ChatGPT。
開啟 Settings（設定）。
選擇 Security and login（安全與登入）。
開啟 Developer mode。

然後在 Developer mode 中建立 App：

開啟 Settings → Plugins 或 Plugins 頁面。
選擇加號按鈕。
在彈窗中為 MCP server 建立 Developer mode App。
ChatGPT 建立完成後，從瀏覽器 URL 複製 App ID；它以 plugin_asdk_app 開頭。

在 ChatGPT Work 對話中，把這個 plugin_asdk_app... ID 交給 @plugin-creator；在 Codex 中則交給 $plugin-creator。例如，在 ChatGPT Work 中輸入：

@plugin-creator create a Codex plugin for my ChatGPT app.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.

plugin-creator skill 會建立外掛資料夾和必要的 .codex-plugin/plugin.json，併為 ChatGPT App 新增關聯設定。如果還要求建立個人外掛市場條目，該外掛會出現在 Plugins Directory 的本機來源下供測試。

完成後：

檢查 .app.json，確認它指向正確的 plugin_asdk_app... ID。
檢查 .codex-plugin/plugin.json，確認 apps 欄位指向 ./.app.json。
如果外掛除 App 外還應包含可重複工作流程，請把內建技能放在 skills/ 下。
如果該 skill 建立了個人外掛市場條目，請重新整理 ChatGPT，從 Plugins Directory 的本機來源安裝，並在新聊天中測試。

清單格式與檔案佈局參見外掛結構和路徑規則。

建置你自己的精選外掛列表

外掛市場清單（marketplace）是一個描述外掛列表的 JSON 目錄。@plugin-creator 可以先為單個外掛生成一份外掛市場，之後你可以持續往同一個外掛市場中追加條目，形成一個面向儲存庫、團隊或個人工作流程的精選外掛列表。

在 ChatGPT 桌面 App 的 ChatGPT Work 或 Codex 中，每份外掛市場都會作為 Plugins Directory 裡的一個可選來源出現。

儲存庫級外掛市場：$REPO_ROOT/.agents/plugins/marketplace.json
個人級外掛市場：~/.agents/plugins/marketplace.json

使用時，在 plugins[] 下為每個外掛新增一條記錄，把 source.path 指向外掛目錄，並使用相對於外掛市場根目錄的 ./ 字首路徑。interface.displayName 控制 App 在外掛市場選擇器中顯示的名稱。完成後重啟 ChatGPT 桌面應用，開啟 Plugins Directory，選擇該外掛市場，就可以瀏覽和安裝精選列表中的外掛。

你不需要為每個外掛單獨維護一份外掛市場。一個外掛市場完全可以在測試階段只暴露一個外掛，之後再逐步擴充套件成一個更完整的精選目錄。

從 CLI 新增外掛市場

使用 codex plugin marketplace add 可以新增並跟蹤外掛市場來源，無需手動編輯 config.toml。這些命令面向外掛開發和外掛目錄設定；本機外掛的安裝與測試請使用 ChatGPT 桌面 App。

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
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 / HTTPS Git URL、SSH Git URL，或本機外掛市場根目錄。使用 --ref 可以固定 Git ref；對基於 Git 的外掛市場儲存庫，可以重複傳入 --sparse PATH 來使用 sparse checkout。--sparse 只適用於 Git 外掛市場來源。

如需檢視、重新整理或移除已經設定的外掛市場：

codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-name

codex plugin marketplace list 會列印 Codex 當前會考慮的每個外掛市場，以及它解析出的根路徑，包括本機預設外掛市場和已設定的外掛市場快照。

手動建立外掛

你可以從一個只打包單個技能的最小外掛開始。

建立外掛目錄，並在 .codex-plugin/plugin.json 中放入清單檔案。

mkdir -p my-first-plugin/.codex-plugin

my-first-plugin/.codex-plugin/plugin.json

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

name 建議使用穩定的 kebab-case。Codex 會把它作為外掛識別符號和元件名稱空間。

在 skills/<skill-name>/SKILL.md 下新增一個技能。

mkdir -p my-first-plugin/skills/hello

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

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

把這個外掛加入某個外掛市場清單。你可以用 @plugin-creator 自動生成，也可以按下文的精選外掛列表方式手動接入。

之後，可以按需加入 MCP 設定、連接器或外掛市場後設資料。

手動安裝本機外掛

你可以根據外掛面向的範圍，選擇儲存庫級外掛市場清單或個人級外掛市場清單。

Repo（儲存庫）

把外掛市場檔案放到 $REPO_ROOT/.agents/plugins/marketplace.json，並把外掛放到 $REPO_ROOT/plugins/。

儲存庫級外掛市場範例

第 1 步：把外掛複製到 $REPO_ROOT/plugins/my-plugin。

mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-plugin

第 2 步：建立或更新 $REPO_ROOT/.agents/plugins/marketplace.json，讓 source.path 使用帶 ./ 字首、相對於外掛市場根目錄的路徑指向外掛目錄：

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

第 3 步：重啟 ChatGPT 桌面 App，確認外掛已出現在目錄中。

Personal（個人）

把外掛市場檔案放到 ~/.agents/plugins/marketplace.json，並把外掛放到 ~/.codex/plugins/。

個人外掛市場範例

第 1 步：把外掛複製到 ~/.codex/plugins/my-plugin。

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin

第 2 步：建立或更新 ~/.agents/plugins/marketplace.json，讓外掛條目的 source.path 指向該目錄。

第 3 步：重啟 ChatGPT 桌面 App，確認外掛已出現在目錄中。

外掛市場檔案決定的是“外掛從哪裡載入”，所以上述目錄只是範例，並不是固定要求。Codex 會把 source.path 解釋為相對於外掛市場根目錄的路徑，而不是相對於 .agents/plugins/ 目錄的路徑。更多格式細節，請參見外掛市場後設資料。

修改本機外掛後，請同步更新外掛市場指向的外掛目錄，並重啟 ChatGPT 桌面 App，讓本機安裝副本載入新檔案。

建立外掛後，從 ChatGPT 桌面 App 新增它：選擇 ChatGPT 並在切換器中切換到 Work，或選擇 Codex，然後開啟 Plugins。之後就可以把它分享給工作區其他成員。

在 ChatGPT 桌面 App 中開啟 Plugins。
進入 Created by you（由你建立），並開啟外掛詳情頁。
選擇 Share（共享）。
新增工作區成員或工作區群組，或複製共享連結。
選擇誰可以存取，然後傳送邀請或連結。

被分享的人可以在 Plugins Directory 的 Shared with you（與你共享） 下找到它。把本機外掛分享給工作區，不等於釋出到公開 Plugins Directory。共享內容會留在工作區與組織邊界內；未登入該工作區的賬號無法存取。團隊或角色應共享同一存取權限時使用群組；需要儲存庫或 CLI 分發時使用外掛市場；希望選定隊友從 ChatGPT 桌面應用安裝時使用工作區共享。

工作區管理員可以在雲端託管的 requirements.toml 中加入 features.plugin_sharing = false，停用外掛共享：

features.plugin_sharing = false

外掛市場後設資料

如果你維護儲存庫級外掛市場，請使用 $REPO_ROOT/.agents/plugins/marketplace.json；個人外掛市場使用 ~/.agents/plugins/marketplace.json。外掛市場檔案控制 ChatGPT 桌面 App 中的外掛排序和安裝策略。它可以只描述一個測試中的外掛，也可以描述一組希望一起展示的精選外掛。加入外掛市場前，應確認 version、釋出者後設資料和安裝介面文案已經適合其他開發者檢視。

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

使用頂層 name 作為外掛市場的穩定標識。
使用 interface.displayName 作為 ChatGPT 桌面 App 中顯示的外掛市場標題。
在 plugins 下為每個外掛新增一個物件，構成 App 在該標題下展示的精選目錄。
讓每個外掛條目的 source.path 指向你希望 App 載入的外掛目錄。儲存庫級安裝通常會放在 ./plugins/ 下；個人級安裝常見佈局則是 ./.codex/plugins/<plugin-name>。
讓 source.path 保持相對於外掛市場根目錄、使用 ./ 開頭，並確保路徑落在該根目錄之內。
對本機條目，source 也可以直接是普通字串路徑，例如 "./plugins/my-plugin"。
每個外掛條目都應包含 policy.installation、policy.authentication 和 category。
policy.installation 常見值包括 AVAILABLE、INSTALLED_BY_DEFAULT 和 NOT_AVAILABLE。
用 policy.authentication 決定認證發生在安裝時還是第一次使用時。

外掛市場決定的是 App 從哪裡載入外掛。即使外掛不在上述範例目錄裡，本機 source.path 也可以指向其他位置。外掛市場檔案可以放在正在開發外掛的儲存庫裡，也可以放在獨立外掛市場儲存庫裡；同一檔案可以指向一個或多個外掛。

外掛市場條目也可以指向基於 Git 的外掛來源。當外掛位於儲存庫根目錄時使用 "source": "url"；當外掛位於子目錄時使用 "source": "git-subdir"：

{
  "name": "remote-helper",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/codex-plugins.git",
    "path": "./plugins/remote-helper",
    "ref": "main"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

基於 Git 的條目可以使用 ref 或 sha selector。如果 Codex 無法解析某個外掛市場條目的 source，它會跳過該外掛條目，而不是讓整個外掛市場載入失敗。

外掛市場條目還可以從 JavaScript 軟體包 registry 安裝外掛：

{
  "name": "npm-helper",
  "source": {
    "source": "npm",
    "package": "@example/codex-plugin",
    "version": "^1.2.0",
    "registry": "https://registry.npmjs.org"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

package 為必填項，可以包含 registry scope。version 可選，接受 package version、distribution tag 和 version range，但不接受 path 或 URL selector。registry 可選，必須是不含嵌入憑據、query 或 fragment 的 HTTPS URL。Codex 下載 package 時不會執行 lifecycle scripts。系統必須安裝 npm CLI，registry 認證來自其設定。

ChatGPT 桌面 App 如何使用外掛市場

外掛市場是 ChatGPT 桌面 App 可以讀取並安裝的 JSON 目錄。

App 可以從以下位置讀取外掛市場檔案：

官方 Plugins Directory 背後的精選外掛市場
儲存庫級外掛市場：$REPO_ROOT/.agents/plugins/marketplace.json
相容舊版的外掛市場：$REPO_ROOT/.claude-plugin/marketplace.json
個人級外掛市場：~/.agents/plugins/marketplace.json

只要外掛通過外掛市場暴露出來，App 就可以安裝到 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/。對於本機外掛，$VERSION 為 local。App 讀取安裝後的快取副本，而不是直接從外掛市場條目宣告的位置載入。

每個外掛都可以單獨啟用或停用；App 會把開關狀態儲存在 ~/.codex/config.toml 中。

打包與分發外掛

外掛結構

每個外掛都必須在 .codex-plugin/plugin.json 中提供清單。除此之外，它還可以包含 skills/ 目錄、用於生命週期鉤子的 hooks/ 目錄、指向一個或多個連接器的 .app.json、設定 MCP servers 的 .mcp.json，以及用於展示外掛的資原始檔。

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # 必需：插件清单文件
├── skills/
│   └── my-skill/
│       └── SKILL.md         # 可选：技能指令
├── hooks/
│   └── hooks.json           # 可选：生命周期 hooks
├── .app.json                # 可选：app 或连接器映射
├── .mcp.json                # 可选：MCP server 配置
└── assets/                  # 可选：图标、徽标、截图

.codex-plugin/ 目錄裡只應該放 plugin.json。skills/、hooks/、assets/、.mcp.json 和 .app.json 都應該放在外掛根目錄。

已釋出外掛通常會使用比最小腳手架範例更完整的清單。清單主要承擔三項職責：

標識外掛本身
指向它打包的技能、連接器、MCP servers 或鉤子
提供安裝介面所需的描述、圖示和法務連結等後設資料

下面是一份完整的清單範例：

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Bundle reusable skills and connectors.",
  "author": {
    "name": "Your team",
    "email": "team@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/plugins/my-plugin",
  "repository": "https://github.com/example/my-plugin",
  "license": "MIT",
  "keywords": ["research", "crm"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "hooks": "./hooks/hooks.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Reusable skills and connectors",
    "longDescription": "Distribute skills and connectors together.",
    "developerName": "Your team",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "websiteURL": "https://example.com",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "Use My Plugin to summarize new CRM notes.",
      "Use My Plugin to triage new customer follow-ups."
    ],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": ["./assets/screenshot-1.png"]
  }
}

.codex-plugin/plugin.json 是必需的入口檔案。其他清單欄位都是可選的，但對正式釋出的外掛來說，這些欄位通常都會用到。

清單欄位

頂層欄位用於定義包後設資料，並指向外掛打包的元件：

name、version 和 description 用於標識外掛
author、homepage、repository、license 和 keywords 提供釋出者與發現相關後設資料
skills、mcpServers、apps 和 hooks 指向相對於外掛根目錄的元件入口
interface 控制安裝介面如何展示這個外掛

interface 物件用於定義安裝介面後設資料：

displayName、shortDescription 和 longDescription 控制標題和描述文案
developerName、category 和 capabilities 提供釋出者與能力資訊
websiteURL、privacyPolicyURL 和 termsOfServiceURL 提供外部連結
defaultPrompt、brandColor、composerIcon、logo 和 screenshots 控制啟動提示和視覺呈現

路徑規則

讓清單中的路徑都保持相對於外掛根目錄，並使用 ./ 開頭。
composerIcon、logo 和 screenshots 這類視覺資源，儘量統一放到 ./assets/ 下。
skills 應指向打包技能的目錄，apps 應指向 .app.json，mcpServers 應指向 .mcp.json，hooks 應指向生命週期鉤子。
已啟用的外掛可以同時包含生命週期鉤子、技能、MCP servers 和連接器。
如果外掛把鉤子放在 ./hooks/hooks.json，就不需要在 .codex-plugin/plugin.json 中寫 hooks 條目；Codex 會自動檢查這個預設檔案。

打包 MCP server 與生命週期鉤子

mcpServers 可以指向一個 .mcp.json 檔案。該檔案既可以直接包含 server 對映，也可以用 mcp_servers 物件包一層。

直接 server 對映：

{
  "docs": {
    "command": "docs-mcp",
    "args": ["--stdio"]
  }
}

帶 mcp_servers 包裝的對映：

{
  "mcp_servers": {
    "docs": {
      "command": "docs-mcp",
      "args": ["--stdio"]
    }
  }
}

安裝後，使用者可以在 Codex 設定中啟用或停用外掛打包的 MCP server，並調整工具審批策略，而不需要修改外掛本身。外掛作用域的 MCP server 策略使用 plugins.<plugin>.mcp_servers.<server>：

[plugins."my-plugin".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search"]

[plugins."my-plugin".mcp_servers.docs.tools.search]
approval_mode = "approve"

啟用外掛後，Codex 可以從外掛中載入生命週期鉤子，並與使用者、專案和託管鉤子一起使用。

安裝或啟用外掛並不會自動信任它的鉤子。外掛打包的鉤子屬於非託管鉤子，因此 Codex 會跳過它們，直到使用者稽核並信任當前鉤子定義。

預設的外掛鉤子檔案是 hooks/hooks.json：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",
            "statusMessage": "Loading plugin context"
          }
        ]
      }
    ]
  }
}

如果在 .codex-plugin/plugin.json 中定義了 hooks，Codex 會使用清單中的條目，而不是預設的 hooks/hooks.json。該清單欄位可以是單個路徑、路徑陣列、內聯鉤子物件，或內聯鉤子物件陣列。

{
  "name": "repo-policy",
  "hooks": ["./hooks/session.json", "./hooks/tools.json"]
}

Hook 路徑遵循與 skills、apps 和 mcpServers 相同的清單路徑規則：以 ./ 開頭，相對於外掛根目錄解析，並且必須留在外掛根目錄內。

外掛鉤子命令會收到 Codex 專用環境變數 PLUGIN_ROOT 和 PLUGIN_DATA。PLUGIN_ROOT 指向已安裝外掛根目錄，PLUGIN_DATA 指向外掛的可寫資料目錄。為了相容現有外掛鉤子，Codex 還會設定 CLAUDE_PLUGIN_ROOT 和 CLAUDE_PLUGIN_DATA。

外掛鉤子使用和普通鉤子相同的事件 schema。安裝或啟用外掛並不會自動信任它的鉤子；Codex 會跳過外掛打包的鉤子，直到使用者審查並信任當前鉤子定義。支援的事件、輸入、輸出、信任審查和當前限制參見 Hooks（鉤子）。

釋出官方公共外掛

要釋出供公眾使用的外掛，請通過外掛提交門戶提交。完整審查與釋出流程參見提交外掛。

來源：</zh-TW/docs/build-plugins> 更新時間：2026-07-15（UTC）

最近搜尋

建議搜尋

文件導覽

建置外掛

使用 `@plugin-creator` 建立外掛

建立並本機測試由 MCP server 支援的 Developer mode App 外掛

建置你自己的精選外掛列表

從 CLI 新增外掛市場

手動建立外掛

手動安裝本機外掛

Repo（儲存庫）

Personal（個人）

外掛市場後設資料

ChatGPT 桌面 App 如何使用外掛市場

打包與分發外掛

外掛結構

清單欄位

路徑規則

打包 MCP server 與生命週期鉤子

釋出官方公共外掛

使用 @plugin-creator 建立外掛

建立並本機測試由 MCP server 支援的 Developer mode App 外掛

建置你自己的精選外掛列表

從 CLI 新增外掛市場

手動建立外掛

手動安裝本機外掛

Repo（儲存庫）

Personal（個人）

與工作區共享本機外掛

外掛市場後設資料

ChatGPT 桌面 App 如何使用外掛市場

打包與分發外掛

外掛結構

清單欄位

路徑規則

打包 MCP server 與生命週期鉤子

釋出官方公共外掛

使用 `@plugin-creator` 建立外掛