Claude Codeプラグインマーケットプレイスを必須化し、自動更新まで設定する

マーケットプレイスの必須化とは何か

結論から書くと、設定は3つで足ります。マーケットプレイスの配布は extraKnownMarketplaces、プラグインの既定有効化は enabledPlugins、自動更新は各エントリの "autoUpdate": true です。ただしGitHubなど外部ソースのプラグインは、各メンバーが claude plugin install <name>@<marketplace> --scope project を一度実行するまで有効になりません。

チーム管理者がプラグインマーケットプレイスを必須化するとは、.claude/settings.json にマーケットプレイスの登録情報を書いておき、メンバーが手動で /plugin marketplace add を実行しなくても自動で使える状態にすることです。前提として、マーケットプレイスの仕組みと個人での追加方法はすでに理解している読者を想定します。本記事はその先、チーム全員に同じマーケットプレイスを配る設定と、バックグラウンドで最新版へ揃える自動更新の設定を扱います。

メンバー側の操作は増えません。リポジトリのフォルダを最初に信頼した時点(workspace trustダイアログの承認)で、.claude/settings.json に書かれたマーケットプレイスが確認プロンプトなしに登録されます。信頼していないフォルダでは、-p での非対話実行も含めて、この設定は警告も出ずに無視されます。「書いたのに反映されない」という問い合わせの最初の切り分けは、この信頼ゲートです。

.claude/settings.json でマーケットプレイスを配布する

必須化の中心は extraKnownMarketplaces キーです。リポジトリ直下の .claude/settings.json に書いてコミットすると、そのリポジトリを開いた全員に効きます。

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

source にはGitHubの owner/repo のほか、任意のgit URL、marketplace.json への直接URL、ローカルパスを指定できます。マーケットプレイス名(この例では company-tools)は任意の文字列で、/plugin install <plugin>@company-tools の形式で参照する際のキーになります。JSONを手で書かない方法もあります。v2.1.285の claude plugin marketplace add --help には、宣言先を選ぶ --scope オプションが載っています。

--scope <scope>      Where to declare the marketplace: user (default),
                     project, or local
--sparse <paths...>  Limit checkout to specific directories via git
                     sparse-checkout (for monorepos). Example: --sparse
                     .claude-plugin plugins

既定は user です。チームに配りたいときは --scope project を付けて実行します。モノレポ内にマーケットプレイスを置く場合は --sparse でチェックアウト範囲を絞れます。

managed settingsを含む複数ファイルの互換性にも注意点があります。v2.1.232以降は extraKnownMarketplaces を additionalMarketplaces と書けますが、古いバージョンはこの別名を無視します。バージョンが混在する環境で使うファイルには、正式名のままにしておきます。

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

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

ここで押さえておきたい挙動があります。v2.1.195以降、extraKnownMarketplaces はマーケットプレイスのカタログを登録するだけで、外部ソース(GitHubリポジトリやnpmパッケージなど)由来のプラグイン本体までは自動インストールしません。プロジェクトの .claude/settings.json だけが有効化しているプラグインは、メンバー自身が claude plugin install を実行するまで「未インストール」の扱いになります。それまでClaude Codeには Plugin "<name>" is enabled in project settings but isn't installed と出るので、各自が claude plugin install <name>@<marketplace> --scope project を実行する、とチームに伝えておくと混乱を防げます。

個人側の逃げ道も知っておく価値があります。プロジェクトが true にしたプラグインは、~/.claude/settings.json で false にしても無効になりません。プロジェクト設定のほうが優先されるためで、手元だけ外すには .claude/settings.local.json に書きます。managed settingsで false にしたプラグインは、どのスコープからも導入できず、マーケットプレイス上でも非表示になります。

配る前に claude plugin validate でマニフェストを検査する

必須化した後に marketplace.json の不備が見つかると、全員に影響します。claude plugin validate <path> は、マーケットプレイスまたはプラグインのマニフェストを検査します。最小構成のマーケットプレイスを作って、v2.1.285で実行した結果です。

claude plugin validate ./mk

Validating marketplace manifest: ./mk/.claude-plugin/marketplace.json
 
⚠ Found 2 warnings:
 
  ❯ description: No marketplace description provided. Adding a description helps users understand what this marketplace offers
  ❯ plugins[0] plugin.json → author: No author information provided. Consider adding author details for plugin attribution
 
✔ Validation passed with warnings

警告が出ても終了コードは0で通ります。--strict を付けると警告もエラー扱いになり、同じ入力で終了コード1、✘ Validation failed (--strict treats warnings as errors) になりました。--json を付ければレポートをJSONで受け取れます。マーケットプレイスのリポジトリ側のCIに claude plugin validate . --strict を置けば、説明文や作者情報の欠けたマニフェストがマージされる前に止まります。

なお、公式マーケットプレイスと同じ名前(claude-plugins-official)にしてもこの検査は通りました。予約名の衝突を検査で防げるかどうかは、確認できていません。

managed settingsでマーケットプレイスの追加を制限する

extraKnownMarketplaces は「配る」ための設定で、ユーザーが自分で別のマーケットプレイスを追加すること自体は止めません。追加できるマーケットプレイスそのものを制限したい場合は、strictKnownMarketplaces をmanaged settingsに書きます。

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/claude-plugins" }
  ]
}

この設定の挙動は、書き方で3通りに分かれます。

許可リストの照合は、追加時だけでなくインストール・更新・再取得・自動更新のたびに、ネットワークやファイルシステムの操作より前に行われます。ポリシー適用前に追加済みだったマーケットプレイスも、次の操作から許可リストに縛られます。

CLIフラグでプラグイン・エージェント・MCPサーバーを一時的にサイドロードする経路(--plugin-dir 等)まで塞ぎたい場合は disableSideloadFlags を、コマンドソース型のプラグイン経由での抜け道まで塞ぎたい場合は disableCommandPluginSources を組み合わせます。strictKnownMarketplaces はプラグインの出所となるマーケットプレイスを見るだけで、許可済みマーケットプレイス内のコマンドソースまでは制限しないためです。

許可リストに書けるソースの型は github / git / url / file / directory に加え、正規表現で照合する hostPattern(社内GitHub EnterpriseやGitLabのホスト全体を1エントリで許可したいとき用)、pathPattern(ローカルディレクトリ配下を許可したいとき用)があります。GitHubの repo フィールドは "acme-corp/*" のようにオーナー名だけを固定したワイルドカードにもでき、その組織配下のリポジトリを丸ごと許可できます。ここで見落としやすいのが、許可リストを設定すると(空配列でも)、.claude-plugin/plugin.json を持つスキルディレクトリ型のプラグイン(@skills-dir)の読み込みまで止まる点です。manifestの無い通常のスキルは影響を受けません。この経路を維持したい場合は、リストに { "source": "skills-dir" } を明示的に加える必要があります。社内のGitHub Enterpriseを丸ごと許可する運用は、GHESプラグインマーケットプレイスを許可リストで運用するが詳しいです。

許可リストは、github と git のソースで ref と path まで含めた完全一致で照合します。{ "source": "github", "repo": "acme-corp/plugins" } と、そこに "ref": "main" を足したエントリは別のソースとして扱われます。同じリポジトリでも、ref を固定した形で追加しようとすると許可リストに弾かれます。path も ref と同じく、両側で一致するか、両側とも無い場合だけ一致します。エントリに path を書かずにリポジトリ内の任意の path を通せるのは、"acme-corp/*" のようなオーナー名ワイルドカードのエントリだけです。

逆に「これだけは禁止」と書きたいときは、managed settingsの blockedMarketplaces を使います。書式は strictKnownMarketplaces と同じソースの配列です。照合の癖が違うため、許可リストの感覚で書くと外れます。

自動更新(auto-update)を設定する

Claude Codeはセッション開始後、バックグラウンドでマーケットプレイスと導入済みプラグインの更新を確認できます。対話セッションでは、最初のメッセージを送ってから最大10分のランダムな遅延を挟み、自動更新が有効なマーケットプレイスを再取得して、導入済みプラグインの手元のコピーを更新します。実行中のセッションは読み込み済みのバージョンのままです。更新後は Plugin updated: <name> · Run /reload-plugins to apply と表示され、リロードしなくても次回起動で新しい版が読み込まれます。

既定値は配布元によって違います。claude-plugins-official を含む公式のAnthropicマーケットプレイスの多くは自動更新が有効、サードパーティやローカル開発中のマーケットプレイスは無効です。個々のマーケットプレイスの設定は /plugin を開き、Marketplacesタブから対象を選んで「Enable auto-update」または「Disable auto-update」で切り替えられます。

チーム全体で自動更新を揃えたい場合、メンバーにUIでの切り替えを頼らず、管理者が extraKnownMarketplaces の各エントリに "autoUpdate": true を書く方法があります。設定ファイル側の autoUpdate が判定の最優先で、UIのトグルより先に参照されます。

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

逆に自動更新を止めたい場合は環境変数 DISABLE_AUTOUPDATER=1 を設定します。この変数は本体だけでなくプラグインの更新も止め、/plugin の「Enable auto-update」トグルも隠れます。本体の自動更新だけ止めてプラグインは維持したいときは、FORCE_AUTOUPDATE_PLUGINS=1 を併用します。DISABLE_UPDATES=1 や CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 を設定した場合も、プラグインの更新は止まります。プラグインごとにバージョンを固定したい場合は、Claude Codeプラグインのリリースチャネルとバージョン解決が扱っています。

export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

コマンドソース型のプラグイン(ローカルツールの出力を動的にマーケットプレイスへ取り込む方式)は、この自動更新設定とは別のサイクルで動きます。セッションごとに一度コマンドを再実行し、出力のハッシュが変わっていれば新しいバージョンとしてインストールする仕組みで、DISABLE_AUTOUPDATER の影響を受けません。

プライベートリポジトリをマーケットプレイスに使う場合は、認証まわりに注意点があります。バックグラウンドの確認はgitのクレデンシャルヘルパーを有効のまま使いますが、パスワードの入力は求めません。ヘルパーがすでに資格情報を保持していれば通り、聞き返す必要がある場合は失敗します。GitHubなら gh auth login のあとに gh auth setup-git で保存できます。

新しいコミットを検出した場合や、到達・認証に失敗した場合、Claude Codeはマーケットプレイスを再クローンして既存のチェックアウトと置き換えます。再クローンが失敗しても既存のチェックアウトは残りますが、大きなリポジトリではタイムアウトすることがあります。CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定しておくと、到達・認証に失敗した時点で再クローンを試みず、既存のチェックアウトのまま動き続けます。オフライン環境でも同じ設定が使えます。

自動更新を待たずに今すぐ更新する

自動更新が無効なマーケットプレイスや、次の起動を待てない場面では、手動で更新します。1つのプラグインなら、/plugin のInstalledタブで「Update now」を選ぶか、シェルで claude plugin update <plugin>@<marketplace> を実行します。

全プラグインを一度に更新するコマンドはありません。1つのマーケットプレイス分をまとめて更新するには、/plugin のMarketplacesタブで対象を選び、「Update marketplace」を実行します。

シェルの claude plugin marketplace update は、名前の有無にかかわらずマーケットプレイスの一覧を更新するだけで、導入済みプラグインは更新しません。「marketplace updateを打ったのにプラグインが古いまま」という場合は、この違いが原因です。

CI・コンテナ環境では実行時のクローンを避ける

コンテナイメージや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 plugin disable を使います。シードのマーケットプレイスに対する claude plugin marketplace update <name> や、--scope なしの remove は、シードのディレクトリ名を示して失敗します。許可リストはシードの記録済みソースも照合するため、シードの元にしたソースは許可しておく必要があります。

正しく読み込まれたかは、イメージ内で claude -p に --output-format stream-json --verbose を付けて確認できます。init イベントの plugins リストで、各プラグインの path がシード配下になっていれば成功です。

使い分け早見表

チーム管理に関わる設定は名前が似ていて混同しやすいため、目的別に分けて示します。

複数の設定ファイルで同じ名前のマーケットプレイスを定義した場合、優先度の高いファイル(managed > local > project > user)のエントリが丸ごと使われ、低い優先度のエントリからフィールドを引き継ぐことはありません。v2.1.228より前はフィールド単位でマージしていたため、あるファイルの source.headers の資格情報と別ファイルのURLが意図せず組み合わさることがありましたが、現在は上書きに統一されています。

よくあるつまずき

まとめ

配るだけなら extraKnownMarketplaces、追加できるソースを縛るならmanaged settingsの strictKnownMarketplaces と、目的で使う場所が分かれます。両方を書く場合は、許可リストに自動登録するソースを含めます。自動更新は既定がマーケットプレイスの出所で違うので、公式以外まで揃えたいときだけ autoUpdate: true を明示します。settings.json全体の構成はsettings.json完全ガイドから見直せます。