外掛程式管理

開始之前

工作區管理員可以從 GitHub 匯入外掛程式市集，並從程式碼庫取得更新，讓外掛程式保持最新。市集是一份 JSON 目錄，列出要匯入的外掛程式。

本頁說明工作區的匯入與同步功能。若要透過雲端管理或系統的 config.toml， 直接在本機用戶端設定市集，請參閱 設定外掛程式市集與預設值。 若要為特定專案啟用或停用外掛程式，請參閱為程式碼庫 啟用或停用外掛程式。

請使用能讀取市集程式碼庫及其參照的所有其他程式碼庫的 GitHub 帳戶。公開與私人的 GitHub 程式碼庫皆受支援。匯入前，請先完成存取程式碼庫所需的任何 GitHub 組織核准程序。

匯入前請先審查程式碼庫內容。新外掛程式的初始安裝政策為 可用 ，並設定為在安裝時進行身分驗證。新市集預設啟用每日自動同步。匯入作業會處理所有有效項目，之後的同步也會自動加入程式碼庫中的任何新外掛程式。

設定市集同步

1. 開啟 管理 > 外掛程式 ，然後選取 新增 > 匯入市集。
2. 在 來源中輸入程式碼庫網址，例如 https://github.com/example/team-plugins。請僅使用程式碼庫網址，不要使用分支或資料夾網址。
3. 如果市集位於子目錄中，請在 路徑中輸入該目錄。例如，對於 team-tools/.agents/plugins/marketplace.json，請輸入 team-tools。若使用程式碼庫根目錄，請將 路徑 留空。不要輸入資訊清單的檔名。
4. 你也可以輸入 分支、標籤或提交。留空即可使用程式碼庫的預設分支。使用分支可接收後續提交；指定固定提交則會停留在該版本。
5. 選取 匯入市集 ，並依提示授權 GitHub 存取。對於非常大型的市集，首次匯入可能需要長達一小時。後續的每日同步通常只需幾分鐘。
6. 檢查 匯入結果，然後逐一開啟已匯入的外掛程式，設定其安裝政策與任何必要的應用程式。

若要立即要求更新而不等待每日同步，請在 管理 > 外掛程式 > 市集 中開啟該市集，然後選取 立即同步。

支援的格式

所選目錄必須包含下列其中一個檔案：

市集中的項目可以參照含有 .codex-plugin/plugin.json 的原生外掛程式、與 Claude 相容的外掛程式、Agent Plugins 1.0 套件，或支援的技能套件。

在 Codex 市集中，請使用本機路徑來指定同一程式碼庫內的外掛程式：

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

此路徑以所選市集的根目錄為基準，而非 .agents/plugins/。

與 Claude 相容的市集可以使用路徑字串來指定各個本機外掛程式：

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Codex 市集項目也支援使用 source: "url" 來指定 GitHub 程式碼庫根目錄中的外掛程式，以及使用 source: "git-subdir" 來指定 GitHub 子目錄中的外掛程式。例如：

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Git 來源可以選擇 ref 或完整的 40 字元提交 sha。用於授權的 GitHub 帳戶必須能讀取每個參照的程式碼庫。工作區匯入目前僅支援 GitHub 程式碼庫。

設定工作區存取權

GitHub 匯入與同步不會套用程式碼庫中的安裝或身分驗證政策，包括 AVAILABLE、INSTALLED_BY_DEFAULT、NOT_AVAILABLE、ON_INSTALL 和 ON_USE。工作區管理員需為每個外掛程式設定這些選項。同步更新或將現有外掛程式改由 GitHub 管理時，都會保留其工作區政策。

使用 安裝政策 ，為每個符合資格的角色選擇 可用 或 已安裝 。必要的應用程式也必須啟用，且成員必須擁有所連接服務的存取權。匯入外掛程式不會授予應用程式存取權，也不會連接成員的帳戶。如需角色、應用程式及動作控制措施的詳細資訊，請參閱外掛程式控制措施。

將現有外掛程式改由 GitHub 管理

在現有外掛程式的市集項目中加入 pluginId：

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

從 管理 > 外掛程式 開啟該外掛程式，並複製其網址中 /admin/plugins/ 後面的 ID。在市集項目中，將 pluginId 與 name 和 source 放在同一層級。現有外掛程式必須位於同一工作區。

這會將已上傳或以其他方式建立、尚未受管理的工作區外掛程式改由 GitHub 管理。外掛程式會保留其 ID、共用設定與工作區政策。之後的更新會來自 GitHub；你將無法再透過上傳封存檔來取代受管理的外掛程式。已由其他 GitHub 來源管理的外掛程式無法透過此方式接管。

僅限桌面版的外掛程式

任何在 mcp.json 或 .mcp.json 中宣告 MCP 伺服器的已匯入外掛程式，都會標示為 僅限桌面版 ，且只能在 ChatGPT 桌面版應用程式中使用。這也包括使用遠端 HTTPS 網址的伺服器。其他支援的 MCP 組態形式（例如行內伺服器宣告）也適用相同限制。

使用 .app.json 參照現有應用程式

在外掛程式根目錄加入 .app.json。檔名前方包含一個點；不支援省略該點的 app.json。

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

將 asdk_app_example 替換為現有應用程式的 ID。支援的應用程式 ID 以 asdk_app_、connector_ 或 templated_apps_ 開頭。請使用應用程式 ID，而非 plugin_... ID。例如，包含 plugin_asdk_app_example 的外掛程式網址代表應用程式 asdk_app_example。

鍵 team-tools 用來命名此檔案中的參照。當外掛程式依賴該應用程式時，請將 required 設為 true。你可以加入更多項目，以參照其他現有應用程式。

對於原生外掛程式，請在 .codex-plugin/plugin.json 中將 apps 設為 ./.app.json。以下是此範例的完整資訊清單：

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

請依照下列結構放置檔案：

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

此參照不會建立應用程式或授予權限。管理員必須讓預定的角色能使用該應用程式，成員則必須完成任何必要的身分驗證。既有的應用程式權限、動作控制措施與服務存取規則仍然適用。

讓外掛程式保持最新

新市集會每天檢查更新。開啟 管理 > 外掛程式 > 市集，選取該市集，再選擇 立即同步 ，即可要求更新，無須等待自動同步。

同步可以加入新的市集項目，並更新現有外掛程式。請在合併程式碼庫變更前先進行審查，因為自動同步會匯入所有新外掛程式。

同步後，請檢查狀態與已儲存的報告。 已完成，N 個錯誤 表示本次作業已結束，但部分外掛程式無法處理。如果現有外掛程式的更新無效，系統會保留其最後一個可正常運作的版本。請在 GitHub 中修正報告指出的問題，再選取 立即同步 重試。

從程式碼庫移除項目，不會刪除已匯入工作區的副本。該副本會標示為 已不在來源中。在 ChatGPT 中刪除市集，會一併刪除從該市集匯入的所有外掛程式。

重新連接或變更 GitHub 存取權

若要 重新連接 GitHub 存取權，請先確認匯入時使用的 GitHub 帳戶仍可存取該程式碼庫及其參照的所有程式碼庫。接著，應由最初匯入市集的管理員在 ChatGPT 中開啟 GitHub 外掛程式，並重新連接自己的帳戶，因為市集同步使用的是該管理員的 GitHub 連線。

若要 轉移給新擁有者，新的工作區管理員應開啟 管理 > 外掛程式 > 新增 > 匯入市集 ，並使用相同的 來源、 路徑與 分支、標籤或提交 值匯入同一市集。之後的同步會使用新管理員的 GitHub 連線。

請勿僅為了重新連接市集或變更擁有者而刪除市集：刪除市集也會移除從中匯入的外掛程式。