外掛管理

開始之前

工作區管理員可以從 GitHub 匯入外掛市場，並使其中的外掛與儲存庫保持同步。外掛市場是一個 JSON 目錄，其中列出了要匯入的外掛。

本頁介紹工作區的匯入與同步。要通過雲端受管設定或系統 config.toml 直接 在本機客戶端上設定市場，請參閱 設定外掛市場和預設設定。 要為特定專案啟用或停用外掛，請參閱為儲存庫啟用或停用 外掛。

請使用能夠讀取外掛市場儲存庫及其引用的任何其他儲存庫的 GitHub 帳戶。支援公開和私有 GitHub 儲存庫。匯入前，請完成 GitHub 組織針對儲存庫存取所要求的所有審批。

匯入前請檢查儲存庫內容。新外掛最初的安裝策略為 Available，並在安裝時進行身份驗證。新外掛市場預設啟用每日自動同步。匯入會處理所有有效條目，後續同步會自動新增儲存庫中的任何新外掛。

設定外掛市場同步

1. 開啟 Admin > Plugins，然後選擇 Add > Import marketplace。
2. 在 Source 中輸入儲存庫 URL，例如 https://github.com/example/team-plugins。請僅使用儲存庫 URL，不要使用分支或資料夾 URL。
3. 如果外掛市場位於子目錄中，請在 Path 中輸入該目錄。例如，對於 team-tools/.agents/plugins/marketplace.json，請使用 team-tools。如果位於儲存庫根目錄，請將 Path 留空。不要輸入清單檔名。
4. 可選擇輸入 Branch, tag, or commit。將其留空可使用儲存庫的預設分支。使用分支可以接收後續提交；固定的提交則會停留在該修訂版本。
5. 選擇 Import marketplace，並在出現提示時授權 GitHub 存取。對於非常大的外掛市場，首次匯入最長可能需要一小時。後續的每日同步通常只需幾分鐘。
6. 檢視 Import results，然後開啟每個已匯入的外掛，設定其安裝策略和任何必需的應用。

若要立即請求更新而不等待每日同步，請在 Admin > Plugins > Marketplaces 下開啟該外掛市場，然後選擇 Sync now。

支援的格式

所選目錄必須包含以下檔案之一：

在外掛市場中，條目可以引用使用 .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 管理時，會保留其工作區策略。

使用 Installation policy 為每個符合條件的角色選擇 Available 或 Installed。必需的應用也必須啟用，並且成員必須有權存取所連線的服務。匯入外掛不會授予應用存取權限，也不會連線成員的帳戶。有關角色、應用和操作控制，請參閱外掛控制。

將現有外掛轉為由 GitHub 管理

將 pluginId 新增到現有外掛的外掛市場條目中：

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

從 Admin > Plugins 開啟該外掛，並複製其 URL 中 /admin/plugins/ 後面的 ID。在外掛市場條目中，將 pluginId 與 name 和 source 放在同一級。現有外掛必須位於同一工作區中。

這會將已上傳或以其他方式處於未管理狀態的工作區外掛轉為由 GitHub 管理。該外掛會保留其 ID、共享設定和工作區策略。後續更新將來自 GitHub；無法再通過上傳歸檔檔案替換該託管外掛。已由其他 GitHub 源管理的外掛無法通過此方式接管。

僅限桌面端的外掛

任何在 mcp.json 或 .mcp.json 中宣告 MCP server的已匯入外掛都會標記為 Desktop only，並且僅可在 ChatGPT 桌面應用中使用。這包括使用遠端 HTTPS URL 的伺服器。相同限制也適用於其他受支援的 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 的外掛 URL 表示應用 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

該引用不會建立應用或授予權限。管理員必須向預期角色開放該應用，成員則必須完成任何必需的身份驗證。現有的應用權限、操作控制和服務存取權限仍然適用。

使外掛保持最新

新外掛市場每天檢查更新。開啟 Admin > Plugins > Marketplaces，選擇該外掛市場，然後選擇 Sync now，即可立即請求更新而不等待自動同步。

同步可以新增新的外掛市場條目並更新現有外掛。合並儲存庫變更之前請先進行檢查，因為自動同步會匯入任何新外掛。

同步後，請檢視狀態和已儲存的報告。Completed — N errors 表示此次同步已完成，但有些外掛無法處理。如果現有外掛的更新無效，系統會保留其上一個可用版本。在 GitHub 中修復報告的問題，然後選擇 Sync now 重試。

從儲存庫中移除條目不會刪除其已匯入的工作區副本。它會被標記為 No longer in source。在 ChatGPT 中刪除外掛市場會刪除從中匯入的所有外掛。

重新連線或更改 GitHub 存取權限

若要重新連線 GitHub 存取權限，請先確認用於匯入的 GitHub 帳戶仍有權存取該儲存庫及其引用的任何儲存庫。然後，最初匯入該外掛市場的管理員應在 ChatGPT 中開啟 GitHub 外掛並重新連線自己的帳戶，因為外掛市場同步使用該管理員的 GitHub 連線。

若要轉移給新所有者，新的工作區管理員應開啟 Admin > Plugins > Add > Import marketplace，並使用相同的 Source、Path 和 Branch, tag, or commit 值匯入同一外掛市場。後續同步將使用其 GitHub 連線。

不要僅為了重新連線或更改所有權而刪除外掛市場：刪除外掛市場也會移除從中匯入的外掛。