Claude Codeプラグインマーケットプレイスの必須化と自動更新設定

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

チーム管理者がプラグインマーケットプレイスを必須化するとは、.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 の形式で参照する際のキーになります。

特定のプラグインを既定で有効にしたい場合は、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はその案内コマンドを表示するので、必須化イコール即インストールではない点をチームに伝えておくと混乱を防げます。

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

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

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

この設定は3段階の挙動を持ちます。キー自体を書かなければ制限なしで誰でも任意のマーケットプレイスを追加できます。空配列 [] を指定すると、公式のAnthropicマーケットプレイスを含めて一切追加できない完全ロックダウンになります。ソースのリストを書くと、それに一致するものだけを許可するアローリストとして働きます。許可リストの照合はマーケットプレイスの追加時だけでなく、追加・インストール・更新・再取得・自動更新のたびにネットワークやファイルシステム操作の前で行われるため、ポリシー適用前に追加済みだったマーケットプレイスも、次の操作からは許可リストに縛られます。

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

許可リストに書けるソースの型は github / git / url / npm / file / directory に加え、正規表現で照合する hostPattern(社内GitHub EnterpriseやGitLabのホスト全体を1エントリで許可したいとき用)、pathPattern(ローカルディレクトリ配下を許可したいとき用)があります。GitHubの repo フィールドは "acme-corp/*" のようにオーナー名だけを固定したワイルドカードにもでき、その組織配下のリポジトリを丸ごと許可できます。ここで見落としやすいのが、許可リストを1件でも設定すると ~/.claude/skills/ に置いた個人スキルをプラグインとして自動読み込みする経路(@skills-dir)まで一緒にブロックされる点です。この経路を維持したい場合は、リストに { "source": "skills-dir" } を明示的に加える必要があります。

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

Claude Codeはセッション開始後、バックグラウンドでマーケットプレイスと導入済みプラグインの更新を確認できます。有効なマーケットプレイスでは、セッション起動から最大10分のランダムな遅延を挟んでチェックが走り、実行中のセッションは起動時に読み込んだバージョンのまま動き続けます。更新があれば /reload-plugins を促す通知が出るか、次回起動時に新しいバージョンが読み込まれます。

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

チーム全体で自動更新を強制したい場合、メンバーにUIでの切り替えを頼らず、管理者が extraKnownMarketplaces の各エントリに "autoUpdate": true を書く方法があります。

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

逆にClaude Code本体とプラグインの両方の自動更新を止めたい場合は環境変数 DISABLE_AUTOUPDATER を設定します。本体の自動更新だけ止めてプラグインの自動更新は維持したいときは、DISABLE_AUTOUPDATER と FORCE_AUTOUPDATE_PLUGINS=1 を組み合わせます。

export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

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

プライベートリポジトリをマーケットプレイスに使う場合は注意点があります。バックグラウンドの自動更新は既定で git pull のクレデンシャルヘルパーを無効化するため、HTTPS経由のプライベートリポジトリは認証に失敗し、Claude Codeはマーケットプレイスを再クローンしてフォールバックします。この再クローンは手元の資格情報を使いますが、リポジトリが大きいとタイムアウトすることがあります。CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定しておくと、バックグラウンド更新の失敗時に既存のクローンを保持し、削除・再クローンを避けられます。

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

コンテナイメージやCI環境では、起動のたびにマーケットプレイスをネットワーク経由でクローンするのは避けたいケースがあります。この場合は環境変数 CLAUDE_CODE_PLUGIN_SEED_DIR でプラグインの事前展開ディレクトリを指定します。イメージのビルド時にClaude Codeを一度起動して必要なプラグインを導入し、生成された ~/.claude/plugins ディレクトリをイメージにコピーして、実行時に CLAUDE_CODE_PLUGIN_SEED_DIR でそのパスを指すだけです。コピー手順自体を省きたい場合は、ビルド時に CLAUDE_CODE_PLUGIN_CACHE_DIR を目的のシード先に設定してからプラグインを導入すれば、直接そこへインストールされます。

シードディレクトリは読み取り専用として扱われ、シードに含まれるマーケットプレイスの自動更新は無効化されます。起動のたびにシード側のエントリがユーザー設定の同名エントリを上書きするため、シード内のプラグインを個別に無効化したい場合は /plugin disable を使い、マーケットプレイス自体を消す操作は避けます。

使い分け早見表

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

extraKnownMarketplaces と strictKnownMarketplaces は役割が異なるので両方をmanaged settingsに書くのが安全な組み合わせです。strictKnownMarketplaces だけを設定した場合、ユーザーは許可された範囲内のマーケットプレイスなら自分で /plugin marketplace add を実行できてしまいます。両方を同じファイルに書くことで、許可と同時に自動登録まで完結させられます。

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

よくあるつまずき

まとめ

チーム管理者がやることは、配布・制限・更新の3つの軸で整理すると迷いにくくなります。まず配布と制限の2つを固め、必要に応じて更新の運用を足していく順番が扱いやすいはずです。プロジェクトの .claude/settings.json に extraKnownMarketplaces を書いてマーケットプレイスを配り、必要なら enabledPlugins で個別プラグインまで既定有効化すること。そしてポリシーとして追加できるソースを絞りたい場合に、managed settingsで strictKnownMarketplaces を設定することです。自動更新は既定挙動を理解したうえで、公式以外のマーケットプレイスまで揃えたいなら autoUpdate: true を明示します。マーケットプレイスの許可リストと合わせて運用したいチームはGHESプラグインマーケットプレイスを許可リストで運用する、配布バージョンをグループ別に固定したいチームはClaude Codeプラグインのリリースチャネルとバージョン解決も合わせて確認すると設計の抜けを防げます。settings.json全体の構成を見直すならsettings.json完全ガイドが起点になります。