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より前は、コマンドが何を出力しても前後の空白を削っただけでそのままキーとして送信していました。バナー付きの出力を送ってしまい、実際のエラーは後段のInvalid API keyとして出ていたということです。現在はこの時点で弾かれるため、原因の切り分けがしやすくなっています。
エラーが表示されるまでの内部の流れ
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が実際に使われているソースかどうかがここで分かり、スクリプトが失敗するたびにその終了コードとエラー出力がAuthenticationパネルに残ります。原因を特定できないまま何度も試すより、まずこのパネルを読むほうが早く終わります。
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/anthropic悪い例のような「余計な1行」は、開発時のデバッグ出力を消し忘れたときによく残ります。ログや進捗表示は標準エラー出力(stderr)に逃がすか、削除します。シェルは/bin/sh(macOS・Linux)またはcmd(Windows)で実行される点も、複数OSで同じスクリプトを配る場合は確認が必要です。
よくある落とし穴
条件を満たしているつもりでも、実際にはまる落とし穴がいくつかあります。
1つ目はOS間のシェルの違いです。apiKeyHelperはmacOS・Linuxでは/bin/sh、Windowsではcmd経由で実行されます。普段の開発で使っているzshやPowerShellのプロファイルに依存したパスや関数を前提にスクリプトを書くと、Claude Codeから呼ばれたときだけ失敗します。クロスプラットフォームで配る場合は、シェル固有の機能を避けた素朴なコマンド1行に絞るのが安全です。
2つ目はトークン末尾の改行です。多くのシークレット管理ツールはechoやprintfの実装差で、値の末尾に意図しない改行文字を付け足します。単一トークンという条件は末尾の改行も含めて厳密なので、printf '%s'のように改行を付けない出力方法へ切り替えると解消することがあります。
3つ目はTTLの設定ミスです。CLAUDE_CODE_API_KEY_HELPER_TTL_MSを極端に短くすると、スクリプトの呼び出し頻度が上がり、認証情報プロバイダー側のレート制限に引っかかってかえって失敗が増えることがあります。頻度を上げる前に、失敗の原因が本当にTTLなのか、それとも別の3原因のどれかなのかをAuthenticationパネルで確認してから調整する順番が無難です。
リフレッシュ間隔と表示タイミングを理解する
apiKeyHelperは毎回のリクエストで呼ばれるわけではありません。既定では5分ごと、または直前のリクエストが401を返したタイミングで再実行されます。この間隔は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 | 変更前出力を空白トリムしてそのまま送信 | 変更後余計な出力を検知して弾く |
古い挙動を前提にした社内ドキュメントやトラブルシュートの手順が残っている場合、現在のバージョンでは症状の出方が違う可能性があります。アップデートの手順はClaude Codeアップデートの方法にまとめています。
よくある質問
スクリプトを直接実行すると成功するのに、Claude Code経由だと失敗します
シェルの違いが原因になりやすいところです。apiKeyHelperは/bin/sh(macOS・Linux)またはcmd(Windows)経由で実行されます。普段使っているシェル(zshやbash)の設定ファイルに依存した環境変数やパスがあると、/bin/sh経由では読み込まれず失敗することがあります。
エラーは出ないのに、モデルへのリクエストが401で拒否されます
apiKeyHelper自体は成功していて、返したキーをAPI側が拒否しているケースです。この場合はapiKeyHelperスクリプトの失敗ではなくInvalid API keyとして表示されます。両者はメッセージの文言で区別できるので、実際に出ている文言を確認してください。
管理者が配布した設定でapiKeyHelperを止められますか
管理設定(managed settings)でapiKeyHelperを配布している組織では、ユーザー側のsettings.jsonを書き換えても上書きされません。組織の設定ファイル配布経路はClaude Code組織管理ガイドで扱っています。
CLAUDE_CODE_API_KEY_HELPER_TTL_MSはどのくらいの値にすべきですか
短命トークンの有効期限より短い値にするのが基本です。ボールト側のトークンが10分で失効するなら、5分より短い間隔に設定しておくと期限切れのまま使い続けるリスクを減らせます。極端に短くすると呼び出し回数が増え、10秒警告が出やすくなる副作用もあります。
まとめ
「Your apiKeyHelper script is failing」は、指定したコマンドがエラー終了・無出力・余計な出力のいずれかを返したときに出ます。/statusとスクリプトの直接実行で原因を切り分け、標準出力にキーだけを単一トークンで返し終了コード0で終わる形に直すのが対処です。/loginはこのエラーの解決策にはならず、設定が残っている限りスクリプトの出力が優先され続けます。バージョンによって表示されるメッセージやパネル名が違うため、古い手順書を参照している場合は現在のバージョンでの挙動をあわせて確認してください。