Claude Code Bedrockセットアップ — /setup-bedrockウィザードの使い方

Claude CodeをAmazon Bedrock経由で使い始めるとき、環境変数を手で並べる方法とは別に/setup-bedrockという対話ウィザードがあります。AWS認証・リージョン・モデルピン留めを、CLI内の質問に答えるだけで済ませられます。

このコマンドは、CLAUDE_CODE_USE_BEDROCK=1を設定するまでメニューに出ません。ウィザードが設定ファイルに何を書くか、検証で止まったときに何を疑うかも押さえておくと、チーム展開で迷いません。

Google Cloud側にも同じ形のウィザードがあり、手順は/setup-vertexウィザードの手順にまとめています。

/setup-bedrockが見つからないときの入り方

入り口は2つあります。

/setup-bedrockは、CLAUDE_CODE_USE_BEDROCK=1を設定するまでコマンドメニューの候補に出ません。メニューに無くても、名前を最後までタイプすれば呼び出せる扱いです。「候補に出ないから使えない」と判断しないのが最初のポイントです。

v2.1.287でclaudeのヘルプを確認すると、Bedrock専用のサブコマンドやフラグはありません。Bedrockに触れているのは、--bareの説明にある次の1行だけです(ホームと設定ディレクトリを空にした環境で実行)。

claude --version
claude --help | grep -i -E "bedrock|setup"

2.1.287 (Claude Code)
                                        (Bedrock/Vertex/Foundry) use their own
  setup-token                           Set up a long-lived authentication token

setup-tokenは別の認証トークン用のサブコマンドで、Bedrockのウィザードとは関係がありません。ウィザードを開けるのは、ログイン画面とチャット内のスラッシュコマンドだけです。

一度Bedrockでサインインした後は、認証情報・リージョン・モデルピンを変えたいときにいつでも/setup-bedrockを再実行できます。モデルピンの選択画面は、そのとき既にピン留めされているモデルから始まります。

ウィザードを開く前に済ませておく2つの準備

ウィザードはClaude Code側の設定を埋めるだけで、AWS側の準備は含みません。次の2つが未了だと、認証や検証のステップで止まります。

1. Anthropicモデルの利用申請(アカウントごとに1回): Amazon BedrockコンソールのモデルカタログでAnthropicモデルを選び、ユースケースフォームを送信します。承認は送信直後に下ります。AWS Organizationsを使っている場合、管理アカウントからPutUseCaseForModelAccess APIで一括申請でき、子アカウントにも自動で承認が及びます。この呼び出しにはbedrock:PutUseCaseForModelAccess権限が必要です。

2. IAM権限の付与: 実行ロールには、モデル呼び出しとMarketplaceサブスクリプションの権限が要ります。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles",
        "bedrock:GetInferenceProfile"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*",
        "arn:aws:bedrock:*:*:foundation-model/*"
      ]
    },
    {
      "Sid": "AllowMarketplaceSubscription",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:ViewSubscriptions",
        "aws-marketplace:Subscribe"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": { "aws:CalledViaLast": "bedrock.amazonaws.com" }
      }
    }
  ]
}

aws-marketplace:Subscribeは、モデル有効化がAWS Marketplaceへのサブスクリプションとして裏側で処理されるために必要です。より厳しく絞るなら、Resourceを特定の推論プロファイルARNに限定できます。

ウィザードの流れ

/setup-bedrock

結果はユーザー設定ファイルのenvブロックに書き込まれます。保存先は~/.claude/settings.jsonで、CLAUDE_CONFIG_DIRを設定している場合は$CLAUDE_CONFIG_DIR/settings.jsonです。シェルの環境変数を自分で管理し続けなくて済むのが、ウィザードの実利です。

ウィザードで進めるか、環境変数で組むか

手動設定で最低限必要なのはCLAUDE_CODE_USE_BEDROCK=1です。リージョンは次の順に解決されます。

1. AWS_REGION
2. AWS_DEFAULT_REGION
3. アクティブなAWSプロファイルのregion(共有認証情報ファイル、共有設定ファイルの順に読む)
4. us-east-1

値がリージョン名の形でなければ、未設定として次の候補に進みます。スラッシュ・ドット・スペースを含む値が該当します。解決結果は/statusで確認でき、設定ファイルや既定値から来た場合は出典も表示されます。

手動設定では、SSOを使う場合のプロファイルのsso_regionにも注意します。Claude Codeは資格情報をsso_regionのIAM Identity Centerから取得し、Bedrockを使うリージョンとは一致していなくて構いません。v2.1.207では、Bedrockのリージョンがsso_regionを上書きしていました。そのため、別リージョンのIdentity Centerを使うプロファイルがSession token not found or invalidで失敗しました。この回帰はv2.1.208で修正されています。

認証情報のキャッシュと、検証で止まったとき

Claude CodeはAWSの既定の資格情報チェーンを1回解決し、有効期限の5分前までメモリに保持します。有効期限が無い資格情報は1時間です。APIが資格情報エラーを返すとキャッシュは消え、次のリクエストで再解決します。

Bedrock APIキー(AWS_BEARER_TOKEN_BEDROCK)はチェーンを使わないので、キャッシュの対象外です。毎回解決させたいときはCLAUDE_CODE_SKIP_AWS_CRED_CACHE=1を設定します。

チェーンの解決は1回60秒で打ち切られます。credential_processのヘルパーが入力待ちで止まった場合などです。ウィザードも、APIキー以外の認証では同じ60秒の上限を、検証中のAWS呼び出しごとに当てます。超えると次のように表示されます。

Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

原因として多いのは、AWSへの通信を止めるネットワークやプロキシ(SSOトークンの更新を含む)と、見えない入力を待つ資格情報ヘルパーです。aws-vaultでMFA付きのブラウザSSOを通すように、本当に時間がかかる構成ならCLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MSをミリ秒で引き上げます。1回のリクエストだけが先に失敗すると、より短い文言が出ます。

A request to AWS timed out. Check your network and proxy settings, then try again.

通常のチャットのリクエストでチェーンが打ち切られた場合は、別の文言になります。

API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

v2.1.267より前は、API Error: AWS default-chain credential resolve timed outだけでした。原因は、入力を待つのに受け取れないcredential_processコマンドと、インスタンスメタデータサービス(IMDS)がチェーンの問い合わせに応答しないコンテナやVMです。

TLS検査をするプロキシの内側では、v2.1.261より前だとウィザードの「環境にある資格情報を使う」選択肢だけ別の挙動になっていました。ルート証明書がOSの証明書ストアにしかない環境で、資格情報の取得が実行環境の既定の証明書ストアしか信頼しなかったためです。結果はunable to get local issuer certificateでの失敗か、モデルのunreachable表示です。推論リクエストは通るのにウィザードだけ失敗するときは、バージョンを疑います。

AWSや資格情報ヘルパーが応答しないときにウィザードが固まらず、タイムアウトの明確なエラーを出すようになったのもv2.1.261です。v2.1.218では、パーティション付きのAWSリージョンのassume-roleプロファイルと、プロキシ経由しか出口がないネットワークで、プロファイル検証が失敗する問題が直っています。

モデルのピン留め画面で同じタイムアウトが起きると、上の2つの文言は出ず、そのモデルがunreachableと表示されます。

モデルを固定する(ピン留め)

複数人へ展開するなら、ピン留めを済ませてから配ります。sonnetやopusのエイリアスは、ピン留めが無いとClaude Code組み込みの既定値に解決されます。その既定値は最新リリースに遅れることがあり、自分のAWSアカウントでまだ有効でない場合もあります。

環境変数で固定する例です。

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

us.はクロスリージョン推論プロファイルの接頭辞です。別の接頭辞やアプリケーション推論プロファイルを使うときは、ここを調整します。GovCloudリージョンはus-gov.です。

組み込みの既定値は版ごとに変わってきた

ピン留めしない構成では、Claude Codeを更新するたびに既定のモデルが入れ替わります。BedrockでのメインモデルとOpusエイリアスの既定は、次のように推移しました。

v2.1.207以降は、メインモデルを固定していない展開がOpus料金で課金されます。Sonnet 4.5をメインに残したいときは、ANTHROPIC_MODELにそのフルモデルIDを指定します。ANTHROPIC_DEFAULT_SONNET_MODELで既定を寄せ、ANTHROPIC_DEFAULT_OPUS_MODELを設定していない展開は別です。寄せたSonnetが既定のまま残ります。

接頭辞だけを変える

組み込みの既定モデルを保ったまま接頭辞だけ変えるときは、個別にピン留めせずANTHROPIC_BEDROCK_REGION_PREFIXを使います。個別のモデルIDを指定すればそのIDがそのまま使われ、接頭辞だけをeuにすれば、組み込みの既定(eu.anthropic.claude-opus-5-5)に接頭辞だけが反映されます。

接頭辞は、解決されたAWSリージョンから次のように選ばれます。

ANTHROPIC_BEDROCK_REGION_PREFIXに指定できるのはus・eu・apac・jp・au・globalで、v2.1.224以降が対象です。アカウントで有効な推論プロファイルを列挙できるときは、希望の接頭辞のプロファイル、次に一致する任意のプロファイルの順で選びます。列挙できないときは可用性を確かめずに接頭辞を当てるので、そのプロファイルが無効なアカウントでは400になります。

バックグラウンドタスクとSonnetの関係

セッションタイトルの生成のようなバックグラウンドタスクは、通常はHaikuクラスで動きます。ただしBedrockではHaikuがすべてのアカウント・リージョンで有効とは限らないため、既定のSonnetが使われます。次の場合は、そのメインモデルがバックグラウンドタスクも担当します。

• --model・ANTHROPIC_MODEL・model設定でメインモデルを選んだとき
• ANTHROPIC_DEFAULT_MODELで指定したモデルでセッションを始めたとき
• ANTHROPIC_DEFAULT_OPUS_MODELだけを設定し、ANTHROPIC_DEFAULT_SONNET_MODELを設定しなかったとき

最後の構成が「選択」扱いになるのは、組み込みのSonnetがそのアカウントで有効とは限らないからです。Haikuで動かしたいときは、ANTHROPIC_DEFAULT_HAIKU_MODELにアカウントで使えるモデルIDを設定します。

起動時のモデルチェックと自動フォールバック

Bedrock設定で起動すると、Claude Codeは使う予定のモデルにアカウントからアクセスできるかを確かめます。結果で挙動が分かれます。

• 古いピンがあり、新しい版も呼べる: ピンの更新を促します。承諾するとユーザー設定ファイルへ新しいモデルIDを書いて再起動し、断ると次の既定バージョン変更まで覚えています。アプリケーション推論プロファイルARNのピンは管理者が決めるものとして対象外です。
• ピンが無く、既定のモデルがアカウントで使えない: そのセッションに限り、既定より前の版を先に試します。既定がOpusでOpus系がどれも使えなければ、既定のSonnetに落とします。フォールバックは保存されません。

使えないと判明したモデルは、このマシンに最大1日記憶され、その間の起動では再確認されません。現行の既定モデルは、前回から10分たつと起動時に再確認されるので、管理者が有効に戻せば復帰します。記憶を切るにはCLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1を設定します。

セッションの途中でアカウントがモデルへのアクセスを失った場合は、別のモデルへ切り替わります。画面にはSwitched to <fallback> because <model> is not availableと出ます。切り替わるのはピン留めしていない階層だけです。自分で選んだ特定のバージョンやARNのセッションはモデルを保ち、フォールバックのチェーンも無ければリクエストが失敗します。切り替えを止めて失敗させたいときはCLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1を設定します。

つまずきやすいポイント

IAM権限を絞ってbedrock:GetInferenceProfileを落とした: この権限は、アプリケーション推論プロファイルARNを裏側の基盤モデルへ解決するために使われます。無くても致命的なエラーにはならず、Claude Codeは代替の形式で1回リトライして復旧します。ただし新しいモデルを呼ぶたびに往復が1回増えます。AWS_BEARER_TOKEN_BEDROCKのAPIキー運用はトークンのポリシーが狭くなりがちなので、最初から含めておくとリトライ分の遅延を避けられます。

SSOと社内プロキシでブラウザタブが繰り返し開く: 原因は設定ファイルのawsAuthRefreshである可能性が高いです。VPNやTLS検査プロキシがSSOのブラウザフローを妨げると、Claude Codeはそれを認証失敗と見てawsAuthRefreshを再実行し、ループに入ります。awsAuthRefreshを設定ファイルから外し、aws sso loginを起動前に手動で済ませる運用に切り替えます。

awsAuthRefreshとawsCredentialExportの使い分け: awsAuthRefreshは、資格情報の期限切れを検知したときだけ動きます。実行前にSTSのGetCallerIdentityで本当に期限切れかを確かめ、通るなら実行を省きます。この確認がプロキシ設定を通るようになったのはv2.1.239からで、それ以前は直接送信するため、出口がプロキシだけのネットワークで起動時に固まりました。awsCredentialExportは、資格情報が有効でもセッション開始時と再読み込みのたびに動きます。.awsを書き換えられず、資格情報を直接返す必要があるときにだけ使います。

リージョンのエラー: aws bedrock list-inference-profiles --region <リージョン>でそのリージョンのモデル可用性を確認するのが最初の一手です。「on-demand throughputはサポートされていない」というエラーは、モデルIDを推論プロファイルIDで指定し直すと解消します。Claude CodeはBedrockのInvoke APIを使い、Converse APIには対応していません。

ゲートウェイ経由でストリーミングが崩れる: Bedrockはバイナリ形式でストリームを返し、ヘッダーはContent-Type: application/vnd.amazon.eventstreamです。ゲートウェイがこのヘッダーをtext/event-streamなどへ書き換えると、Bedrock streaming response has content-typeで始まるエラーになります。ヘッダーを落とした上でサーバー送信イベントに変換する構成では、毎ターン非ストリーミングの経路に落ち、応答が完成してからまとめて表示されます。この場合はCLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT=1で、本文をサーバー送信イベントとして読ませます。

/contextで全ツールグループが0トークンと表示される: v2.1.196より前の既知の不具合です。ツールのスキーマがBedrockのトークン数カウントAPIの受け付けない項目を含んでいたため、リクエストが拒否されていました。メッセージやメモリファイルなど他の行には影響せず、v2.1.196以降で解消しています。

Bedrockを選んだ環境には、ほかにも制約があります。認証をAWSの資格情報が担うので/logoutは使えず、WebSearchツールも使えません。

料金と周辺機能は別記事へ

BedrockとAnthropic直接APIの料金差はAWS BedrockのClaude料金は直接APIとどう違うかにあります。

Bedrock経由でも使える機能の制約はClaude Codeコードレビューで確認できます。