その週は、朝いちばんに届く無人タスクの失敗通知が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 でヘッダを返すと、それがリクエストに乗ります。
ここで大事なのは、カタログ項目に置いたヘルパーは黙って走らない ということです。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 が途中で変わっていれば、インストールそのものが拒否されます
ヘルパーに課される条件(2026年11月時点の公式仕様)
ヘルパーは何を書いてもよいわけではありません。公式ドキュメントにある条件を、私が実際に引っかかりやすいと感じた順に並べ直しました。
カタログ項目にヘルパーを置くときの最小形は次のとおりです。sha256 を省くと claude plugin validate が警告を出すので、私はピン留めまでを一組として書いています。
{
"name" : "my-shared-skills" ,
"description" : "Shared skills for app and site work" ,
"strict" : false ,
"source" : {
"source" : "archive" ,
"url" : "https://catalog.example.com/plugins/my-shared-skills-1.4.0.zip" ,
"sha256" : "<zip の SHA-256>"
},
"headersHelper" : "/Users/me/bin/headers-store.sh"
}
headersHelper に絶対パスを書いているのは、作業ディレクトリが設定ディレクトリになるためです。./headers-store.sh と書くと、プロジェクトではなく ~/.claude の中を探しに行きます。
半日溶かした原因は「認証情報を継承しない」でした
ユーザースコープに置いたヘルパーは動くのに、プロジェクト配下に置くと落ちます。最初は信頼ダイアログの問題だと思い込んで、そちらばかり見ていました。
実際の原因は別のところにありました。リポジトリやプラグインが持ち込む headersHelper は、認証情報らしい名前の環境変数を取り除いた状態で実行されます 。公式ドキュメントによれば、名前に TOKEN・SECRET・PASSWORD・KEY・AUTH を含む変数(大文字小文字を問わない)と、ANTHROPIC_CUSTOM_HEADERS などの決まった一覧が対象です。
対象になる置き場所は、マーケットプレイス用と MCP 用とで少しずつ違います。
マーケットプレイス用 : marketplace.json の項目、プロジェクトの .claude/settings.json・.claude/settings.local.json に書いたものは取り除かれます。ユーザー設定・--settings のファイル・managed 設定に書いたものは取り除かれません
MCP 用 : プロジェクトの .mcp.json、プラグイン、プロジェクトか --add-dir のエージェントファイルに書いたインラインサーバーは取り除かれます。ユーザー/ローカルスコープ、managed MCP、claude.ai のコネクタは取り除かれません
つまり「リポジトリに置かれた設定ファイルが、手元の鍵を持ったまま外部へ出ていく」経路をあらかじめ塞いでいるわけです。設計としては納得できます。ただ、環境変数からトークンを読む素朴なヘルパーを書いていると、この違いはユーザースコープで試している限り絶対に表面化しません 。
手元で挙動を確かめるために、環境変数を落とした状態で同じスクリプトを走らせてみました。
# 環境変数からトークンを読む素朴なヘルパー
cat << 'EOF' > headers-env.sh
#!/usr/bin/env bash
set -euo pipefail
: "${CATALOG_TOKEN:?CATALOG_TOKEN is not set}"
printf '{"Authorization":"Bearer %s"}\n' "$CATALOG_TOKEN"
EOF
chmod +x headers-env.sh
# (1) 手元の環境で実行 — 通る
CATALOG_TOKEN = demo123 ./headers-env.sh
# => {"Authorization":"Bearer demo123"}
# (2) 継承環境を落として実行 — プロジェクト由来ヘルパーの近似
env -i HOME=" $HOME " PATH=" $PATH " ./headers-env.sh ; echo "exit= $? "
# => headers-env.sh: line 3: CATALOG_TOKEN: CATALOG_TOKEN is not set
# => exit=1
env -i で継承環境を落とすと、同じスクリプトが exit=1 で落ちます。私の手元では実際にこの通りになりました。プロジェクト配下に置いたヘルパーの失敗と症状が一致したところで、ようやく原因にたどり着いています。
ここで一つ訂正があります。当時の私は「環境変数がまるごと消える」と理解していましたが、公式の説明は上のとおり名前による選別です。env -i は実際より厳しい近似で、これを通れば本番でも通る、という十分条件として使うのが正確です。本番の挙動に近づけて確かめたいときは、名前で落とすほうが手触りが近くなります。
# 認証情報らしい名前の変数だけを落として実行する(公式の規則の近似)
run_like_project_scope () {
local keep = ()
while IFS = '=' read -r name _ ; do
case " $name " in
* [Tt][Oo][Kk][Ee][Nn] *|* [Ss][Ee][Cc][Rr][Ee][Tt] *|* [Pp][Aa][Ss][Ss][Ww][Oo][Rr][Dd] *|* [Kk][Ee][Yy] *|* [Aa][Uu][Tt][Hh] * ) ;;
*) keep += ( " $name =${ ! name }" ) ;;
esac
done < <( env | grep -E '^[A-Za-z_][A-Za-z0-9_]*=')
( cd "${ CLAUDE_CONFIG_DIR :- $HOME / . claude }" && env -i "${ keep [ @ ]}" " $@ " )
}
CATALOG_TOKEN = demo123 run_like_project_scope " $PWD /headers-env.sh" ; echo "exit= $? "
# => CATALOG_TOKEN: CATALOG_TOKEN is not set
# => exit=1
作業ディレクトリを設定ディレクトリへ移しているのは、本番の実行条件に合わせるためです。ヘルパーの中に相対パスが残っていると、この時点で気づけます。
配布前にこの1行を通しておけば、半日は使わずに済みました。ヘルパーを書いたら、まず継承環境なしで走ることを確かめます。これが今回いちばん高くついた学びです。
鍵はヘルパーが自分で取りに行き、呼び出し元からは何も受け取らない前提で書く。 いまはこの線引きを、マーケットプレイス用にも MCP 用にも同じように当てはめています。
資格情報の取り出しをヘルパーの外へ出す
対処は単純で、環境変数に依存するのをやめ、ヘルパー自身が資格情報ストアから取り出す形にします。
cat << 'EOF' > headers-store.sh
#!/usr/bin/env bash
set -euo pipefail
# 環境変数ではなく、ヘルパー自身がストアから取り出す
TOKEN=""
# macOS のキーチェーンがあればそちらを優先
if command -v security >/dev/null 2>&1; then
TOKEN="$(security find-generic-password -a "$USER" -s claude-catalog -w 2>/dev/null || true)"
fi
# 手元にキーチェーンがない環境(CI・コンテナ)向けのフォールバック
if [ -z "$TOKEN" ]; then
STORE="${HOME}/.config/claude-catalog/token"
TOKEN="$(cat "$STORE" 2>/dev/null || true)"
fi
if [ -z "$TOKEN" ]; then
echo "catalog token not found (keychain / ~/.config/claude-catalog/token)" >&2
exit 1
fi
printf '{"Authorization":"Bearer %s"}\n' "$TOKEN"
EOF
chmod +x headers-store.sh
# 継承環境なしでも通ることを確認する
env -i HOME=" $HOME " PATH=" $PATH " ./headers-store.sh ; echo "exit= $? "
# => {"Authorization":"Bearer ..."}
# => exit=0
フォールバックのファイルには chmod 600 を掛けておきます。標準エラーへ出すメッセージに、探した場所を書いておくのも地味に効きます。失敗したときにヘルパーが黙って空を返すと、呼び出し側からは「認証に失敗した」としか見えず、原因の切り分けに時間がかかるためです。
なお、ここで command -v security を使って分岐しているのは、同じヘルパーを macOS の手元とコンテナの両方で使い回したかったからです。分岐せずにキーチェーン専用で書くと、コンテナ側で毎回書き換える羽目になります。
短命トークンを都度発行する形にする
固定トークンをストアに置き換えただけでは、失効の痛みは減っても寿命の問題は残ります。カタログの取得ごとにヘルパーが走るのですから、そこで短命の資格情報を発行してしまうほうが素直です。
手元のリポジトリ配布用に組んだのは、鍵で署名した5分間有効の JWT を毎回作る形です。
cat << 'EOF' > headers-jwt.sh
#!/usr/bin/env bash
set -euo pipefail
KEY="${CATALOG_SIGNING_KEY:-$HOME/.config/claude-catalog/key.pem}"
[ -f "$KEY" ] || { echo "signing key not found: $KEY" >&2; exit 1; }
b64() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
NOW=$(date +%s)
HEADER=$(printf '{"alg":"RS256","typ":"JWT"}' | b64)
PAYLOAD=$(printf '{"iss":"catalog-client","exp":%d}' $((NOW + 300)) | b64)
SIG=$(printf '%s.%s' "$HEADER" "$PAYLOAD" | openssl dgst -sha256 -sign "$KEY" | b64)
printf '{"Authorization":"Bearer %s.%s.%s"}\n' "$HEADER" "$PAYLOAD" "$SIG"
EOF
chmod +x headers-jwt.sh
exp を300秒にしているのは、カタログ取得とアーカイブ取得が連続で走ることを見込んでいるためです。ここを短くしすぎると、取得の途中で切れます。
署名鍵のパスを CATALOG_SIGNING_KEY で上書きできるようにしていますが、既定値をホーム配下の固定パスにしている点が肝心です。前節の理由から、環境変数が渡ってこない前提で既定値だけで動く必要があります。
しかもこの変数名には KEY が含まれているので、プロジェクトの設定や marketplace.json から呼ばれたときは、値を入れていても必ず取り除かれます。上書きが効くのはユーザー設定から呼ぶ場合だけです。名前を変えて逃がすこともできますが、私は「上書きは手元の検証用、本番は既定パス」と割り切りました。秘密の置き場所を変数名の工夫で守ろうとすると、いずれ自分が混乱すると感じたからです。
実行コストを測ってから、どちらを使うか決める
ヘルパーは取得のたびに走ります。プラグインが増えるほど回数も増えるので、実行コストを一度測っておくと判断が楽になります。手元の Linux コンテナ(openssl 3 系)で、それぞれ20回ずつ実行した結果です。
差は1回あたり16ミリ秒ほどです。プラグインを数十個抱えていても、体感に出る規模ではありませんでした。URL ソースのヘルパーは1回の出力を最大60秒使い回すため、実際の実行回数は取得回数より少なくなります。私が事前に警戒していたのは署名コストのほうでしたが、実際に効いてきたのは別の要素です。
外部サービスへ問い合わせてトークンを発行する形にすると、ここにネットワーク往復が丸ごと乗ります。取得のたびに走る場所なので、往復が入ると桁が変わります。しかもヘルパーには10秒の上限があり、発行サービスが遅い日はカタログの取得そのものが止まります。手元で署名して済ませられるなら、そちらを選んでおくほうが安全だと感じました。
判断の目安は次のように置いています。
配布先が自分と手元のマシンだけなら、ストアからの静的読み出しで十分です
配布先が増える、あるいは取り消しを効かせたいなら、手元署名の短命トークンにします
外部の発行サービスを噛ませるのは、取り消しの即時性がどうしても要る場合に限ります
どのスコープのヘルパーが実際に応答したのかを知りたい場面もあります。ヘルパーの標準出力は取得処理がそのまま解釈するので、デバッグ用の出力を混ぜると壊れます。書き足すなら標準エラーの側です。
# 標準出力は JSON のみ。手がかりは標準エラーへ回す
echo "[headers-store] plugin=${ CLAUDE_CODE_PLUGIN_NAME :- none } marketplace=${ CLAUDE_CODE_MARKETPLACE_NAME :- none } url=${ CLAUDE_CODE_MARKETPLACE_URL :- ${ CLAUDE_CODE_PLUGIN_ARCHIVE_URL :- none }}" >&2
ここが二つ目の訂正です。以前の版では $PWD を出して起動場所からスコープを見分けていましたが、公式ドキュメントを読み直すと、ヘルパーの作業ディレクトリはどこから呼ばれても設定ディレクトリでした。$PWD を見ても毎回同じ値が出るだけで、スコープの判別には使えません。私がそれで納得していたのは、たまたまユーザースコープでしか試していなかったからなのだと思います。
代わりに、Claude Code が渡す変数を出します。CLAUDE_CODE_PLUGIN_NAME が入っていればカタログ項目から、CLAUDE_CODE_MARKETPLACE_URL が入っていれば URL ソースから呼ばれたと分かります。追加したばかりのマーケットプレイスの最初の取得では CLAUDE_CODE_MARKETPLACE_NAME が空になるので、空でも慌てなくて大丈夫です。トークンそのものを標準エラーへ出さないことだけは守ってください。ログに残ります。
信頼ダイアログの承認が前提になった点
もう1つ、無人実行を組んでいる場合に効いてくる変更があります。プロジェクトの .mcp.json に置いた headersHelper と、プロジェクトや --add-dir のエージェントファイルに書いたインライン MCP サーバーは、そのフォルダの信頼ダイアログを承認済みであることが条件 になりました。マーケットプレイス側も同じで、プロジェクトの .claude/settings.json に書いた URL ソースのヘルパーは、そのフォルダ自身の信頼を承認するまで走りません。
claude -p でも条件は同じですが、ここに落とし穴があります。-p や SDK のセッションは、信頼の承認としては数えられません。親フォルダを信頼していても数えられません。承認がないあいだ、MCP は静的な headers だけで接続し、claude -p では headersHelper not run という行がサーバーごとに標準エラーへ出ます。
私の手元では、CI 用に新しく切ったチェックアウト先で最初の1回だけ引っかかりました。人が一度承認すれば以降は通るので、恒久的な障害にはなりません。ただ、フォルダを毎回作り直す構成にしていると、毎回引っかかります。
対処としては、作業用のチェックアウト先を固定パスに寄せました。フォルダを使い捨てる設計と、フォルダ単位の信頼という前提は噛み合いません。ここは実行環境側を合わせにいくのが早いと判断しています。
ダイアログを出せない環境のために、公式には ~/.claude.json の projects["<path>"].hasTrustDialogAccepted を true にする方法も書かれています。私はこれを使うのは固定パスのチェックアウト先だけにしています。使い捨てのフォルダに毎回書き込む仕組みを組むと、信頼という仕組みそのものを素通りさせることになるからです。また、--add-dir で足したディレクトリの設定に書いたヘルパーは、承認とは関係なく無視されます。
この表を最初に持っていたら、私は半日を使わずに済みました。スコープごとに前提が違うという一点さえ押さえておけば、切り分けは数分で終わります。
症状から逆引きする切り分け表
半日を溶かしたあと、同じ症状に出会ったときに上から順に見る表を作りました。左の症状に当てはまる行から確かめていただければと思います。
よくある誤解
誤解1: 「headersHelper の中では環境変数がすべて消える」 。実際に取り除かれるのは、認証情報らしい名前の変数と決まった一覧だけです。PATH や HOME は残ります。ただ、残るからといって設計を変数に頼る理由にはならない、というのが私の考えです。
誤解2: 「$PWD を見ればどのスコープから呼ばれたか分かる」 。作業ディレクトリは常に ~/.claude(または CLAUDE_CONFIG_DIR)です。見分けるなら CLAUDE_CODE_PLUGIN_NAME や CLAUDE_CODE_MARKETPLACE_URL を使います。私自身、ここを長く誤解しておりました。
誤解3: 「claude -p で一度通れば、そのフォルダは信頼済みになる」 。-p や SDK のセッションは信頼の承認として数えられません。人がダイアログで承認するか、~/.claude.json に明示するかのどちらかが必要です。
次に詰まりやすいところ
ヘルパーが動いたあとに当たりやすいのは、アーカイブの sha256 が再ビルドのたびに変わってピン留めが壊れる問題です。同じコミットから作った zip でもハッシュが揃わない理由と直し方は、zip の SHA-256 を安定させる正規化 にまとめています。
信頼をリポジトリ側の設定で持つか、環境側の登録に寄せるかで迷ったら、リポジトリの allow を信じるか、環境側の信頼登録に寄せるか が判断の助けになるかもしれません。夜間の claude -p でキーチェーンからの読み出しが失敗する場合は、sleep とキーチェーンを切り分ける事前確認 を先に通しておくと、ヘルパーの問題と取り違えずに済みます。
次にやること
もし自分用のカタログを private リポジトリに置いていて、トークンを設定ファイルに直接書いているなら、まずヘルパーを1本だけ書いて env -i HOME="$HOME" PATH="$PATH" ./headers-store.sh を通してみていただければと思います。ここが通れば、変数の取り除きについてはどのスコープに置いても困りません。通らなければ、環境変数に依存している箇所がどこかに残っています。
移行そのものより、この確認を先に済ませておくことのほうが効きます。私自身、順番を逆にしたせいで半日を落としました。同じ穴を踏まずに済む方がいれば嬉しく思います。