extraKnownMarketplacesでチームにマーケットプレイスを自動配布する

extraKnownMarketplacesとは何を自動化する設定か

extraKnownMarketplaces は、settings.json に書いたマーケットプレイスを、そのファイルが効くユーザー全員に自動登録する設定です。メンバーが自分で /plugin marketplace add を打つ手間をなくします。登録先はプロジェクトの .claude/settings.json から個人の ~/.claude/settings.json、組織のmanaged settingsまで、設定ファイルなら基本的にどこでも書けます(スコープは「Any file」)。

ここで押さえておきたいのは、登録と制限は別の話だという点です。extraKnownMarketplaces はマーケットプレイスを足す設定であって、他のマーケットプレイスの追加を止める力はありません。同じ画面でよく混同される strictKnownMarketplaces(組織単位でマーケットプレイスを許可リスト化する設定)とは目的も設定ファイルも異なります。両者の違いは後段の表にまとめます。

登録はマーケットプレイス単位で、プラグインのインストールとは別の処理です。extraKnownMarketplaces がマーケットプレイスを登録しても、そこにあるプラグインが自動でインストールされるわけではありません。enabledPlugins で明示的に有効化した場合だけ、プラグインのソースとどのファイルが有効化を宣言したかに応じてインストールが動きます。

チームのリポジトリでマーケットプレイスを自動登録する

もっとも典型的な使い方は、チームのリポジトリに .claude/settings.json を置いて、そのリポジトリを開いた人全員に同じマーケットプレイスを配ることです。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

この設定はコミットしてリポジトリに含めておけます。メンバーがリポジトリを開き、ワークスペースの信頼ダイアログを承諾した時点で、company-tools という名前のマーケットプレイスが自動登録されます。信頼していないフォルダでは、この設定はメッセージも出さず単に無視されます。-p フラグの非対話実行でも同じ扱いです。信頼していないリポジトリを開いただけでは何も起きません。

登録するだけでなく、特定のプラグインを既定で有効にしたい場合は enabledPlugins を並べて書きます。

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

ただし注意点があります。プロジェクトの .claude/settings.json でGitHubリポジトリのような外部ソースからプラグインを有効化しても、それだけでは他のメンバーの環境にプラグイン本体はインストールされません。プラグインを読み込むあらゆる経路で、各ユーザーが自分でインストールを実行するまで「未インストール」と表示されます。extraKnownMarketplaces が配るのはマーケットプレイスの登録情報までで、インストール自体は各自の操作が要る、という点は覚えておく価値があります。

sourceの形式を使い分ける

extraKnownMarketplaces の各エントリは、名前をキーにして source オブジェクトをネストする形で書きます。source に指定できる形式は6つです。GitHubリポジトリを指す github、任意のgit URLを指す git、ホスティングされた marketplace.json を直接指す url、ローカルの marketplace.json ファイルを指す file、開発用のローカルディレクトリを指す directory、そしてホストされたリポジトリを持たずに設定ファイル内で直接マーケットプレイスを宣言する settings です。

見落としやすいのは、この6形式に npm が含まれていない点です。strictKnownMarketplaces の許可リストはnpmパッケージ形式のマーケットプレイスも対象にできますが、extraKnownMarketplaces で新規登録する場合の形式には npm が挙がっていません。npmパッケージで配布しているマーケットプレイスをチームに自動登録したい場合は、この制約を踏まえて別の配布経路を検討する必要があります。

github / git 形式でプライベートリポジトリを社内マーケットプレイスに使う場合、認証はClaude Code独自の仕組みではなく、そのマシンで git clone が使うのと同じ認証(設定済みのcredential helperやSSH鍵)に委ねられます。GITHUB_TOKEN のようなプロバイダートークンも、それを読むcredential helperを経由して初めて効きます。トークンをそのままURLに埋め込む運用も可能ですが、平文でgitconfigに残るため、読み取り専用スコープのトークンに絞るのが安全です。

url 形式には注意点があります。url 形式のマーケットプレイスは marketplace.json ファイルだけを取得し、そこからの相対パスでプラグイン本体を取りに行くことはしません。プラグインの source を相対パスにしている構成では、url 形式のマーケットプレイスは機能しません。相対パスのプラグインを配りたいなら、Gitベースのマーケットプレイスに切り替えます。

認証が必要なプライベートなマーケットプレイスやレジストリには、url の source オブジェクトに headers を設定します。トークンの有効期限が短くて固定の headers に書けない場合は、headersHelper に新しいヘッダーを都度出力するコマンドを指定できます(Claude Code v2.1.238以降)。headersHelper は marketplace.json の取得前と、そのマーケットプレイスと同じオリジンからのプラグインアーカイブのダウンロード前の2か所で実行され、1回の出力を最大60秒使い回します。github / git の source に "skipLfs": true を添えると、Git LFSの大きなオブジェクトをポインタのまま残し、クローンや更新を軽くできます。

autoUpdateの既定値は公式マーケットプレイスだけtrueになる

各エントリには autoUpdate という真偽値を任意で添えられます。省略した場合の既定値は一律ではありません。claude-plugins-official をはじめとする公式Anthropicのマーケットプレイスは既定で true(バックグラウンドで自動更新)になり、サードパーティのマーケットプレイスは既定で false になります。

社内マーケットプレイスを自動更新させたいなら、"autoUpdate": true を明示する必要があります。書き忘れると、プラグインを更新してもメンバーの環境には届かず、手動での /plugin update 待ちになります。逆に、意図せず自動更新させたくない外部マーケットプレイスには、明示的に false を書いて既定挙動をコードに残しておくと事故が減ります。

strictKnownMarketplacesとは何が違うのか

名前も見た目も似ている2つの設定ですが、担っている役割は正反対に近いものです。

strictKnownMarketplaces だけを設定した場合、ユーザーは許可されたマーケットプレイスを自分で /plugin marketplace add して追加できます。自動では登録されません。唯一の例外は公式Anthropicマーケットプレイスで、許可リストがそれを許している場合に限り、対話モードで初回起動したタイミングで自動登録されます。逆に extraKnownMarketplaces だけを設定した場合は、指定したマーケットプレイスが自動で増えるだけで、ユーザーが他の未承認マーケットプレイスを追加すること自体は止められません。片方だけでは「配る」と「絞る」のどちらか一方しか実現できない、という理解が両者を混同しないための出発点です。

両方を組み合わせて配布と制限を両立する

配布と制限を同時に実現したい場合は、managed-settings.json に両方を書きます。

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

同じリポジトリを両方のキーに書く形になります。strictKnownMarketplaces が許可リストとしてそのリポジトリ以外の追加を拒み、extraKnownMarketplaces が同じリポジトリを全ユーザーに自動登録します。

公式マーケットプレイスだけを許可する構成でも、この組み合わせが効いてくる場面があります。strictKnownMarketplaces に公式リポジトリだけを許可リストとして書くと、対話モードで初回起動したときに限り自動登録されますが、これは万能ではありません。マシンの初回対話起動より前に動く非対話環境や、以前ブロックされたポリシーの下で一度起動してしまい登録の試行が記録されてしまったマシンでは、自動登録が働きません。こうしたマシンを取りこぼさないためには、同じ managed-settings.json の extraKnownMarketplaces にも公式マーケットプレイスを追加しておくか、claude plugin marketplace add anthropics/claude-plugins-official を明示的に実行します。

もう一つ組み合わせておきたいのが disableSideloadFlags です。strictKnownMarketplaces はマーケットプレイス経由の追加を絞りますが、--plugin-dir や --plugin-url といったCLIフラグを使えば、その回だけ許可リストを迂回してプラグインを読み込めてしまいます。disableSideloadFlags を true にすると、これらのフラグを起動時に拒否し、Claude Codeはどのフラグが拒否されたかを示すエラーで終了します。ZIP配布で使う --plugin-url の運用はClaude Codeプラグインをzip配布するで扱っています。

設定ファイルが競合したときの優先順位

複数の設定ファイルが同じ名前でマーケットプレイスを定義した場合、Claude Codeは最も優先度の高いファイルのエントリをまるごと採用します。低い優先度のファイルの値を一部でも引き継ぐことはありません。この挙動はv2.1.228以降のもので、それより前のバージョンでは同名エントリをフィールド単位でマージしていました。旧挙動では、優先度の高いファイルが設定していないフィールドを低い優先度のファイルから意図せず引き継ぐことがあり、たとえば別のファイルが管理する headers の認証情報を高優先度側のURLに継ぎ足してしまうケースがありました。古いバージョンが混在する環境では、この差を踏まえて設計する必要があります。

キー名にも歴史的な事情があります。Claude Code v2.1.232以降では、extraKnownMarketplaces を additionalMarketplaces という別名で書けます(strictKnownMarketplaces も同様に allowedMarketplaces と書けます)。古いバージョンはこの別名を無視するため、バージョンが混在する環境で使うファイルには正規のキー名を残しておく必要があります。同じファイルに両方の綴りを書いた場合は、正規のキー名の値が優先され、別名側は無視されます。Claude Codeが設定ファイルを更新する際に additionalMarketplaces を extraKnownMarketplaces へ書き換えることもあります。

自動登録がうまく効かないときに確認すること

想定どおりに登録が反映されないときに確認すべき点はいくつかあります。まず、プロジェクトの .claude/settings.json や .claude/settings.local.json に書いたエントリは、そのフォルダのワークスペース信頼ダイアログを承諾するまで一切効きません。信頼していないフォルダでは黙って無視されるだけで、エラーは出ません。CIなど非対話環境で -p を使う場合も同じ扱いです。

コンテナ環境で CLAUDE_CODE_PLUGIN_SEED_DIR を使ってマーケットプレイスを事前展開している場合は、シード側のエントリが優先されます。extraKnownMarketplaces や enabledPlugins がシードに既に存在するマーケットプレイスを宣言していても、Claude Codeはクローンし直さずシード側のコピーをそのまま使います。コンテナへの事前展開の具体的な手順はプラグインをコンテナへ事前展開する手順にまとめています。

strict フィールドと strictKnownMarketplaces を混同していないかも確認しておくべき点です。前者はプラグイン1つの中で定義の権威をどちらに置くかを決める設定で、後者は組織全体でどのマーケットプレイスを追加してよいかを絞る設定です。この2つの違いはマーケットプレイスのstrict modeとvalidateの使い方で扱っています。GitHub Enterprise Server上で運用している場合の許可リスト設計はGHESプラグインマーケットプレイスを許可リストで運用するが参考になります。

まとめ

extraKnownMarketplaces はマーケットプレイスを自動登録してチームに配る設定で、strictKnownMarketplaces は組織としてどのマーケットプレイスを許可するかを絞る設定です。片方だけでは「配る」と「絞る」の一方しか実現できないため、社内マーケットプレイスを全員に強制したい場合はmanaged-settings.jsonで両方を組み合わせます。設定を書く前に、プロジェクト設定ならワークスペースの信頼ダイアログが前提になること、url 形式は相対パスのプラグインに対応しないこと、autoUpdateの既定値がマーケットプレイスの出所で変わることの3点を押さえておくと、配布後の「反映されない」に振り回されずに済みます。マーケットプレイスの作り方全体はClaude Codeプラグイン完全ガイドにまとめています。