◉CLAUDE LABEN
●CC 2.1.328 — Claude Code 2.1.328(11/19)で、予約タスクを保存したときにほかのタスクが消えることがある問題が直りました●SONNET 4.5 — Claude API での提供終了は 11/30、残り10日。コードと保存済みのモデル設定を一度に洗い出してください●USAGE — 11/9 の週から、使用量の上限が以前の3〜5倍の速さで尽きる、という報告が出ています●NEW — Claude Code と Gemini CLI の MCP 設定は一つの正本から●GEMINI API — Gemini API にも、道具の定義を必要なときだけ読み込む tool retrieval(Preview)が入りました●CREDIT — Credit balance が足りないと出たら、まずどの請求先の残高かを確かめると早く片づきます●CC 2.1.328 — Claude Code 2.1.328(11/19)で、予約タスクを保存したときにほかのタスクが消えることがある問題が直りました●SONNET 4.5 — Claude API での提供終了は 11/30、残り10日。コードと保存済みのモデル設定を一度に洗い出してください●USAGE — 11/9 の週から、使用量の上限が以前の3〜5倍の速さで尽きる、という報告が出ています●NEW — Claude Code と Gemini CLI の MCP 設定は一つの正本から●GEMINI API — Gemini API にも、道具の定義を必要なときだけ読み込む tool retrieval(Preview)が入りました●CREDIT — Credit balance が足りないと出たら、まずどの請求先の残高かを確かめると早く片づきます
記事一覧/Claude Code
⟐ Claude Code/2026-08-22中級

Claude Code の headersHelper に移したら、プロジェクト配下のカタログだけ認証が通らなくなりました

自前のプラグインカタログを headersHelper へ移す途中で、ユーザースコープでは動くヘルパーがプロジェクト配下だけ落ちました。原因は認証情報の非継承です。動くヘルパー2種と実測した実行コスト、無人実行での注意点をまとめました。

Claude Code290プラグイン8マーケットプレイス認証9個人開発131

✦ プレミアム記事

その週は、朝いちばんに届く無人タスクの失敗通知が3回続きました。原因はどれも同じで、自分用のプラグインカタログを置いている private リポジトリのトークンが失効していたことでした。

個人開発者として、私はアプリ側とサイト側で共通のスキルとプラグインを使っており、それらを private リポジトリにまとめて、複数のマシンとプロジェクトから取得しています。トークンは設定ファイルに直接書いていました。ローテーションのたびに置き場所を思い出し、書き換え、書き換え漏れに気づくのはいつも無人タスクが落ちた翌朝、という運用です。

2026年8月の Claude Code v2.1.238 でプラグインマーケットプレイスに headersHelper が入り、この形をやめられるようになりました。カタログを取りに行くたびに HTTP ヘッダを生成するコマンドを走らせられるので、短命トークンを都度発行して渡せます。

移行そのものは30分ほどで終わるはずでした。実際には、ユーザースコープに置いたヘルパーは問題なく動くのに、プロジェクト配下に置いた途端に認証が通らなくなり、そこで半日溶かしています。原因が分かってしまえば設計意図として筋が通っているのですが、事前には予想していませんでした。

この記事は、2026年11月時点の公式ドキュメント(marketplace reference・host a marketplace・MCP・CLI リファレンス)を読み直したうえで書き改めています。読み直してみると、当時の私の理解には小さな誤りが二つ混ざっていました。その訂正も本文に残しておきます——同じところで迷っている方がいるかもしれないと思うからです。

設定ファイルにトークンを書いていた頃、何が面倒だったのか

private リポジトリのカタログを使う構成では、カタログの JSON を取得するときと、そこから参照されるアーカイブを取得するときの両方に認証が要ります。従来はここに固定トークンを置いていました。

固定トークンの面倒さは、失効そのものよりも「失効に気づく経路が事故だけ」という点にあります。有効期限の長いトークンは、切れるまで何の兆候も出しません。切れた瞬間に、複数のマシンで、複数のプロジェクトが、同時に取得へ失敗します。

さらに、リポジトリに置く設定ファイルにトークンを書くと、そのファイル自体が持ち出しの対象になります。個人開発者ひとりで回している規模でも、.mcp.json のようなプロジェクト直下のファイルを git 管理から外し忘れる事故は起こり得ます。

headersHelper は、この2つをまとめて構造で解こうとしています。

headersHelper が実際に置き換えるのはどの部分か

headersHelper は、URL マーケットプレイスの定義とカタログ項目の両方に置けます。指定したコマンドが標準出力に JSON でヘッダを返すと、それがリクエストに乗ります。

置き場所実行されるタイミング主な用途
URL マーケットプレイス(settings の extraKnownMarketplaces などで宣言)marketplace.json の取得と、同一オリジン(スキーム・ホスト・ポートが同じ)のアーカイブ取得の前。1回の出力を最大60秒使い回すカタログ全体を守る
カタログ項目(marketplace.json の各エントリ)そのプラグインを単体で install / update し、表示されたコマンドを承認したときだけ項目ごとに配布元を分ける。archive ソース専用で "strict": false が必須

ここで大事なのは、カタログ項目に置いたヘルパーは黙って走らないということです。claude plugin install や claude plugin update はコマンドの内容を表示したうえで [y/N] を尋ねます。-y を付ければ省略できますが、省略するかどうかを人間が一度決める設計になっています。

無人実行を組んでいる場合、この一点は最初に確認しておいたほうがよいところです。私は最初これを見落とし、無人タスクの経路でインストールが先へ進まないまま朝を迎えました。現行の CLI リファレンスでは、標準入力か標準出力が TTY でないときに -y も --accept-command も付いていなければ、インストールは拒否されて終了コード 1 を返すと書かれています。

あわせて覚えておきたいのが、次の三つの例外です。

  • Claude Code のセッション内(Bash ツールやフック)から実行した -y は無視されます。自分の端末から実行する必要があります
  • 複数プラグインの一括インストール、依存関係としてのインストール、バックグラウンドの自動更新では、項目のヘルパーは走りません。そのプラグインだけが取り残され、/plugin の Errors タブに出ます
  • --accept-command <sha256>(v2.1.271 以降) を使うと、事前に --json で表示されたコマンドだけを承認できます。コマンドやアーカイブ URL が途中で変わっていれば、インストールそのものが拒否されます
✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦自前のプラグインカタログを短命トークン方式へ移すとき、headersHelper をどのスコープに置けば動くのかを迷わず決められるようになります
✦環境変数を前提に書いたヘルパーが「手元では動くのに配ると落ちる」事故を、配布する前に潰せるようになります
✦静的な読み出しと RS256 の都度発行のどちらを選ぶかを、実測した1回あたり5ミリ秒と21ミリ秒という差を根拠に決められるようになります
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

⟐ Claude Code2026-09-20
Pro を払っているのに Console に請求が立っていたとき、私が最初に見た一行
サブスクリプションと API の従量は別会計で、Claude Code はそのどちらでも動きます。どちらが選ばれているかを決めるのは優先順位で、ログインはその最下段です。status の読み方と、無人実行だけが別の答えを返す理由を書き残します。
⟐ Claude Code2026-09-10
plugin.json を1枚置くと、スキルの棚がまとめて外せる単位になります
スキルを用途ごとに色分けしたら、毎日使う一群は全体の5パーセントしかありませんでした。.claude-plugin/plugin.json を1枚置いてフォルダをプラグインに変え、その日に使わない棚をグループごと外せるようにするまでの手順と、途中で二度つまずいた読み込みの規則を書き残します。
⟐ Claude Code2026-09-06
スキルを数えたら42本ありました。うち4本は中身が『移動しました』だけでした
Claude Code v2.1.261 で入った /skill-doctor を入り口に、自分のスキル棚を実際に数えてみました。毎ターン乗るのは説明の1行だけという構造と、名前の重複を素朴な awk で探すと別のスキルまで拾ってしまう落とし穴を、手元で動かした小さなスクリプトとともに書き残します。