為您的組織管理 Claude Code 外掛程式

​

預先安裝和要求外掛程式

​

選擇傳遞機制

• 伺服器受管設定：在組織設定 > Claude Code > 受管設定將外掛程式金鑰設定為 JSON。需要在您的 Claude 組織中具有擁有者角色。雲端工作階段在安裝外掛程式之前會擷取這些設定。
• MDM 政策：在 macOS 上，提供一個 plist，其頂級金鑰是設定金鑰。在 Windows 上，將整個 JSON 文件儲存為登錄值中的字串。plist 網域和登錄金鑰位於每個機制儲存政策的位置。
• 受管設定檔案：在平台的系統路徑放置 managed-settings.json。您也可以將檔案新增到其旁邊的 managed-settings.d/ 放入目錄。每個平台的檔案路徑位於每個機制儲存政策的位置，放入合併規則位於將基於檔案的政策分割到各個團隊。

​

哪個受管來源在機器上適用

​

要求市場及其外掛程式

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  }
}

• autoUpdate：true 保持市場及其外掛程式在背景中重新整理，false 關閉它。請參閱設定更新政策。
• source：github 是幾種來源類型之一。git 來源採用 GitLab 或內部主機的 url，url 來源採用託管 marketplace.json 的位址。每個來源形狀都在市場參考中。

• 市場：受管市場項目替換具有相同名稱的較低優先順序項目，兩個項目的欄位不合併。
• --plugin-dir 複本：--plugin-dir 為一個工作階段從本機目錄載入外掛程式。如果該複本的名稱與您的受管 enabledPlugins 命名的外掛程式相符，請參閱名稱衝突。

​

按儲存庫要求外掛程式

• 互動式工作階段：Claude Code 僅在貢獻者接受該資料夾的工作區信任對話後才註冊市場。
• 非互動式 -p 執行：項目僅適用於使用者已互動式接受信任的資料夾，或您在 ~/.claude.json 中設定 hasTrustDialogAccepted 旗標的資料夾。

​

每個表面何時應用外掛程式金鑰

​

確認推出

• 在一台機器上：啟動 Claude Code 並執行 /plugin。市場和外掛程式已列出。
• 在 CI 中：使用 --output-format stream-json --verbose 執行 claude -p。init 事件在 plugins 下列出已載入的外掛程式。

​

為容器和 CI 設定種子

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install code-formatter@your-marketplace

• 唯讀：Claude Code 永遠不會寫入種子，並強制為種子市場關閉 autoUpdate。
• 種子項目優先：在每次啟動時，種子中聲明的市場會覆蓋使用者的同名項目。使用者使用 claude plugin disable 而不是移除市場來選擇退出種子外掛程式。
• 更新和移除失敗：claude plugin marketplace update <name> 和在種子市場上不帶 --scope 的 remove 失敗，並顯示命名種子目錄的訊息。
• 政策仍適用：允許清單和封鎖清單也檢查種子市場的記錄來源。允許您建置種子的來源。

​

限制使用者可以安裝的內容

• 下載前：當使用者新增市場以及在每次安裝、更新、重新整理和自動更新時應用清單。
• 在工作階段開始時：清單再次應用於已安裝的外掛程式，因此已安裝的外掛程式其市場來源不再符合不會載入。/plugin 使用 Marketplace "<name>" is not in the allowed marketplace list 或 Marketplace "<name>" is blocked by enterprise policy 列出它。

• claude.ai 管理員主控台：Claude Code 在讀取伺服器受管設定的工作階段中執行兩個清單。claude.ai 也在您組織中的任何人從 git 儲存庫在 claude.ai 上新增新市場，或從 Claude Desktop 應用程式外其 Code 標籤中的自訂新增時檢查它們。這涵蓋成員為自己的帳戶新增的市場和在組織設定 > 外掛程式下為整個組織新增的市場。claude.ai 拒絕允許清單不允許或封鎖清單命名的儲存庫。它不重新檢查在您設定清單之前在任一位置新增的市場，也不檢查上傳的外掛程式。
• 受管設定檔案、OS 級政策或其他受管來源：Claude Code 在讀取該來源的位置執行兩個清單。claude.ai 不讀取它。

​

控制矩陣

• enabledPlugins：您可以在任何範圍設定它，受管設定會鎖定它。
• syncClaudeAiPlugins：每個使用者也可以在自己的使用者或本機設定中設定它。請參閱其設定參考中的範圍。
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL：這是一個環境變數，您透過關閉整個車隊的更新下顯示的受管 env 區塊提供。

​

市場金鑰的別名

• 版本：別名需要 Claude Code v2.1.232 或更新版本，較舊的用戶端會忽略它們。在混合車隊讀取的檔案中，保持規範名稱。
• 兩個拼寫都設定：當檔案設定兩個拼寫時，規範金鑰的值適用。

​

使用 strictKnownMarketplaces 的允許清單

• github：{ "source": "github", "repo": "your-org/approved-plugins" }，帶有可選的 ref 和 path。
• github 擁有者萬用字元：{ "source": "github", "repo": "your-org/*" } 匹配該擁有者下的每個儲存庫。* 必須代表整個儲存庫名稱。Claude Code 忽略 */plugins 和 your-org/tools-* 等項目作為無效，因此它們不匹配任何內容。需要 Claude Code v2.1.223 或更新版本。
• git：{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }，帶有可選的 ref 和 path。
• url：{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }，帶有可選的 headers。
• file 和 directory：{ "source": "file", "path": "/opt/marketplace/marketplace.json" } 或 { "source": "directory", "path": "/opt/marketplace/plugins" }，帶有絕對路徑。
• hostPattern：{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }，針對 github、git 和 url 來源的主機進行匹配。該模式在主機名中的任何地方匹配，因此使用 ^ 和 $ 進行錨定如所示以匹配整個主機。github 來源始終計為 github.com。對於開發人員建立自己的市場的 GitHub Enterprise Server 或 GitLab 主機，使用 hostPattern 項目。GHES 頁面有工作範例。
• pathPattern：{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }，針對 file 和 directory 來源的 path 進行匹配。該模式在路徑中的任何地方匹配，因此以 ^ 開頭以固定目錄前綴。".*" 允許每個本機路徑。
• skills-dir：{ "source": "skills-dir" } 在設定允許清單時保持技能目錄外掛程式載入，並不匹配任何市場。

​

項目如何匹配

• 沒有 ref 的項目不涵蓋具有 ref: "main" 的來源。
• your-org/your-marketplace 的項目不涵蓋複製相同儲存庫的 git URL。
• 尾部斜線、.git 後綴或 ssh:// 代替 https:// 是不同的值。當市場可以由多個 URL 複製時，更喜歡 hostPattern 項目。

​

保持技能目錄外掛程式載入

​

託管在 claude.ai 上的市場

​

鎖定每個來源

​

使用 blockedMarketplaces 的封鎖清單

• Git URL 被規範化，因此一個 github.com 儲存庫的 git@ 和 https:// 形式、.git 後綴和尾部斜線都匹配相同的項目。
• github 項目也阻止等效的 git URL，反之亦然。
• 對於 owner/* 項目，擁有者比較不區分大小寫。
• 沒有 ref 或 path 的項目阻止它匹配的儲存庫的每個 ref 和 path。

{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted-org/*" }
  ]
}

​

允許官方市場和您自己的

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "your-org/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
    },
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  },
  "disableSideloadFlags": true
}

• 允許清單不註冊任何內容：extraKnownMarketplaces 項目執行，它本身必須通過允許清單。Claude Code 拒絕註冊受管市場，其來源允許清單不匹配。
• 官方市場僅在互動式終端機工作階段中自行註冊：即使在那裡，它也僅在允許清單允許時註冊。-p 執行或附加到雲端工作階段的終端機永遠不會註冊它。
• 被阻止的嘗試被記住：如果機器曾在阻止官方市場的政策下執行，Claude Code 會記錄被阻止的嘗試，並在政策更改後不重試。[] 鎖定是一個此類政策。該機器僅透過此政策中的 extraKnownMarketplaces 項目、其中一個外掛程式的 enabledPlugins 項目或手動 /plugin marketplace add 再次註冊它。

​

設定更新政策

​

按市場開啟或關閉自動更新

• 如果受管項目設定欄位，Claude Code 拒絕使用者的 /plugin 切換並顯示以 Auto-update for '<name>' is set by 開頭的錯誤。
• 如果受管項目保留欄位未設定，使用者的切換保持。

​

關閉整個車隊的更新

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

​

將發佈頻道指派給使用者群組

• 將單獨的端點受管設定（例如受管設定檔案或 MDM 設定檔）部署到每個群組的裝置。若要檢查每個群組檔案或設定檔是否適用於也有組織範圍來源的裝置，請參閱Claude Code 如何組合受管來源。
• 為每個群組定義一個 Claude 應用程式閘道政策。閘道應用第一個符合使用者的匹配規則的政策，因此排序政策以便每個使用者到達其群組的政策。該政策的 extraKnownMarketplaces 對應不與任何其他政策的合併，因此列出群組需要的每個市場，而不僅僅是其頻道市場。

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": { "source": "github", "repo": "your-org/stable-tools" }
    }
  }
}

​

推薦外掛程式

​

稽核和檢視

​

OpenTelemetry 事件

​

Analytics API

​

規劃受管設定無法執行的內容

• 按使用者或按群組目標：每個外掛程式金鑰適用於接收設定的每個使用者。伺服器受管設定為每個組織提供一個配置。對於按群組政策，使用單獨的端點受管設定或閘道政策，如將發佈頻道指派給使用者群組下所述。
• 限制允許市場內的項目：允許清單匹配市場來源。若要從允許的市場阻止一個外掛程式，請在受管 enabledPlugins 中將其設定為 false。
• 隱藏 /plugin：沒有金鑰禁用命令。最接近的等效項結合僅命名您的市場的允許清單、您提供的外掛程式的受管 enabledPlugins 項目和 disableSideloadFlags。
• 透過允許清單控制 --plugin-dir：允許清單不涵蓋 --plugin-dir。disableSideloadFlags 執行。
• 透過這些金鑰執行 claude.ai 外掛程式切換：組織設定 > 外掛程式與技能不設定此頁面上的金鑰。成員和您的組織在那裡開啟的內容作為同步外掛程式到達 CLI，它們有自己的控制項。

​

疑難排解政策

• 受管檔案未解析：當 managed-settings.json 不是有效 JSON 時，Claude Code 拒絕啟動並列印命名檔案的錯誤。解析但有一個無效項目的檔案保持其政策的其餘部分。請參閱受管設定中的無效項目。
• 受管來源未載入：執行 /status 並在 Setting sources 行中尋找 Enterprise managed settings。如果遺失，來源未載入。
• 使用者報告 blocked by enterprise policy：訊息命名市場或其來源。對於允許清單，它也列出允許的來源。使用者面向的項目位於疑難排解外掛程式。
• 使用者在 ~/.claude/settings.json 中禁用的外掛程式仍然載入：另一個設定來源重新啟用它，例如強制啟用它的受管 enabledPlugins 項目。/plugin 和 claude plugin list 顯示 Disabled in ~/.claude/settings.json but still loads 與該設定來源。

​

後續步驟

• 市場參考：extraKnownMarketplaces、strictKnownMarketplaces 和 blockedMarketplaces 接受的 source 值
• 託管和維護市場：執行您的政策指向的市場
• 外掛程式安全性和信任：外掛程式可以在機器上執行的內容以及在安裝前如何檢視一個
• 伺服器受管設定：從 claude.ai 管理員主控台提供這些金鑰
• 疑難排解外掛程式：政策阻止使用者時看到的訊息