Your apiKeyHelper script is failing
鍵を返すはずのコマンドが失敗したか、何も出力しなかった状態。標準エラーの1行で、どちらかが分かる。
エラー文字列
Your apiKeyHelper script is failing
⚠️ 標準出力に出ます。終了コードは 1 です。 原因は標準エラーに別の1行で出ます。
実際には1行でこう出ます。
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
何が起きているか
settings.json の apiKeyHelper は、API キーを出力するコマンドを指定する設定です。
Claude Code はこれを実行し、出力された値を鍵として使います。
そのコマンドが失敗したか、何も出力しませんでした。
⭐ 標準エラーを見れば、どちらかが分かります。 v2.1.283 で実測した結果です。
apiKeyHelper の中身 |
標準エラーに出た行 |
|---|---|
| 終了コード 1 で終わる | apiKeyHelper failed: exited 1 |
| 何も出力せず、終了コード 0 で終わる | apiKeyHelper failed: did not return a value |
| 存在しないコマンド | apiKeyHelper failed: exited 1: '...' は、内部コマンドまたは外部コマンド… |
| 改行を含む値を出力する（例: 2行に分けて出す） | apiKeyHelper failed: returned output that cannot be used as an API key: it contains a line break at character 10 (14 characters on 2 lines). The script must print only the key to stdout. |
⚠️ どの場合も、同じ行が3回出ました。3回試してから諦めています。
🔴 Windows では cmd.exe で実行される
存在しないコマンドを指定したとき、エラーの文面は cmd.exe のもの（「内部コマンドまたは外部コマンド、操作可能なプログラム…」）でした。
⚠️ bash 向けに書いたスクリプトは、そのままでは動きません。
./get-key.sh のような指定は、Windows では cmd.exe が解釈します。
⚠️ claude auth status では見分けられない
ヘルパーが失敗する状態でも、claude auth status は "loggedIn": true を返しました（終了コード 0）。
{
"loggedIn": true,
"authMethod": "api_key_helper",
"apiKeySource": "apiKeyHelper"
}
「ヘルパーが設定されているか」を見ているだけで、実行はしていません。
直し方
1. ヘルパーを自分で実行してみる
settings.json に書いたそのままの文字列を、同じ種類のシェルで実行します。
Windows — cmd.exe で実行されるので、cmd で試します。
cmd /c "ここに apiKeyHelper の中身" ; "終了コード: $LASTEXITCODE"
macOS / Linux
sh -c 'ここに apiKeyHelper の中身'; echo "終了コード: $?"
⭐ 確かめるのは2点だけです。
| 見るもの | 正しい状態 |
|---|---|
| 終了コード | 0 |
| 標準出力 | 鍵が1行出る（🔴 余計な行を出すと、上の returned output that cannot be used になる） |
⚠️ 鍵を画面に出したくない場合は、出力の長さだけを見てください。
2. どの設定ファイルに書かれているか確認する
apiKeyHelper は、ユーザー設定とプロジェクト設定のどちらにも書けます。
| 場所 | ファイル |
|---|---|
| ユーザー | ~/.claude/settings.json |
| プロジェクト | .claude/settings.json / .claude/settings.local.json |
⚠️ 自分で書いた覚えが無いなら、プロジェクト側を見てください。
v2.1.283 で、プロジェクトの .claude/settings.json と .claude/settings.local.json に書いたヘルパーは、
どちらも claude -p で実行されました。リポジトリに含まれていた設定が効いていることがあります。
3. 🔴 鍵が拒否される場合は、すぐには終わらない
ヘルパーが動いてはいるが、無効な鍵を返す場合は、このエラーにはなりません。
v2.1.283 で、無効な鍵を返すヘルパーを使って claude -p を実行したところ、
2分半たっても何も出力されず終わりませんでした。
さらに ANTHROPIC_API_KEY も置いた状態では、ヘルパーが11回呼び直され、終わるまで約3分半かかりました。
CI では処理全体に時間の上限を付けてください。固まったように見えても、原因は認証です。
再発防止
- ヘルパーを変えたら、
settings.jsonに書く前に単体で実行し、終了コード 0 と鍵1行を確かめる - Windows では cmd.exe が実行することを前提に書く
claude auth statusを事前確認に使わない。ヘルパーを実行していない- CI では
claude -pに時間の上限を付ける。鍵が拒否されると数分間終わらないことがある