Claude Code apiKeyHelperスクリプトが失敗する原因と対処
Claude Codeで「Your apiKeyHelper script is failing」が出る3つの原因と、動くスクリプトの条件、切り分け手順をまとめます。/loginでは直らない理由も扱います。
apiKeyHelperを設定したClaude Codeで「Your apiKeyHelper script is failing」が出たら、原因は3つのどれかです。スクリプトがエラーで終了した、標準出力に何も出さなかった、キー以外の文字列を出力した。/loginを実行しても直らないのがこのエラーの厄介なところで、設定が残っている限りスクリプトの出力が優先され続けます。
「Your apiKeyHelper script is failing」は何が起きているサイン
apiKeyHelperとは、Claude CodeがAPIキーの代わりに実行するコマンドをsettings.jsonで指定する設定です。指定したコマンドの標準出力がそのままAPIキーとして扱われ、モデルへのリクエストにX-Api-KeyとAuthorization: Bearerの両方のヘッダーとして送られます。
このエラーは、指定したコマンドを実行したのに使えるキーが得られなかったときに出ます。ターミナルのAuthenticationパネルに、次のどれが起きたかが表示されます。
- コマンドがエラーで終了したか、タイムアウトした
- 標準出力に何も出さなかった
- キー以外の文字列を出力した(ログイン時のバナーやログ行など)。この場合パネルには
returned output that cannot be used as an API keyと表示され、出力内容そのものは繰り返されません
3つ目のケースは挙動が変わった経緯があります。v2.1.227より前は、コマンドが何を出力しても前後の空白を削っただけでそのままキーとして送信していました。現在はこの時点で弾かれるため、原因の切り分けがしやすくなっています。
エラーが表示されるまでの内部の流れ
Claude Codeはコマンドが失敗すると、その場で諦めずに再実行します。スクリプトを再度呼び出してリクエストをもう2回まで再送し、合計3回の試行以内にこのメッセージを表示します。
この挙動もバージョンで変わっています。v2.1.208より前は、失敗したスクリプトの出力(プレースホルダーの認証情報)をそのまま使ってリクエストを送り続け、リトライの持ち分を使い切ったあとに汎用的な401エラーとして表示していました。スクリプトが原因だと気づきにくい表示だったということです。現在のバージョンでは3回以内に「apiKeyHelperが失敗している」という具体的な原因が出るため、切り分けの初手を間違えにくくなっています。
Authenticationパネルの名称も変わっていて、v2.1.212より前はCloud authenticationという表示でした。古いバージョンのスクリーンショットや社内手順書を参照している場合、パネル名の違いで戸惑うことがあります。
原因を切り分ける3つの手順
まず疑うべきは、Claude Codeの側ではなくスクリプト自身です。3つの手順で、どこで止まっているかが分かります。
# 1. settings.jsonに書いたコマンドを直接実行して、キーだけが出るか確認する
/bin/generate_temp_api_key.shこのコマンドを直接実行して失敗するなら、Claude Codeとは無関係にスクリプト側かその認証情報プロバイダー側の問題です。ボールト(vault)やSSOのセッションが切れていないか、まずここで確認します。
/status/statusは、現在有効な認証情報のソースを表示します。apiKeyHelperが実際に使われているソースかどうかがここで分かります。
v2.1.274以降は、/statusにapiKeyHelperの行がFailingとして出ます。終了コードやコマンドのエラー出力といった直近の失敗内容つきで、次に成功すると行は消えます。v2.1.274より前は認証情報のソースしか表示されませんでした。原因を特定できないまま何度も試すより、まずここを読むほうが早く終わります。
エラー本文は3部構成です。
- Your apiKeyHelper script is failing
- This usually means you need to re-authenticate with your provider
- Run /status to see the script's error output
非対話モードでは、標準エラー出力にapiKeyHelper failed:で始まる具体的な理由も出ます。
settings.json側の設定も見ておく価値があります。ユーザー・プロジェクト・ローカル・管理設定のどこにapiKeyHelperが書かれているかによって、書き換えるべきファイルが変わるためです。設定ファイルの優先順位と全項目はClaude Code settings.json完全ガイドにまとめています。
動くapiKeyHelperスクリプトが満たす条件
修正の的は明確です。スクリプトは次の4条件をすべて満たす必要があります。
- 標準出力にキーだけを出す(ログインメッセージやログ行を混ぜない)
- 出力は印字可能なASCII文字の単一トークン
- 長さは最大16,384文字まで
- 終了コードは0
#!/bin/bash
# 標準出力にキーだけを1行で出す
vault read -field=api_key secret/anthropic#!/bin/bash
# ログインメッセージが標準出力に混ざる
echo "Logging in to vault..." # ← これが原因でエラーになる
vault read -field=api_key secret/anthropicvaultはHashiCorp Vaultのコマンドです。
悪い例のような「余計な1行」は、開発時のデバッグ出力を消し忘れたときによく残ります。ログや進捗表示は標準エラー出力(stderr)に逃がすか、削除します。
OS間のシェルの違いに注意する
条件を満たしているつもりでも、Claude Codeから呼ばれたときだけ失敗することがあります。原因になりやすいのはシェルの違いです。apiKeyHelperはmacOS・Linuxでは/bin/sh、Windowsではcmd経由で実行されます。普段の開発で使っているzshやPowerShellのプロファイルに依存したパスや関数を前提にスクリプトを書くと、Claude Codeから呼ばれたときだけ失敗します。クロスプラットフォームで配る場合は、シェル固有の機能を避けた素朴なコマンド1行に絞るのが安全です。スクリプトを直接実行すると成功するのにClaude Code経由だと失敗する場合は、まずこの違いを疑います。
リフレッシュ間隔と表示タイミングを理解する
apiKeyHelperは毎回のリクエストで呼ばれるわけではありません。既定では5分ごと、またはAPIへのリクエストが401か403を返したタイミングで再実行されます。v2.1.246以降は、キャッシュ済みの出力が発行後に期限切れになったJWTの場合、送信前にも再実行されます。後半の2つは、ヘルパーの出力が送信する認証情報で、ANTHROPIC_AUTH_TOKENが未設定のときに限られます。この間隔はCLAUDE_CODE_API_KEY_HELPER_TTL_MS環境変数で変更できます。頻繁に失敗が起きる環境で間隔を調整したい場合はここを触ります。
スクリプトの実行に10秒以上かかると、プロンプトバーに経過時間つきの警告が表示されます。エラーにはなりませんが、頻繁に出るなら認証情報プロバイダー側のレスポンスが遅いサインです。
apiKeyHelperを含む認証情報系の設定は、Claude Codeが設定ファイルの変更を監視しているため、settings.jsonを書き換えれば再起動なしで反映されます。変更のたびにConfigChangeフックが発火する設計です。書き換えた直後にエラーが直っているかをすぐ確認できます。
apiKeyHelperと他の認証方式の使い分け
複数の認証方式を比較すると、apiKeyHelperが向く場面がはっきりします。
| 方式 | 向くケース | 更新の仕組み | 適用範囲 |
|---|---|---|---|
ANTHROPIC_API_KEY | 向くケース個人開発で固定キーを使う | 更新の仕組み手動でローテーション | 適用範囲CLI + VS Code拡張・Agent SDK・GitHub Actions |
apiKeyHelper | 向くケースボールト連携・短命トークン | 更新の仕組みスクリプトが自動更新(既定5分) | 適用範囲CLI + 同上(Desktop・クラウドセッションは対象外) |
CLAUDE_CODE_OAUTH_TOKEN | 向くケースCI・ヘッドレス環境 | 更新の仕組みclaude setup-tokenで再発行(1年有効) | 適用範囲bare modeでは非対応 |
/loginのサブスクリプション | 向くケース個人の対話利用 | 更新の仕組みブラウザーで都度再認証 | 適用範囲全形態 |
apiKeyHelperとANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKENは、CLIとそれをラップする面(VS Code拡張・Agent SDK・GitHub Actions)に適用されます。Claude Desktopとクラウドセッションはこれらを読まず、OAuthで認証します。例外は、サードパーティの推論設定を使うDesktopセッションで、その設定固有の認証情報を使います。Desktopでボールト連携のキーを使うつもりでapiKeyHelperを設定しても、期待どおりには動きません。
優先順位の全体では、apiKeyHelperはクラウドプロバイダー認証情報・ANTHROPIC_AUTH_TOKEN・ANTHROPIC_API_KEYの下、CLAUDE_CODE_OAUTH_TOKENとサブスクリプションログインの上に位置します。ログイン方式全体の優先順位はClaude Codeログイン方法3種の使い分けで扱っています。
バージョンで変わった挙動のまとめ
同じ原因でも、使っているバージョンによって画面に出るメッセージが違います。
| バージョン | 変更前 | 変更後 |
|---|---|---|
| v2.1.208 | 変更前全リトライを使い切ってから汎用的な401を表示 | 変更後3回以内にapiKeyHelper固有のエラーを表示 |
| v2.1.212 | 変更前パネル名がCloud authentication | 変更後パネル名がAuthentication |
| v2.1.227 | 変更前出力を空白トリムしてそのまま送信 | 変更後余計な出力を検知して弾く |
| v2.1.274 | 変更前/statusは認証情報のソースだけを表示 | 変更後Failing行に直近の失敗内容(終了コード・エラー出力)を表示 |
古い挙動を前提にした社内ドキュメントやトラブルシュートの手順が残っている場合、現在のバージョンでは症状の出方が違う可能性があります。アップデートの手順はClaude Codeアップデートの方法にまとめています。
よくある質問
エラーは出ないのに、モデルへのリクエストが401で拒否されます
apiKeyHelper自体は成功していて、返したキーをAPI側が拒否しているケースです。この場合はapiKeyHelperスクリプトの失敗ではなくInvalid API keyとして表示されます。両者はメッセージの文言で区別できるので、実際に出ている文言を確認してください。
管理者が配布した設定でapiKeyHelperを止められますか
ユーザー側からは止められません。管理設定(managed settings)でapiKeyHelperを配布している組織では、ユーザー側のsettings.jsonを書き換えても上書きされません。組織の設定ファイル配布経路はClaude Code組織管理ガイドで扱っています。
CLAUDE_CODE_API_KEY_HELPER_TTL_MSはどのくらいの値にすべきですか
スクリプトが返すトークンの有効期限が既定の5分より短い場合に、有効期限より短い値にします。10分で失効するトークンなら、既定のままで失効前に取り直されます。JWTなら、v2.1.246以降は期限切れを送信前に検知して再実行されます。短くするほど、スクリプトの実行回数は増えます。
まとめ
「Your apiKeyHelper script is failing」は、指定したコマンドがエラー終了・無出力・余計な出力のいずれかを返したときに出ます。/statusとスクリプトの直接実行で原因を切り分け、標準出力にキーだけを単一トークンで返し終了コード0で終わる形に直すのが対処です。/loginはこのエラーの解決策にはならず、設定が残っている限りスクリプトの出力が優先され続けます。バージョンによって表示されるメッセージやパネル名が違うため、古い手順書を参照している場合は現在のバージョンでの挙動をあわせて確認してください。