如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
總覽 智慧體存取權 ChatGPT 與 Codex 使用者文件 使用案例

上傳並提交外掛程式

將外掛程式上架至目錄,並持續更新。

如果你已建置外掛程式,希望讓更多人使用,可以將它上架至外掛程式目錄,方便使用者在 ChatGPT 和 Codex 中找到並使用。外掛程式可以包含 MCP 連線、技能,或同時包含兩者。

將已建置的套件打包成 ZIP 上傳,修正自動檢查發現的問題,再提交審查。通過審查後,由你決定何時發布。

首次發布後,系統會自動偵測 MCP 伺服器的變更。符合條件的更新通過自動檢查後就會上線,無須上傳新的外掛程式 ZIP 檔或逐次發布更新。如果變更外掛程式的中繼資料或技能,仍須上傳新的 ZIP 檔。

提交前,請依照外掛程式套件指南準備套件,並閱讀外掛程式規範。如需協助準備送審資料,可使用外掛程式目錄中的 Plugin Creator。

外掛程式儀表板顯示上傳、發布、審查與 MCP 設定狀態。

外掛程式總覽。 在「外掛程式」頁面開始準備送審資料,並追蹤發布狀態、審查進度與 MCP 設定狀態。

如要提交遠端 MCP 伺服器,請選擇含 MCP,並使用穩定、可公開存取的 HTTPS 端點。如果外掛程式會執行本機 MCP 伺服器,或必須在桌面環境中執行,請參閱提交僅適用於桌面版的外掛程式。

1. 上傳外掛程式 ZIP 檔

確認權限與發布身分

選取外掛程式將歸屬的組織和專案。組織擁有者可以直接提交,其他成員則需要應用程式管理寫入權限。擁有者可以透過組織角色授予這項權限。

在組織設定中完成個人或企業驗證,即可以個人姓名或公司名稱發布。

建立草稿

如果外掛程式使用 MCP 伺服器,請在首次上傳的 ZIP 檔中納入該伺服器的設定。目前不支援為現有的純技能外掛程式新增 MCP 伺服器。

  1. 開啟外掛程式頁面,選取上傳新的或現有的外掛程式。
  2. 選擇已通過驗證的開發者身分。目錄會顯示與此身分關聯的名稱。
  3. 選取上傳外掛程式,再選擇 ZIP 檔。
  4. 驗證通過後,系統會開啟外掛程式詳細資料頁面,顯示新草稿。

如果驗證失敗,請修正系統回報的套件錯誤後重新上傳。請勿將私人憑證或機密資訊放入 ZIP 檔。

2. 查看檢查結果並解決問題

上傳 ZIP 檔後,外掛程式詳細資料頁面會顯示自動檢查的進度與結果,方便你在送審前修正問題。中繼資料與技能會顯示已上傳的外掛程式套件版本,MCP 伺服器則會顯示已連線的伺服器與掃描到的工具。兩者分開顯示,因為變更套件必須上傳新的 ZIP 檔,而伺服器上託管的工具有變更時,系統會直接連線至伺服器檢查。

檢查中繼資料

  1. 開啟中繼資料與技能。系統會自動顯示最近上傳的版本。
  2. 等待中繼資料檢查完成,再查看問題中是否列出任何項目。
  3. 選取複製問題,以便在開發流程中使用檢查結果。
  4. 修正套件中受影響的欄位,然後選取上傳外掛程式以修正問題,上傳修正後的 ZIP 檔,再查看新的檢查結果。

提示: 可以請 Codex 或 ChatGPT 檢查套件及你複製的檢查結果、解釋問題,並建議如何修正中繼資料或技能。

外掛程式的中繼資料與技能,以及「問題」面板中列出的自動檢查結果。

中繼資料檢查結果。 查看所選套件版本的檢查結果,並上傳修正後的 ZIP 檔。

此處的套件詳細資料為唯讀。如要修改,請參照套件欄位參考資料,在原始套件中編輯。公開網址必須可供存取,且網址所標示的發布者必須與送審資料中的發布者相同。

檢查技能

如果套件包含技能,請在中繼資料與技能中查看檢查結果。開啟問題項目,確認受影響的技能及需修改之處,再更新該技能的指示或相關檔案,並上傳修正後的 ZIP 檔。查看更新後的檢查結果。所有必要的技能掃描都必須順利完成,才能送審。

連線至 MCP 伺服器並執行掃描

套件可以宣告多個 MCP 伺服器,但每個外掛程式只能連線至一個 MCP 伺服器。首次連線至該伺服器時,請完成以下設定。如果連線發生問題,請使用重新連線。如果變更了工具,請依照掃描最新變更的步驟操作。

  1. 開啟 MCP 伺服器,選取要連線的伺服器。
  2. 選取連線,開啟連線至 MCP 伺服器面板。
  3. 檢查 MCP 伺服器網址、驗證方式及相關設定。
  4. 完成入口網站顯示的網域驗證挑戰,再連線至伺服器,並視需要完成身分驗證。
  5. 等待工具自動掃描完成,再查看掃描到的工具。開啟問題以查看檢查結果。
  6. 修正連線問題或掃描發現的伺服器端問題,再視情況使用重新連線或重新掃描,並查看新的結果。

「連線至 MCP 伺服器」側邊面板顯示網域已通過驗證,OAuth 授權仍待完成。

MCP 連線與網域驗證。 先連線至伺服器並完成網域驗證,再查看掃描到的工具。

若是已獲核准的本機 MCP 外掛程式,請選擇僅限技能,並依照僅適用於桌面版外掛程式的提交說明操作。

填寫表單時,入口網站會將送審資料儲存為草稿。

如果連線或掃描失敗,請確認端點可供存取且驗證設定正確,再重新連線或掃描。提交前,請處理完成 MCP 設定中列出的問題,並排除連線故障。關於 MCP 伺服器網址、驗證方式、工具中繼資料和使用者介面的要求,請參閱外掛程式規範。

設定送審所需的驗證方式

入口網站會從套件的 mcp.json 讀取進階驗證設定。請依照 MCP 驗證參考資料設定驗證方式、OAuth 用戶端註冊方式、端點和授權範圍。連線面板會顯示這些設定,但未提供進階 OAuth 設定編輯器。

如要變更設定,請更新 mcp.json,選取上傳新版本,並在連線前到 MCP 伺服器查看已儲存的設定。如果已有註冊的用戶端,憑證變更可能會受到限制。請檢查已儲存的連線,確認上傳後實際使用的用戶端。

使用 OAuth 時,請選擇供應商支援的註冊方式:

註冊方式 需提供的資料
已註冊的用戶端(provided) 在 mcp.json 中宣告用戶端 ID 和權杖端點的驗證方式。必要時,在入口網站輸入用戶端密鑰。
動態用戶端註冊(dcr) 透過服務探索或 registrationUrl 覆寫設定提供註冊端點。請勿在套件中放入用戶端憑證。
用戶端識別碼中繼資料文件(cimd) 設定是否優先使用 CIMD。執行環境可依其註冊政策改用 DCR。

如果使用已註冊的用戶端:

  1. 向 OAuth 供應商註冊連線流程使用的回呼網址。
  2. 開啟 MCP 伺服器,選取伺服器,再選取連線。
  3. 如果用戶端需要密鑰,請輸入 OAuth 用戶端密鑰。使用自行提供的 OAuth 用戶端時,除非 tokenEndpointAuthMethod 為 "none",否則系統會顯示此欄位。
  4. 視需要完成網域驗證,選取連線,並授權用來連線及掃描伺服器的帳戶。
  5. 等待掃描完成,並修正檢查發現的連線或工具問題。

請勿將用戶端密鑰放入 mcp.json。資訊清單不接受 clientSecret。用戶端密鑰用於驗證 OAuth 應用程式,與帳戶密碼、存取權杖及審查人員的登入憑證不同。

如果 OAuth 服務探索未提供必要端點,請將 authorizationUrl 和 tokenUrl 的覆寫設定加入 mcp.json。確認用戶端 ID、權杖端點驗證方式、授權範圍及回呼網址皆與供應商的設定相符。

驗證方式的限制

入口網站的連線表單支援免驗證、OAuth,以及混合使用免驗證與 OAuth 的存取方式。雖然資訊清單結構描述接受 API 金鑰驗證,但入口網站未提供 API 金鑰連線流程,也沒有可輸入 Bearer 權杖的欄位。這項限制也適用於使用 Basic 或自訂標頭的 API 金鑰宣告。僅上傳 API 金鑰宣告無法完成 MCP 設定。如果送審的外掛程式需要這種驗證方式,請聯絡 OpenAI。

請勿在伺服器的 headers 中嵌入權杖來規避這項限制。提交至公開目錄時,系統會拒絕非空的伺服器標頭。請勿將受保護的伺服器設為 type: "none"。

自行提供 OAuth 用戶端時,結構描述接受 private_key_jwt,但只設定這個值並不會一併設定簽署金鑰。本入口網站指南未提供簽署金鑰的設定步驟。使用這種方式送審前,請先向 OpenAI 確認所需設定。

網域驗證詳細說明

驗證網域時,請在入口網站顯示的網址,以純文字原樣提供驗證用權杖:

https://<challenge-base-host>/.well-known/openai-apps-challenge

只傳回與指定值完全相同的權杖,請勿傳回 JSON 或權杖清單。驗證用的基底來源必須是 MCP 主機名稱或符合條件的上層網域所對應的 HTTPS 來源,系統會忽略路徑。如果其他外掛程式已使用相同的驗證網址,請改用允許的上層網域來源或不同的主機名稱,切勿覆寫其他外掛程式的權杖。如果兩種方式都不可行,請聯絡支援團隊。

3. 提交審查

查看自動檢查結果後,請填妥審查團隊測試外掛程式所需的資料,並提交所選草稿。必須先完成必要設定並修正驗證錯誤。其他自動檢查發現的問題則可一併提交,由審查團隊評估。

填寫審查資料

具有 MCP 連線的外掛程式必須提供審查資料,供審查團隊測試整合功能。你可以將正向與負向測試案例、操作示範影片網址和版本說明放入 plugin.json,上傳 ZIP 檔時即可一併匯入。請參閱審查與發布欄位參考資料及完整中繼資料範例。外掛程式目錄中的 Plugin Creator 可以協助準備這些資料。請在審查詳細資料中另行輸入審查人員的憑證。請準備以下資料:

  • 若需要登入,請提供審查人員專用憑證。 提供專用測試帳戶、登入網址、工作區或租用戶詳細資料,以及登入步驟。請使用範例資料,勿使用真實使用者的帳戶。測試帳戶須具備執行測試案例所需的權限和資料,且應可立即使用,無須 MFA 核准、電子郵件或簡訊驗證碼、免密碼登入連結或私人網路存取權。
  • 五個正向測試案例。 列出情境、使用者提示詞、預期會呼叫的工具及預期結果。送審前,請使用測試帳戶逐一執行。
  • 三個負向測試案例。 提供外掛程式不應採取行動的提示詞或情境,說明不應完成要求的原因,以及預期應如何拒絕、要求釐清或採取安全的替代做法。
  • 操作示範影片。 示範測試案例與外掛程式功能,並提供審查人員可存取的錄影網址。
  • 版本說明。 簡述本次送審的套件版本與變更內容。

在中繼資料與技能中,開啟審查資訊 → 審查詳細資料,檢查匯入的資料,並輸入審查人員的憑證。填妥可編輯的欄位後,選取儲存詳細資料。如果欄位標示為由外掛程式 ZIP 檔管理,請在套件中新增或修改資料,再重新上傳。你也可以在套件中繼資料中指定開放使用的國家並提供譯文。如果有提供,請檢查匯入後的設定。如需瞭解支援的欄位與匯入方式,請參閱自動填入提交與審查資料。

「審查資訊」側邊面板包含審查人員憑證及登入步驟欄位。

審查詳細資料。 檢查從 ZIP 檔匯入的測試案例及相關資料,並另外輸入審查人員專用的私人憑證。

憑證會與公開套件分開保存。請保留測試帳戶和範例資料,供後續審查使用。如果憑證或登入步驟有變,請提交已填入新資料的草稿。

提交草稿

選取草稿,選擇提交審查,並完成必要的政策聲明。提交後,可在「外掛程式」頁面的審查狀態下追蹤進度。審查團隊會透過電子郵件提供意見。

「提交審查」對話方塊顯示必須確認的政策聲明。

提交審查。 確認必要聲明,並提交所選草稿以供審查。

每個外掛程式同一時間只能有一項審查進行中。若要替換審查中的套件,請等待審查結果,或先取消審查再上傳。如果套件遭拒,請依審查意見修正問題,並提交修正後的 ZIP 檔。

如果審查團隊拒絕了你的提交,請查看通知郵件中的原因。如要申訴,請回覆該郵件,說明為何應重新考慮這項決定。

4. 發布已獲核准的外掛程式

外掛程式獲得核准後,由你決定何時開放使用。開啟已獲核准的套件版本,並選取發布外掛程式。發布更新後,新版會取代上一個套件版本。

更新已發布的外掛程式

如要更新中繼資料、素材或隨附的技能,請將新的 ZIP 檔上傳至現有外掛程式。系統會建立新的套件版本,個別檢查該版本並記錄審查結果。伺服器上託管的工具如有變更,會透過 MCP 掃描另行處理,無須上傳套件。

如果之前透過舊版表單送審,可先將現有的外掛程式下載為 ZIP 檔。開啟外掛程式,選取已發布的套件版本,再選擇下載發布版本 ZIP 檔(位於 … 選單中)。如果你已在本機維護套件,也可以直接使用本機的原始套件。

  1. 更新套件內容與版本號碼,再建立完整的 ZIP 檔,納入所有要保留的元件。
  2. 開啟現有的外掛程式,選取上傳外掛程式以進行變更。
  3. 在中繼資料與技能中確認選取的套件版本。查看新的自動檢查結果,並修正必須處理的問題。
  4. 完成適用的審查步驟,並發布已獲核准的套件版本。

新增或移除技能時,請沿用同一個外掛程式。如需變更現有 MCP 伺服器的網址,請聯絡支援團隊。目前的更新流程不支援變更網址。

更新 MCP 伺服器

首次發布後,OpenAI 每天都會掃描你託管的 MCP 伺服器。符合條件的更新通過自動檢查後即可供使用,無須建立新的套件版本或另行發布。部署伺服器變更後,你也可以立即要求掃描。

掃描最新變更

  1. 將變更部署至 MCP 伺服器。
  2. 開啟現有的外掛程式,選取 MCP 伺服器,再選擇已連線的伺服器。
  3. 在問題下選取重新掃描。
  4. 等待掃描完成,查看結果並確認各項工具是否可供使用。

MCP 工具頁面顯示目前可用的工具、暫緩套用的更新及掃描發現的問題。

MCP 掃描總覽。 變更伺服器後,請重新掃描,再查看掃描結果及各項工具的可用狀態。

如果另一項掃描或申訴正在進行,或外掛程式不符合掃描條件,可能無法重新掃描。

找出並修正工具問題

  1. 開啟問題並選取受影響的工具。
  2. 閱讀發現的問題,並在暫緩套用的更新中查看本次受檢的中繼資料。目前生效的定義會顯示正在使用的中繼資料。
  3. 選取複製問題,以便在開發流程中使用檢查結果。
  4. 在伺服器上修正工具的中繼資料或實作,並部署變更。
  5. 返回問題,選取重新掃描,並查看更新後的結果。

提示: 可以請 Codex 或 ChatGPT 檢查 MCP 伺服器和你複製的錯誤訊息,解釋問題並建議修正方式。

系統會分別評估每項工具的變更。即使某項變更遭標記,其他符合條件的工具更新仍可能獲准上線。新工具必須獲得核准後才能使用。既有工具的更新若暫緩套用,該工具會繼續使用先前核准的中繼資料。移除工具的變更會在掃描後生效。

在更新後的中繼資料上線前,請確保 MCP 伺服器與目前已核准的工具結構描述相容。

對自動檢查結果提出申訴

如果你認為工具檢查結果有誤,請選取申訴,並說明審查團隊應重新考慮這些結果的理由。審查團隊會一併評估該次掃描中暫緩套用的工具變更。如果檢查指出的問題屬實,在伺服器上修正後重新掃描,通常會更快。

申訴對話方塊說明,審查範圍包含該次掃描中暫緩套用的工具變更。

MCP 申訴。 說明審查團隊應重新考慮自動檢查結果的理由。

申訴期間,系統會暫停 MCP 自動更新。如要進行變更,請選取撤回申訴,更新伺服器後重新掃描。申訴範圍僅限暫緩套用的工具變更,不含套件變更、驗證方式或共用的伺服器指示。

如需排解問題,請參閱提交錯誤。聯絡支援團隊時,請附上外掛程式 ID。

自動填入提交與審查資料

你可以在外掛程式資訊清單中加入目錄刊登、審查與發布資料,讓系統在上傳 ZIP 檔時自動填入。以下參考資料列出支援的欄位,說明上傳後如何套用欄位值,並提供各種套件格式的範例。

目前無法提交含有應用程式參照(apps / .app.json)或生命週期掛鉤的外掛程式 ZIP 套件。請在 MCP 設定中宣告 MCP 伺服器網址,並在儀表板中完成設定。

提交至公開目錄前,請移除生命週期掛鉤。如果外掛程式依賴生命週期掛鉤,請採用可讓使用者在 Codex 桌面版手動安裝的方式散布。

完整中繼資料範例

以下分別以兩種格式描述同一個筆記外掛程式。請複製符合套件格式的資訊清單,並將發布者資料、網址、工具名稱、審查案例、譯文與開放使用的國家替換為實際值。範例中的測試案例尚未在真實服務上執行過。

請納入資訊清單參照的檔案:

  • skills/get-started/SKILL.md,其 YAML 標頭中須有有效的 name 和 description 欄位。
  • assets/ 下的四個圖示檔。
  • 恰好一個名為 notes 的遠端 MCP 伺服器。請使用下方對應格式的設定:Agent Plugins 使用 mcp.json,Codex 使用 .mcp.json。

請提供可供存取的實際示範影片與審查附件網址。example.com 連結僅用來示範網址格式,無法作為送審資料。如果外掛程式僅包含技能,請省略 review 和 MCP 設定,並從 Codex 資訊清單中省略 mcpServers。

在 Agent Plugins 範例中,請搭配使用以下 mcp.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "notes": {
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    }
  }
}

在 Codex 範例中,請將以下內容儲存為外掛程式根目錄下的 .mcp.json。此格式省略 Agent Plugins 的結構描述:

{
  "mcpServers": {
    "notes": {
      "url": "https://example.com/mcp"
    }
  }
}

Agent Plugins 格式

將以下完整資訊清單儲存為外掛程式根目錄下的 plugin.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "acme-notes",
  "version": "1.0.0",
  "description": "Search and summarize notes from your Acme workspace.",
  "author": {
    "name": "Acme",
    "email": "support@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/notes",
  "repository": "https://github.com/example/acme-notes",
  "license": "MIT",
  "keywords": ["notes", "search", "productivity"],
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "Acme Notes",
        "shortDescription": "Find and summarize your notes",
        "longDescription": "Search notes in your Acme workspace, open matching notes, and summarize decisions with links to the source. Acme Notes only accesses notes available to your connected account.",
        "developerName": "Acme",
        "category": "Productivity",
        "capabilities": ["Search notes", "Read notes"],
        "websiteURL": "https://example.com/notes",
        "supportURL": "https://example.com/support",
        "privacyPolicyURL": "https://example.com/privacy",
        "termsOfServiceURL": "https://example.com/terms",
        "defaultPrompt": [
          "Find my notes about the launch.",
          "Summarize the decisions in my launch notes.",
          "Open the project kickoff notes."
        ],
        "brandColor": "#2357C6",
        "brandColorDark": "#8CB4FF",
        "composerIcon": "./assets/icon.png",
        "composerIconDark": "./assets/icon-dark.png",
        "logo": "./assets/logo.png",
        "logoDark": "./assets/logo-dark.png"
      },
      "onboardingSkill": "./skills/get-started/SKILL.md",
      "review": {
        "test_cases": {
          "positive": [
            {
              "description": "Find notes by topic",
              "prompt": "Find my notes about the launch.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Return accessible notes about the launch with source links.",
              "file_attachment_urls": [
                "https://example.com/review/launch-brief.pdf"
              ],
              "expected_output_url": "https://example.com/review/launch-results"
            },
            {
              "description": "Open a matching note",
              "prompt": "Open the project kickoff notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Find the kickoff note and return its content with a source link."
            },
            {
              "description": "Summarize decisions",
              "prompt": "Summarize decisions in my launch notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Summarize decisions from accessible notes and cite the sources."
            },
            {
              "description": "Find action items",
              "prompt": "What action items are in my kickoff notes?",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "List the action items recorded in the notes without inventing owners or deadlines."
            },
            {
              "description": "Handle no matches",
              "prompt": "Find my notes about Project Northstar.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Report that no matching notes were found in the test workspace."
            }
          ],
          "negative": [
            {
              "description": "Unsupported payment",
              "prompt": "Transfer $100 to another account."
            },
            {
              "description": "Unsupported deletion",
              "prompt": "Delete all my notes."
            },
            {
              "description": "Access outside the connected account",
              "prompt": "Show notes from a workspace I cannot access."
            }
          ]
        },
        "demo_recording_url": "https://example.com/review/acme-notes-demo",
        "commerce": false,
        "commerce_description": "This plugin does not sell products or process payments."
      },
      "publication": {
        "countries": ["US", "GB"],
        "release_notes": "Initial release with note search, reading, and summaries.",
        "translations": {
          "fr-FR": {
            "subtitle": "Retrouvez et résumez vos notes",
            "description": "Recherchez des notes dans votre espace Acme, ouvrez les résultats et résumez les décisions avec des liens vers les sources. Acme Notes accède uniquement aux notes disponibles pour votre compte connecté."
          },
          "ja-JP": {
            "subtitle": "ノートを検索して要約",
            "description": "Acmeワークスペース内のノートを検索し、該当するノートを開き、参照元へのリンク付きで決定事項を要約します。Acme Notesは、接続されたアカウントで閲覧できるノートにのみアクセスします。"
          }
        }
      }
    }
  }
}

Codex 格式

將以下完整資訊清單儲存為 .codex-plugin/plugin.json。顯示用欄位改放在根層級的 interface 中,入門設定、審查與發布資料仍放在 extensions.com.openai 下:

{
  "name": "acme-notes",
  "version": "1.0.0",
  "description": "Search and summarize notes from your Acme workspace.",
  "author": {
    "name": "Acme",
    "email": "support@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/notes",
  "repository": "https://github.com/example/acme-notes",
  "license": "MIT",
  "keywords": ["notes", "search", "productivity"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "interface": {
    "displayName": "Acme Notes",
    "shortDescription": "Find and summarize your notes",
    "longDescription": "Search notes in your Acme workspace, open matching notes, and summarize decisions with links to the source. Acme Notes only accesses notes available to your connected account.",
    "developerName": "Acme",
    "category": "Productivity",
    "capabilities": ["Search notes", "Read notes"],
    "websiteURL": "https://example.com/notes",
    "supportURL": "https://example.com/support",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "Find my notes about the launch.",
      "Summarize the decisions in my launch notes.",
      "Open the project kickoff notes."
    ],
    "brandColor": "#2357C6",
    "brandColorDark": "#8CB4FF",
    "composerIcon": "./assets/icon.png",
    "composerIconDark": "./assets/icon-dark.png",
    "logo": "./assets/logo.png",
    "logoDark": "./assets/logo-dark.png"
  },
  "extensions": {
    "com.openai": {
      "onboardingSkill": "./skills/get-started/SKILL.md",
      "review": {
        "test_cases": {
          "positive": [
            {
              "description": "Find notes by topic",
              "prompt": "Find my notes about the launch.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Return accessible notes about the launch with source links.",
              "file_attachment_urls": [
                "https://example.com/review/launch-brief.pdf"
              ],
              "expected_output_url": "https://example.com/review/launch-results"
            },
            {
              "description": "Open a matching note",
              "prompt": "Open the project kickoff notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Find the kickoff note and return its content with a source link."
            },
            {
              "description": "Summarize decisions",
              "prompt": "Summarize decisions in my launch notes.",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "Summarize decisions from accessible notes and cite the sources."
            },
            {
              "description": "Find action items",
              "prompt": "What action items are in my kickoff notes?",
              "tools_triggered": "search_notes, read_note",
              "expected_behavior": "List the action items recorded in the notes without inventing owners or deadlines."
            },
            {
              "description": "Handle no matches",
              "prompt": "Find my notes about Project Northstar.",
              "tools_triggered": "search_notes",
              "expected_behavior": "Report that no matching notes were found in the test workspace."
            }
          ],
          "negative": [
            {
              "description": "Unsupported payment",
              "prompt": "Transfer $100 to another account."
            },
            {
              "description": "Unsupported deletion",
              "prompt": "Delete all my notes."
            },
            {
              "description": "Access outside the connected account",
              "prompt": "Show notes from a workspace I cannot access."
            }
          ]
        },
        "demo_recording_url": "https://example.com/review/acme-notes-demo",
        "commerce": false,
        "commerce_description": "This plugin does not sell products or process payments."
      },
      "publication": {
        "countries": ["US", "GB"],
        "release_notes": "Initial release with note search, reading, and summaries.",
        "translations": {
          "fr-FR": {
            "subtitle": "Retrouvez et résumez vos notes",
            "description": "Recherchez des notes dans votre espace Acme, ouvrez les résultats et résumez les décisions avec des liens vers les sources. Acme Notes accède uniquement aux notes disponibles pour votre compte connecté."
          },
          "ja-JP": {
            "subtitle": "ノートを検索して要約",
            "description": "Acmeワークスペース内のノートを検索し、該当するノートを開き、参照元へのリンク付きで決定事項を要約します。Acme Notesは、接続されたアカウントで閲覧できるノートにのみアクセスします。"
          }
        }
      }
    }
  }
}

請選擇與套件格式相符的欄位配置:

中繼資料 Agent Plugins:根目錄的 plugin.json Codex:.codex-plugin/plugin.json
套件識別資料與發布者 根層級欄位 根層級欄位
目錄刊登文字、連結、提示詞及圖片 extensions.com.openai.interface interface
入門技能 extensions.com.openai.onboardingSkill extensions.com.openai.onboardingSkill
審查與發布詳細資料 extensions.com.openai.review 和 extensions.com.openai.publication extensions.com.openai.review 和 extensions.com.openai.publication

如果使用 Agent Plugins 套件,請將 OpenAI 專屬設定放在 plugin.json 的 extensions.com.openai 下。如果這個物件存在,OpenAI 會忽略 .codex-plugin/plugin.json 中的設定,兩個檔案不會合併。如果該物件不存在,OpenAI 才會從 .codex-plugin/plugin.json 讀取這些設定。套件識別資料仍取自根目錄的 plugin.json,技能取自 skills/,MCP 伺服器則取自 mcp.json。

你可以從完整中繼資料範例開始設定。如果開發者儀表板指出缺少隱私權政策網址、支援服務網址或應用程式圖示,請查閱欄位參考資料,找出資訊清單中對應的欄位。

資訊清單欄位

「要求」欄分別列出套件格式與送審時的要求。ZIP 檔可以不含審查詳細資料,但送審前必須備齊必要資料。

套件識別資料與元件

下列欄位描述套件本身。除表格指定為 OpenAI 擴充欄位者外,兩種格式都應將這些欄位放在資訊清單的根層級。

欄位 要求 值與用途
$schema Agent Plugins 必填,Codex 須省略 可攜式格式必須使用 https://agent-plugins.org/schemas/1.0.0/plugin.schema.json 作為此欄位的值。獨立的 Codex 相容資訊清單須省略此欄位。
name 必填 固定不變的識別碼,最多 64 個字元。預計送審的套件請使用小寫英文字母、數字及不連續的單一連字號。此識別碼與顯示名稱須分開設定。
version Codex 必填,可攜式結構描述選填 發布版本,例如 1.0.0。可攜式結構描述允許省略,但送審與更新時請明確指定語意化版本號碼。Codex 格式必填。
description Codex 必填,Agent Plugins 選填 套件摘要,最多 4000 個字元。可攜式結構描述選填,Codex 格式必填。
author Codex 必填,Agent Plugins 選填 發布者物件包含 name,以及選填的 email 和 HTTPS url。可攜式結構描述允許省略整個物件,Codex 格式則要求提供 author.name。名稱最多 120 個字元,電子郵件地址最多 320 個字元,網址最多 2048 個字元。
homepage 選填 專案首頁的 HTTPS 網址,最多 2048 個字元。目錄刊登資料中的 interface.websiteURL 需另行設定。
repository 選填 原始碼所在的程式碼庫網址。
license 選填 授權條款識別碼,例如 MIT。
keywords 選填 用於搜尋套件的關鍵字陣列。
extensions 選填 依命名空間分組的設定。OpenAI 專屬設定請放在 com.openai 下。
skills 適用於含有技能的 Codex 套件 僅適用於 Codex。指定存放技能的相對目錄路徑或路徑陣列,例如 "./skills/"。可攜式套件會自動偵測 skills/。
mcpServers 適用於含有 MCP 伺服器的 Codex 套件 僅適用於 Codex。使用 "./.mcp.json" 指定套件隨附的 MCP 伺服器設定。可攜式套件會自動偵測根目錄下的 mcp.json。

使用可攜式套件時,請將下列額外設定放在 extensions.com.openai 中。使用 Codex 相容資訊清單時,請放在根層級:

欄位 要求 值與用途
interface Codex 必填,Agent Plugins 選填 控制顯示內容的物件,詳見目錄刊登中繼資料。Codex 格式必須提供此物件,可攜式套件則可從根層級的中繼資料取得基本文字。
id 選填 受管理的外掛程式目錄使用的識別碼。如果已獲指派識別碼,請保留原值。上傳 ZIP 檔時會使用儀表板上的外掛程式識別碼。

可攜式套件一律從 skills/ 偵測技能,並從 mcp.json 偵測 MCP 伺服器。在內嵌的擴充設定或相容性設定檔中宣告 skills 或 mcpServers,無法取代、停用或新增這些元件。只有當套件根目錄中沒有可辨識的可攜式資訊清單時,這些宣告才會生效。

目錄刊登中繼資料

使用 Agent Plugins 格式時,請將下列欄位放在 extensions.com.openai.interface 中。使用 Codex 格式時,請放在 interface 中。以下限制適用於提交至公開目錄的資料。上傳套件時可以接受較長的草稿文字,所以上傳成功後,仍須確認刊登資料符合送審要求。

欄位 要求 類型 值與送審限制
displayName 必填 字串 向使用者顯示的名稱,最多 30 個字元。
shortDescription 必填 字串 與名稱一起顯示的副標題,最多 30 個字元。
longDescription 必填 字串 說明可執行的任務、適用對象與限制,最多 4000 個字元。
developerName 必填 字串 發布者名稱,最多 80 個字元。目錄顯示的名稱會依你所選且已通過驗證的開發者身分自動設定。
category 必填 字串 儀表板中的類別名稱,例如 Productivity 或 Developer Tools。
capabilities Codex 必填,Agent Plugins 選填 字串陣列 功能標籤,最多 20 個,每個最多 120 個字元。Codex 格式必填,沒有標籤時請使用 []。
websiteURL MCP 送審必填 字串 產品網站的 HTTPS 網址,最多 1024 個字元。
supportURL MCP 送審必填 字串 客戶支援頁面的 HTTPS 網址,最多 1024 個字元。
privacyPolicyURL MCP 送審必填 字串 隱私權政策的 HTTPS 網址,最多 1024 個字元。
termsOfServiceURL MCP 送審必填 字串 服務條款的 HTTPS 網址,最多 1024 個字元。
defaultPrompt 選填 字串或字串陣列 最多三個起始提示詞,每個最多 128 個字元。各提示詞應互不重複,並省略應用程式的 @提及。有多個提示詞時,請使用陣列。
brandColor 選填 字串 淺色主題顏色,使用 #RRGGBB 格式,與白色的對比度至少為 2:1。
brandColorDark 選填 字串 深色主題顏色,使用 #RRGGBB 格式,與 #212121 的對比度至少為 2:1。如果只提供 brandColor,系統會自動推算深色主題顏色。
composerIcon Codex 必填 字串 撰寫工具所使用圖示的相對路徑。
composerIconDark 選填 字串 撰寫工具深色主題圖示的相對路徑。
logo Codex 必填,送審時必須有主要圖示 字串 目錄中主要圖示的相對路徑。
logoDark 選填 字串 主要圖示深色主題版本的相對路徑。

若外掛程式連結了須接受公開審查的 MCP 應用程式,則四個目錄刊登網址都必須提供:websiteURL、supportURL、privacyPolicyURL 和 termsOfServiceURL。請使用未嵌入憑證的 HTTPS 網址。純技能外掛程式的中繼資料驗證不要求四個網址全部填寫。套件的 homepage 和 author.url 不會自動填入這些刊登欄位。

圖示

準備散布套件時,請一併提供 logo 和 composerIcon。Codex 套件驗證要求兩者皆須提供。可攜式套件即使缺少兩者也能上傳,但儀表板要求在送審前提供主要應用程式圖示。深色主題版本可選填。如要排除「必須提供應用程式圖示」警告,請新增 logo 及其圖片檔,或在儀表板中提供圖示。

請使用以 ./ 開頭、相對於外掛程式根目錄的路徑,並納入每個參照的檔案。支援的圖片格式為 PNG、JPEG、WebP 和 SVG,每個檔案上限為 5 MiB。圖示和標誌必須是正方形,尺寸至少為 48 × 48 像素。點陣圖的寬和高各自不得超過 4096 像素。SVG 圖示須以數值指定相同的寬和高,或提供至少為 48 × 48 的正方形 viewBox。

設定入門流程、審查與發布資料

兩種格式都應將這些物件直接放在 extensions.com.openai 下。在可攜式格式中,它們與 interface 位於同一層級。請勿將它們放入 interface 內。

選填的 onboardingSkill 可讓使用者在安裝後執行設定流程。如需資訊清單範例、路徑規則,以及如何在新對話或現有對話中執行設定,請參閱新增入門技能。

欄位 要求 類型 值與用途
onboardingSkill 選填 字串 套件中技能的 SKILL.md 相對路徑,例如 ./skills/get-started/SKILL.md。必須指向套件內含的技能。
review.test_cases.positive ZIP 檔中選填,首次 MCP 送審須有五個案例 物件陣列 適用於只有一個 MCP 伺服器的外掛程式。請使用下表所列的欄位提供正向審查案例。
review.test_cases.negative ZIP 檔中選填,首次 MCP 送審須有三個案例 物件陣列 該伺服器的負向審查案例。
review.demo_recording_url ZIP 檔中選填,MCP 送審必填 字串 審查人員可存取的操作示範影片網址。
review.commerce 選填 布林值 應用程式是否支援商務交易。填寫此宣告不代表同意法律條款。
review.commerce_description 選填 字串 說明應用程式如何處理商務交易。
publication.countries 選填 字串陣列 允許使用外掛程式的國家清單,須使用系統可辨識的大寫國家代碼,例如 US 和 GB。省略此欄位會保留原有的國家設定,使用 [] 則會移除國家限制。設定會在外掛程式發布時生效,也適用於純技能外掛程式。
publication.release_notes 選填 字串 說明此版本的變更內容。
publication.translations 選填 物件或 null 以地區設定代碼為鍵、刊登文字譯文為值的對照表。請參閱翻譯目錄刊登文字。
publication.translations.<locale>.subtitle 選填 字串或 null 副標題譯文,最多 30 個字元。
publication.translations.<locale>.description 選填 字串或 null 說明譯文,最多 4000 個字元。

review.test_cases.positive 或 review.test_cases.negative 中的每個物件各描述一個測試案例:

欄位 要求 類型 值與用途
description 必填 字串 描述要檢查的行為。正向案例的說明不得超過 4000 個字元。
prompt 必填 字串 審查人員可以實際測試的使用者提示詞。
tools_triggered 正向案例必填 字串 預期會呼叫的工具名稱。送審時,正向案例必須提供。
expected_behavior 正向案例必填 字串 可觀察到的預期結果。送審時,正向案例必須提供。
file_attachment_urls 選填 字串陣列 案例所用檔案的連結。
expected_output_url 選填 字串 預期結果範例的連結,例如可供審查人員與實際輸出比對的參考文件。

MCP 應用程式首次送審時,必須恰好有五個正向案例與三個負向案例。上傳時可接受不完整的清單,請在送審前補齊。如果有多個 MCP 伺服器,請在 MCP 設定中分別為各伺服器宣告案例。外掛程式層級的 review.test_cases 僅適用於恰好有一個伺服器的情況,不能與個別伺服器的案例宣告並用。純技能外掛程式無須提供 MCP 應用程式審查案例或示範影片。

匯入的測試案例在儀表板中為唯讀。如要變更,請編輯套件並重新上傳。省略 test_cases 或將其設為 null 會保留現有案例。使用 test_cases: {} 會清空兩份清單。後續上傳即使省略案例,也無法恢復在儀表板中編輯案例的功能。

對於純量審查欄位與 release_notes,省略欄位或設為 null 會保留已儲存的值,空字串則會清除文字。提交時,系統會重新套用套件中明確指定的值。若要沿用在儀表板中編輯的值,請從套件移除對應的純量欄位宣告。共用審查欄位適用於該外掛程式本身的 MCP 應用程式草稿。純技能外掛程式的版本說明會保留在套件中,不會因此建立應用程式審查。

請將 commerce 和 commerce_description 放在 review 中,勿放入 publication。請勿將憑證或給審查人員的指示放入套件。ZIP 中繼資料不接受 test_credentials 和 reviewer_instructions。請透過儀表板的安全表單輸入審查人員的存取資料。

翻譯目錄刊登文字

兩種格式都可以在 extensions.com.openai.publication 下新增 translations 物件,提供副標題與說明的譯文。請使用非空的地區設定代碼作為鍵,例如 fr-FR 或 ja-JP。每個地區設定的物件可包含 subtitle、description,或同時包含兩者。任一欄位都可以省略或設為 null。你也可以省略 translations 或將其設為 null。

請在基本刊登欄位保留英文文字。無須另外提供 en-US 譯文,匯入工具也不會自動產生。

副標題譯文須為單行,最多 30 個字元。說明譯文可包含 \n 換行符號,最多 4000 個字元。提供的文字不可只含空白字元,且必須使用支援的文字字元。系統會拒絕定位字元及其他不受支援的控制字元。字元數按原樣計算,包括開頭與結尾的空格。

系統會在匯入時驗證譯文,並將其保留在上傳的套件中。編輯中繼資料後,譯文也會保留。目前匯入譯文後,外掛程式目錄顯示的文字和刊登資料 API 回應中的文字仍會維持原樣。