awsCredentialExportとは — .awsを書き換えずBedrock認証を注入する設定

Claude CodeでAmazon Bedrockを使うとき、認証情報の取得元を.awsディレクトリ以外に切り替えられる設定がawsCredentialExportです。仕組みは単純です。自分で用意したコマンドの標準出力からAWSの一時認証情報を受け取り、Bedrock呼び出し専用のクライアントにだけ適用します。.awsを直接書き換えられない環境や、Bedrock呼び出しだけクロスアカウントの認証情報に切り替えたい場面で使う設定です。

.awsを書き換えられない環境で何が起きるか

Claude Codeは通常、AWS SDKの既定認証チェーンを解決して.awsディレクトリのプロファイルやSSOキャッシュを読みます。解決した認証情報はメモリーに保持され、期限切れの5分前まで、または期限の指定が無ければ1時間、使い回されます(この挙動にはv2.1.207以降が必要です)。認証情報が切れたら、.awsを書き換えるコマンド(aws sso loginなど)をawsAuthRefreshに登録して自動更新するのが標準的な対応です。

問題は、社内の認証基盤が.awsへの書き込みを許さず、代わりに内部APIやスクリプトの出力としてしか一時認証情報を渡せない環境です。この場合awsAuthRefreshは使えません。awsCredentialExportは自分のコマンドを実行し、その標準出力を直接読み込むことで、.awsにまったく触れずに認証情報を渡します。

認証情報の渡し方にはもう一つの選択肢があります。APIキー1本で済む場合はAWS_BEARER_TOKEN_BEDROCKという環境変数だけで足り、スクリプトを書く必要がありません。SSOやクロスアカウントロールのように鍵1本では表現できない認証を、コマンドの出力として渡したいときにawsCredentialExportを使います。

設定の書き方とJSON出力の形式

設定ファイルへの追加はキーとコマンドだけです。

{
  "awsCredentialExport": "/bin/generate_aws_grant.sh"
}

指定したコマンドは、AWSの認証情報をJSONとして標準出力に返す必要があります。受け付ける形式は2種類です。1つはaws stsが返す形にならった、Credentialsでネストした形式です。

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value",
    "Expiration": "2026-01-01T00:00:00Z"
  }
}

もう1つは、aws configure export-credentials --format processが返すフラット形式です。同じキーをネストせずトップレベルに置くだけで、v2.1.181以降で受け付けられます。Expirationは任意項目です。有効なISO 8601形式で返した場合、Claude Codeはv2.1.176以降その時刻の5分前までを認証情報のキャッシュ期間にします。Expirationを返さない場合や、それより前のバージョンでは、キャッシュ期間は1時間固定です。

実務では、独自スクリプトを書かずAWS CLI標準のサブコマンドをそのまま指定できます。クロスアカウントのロールを引き受けたプロファイルの認証情報を、フラット形式でそのまま渡す例です。

{
  "awsCredentialExport": "aws configure export-credentials --format process --profile cross-account-role"
}

cross-account-roleの部分は、~/.aws/configに事前定義したロール引き受け用のプロファイル名に置き換えます。読む先が違います。このコマンド自体は.aws/configを読みに行きますが、Claude Codeが実際に読むのはコマンドの実行結果として返るJSONだけです。

AWS標準のcredential_processとは別物

AWSのSDKには、プロファイルにcredential_processを書いて認証情報コマンドを指定する標準の仕組みがすでにあります。名前も役割も似ています。しかし動く場所が違います。credential_processは~/.aws/configの中に書き、Claude Codeの既定認証チェーンの内側で解決されます。解決処理には60秒のタイムアウトがかかり、ブラウザーでの操作待ちのように応答が返らないcredential_processはここでタイムアウトの対象になります。awsCredentialExportはClaude Codeの設定ファイルに書く、既定チェーンの外側にあるフックです。両者は同時に使うものではなく、どちらか一方を選びます。

awsAuthRefreshとの使い分け早見表

名前は似ています。しかし実行タイミングと.awsへの影響はまったく違います。

認証情報の失効そのものに関する切り分け手順はAWS credentials expired or invalidの直し方にまとまっています。ここで押さえておく点は1つです。awsCredentialExportだけを設定してawsAuthRefreshを設定していない場合、セッションの途中で認証情報が切れても自動では復旧しません。新しいセッションを開始し直すと、そのタイミングでコマンドが再実行され、新しい認証情報を取得し直します。

Google Cloud側にも似た設定があります。ただし対応関係は対称ではありません。awsAuthRefreshに相当するgcpAuthRefreshはGoogle Cloudの認証情報が失効・読み込み不能になったときの更新コマンドとして用意されています。awsCredentialExportのように、認証情報を都度JSONで返す設定はGoogle Cloud側にはありません。マルチクラウドでClaude Codeを使うチームにとって、この非対称さは構成上の制約になります。

いつ、何回コマンドが実行されるか

awsAuthRefreshは実行前にSTSのGetCallerIdentityを呼び、認証情報がまだ有効なら実行をスキップします。awsCredentialExportは確認しません。設定されていれば、既定チェーンの認証情報がまだ有効でも毎回無条件に実行されます。

awsAuthRefreshを設定せずawsCredentialExportだけを設定した場合、Claude Codeはエクスポートされた認証情報をそのまま使い、起動時にAWSの既定認証チェーンを再解決しません。この挙動にはv2.1.206以降が必要です。

既定チェーンを解決する処理自体は60秒でタイムアウトします。ブラウザーSSOのように解決に時間がかかる認証を使っている場合の調整方法は、「AWS default-chain credential resolve timed out」の対処にまとめてあります。ただしawsCredentialExportを単独で設定している構成では、この既定チェーンの再解決自体が起きないため、タイムアウト時間の調整は関係しません。

/setup-bedrockウィザードでは設定できない

/setup-bedrockの対話式セットアップウィザードは、~/.awsから検出したプロファイル、Amazon BedrockのAPIキー、アクセスキーとシークレットの組、環境にすでにある認証情報のいずれかを選ぶ形式です。awsCredentialExportはこの中に含まれておらず、ウィザードが生成することはありません。使う場合は~/.claude/settings.jsonなどの設定ファイルに、キーとコマンドを手動で追記する必要があります。

複数の設定ファイルに書いたときはどれが有効か

awsCredentialExportは~/.claude/settings.json(user)、.claude/settings.json(project)、.claude/settings.local.json(local)、組織が配布するmanaged設定のどこにでも書けます。設定ファイルの優先順位はmanagedが最も高く、次にコマンドライン引数、local、project、userの順です。値はマージされません。同じキーを複数箇所に書いても、優先順位が最も高いファイルの値だけが使われます。設定ファイルの全体像はClaude Code設定ガイドにまとまっています。

設定時に見落としやすい注意点

• 出力形式は前述の2種類(ネスト型・フラット型)以外を想定していません。それ以外の形でJSONを返す構成は仕様の対象外です
• エクスポートされた認証情報はBedrock呼び出し専用のクライアントに限定されます。Bashツールで実行するawsコマンドやgitなどの他のプロセスは、この設定と無関係にOS側の通常の認証情報(環境変数や.aws)を見ます
• 組織がmanagedSourcesBehaviorをmergeにして複数のmanagedソースを組み合わせている場合でも、この優先順位は変わりません。permissions.allowのようなリスト型キーは全ソースから値を集約しますが、awsCredentialExportはポリシーキーを持つ最も優先度の高いソースの値だけがそのまま使われます
• 既定チェーンの解決結果を毎回無効化するCLAUDE_CODE_SKIP_AWS_CRED_CACHEは、既定チェーンに対するキャッシュの話です。awsCredentialExport自身が持つExpirationベースのキャッシュ(またはExpiration無しの1時間固定)とは別の仕組みで、この環境変数を設定してもawsCredentialExportのキャッシュ期間は変わりません
• フラット形式の受け入れはv2.1.181以降、Expirationによるキャッシュ計算の変更はv2.1.176以降、既定認証チェーンの5分前キャッシュ挙動はv2.1.207以降、awsAuthRefreshなしの単独運用でデフォルトチェーンの再解決を省略する挙動はv2.1.206以降の追加です。古いバージョンでは想定どおりに動かないことがあります

Bashツールでサンドボックスを使っている場合、AWS認証情報の扱いにさらにもう1つ別の仕組みがあります。名前が近い割に、実体は別物です。サンドボックスがマスクした環境変数からAWSリクエストを再署名するsandbox.credentials.awsPairs(SigV4 re-signing)で、これはawsCredentialExportではなくサンドボックス側の設定です。AWS_ACCESS_KEY_ID・AWS_SECRET_ACCESS_KEY・AWS_SESSION_TOKENという標準名の組はマスクするだけで自動的に連携しますが、変数名が標準と違う場合はこのキーで明示的に紐付けます。

LLMゲートウェイ経由なら、この設定自体が不要になる

組織が中央のLLMゲートウェイを介してモデルへのトラフィックを流し、AWS認証情報をゲートウェイ側でサーバー注入する構成では、awsCredentialExportは不要です。認証自体を手放す構成だからです。CLAUDE_CODE_SKIP_BEDROCK_AUTHを設定すると、Claude Code側でのAmazon Bedrock向けAWS認証そのものをスキップします。渡す認証情報の中身を切り替えたいのか、認証処理自体をゲートウェイに委ねたいのかで、選ぶ設定が変わります。

まとめ

.awsを書き換えられない環境や、Bedrock呼び出しだけクロスアカウントの認証情報に切り替えたい場面では、awsCredentialExportが候補になります。.awsをSSOで更新する運用ならawsAuthRefreshのほうが単純です。どちらもuser・project・local・managedのどの設定ファイルにも書ける設定なので、.claude/settings.local.jsonのような個人用ファイルに書けば、他のメンバーに影響を与えずに動作を確認できます。

複数のBedrockアカウントを切り替えて検証する開発環境でも、.awsのプロファイルを都度書き換える代わりに、アカウントごとにコマンドを分けた設定ファイルを使い分けるだけで済みます。名前が近いawsAuthRefresh・credential_process・sandbox.credentials.awsPairsとどこが違うかを設定前に一度確認しておくと、意図しない認証情報がBedrock呼び出しに使われる事態を避けやすくなります。