Claude Code modが遠隔でoffのまま動かないときの確認と回避策

Claude Code v2.1.287以降はmodが既定でオンのはずなのに、インストールしたmodが何もしない。debugログにthe rollout switch served offと出ているなら、原因は手元の設定ではなく、Anthropic側の段階展開スイッチかもしれません。GitHubのIssue #99130が、この状況を報告しています。

症状: docsは「既定オン」、ログは「rollout switchがoff」

Issueの報告者は、v2.1.288のmacOSでこう書いています。CLAUDE_CODE_PLUGIN_DIRSに登録したhooksモジュール付きプラグインが読み込まれません。マーケットプレイスから入れたコピーでも同じです。

docs側の記述は次のとおりです。modはv2.1.287以降で既定でオンです。早期アクセス中に設定したCLAUDE_CODE_ENABLE_FUNCTION_HOOKSはv2.1.287以降で無視され、0にしてもmodは止まりません。つまり、この環境変数を疑う必要はありません。

debugログ(~/.claude/debug/*.txt)に出た行は、次の2種類です。

どちらの行にもbuilt-in plugins load regardlessと添えられています。組み込みmodはこのスイッチの影響を受けません。docsの組み込みmod一覧でも、cc-plugin-plugin-authoringだけが「Anthropicがインストール済みmodを遠隔で止めていない限り」オンと書かれています。

手元の設定が原因か、遠隔offかを切り分ける

遠隔offを疑う前に、手元で止めている要因を消します。Issueの報告者も、disableAllHooks・ワークスペースの信頼・管理ポリシー・環境変数の4点を確認したうえで、遠隔offと判断しています。

ポリシー側の切り分けはallowManagedModsOnlyの解説、症状別の全体像はmodが動かないときの切り分けにあります。この記事は、その切り分けを通り抜けたあとに残るケースだけを扱います。

claude plugin testでスイッチの状態を確かめる

セッションを開かなくても、mod本体を置いていないディレクトリでclaude plugin testを実行すると、modが読み込める環境かどうかが分かります。

cd ~ && claude plugin test

Issueでは、次のメッセージが報告されています。

claude plugin test: hooks modules are turned off in this process:
the rollout switch was saved off by an earlier session and is not
refreshed yet. Start `claude` once with network access, then run
the tests again; if this message returns, installed mods are turned
off remotely

メッセージの指示は2段です。まずネットワークにつながった状態でclaudeを一度起動し、スイッチの値を更新します。そのうえで同じコマンドを再実行し、メッセージが戻ってくるなら、遠隔offです。報告者は完全に終了して再起動してもメッセージが戻り、遠隔offだと判断しました。

served offとsaved offの違いも覚えておくと便利です。前者はサーバーがその場でoffを返した状態、後者は過去の保存値が使われている状態です。後者は更新されれば直る可能性がありますが、前者は手元で直せません。

報告されているパターン3つ

Issueのコメントには、環境の違う報告者が複数います。同じメッセージでも、原因が同じとは限りません。

3つ目の報告は、サインアウトした状態では動き、サインイン後に止まる点が手がかりです。アカウントに紐づく展開設定が効いている可能性を示しています。

報告されている回避策と、その限界

コメントの1つに、キャッシュされたフラグを消す方法があります。Claude Codeを完全に終了してから、~/.claude.jsonをバックアップし、tengu_plugin_hooks_modulesのキャッシュだけを取り除きます。報告者はmacOSのplutilを使っています。

cp "$HOME/.claude.json" "$HOME/.claude.json.backup.$(date +%s)" &&
plutil -remove cachedGrowthBookFeatures.tengu_plugin_hooks_modules \
  "$HOME/.claude.json"

報告者は、これでmodのコマンドが動き、49件のプラグインテストが通ったと書いています。一方で、次のサーバー更新でフラグがfalseに戻るかは確認していません。本人も一時的な回避策と位置づけています。

ここでの注意点は3つです。

• plutilはmacOSのコマンドです。他のOSで同じキーを消すには、別の手段が要ります
• ~/.claude.jsonにはほかの設定も入っています。バックアップなしの編集は避けます
• サーバーが今offを返している場合(3つ目の報告)は、キャッシュを消しても次の取得でfalseに戻ります

フラグ取得が止まっていないかを確かめる

遠隔offに見えて、実はフラグ取得が走っていないだけのこともあります。docsは、取得を省く条件を挙げています。

• DISABLE_GROWTHBOOK・DISABLE_TELEMETRY・DO_NOT_TRACK・CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICのいずれかを設定したセッション
• Amazon Bedrock、Google Cloud、Microsoft Foundryなどのサードパーティプロバイダー経由のセッション
• Claude appsゲートウェイのセッション

もう1つの手がかりがプロキシです。v2.1.300の変更履歴に、TLSを検査するプロキシの背後でフラグと段階展開が古いままになる不具合の修正が載っています。対象は、証明書がOSの証明書ストアでだけ信頼されている環境です。プロキシ経由で使っていて、v2.1.300より古いバージョンなら、更新で変わる可能性があります。ただし、Issueにこの修正との関係を示す記述はありません。

待つ間にできること

遠隔offだと分かった場合、手元でできる対処は限られます。

1. claude plugin testのメッセージと、debugログの該当行を控える。/bugで報告するなら、フィードバックIDも添える
2. Issue #99130に、OS・Claude Codeのバージョン・サインイン方法(個人/Team/Enterprise)・プロキシの有無を書き足す。報告の環境が揃うほど、原因の絞り込みが進む
3. --plugin-dirで開発中のmodは、サインアウト状態では動くという報告に基づき、サインインなしのセッションで動作だけ確認する
4. modを使わないと困る業務は、同じ処理をmodではなくsettings hooksで書けないかを検討する(modとの違いはmods overviewの比較表にあります)

mod導入の背景はv2.1.287のリリース解説にあります。modのテストをスタブで回す方法はmodのtestを書く記事で扱っています。plugin testは環境の確認だけでなく、modの検証にも使えます。

Issueは、10月3日に作成されて以降もopenのままで、最後のコメントは10月12日です。Anthropic側の回答はスレッドに付いていません。docsは組み込みmodの説明で遠隔offの存在を認めていますが、どのアカウントが対象かは書いていません。

要点

遠隔offは、手元の設定をすべて消したうえで、claude plugin testがrollout switchを名指ししたときに初めて疑う原因です。saved offなら更新で直る余地があり、served offなら待つしかありません。回避策のキャッシュ削除は、サーバー側がoffを返している間は効かないと見ておくのが安全です。