awsAuthRefreshとは?AWS認証を自動更新する設定

ひとことで言うと

awsAuthRefresh は、Claude CodeがAWS(Amazon Web Services)経由でAIモデルを使うときに、「認証情報が切れそうになったら、このコマンドを実行して更新してね」 と伝えておくための設定項目です。

Claude CodeはAnthropicのAPIだけでなく、AWSのAmazon Bedrock経由でClaudeを使うこともできます。会社でAWSを使っている場合はこちらのパターンが多いんですが、AWSの認証情報には有効期限があるものが多くて、放っておくと途中で「認証エラーです」と止まってしまう。それを防ぐための仕組み、と考えてもらえれば大丈夫です。

なぜ「更新」が必要なのか

ここがピンと来ないと設定の意味もわからないので、少し寄り道します。

AWSの認証情報は、遊園地の「1日フリーパス」ではなく 「2時間だけ有効な入場券」 に近いものが使われることがよくあります。セキュリティのため、わざと短い時間で失効するようになっているんですね。特に、SSO(シングルサインオン)や一時的な権限の引き受け(AssumeRole)を使っている環境だと、数十分〜数時間で切れます。

問題は、Claude Codeで長時間作業しているときです。コードを書いてもらって、テストを回して、修正して……とやっているうちに、入場券の有効期限が過ぎる。すると突然「認証できません」というエラーが出て作業が止まります。

そこで awsAuthRefresh の出番です。あらかじめ「券が切れそうになったら、この窓口でもう一枚もらってきて」という手順を登録しておく。Claude Codeはそれに従って自動でコマンドを実行し、新しい認証情報を取得します。作業している側からすると、何も起きなかったかのように処理が続く、というわけです。

どこに書くのか

Claude Codeの設定ファイル(settings.json)の中に、他の設定と並べて書きます。値には 実行してほしいシェルコマンドの文字列 を指定します。

{
  "awsAuthRefresh": "aws sso login --profile my-profile"
}

上の例は「my-profile というプロファイルでSSOにログインし直す」という意味のコマンドです。実際にどのコマンドを書くべきかは、あなたの会社や環境がどうやってAWSにログインしているかによって変わります。普段ターミナルで手打ちしている「これを叩けばAWSが使えるようになる」コマンドを、そのまま書くイメージが一番近いです。

つまずきやすいところ

最初にやりがちなのが、普段のターミナルでは動くのに、Claude Codeからだと動かない というパターン。よくある原因は、環境変数やPATHの違いです。手元のシェルでは .zshrc などで設定されている値が、Claude Codeが起動するコマンドには渡っていない、というケースですね。コマンドをフルパスで書いたり、プロファイル名を明示したりすると解決することがあります。

もうひとつは、コマンドが対話を要求してしまう ケース。ブラウザを開いて「承認しますか?」と聞いてくるようなログイン方法だと、裏で自動実行してもそこで止まります。この場合は、人の操作を挟まずに完了する方法を使うか、期限が切れる前に自分でログインし直す運用にするのが現実的です。

この設定が要らない人もいる

誤解のないように補足すると、これはAWS経由でClaudeを使っている人向けの設定です。AnthropicのAPIキーやClaudeのサブスクリプションで普通に使っている場合は、そもそも出番がありません。「設定項目一覧で見かけたけど何これ?」という段階なら、自分がAWS経由かどうかを先に確認してみてください。関係なければ、そのまま素通りして問題ないです。

覚えておきたいポイント

要するに、awsAuthRefresh は 「切れる認証情報を、切れる前に自動で取り直す」ための逃げ道 です。設定していなくてもClaude Code自体は動きますが、AWS環境で長い作業をするなら、入れておくと地味に効いてくる種類の設定だと思ってください。エラーが出てから慌てて調べるより、最初に一行足しておく方がずっと楽です。