Codex CLI 的插件系統正在快速成型，/plugins 命令已經能按市場分組瀏覽、安裝、啓停插件，越來越多團隊開始把內部工具鏈打包成可複用的 Codex 插件。但官方 Marketplace 的自助上架入口目前還處於"審覈制"階段，開發者需要先理解 manifest 結構、本地調試方式，再走完提交審覈流程，才能讓插件真正觸達用戶。這篇文章按照實戰順序梳理了從零搭建、本地測試、Git 市場分發，到官方審覈上架的完整鏈路，並總結了幾個容易踩坑的細節。
Codex 插件到底由什麼組成
一個 Codex 插件本質上是把幾種能力打包成可安裝、可分發的單元。根據 OpenAI 官方文檔，插件可以包含 skills（可複用的技能說明）、MCP-backed app（連接外部工具的服務）、生命週期 hooks，以及可選的瀏覽器擴展和定時任務模板。這些組件不是必須同時存在，一個只包含 skills 的輕量插件同樣可以正常安裝和使用。
理解每個組件的職責邊界，是寫出合格 manifest 的前提。下表梳理了 Codex 插件目錄下四類核心組件的存放路徑和作用：
| 組件 | 存放路徑 | 作用 | 是否必需 |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
插件身份標識與元信息 | 必需 |
| skills | skills/<skill-name>/SKILL.md |
定義可複用的任務指令 | 可選 |
| MCP servers | .mcp.json |
配置外部工具服務連接 | 可選 |
| hooks | hooks/hooks.json |
聲明生命週期鉤子命令 | 可選 |
值得注意的是，如果插件只是團隊內部複用的 SKILL.md 文件，不需要走完整的 manifest 流程——把文件直接放進 .agents/skills/ 目錄，Codex 會自動發現，不需要插件清單。這也是很多團隊從"內部腳本"過渡到"正式插件"之前的常見中間形態。
插件的能力邊界比很多人預想的更廣。除了 skills 和 MCP-backed app 這兩個最常見的組件，官方文檔還提到插件可以攜帶瀏覽器擴展所需的能力聲明，以及可複用的定時任務模板，這意味着一個插件既能處理"用戶主動觸發"的交互式請求，也能承接"週期性後臺執行"的自動化場景。選擇哪些組件組合進同一個插件，本質上是在權衡安裝體驗和維護成本——組件越多，插件功能越完整，但對應的審覈材料和測試用例也會相應增加，提交前最好先想清楚目標用戶真正需要的是哪一層能力，而不是把所有組件都塞進同一個包裏。
從 plugin.json 開始：插件清單文件詳解
plugin.json 是插件的身份證，決定了 Codex 如何識別、加載和展示這個插件。一個最小可用的 manifest 只需要三個字段：
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}
name 字段建議使用穩定的 kebab-case 命名，後續版本升級不應該改變這個標識，否則市場無法正確識別爲同一插件的迭代。version 遵循語義化版本號規範，市場依賴這個字段判斷是否需要提示用戶升級。所有 manifest 中引用的路徑都必須相對於插件根目錄，並以 ./ 開頭，不能跳出插件根目錄之外。
除了這三個基礎字段，skills 也可以指向多個技能目錄的數組，hooks、mcpServers、apps 字段則分別指向 hooks/hooks.json、.mcp.json、.app.json 對應的配置文件。這種"字段指向文件"的設計讓 manifest 本身保持精簡，具體的技能說明、工具配置都拆分到獨立文件裏維護，方便多人協作時並行修改不同組件而不產生衝突。
如果打算把插件提交到官方 Marketplace，還需要補充一組面向展示層的元數據。下表列出了發佈階段建議補全的關鍵字段：
| 字段 | 類型 | 說明 |
|---|---|---|
| author / repository | 字符串 | 標識插件來源，建議與驗證身份一致 |
| interface.displayName | 字符串 | 市場列表中展示的插件名稱 |
| interface.category | 字符串 | 插件分類，影響用戶瀏覽路徑 |
| interface.capabilities | 數組 | 聲明插件具備的能力標籤 |
| mcpServers / apps / hooks | 對象 | 指向對應組件的配置文件 |
寫 manifest 時最容易踩的坑是路徑引用錯誤——比如 skills 字段寫成絕對路徑，或者遺漏開頭的 ./，這會導致插件在本地能跑通，提交審覈時卻被判定爲無效清單。建議在提交前用乾淨的目錄重新克隆一遍插件倉庫，模擬真實的安裝環境跑一次完整測試。
本地腳手架與調試：讓插件先跑起來
從零手寫 manifest 效率不高，官方提供了內置的 $plugin-creator 技能來完成腳手架搭建，直接在 Codex CLI 裏對話式生成：
codex "使用 $plugin-creator 腳手架生成一個名爲 infra-monitor 的插件"
這條命令會自動生成 manifest、示例 skill 和本地市場條目，免去手寫目錄結構的繁瑣工作。生成之後，插件已經可以在本地環境裏直接安裝測試，不需要先發布到任何遠程倉庫。
本地調試階段，如果插件內的 skill 涉及調用不同廠商的大模型做對比測試，統一的 API 網關能顯著減少環境配置的切換成本。我們在驗證插件的 MCP server 能力時，通常會把 base_url 指向 API易 apiyi.com 提供的中轉接口，一套 Key 就能在插件裏切換調用不同模型，方便對比各家模型在同一段插件邏輯下的表現差異：
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
🎯 調試建議: Codex 插件開發過程中經常需要反覆測試 MCP server 在不同模型下的響應質量。我們建議通過 API易 apiyi.com 平臺統一管理多模型調用，避免爲每個模型單獨申請密鑰、維護獨立的調用邏輯，把精力集中在插件本身的功能打磨上。
除了手動搭建本地市場條目，也可以直接在 ~/.agents/plugins/marketplace.json（個人級）或倉庫根目錄的 .agents/plugins/marketplace.json（團隊級）裏聲明本地插件路徑，source 字段設爲 local 即可指向本地目錄，不需要推送到遠程就能完成安裝驗證。
如果插件裏包含需要 ChatGPT 開發者模式配合調試的 MCP-backed app，官方還提供了另一條路徑：先在 ChatGPT 設置裏開啓開發者模式，創建一個 MCP-backed app 並拿到對應的 app ID，再通過 $plugin-creator 關聯這個 ID，就能在真實的對話環境裏驗證插件與 app 之間的數據流轉，這一步比純本地命令行調試更接近上線後的真實體驗，建議在提交審覈之前至少完整走一遍。
Git 市場註冊與團隊內分發
插件在本地驗證通過後，團隊內部分發通常不需要等待官方審覈，用 Git 倉庫搭建一個市場源就足夠。Codex CLI 提供了一組專門的市場管理命令：
| 命令 | 用途 |
|---|---|
codex plugin marketplace add owner/repo |
添加 GitHub 倉庫作爲市場源 |
codex plugin marketplace add owner/repo --ref v2.1.0 |
鎖定特定分支或標籤，控制灰度發佈 |
codex plugin marketplace list |
查看已添加的市場列表 |
codex plugin marketplace upgrade |
拉取市場更新 |
codex plugin marketplace remove |
移除市場源 |
對於代碼倉庫體量較大的團隊，還可以用 --sparse .agents/plugins 參數只拉取插件相關目錄，避免整倉克隆拖慢安裝速度。這種 Git 市場模式非常適合企業內部工具鏈——不需要經過公開審覈，插件更新只需要推送新的 tag，團隊成員執行一次 upgrade 命令即可同步。
從實踐角度看，Git 市場模式還有一個隱藏優勢：可以把插件的迭代節奏和團隊內部的發佈節奏解耦。業務代碼可能一天多次合併，但插件作爲對話式工具鏈的一部分，更新頻率過高反而會打斷使用者的心智模型。建議把插件版本和 tag 綁定在固定的發佈窗口上，比如每週或每兩週合併一次改動，既保證功能迭代速度，也不會讓團隊成員頻繁地重新適應新的交互方式。
官方 Marketplace 提交審覈全流程
官方 Marketplace 的自助上架入口截至目前仍未完全開放，OpenAI 文檔明確標註這部分"即將推出"，現階段面向公開用戶的正式提交走的是插件提交門戶的人工審覈流程。提交前需要先完成身份驗證——個人開發者需要完成 individual verification，以公司名義發佈則需要完成 business verification，審覈人員會覈對發佈身份與提交材料是否一致。
正式提交需要準備的材料清單如下：
| 材料類別 | 具體要求 |
|---|---|
| 插件基礎信息 | 名稱、描述、Logo、分類、相關 URL |
| MCP 服務器 | 公網可訪問域名、CSP 策略、鑑權配置 |
| 演示賬號 | 可直接登錄，不要求 MFA 或郵箱二次驗證 |
| 測試用例 | 恰好 5 個正向場景 + 3 個負向場景 |
| 工具標註 | readOnlyHint、openWorldHint、destructiveHint 需與實際行爲一致 |
提交流程分爲幾個表單區塊：Info（公開列表信息）、MCP（服務器與鑑權配置）、Skills（上傳最終技能包）、Prompts（起始提示詞示例）、Testing（測試用例）、Global（可用國家和地區），最後是 Submit 區塊填寫發佈說明並完成政策確認。審覈通過之後，發佈時機由開發者自己在門戶裏選擇，插件會同步出現在 ChatGPT 和 Codex 的統一插件目錄中。
如果插件包含 MCP-backed app，還需要額外驗證域名所有權，確保 MCP server 部署的域名和插件聲明的域名一致。審覈團隊會重點檢查工具返回結果是否包含多餘的個人數據或密鑰信息，這一點在設計工具輸出格式時就應該提前規避，而不是等審覈打回才修改。
版本管理與常見踩坑
插件上線之後，版本管理的細節直接影響用戶的升級體驗。市場依賴 version 字段判斷是否有更新可用，所以嚴格遵循語義化版本號規範很重要——修復 bug 用 patch 版本號，新增能力用 minor 版本號，破壞性變更才升 major 版本號。
已安裝的插件會緩存在本地路徑 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/，排查"插件更新了但行爲沒變"這類問題時，先確認緩存是否已經刷新到新版本，往往比重新調試代碼邏輯更快定位問題。企業環境下還會遇到 requirements.toml 強制的白名單策略，MCP server 需要名稱和身份同時匹配，任何一項不一致都會導致服務被靜默禁用，不會有明顯報錯提示，這類問題建議先在測試環境裏跑一遍策略配置再上生產。
下表彙總了幾個開發者反饋較多的踩坑點及應對方式：
| 常見問題 | 應對方式 |
|---|---|
| manifest 路徑寫成絕對路徑 | 統一改爲 ./ 開頭的相對路徑 |
| 隱式調用觸發了非預期插件 | 使用 @plugin-name 顯式指定插件 |
| 更新後行爲未生效 | 檢查本地插件緩存目錄是否已刷新 |
| 企業策略下 MCP 靜默失效 | 覈對 requirements.toml 中名稱與身份是否匹配 |
在正式提交官方審覈之前，建議先跑一遍第三方的 codex-plugin-scanner 工具，它會從可安裝性、維護狀態、MCP 安全性、發佈來源等維度給插件打分，尤其是要分發給企業客戶的插件，提前發現問題比被審覈打回更省時間。
另一個容易被忽略的細節是顯式調用和隱式發現之間的差異。Codex 在沒有明確指定插件的情況下，會根據上下文自動匹配最相關的技能，如果同一個工作區裏安裝了多個功能相近的插件，這種隱式匹配有可能選中的不是你預期的那一個。養成用 @plugin-name 顯式聲明的習慣，尤其是在團隊共享的工作區裏，能減少這類"插件互相打架"的排查成本。
Codex 插件開發常見問題（FAQ）
插件和單獨的 SKILL.md 文件有什麼區別？
SKILL.md 是插件裏的一個組件，單獨使用時不需要 manifest，放進 .agents/skills/ 目錄即可被自動發現。插件則是把 skills、MCP server、hooks 等多個組件打包成一個帶身份標識、可版本化管理的整體，適合需要正式分發和更新追蹤的場景。
開發階段需要多個模型賬號做對比測試怎麼辦？
這是插件開發中經常遇到的實際問題，尤其是涉及模型選擇或 prompt 調優的插件。與其爲每個模型廠商單獨開戶、管理密鑰，不如用 API易 apiyi.com 這類統一網關，通過一套 Key 調用主流模型完成 A/B 對比，把調試重心放在插件邏輯本身而不是賬號管理上。
Git 市場分發和官方 Marketplace 上架能否共存？
可以。很多團隊會先用 Git 市場做內部驗證和小範圍灰度，確認穩定後再走官方提交流程，兩種分發方式互不衝突，manifest 結構也是通用的。
插件審覈大概需要多長時間？
官方文檔目前沒有給出固定週期，只說明審覈流程仍在持續建設和擴容中，也不支持加急處理。建議把審覈週期算作項目排期裏的不確定變量，提交前把材料一次性準備齊全，減少因材料補充導致的往返溝通，這是縮短整體上線時間最實際的辦法。
寫在最後
Codex 插件開發的核心難點其實不在代碼本身，而在於理解 manifest 的規範要求和審覈流程的材料準備——這些細節沒有想象中複雜，但容易因爲一個路徑寫法或者一個字段缺失而被打回重來。建議按照"本地腳手架驗證 → Git 市場小範圍分發 → 官方提交審覈"的順序推進，每一步都留出真實環境的測試時間。如果你的插件涉及多模型調用或需要頻繁切換測試模型，API易 apiyi.com 提供的統一 API 中轉能省去不少環境搭建的時間，讓你把更多精力放在插件本身的打磨上。
