Claude CodeのawsAuthRefreshとgcpAuthRefreshで認証切れを自動更新
awsAuthRefreshとgcpAuthRefreshは、Bedrock・Vertexの認証が切れたときだけ指定コマンドを走らせる設定です。判定の流れと書き方、複数ウィンドウでの挙動を解説します。
awsAuthRefresh と gcpAuthRefresh は、Claude CodeがBedrockやVertexの認証切れを検知したときに、あらかじめ決めたログインコマンドを代わりに実行する設定キーです。SSOの期限が切れるたびに別ターミナルで aws sso login を打つ手間がなくなります。どちらも settings.json に1行書くだけで使えます。
2つの設定キーは何を自動化するのか
awsAuthRefresh はAmazon Bedrock向け、gcpAuthRefresh はGoogle CloudのVertex向けです。値はどちらも「シェルのコマンド行」の文字列で、既定では未設定です。未設定のままだとClaude Codeは認証を更新せず、Google側は gcloud auth application-default login を自分で実行するよう案内するエラーを返します。
書ける場所はUser・Project・Local・Managedのどの設定ファイルでも構いません。
| 項目 | awsAuthRefresh | gcpAuthRefresh |
|---|---|---|
| 対象 | awsAuthRefreshAmazon Bedrock | gcpAuthRefreshVertex(Google Cloud) |
| 典型的な値 | awsAuthRefreshaws sso login --profile myprofile | gcpAuthRefreshgcloud auth application-default login |
| 更新の対象 | awsAuthRefresh.aws ディレクトリの認証情報 | gcpAuthRefreshApplication Default Credentials |
| 期限切れの確認方法 | awsAuthRefreshSTSへの問い合わせ | gcpAuthRefresh現在の認証でアクセストークンを要求 |
どちらも「切れていたら更新コマンドを実行し、直ったらリクエストを再試行する」という流れです。常にコマンドを走らせるわけではない点が、次の節の中心になります。
切れていないときは実行されない仕組み
起動のたびにブラウザが開くようでは使い物になりません。そこで、コマンドを走らせる前に認証が本当に切れているかを確かめます。
awsAuthRefreshが走るまでの判定
- 1
切れた疑いを検知する
認証情報の有効期限が過ぎているか、APIが認証エラーを返したときです。
- 2
STSで現在の認証を確認する
GetCallerIdentityを呼び、認証が通るかを見ます。通るならコマンドは実行されません。 - 3
失敗したときだけコマンドを実行する
更新後に
.awsディレクトリを読み直し、リクエストを再試行します。
このSTSの確認は、HTTPS_PROXY と NO_PROXY を含むプロキシ設定を通ります。v2.1.239より前は確認を直接送っていたため、外向き通信がプロキシ経由に限られるネットワークでは、起動時に固まる不具合がありました。古い版でプロキシ環境からBedrockに入れないなら、まずバージョンを疑う価値があります。
手元で同じ確認をしたいときは、AWS CLIで次を実行します。成功すればClaude Code側でも更新コマンドは呼ばれない状態です。
aws sts get-caller-identity --profile myprofileGoogle側も考え方は同じです。現在の認証でアクセストークンを取れるかを確かめ、使えるならコマンドを飛ばします。確認が5秒以内に終わらない場合は、コマンドを先に走らせず、リクエストが認証エラーで失敗してから実行します。v2.1.261より前は、タイムアウトを期限切れと見なしていました。認証が有効なのに起動時にブラウザが開く症状は、この版で直っています。
設定の書き方
最小の構成は、更新コマンドと、使うプロファイルを環境変数で渡す形です。
{
"awsAuthRefresh": "aws sso login --profile myprofile",
"env": {
"AWS_PROFILE": "myprofile"
}
}Vertexの場合は次のようになります。プロジェクトIDは ANTHROPIC_VERTEX_PROJECT_ID で渡します。
{
"gcpAuthRefresh": "gcloud auth application-default login",
"env": {
"ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
}
}Vertexへのリクエストは、GOOGLE_CLOUD_PROJECT や認証ファイルが別のプロジェクトを指していても、ANTHROPIC_VERTEX_PROJECT_ID のプロジェクト宛てに送られます。更新コマンドで入れ替わるのは認証だけで、宛先は変わりません。
ここで押さえておきたい制約が3つあります。
- コマンドの出力は画面に表示されますが、対話入力は渡せません
- 向いているのは、CLIがURLやコードを表示し、ブラウザで認証を終えるSSO型のフローです
- Google側の更新コマンドは、認証が3分以内に終わらないとタイムアウトします
パスワードを都度入力させるタイプのコマンドは、そのままでは使えません。入力を要しない形に包んだスクリプトを指定する形になります。
プロジェクト設定に書くときの注意
.claude/settings.json のようなプロジェクト設定に gcpAuthRefresh を書くと、フックと同じ扱いのワークスペース信頼ルールの対象になります。対話セッションでは信頼ダイアログを承認するまで実行されません。-p で動かす非対話実行は、一度も信頼していないフォルダでも対象になる点が特徴です。チームで共有する設定にコマンドを入れるなら、リポジトリの内容を信頼してよい相手に限る運用が前提です。個人のSSOプロファイル名は、リポジトリに入れずUserかLocalに置くほうが衝突しません。
awsCredentialExportとの使い分け
Bedrockには認証を扱う別のキーがもう1つあります。判断の分かれ目は「更新した結果がどこに出るか」です。
| 観点 | awsAuthRefresh | awsCredentialExport |
|---|---|---|
| コマンドの役割 | awsAuthRefresh.aws を書き換える | awsCredentialExport認証情報をJSONで出力する |
| 実行条件 | awsAuthRefresh切れていると確認できたときだけ | awsCredentialExport設定されていれば常に |
| 出力の扱い | awsAuthRefresh画面に表示される | awsCredentialExport画面には出ない |
| 向いている場面 | awsAuthRefreshブラウザ型のSSOログイン | awsCredentialExport.aws を変更できない環境 |
awsCredentialExport は、起動時と認証の再読み込みのたびに実行されます。デフォルトの認証チェーンで解決される認証と違う、アカウント跨ぎの認証が必要なときの選択肢です。JSONの形は aws sts の出力と、aws configure export-credentials のフラットな形のどちらでも受け付けます。Expiration があれば期限の5分前まで、なければ1時間キャッシュします。
両方を設定した場合の細かい優先関係は、ドキュメントに記載がありません。まず awsAuthRefresh だけで足りるかを試し、足りないときに awsCredentialExport を検討する順番が無難です。
組織で配るときの優先順位
awsAuthRefresh と gcpAuthRefresh は、ポリシー用のキーを持つ最も優先度の高い供給元だけから読むキーに分類されています。下位の設定に書いた値は、最上位の供給元がこのキーを設定していなくても無視されます。個人のUser設定に書いたのに効かないときは、上位の設定ファイルにポリシー用のキーがないかを見てください。管理設定を配る側は、この仕様を知ったうえで配布内容を決めることになります。
複数のウィンドウで同時に切れたとき
ターミナルを3つ、IDEを2つ開いていれば、認証切れは全部に同時に降りかかります。以前はそれぞれがログイン用のブラウザを開いていました。現在は同じコマンドと同じ認証を使うプロセス同士で、実行するのは1つだけです。残りはその完了を待ちます。
- 待ち始めてから60秒たってもリクエストが保留のままなら、そのプロセスが自分でコマンドを実行します
- 無効にするには、環境変数
CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCKを1にします - この環境変数はv2.1.286以降が必要です
ノートPCのスリープ復帰後に、別のプロセスがログイン中なのにブラウザが二重に開く問題はv2.1.288で直りました。また、Claude Codeの終了や更新のタイムアウト時にログインのプロセスが残り、Windowsでコールバック用のローカルポートを握り続ける問題はv2.1.281で直っています。複数ウィンドウで運用していて挙動が怪しいときは、版を上げてから切り分けます。
ロックを無効にすると、全プロセスが各自でコマンドを実行します。ブラウザが何枚も開く状態に戻るため、特別な理由がなければ既定のままで問題ありません。
更新されないときの切り分け
設定したのに認証が戻らないときは、次の順に見ていきます。
- 手動で同じコマンドを打ち、ターミナル上で最後まで終わるか確かめます。対話入力が要る作りだと、Claude Codeからは完了できません
aws sts get-caller-identityが成功していないか見ます。成功しているなら、Claude Codeは切れていないと判断してコマンドを飛ばします。原因は認証ではなく、権限やリージョンのほうにあります- プロジェクト設定に書いたなら、信頼ダイアログを承認済みかを見ます
- プロキシ環境ならClaude Codeのバージョンがv2.1.239以上かを見ます
- Google側なら、ブラウザでの認証を3分以内に終えたかを見ます。超えるとコマンドは打ち切られます
エラー文言が「AWS credentials expired or invalid」であれば、コマンド側の問題とは限りません。v2.1.273以降は、awsAuthRefresh を設定していなくても同じメッセージが出ます。その場合の見分け方と対処は、AWS credentials expired or invalidの直し方にまとめています。awsAuthRefresh を設定済みなら、メッセージの中に実行すべきコマンドが示されます。対話セッションでは /login から「3rd-party platform」を選び、「Claude Platform on AWS · refresh credentials」を選ぶと、再起動せずに同じコマンドを走らせられます。
どの経路の人に効く設定か
BedrockやVertexを使うのは、日本では契約や請求を既存のクラウドにまとめたい組織が中心です。提供経路ごとの違いはClaudeを日本から使う提供経路で扱っています。経路を選んだあとに、Bedrock・Vertex・Foundryで使えない機能がないかを見るならClaude Codeの機能比較が早道です。
SSOの有効期限が短い組織ほど、この設定の効果は大きくなります。1日に何度も期限が切れる環境では、毎回エラーを読んで別ターミナルを開く往復が、そのまま作業の中断になるからです。一方、長期のアクセスキーやAPIキーでBedrockに入っている場合は、期限切れ自体が起きにくく、出番はあまりありません。APIキーで認証する場合の変数はAWS_BEARER_TOKEN_BEDROCKの記事が参考になります。
まとめ
awsAuthRefresh と gcpAuthRefresh は、認証が切れたと確認できたときだけ更新コマンドを走らせる設定です。ブラウザで完結するSSO型のコマンドと相性がよく、複数ウィンドウでも実行は1回にまとまります。パスワード入力が要るコマンドや、.aws を触れない環境では向かないため、後者は awsCredentialExport に回すのが筋です。まずUser設定に1行書き、手動で認証を切らせて動きを見るところから始められます。