先決條件

在使用 Amazon Bedrock 設定 Claude Code 之前，請確保您具有：

• 已啟用 Amazon Bedrock 存取的 AWS 帳戶
• 在 Amazon Bedrock 中存取所需的 Claude 模型（例如 Claude Sonnet 4.6）
• 已安裝並設定 AWS CLI（選用 - 僅在您沒有其他取得認證機制時才需要）
• 適當的 IAM 權限

若要使用您自己的 Amazon Bedrock 認證登入，請遵循下面的使用 Amazon Bedrock 登入。若要在整個團隊中部署 Claude Code，請使用手動設定步驟並在推出前固定您的模型版本。

使用 Bedrock 登入

如果您有 AWS 認證並想開始透過 Amazon Bedrock 使用 Claude Code，登入精靈會引導您完成整個過程。您每個帳戶完成一次 AWS 端的先決條件；精靈會處理 Claude Code 端。

登入後，隨時執行 /setup-bedrock 以重新開啟精靈並變更您的認證、區域或模型固定。

手動設定

若要透過環境變數而不是精靈來設定 Amazon Bedrock，例如在 CI 或指令碼化企業推出中，請遵循下面的步驟。

1. 提交使用案例詳細資訊

Anthropic 模型的首次使用者必須在叫用模型之前提交使用案例詳細資訊。這是每個 AWS 帳戶執行一次的操作。

1. 確保您具有下面所述的正確 IAM 權限
2. 導覽至 Amazon Bedrock 主控台
3. 從模型目錄選取 Anthropic 模型
4. 完成使用案例表單。提交後立即授予存取權限。

如果您使用 AWS Organizations，您可以使用 PutUseCaseForModelAccess API 從管理帳戶提交一次表單。此呼叫需要 bedrock:PutUseCaseForModelAccess IAM 權限。核准會自動延伸到子帳戶。

2. 設定 AWS 認證

Claude Code 使用預設的 AWS SDK 認證鏈。使用以下其中一種方法設定您的認證：

選項 A：AWS CLI 設定

aws configure

選項 B：環境變數（存取金鑰）

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token

選項 C：環境變數（SSO 設定檔）

aws sso login --profile=<your-profile-name>

export AWS_PROFILE=your-profile-name

選項 D：AWS 管理主控台認證

aws login

深入了解 aws login。

選項 E：Amazon Bedrock API 金鑰

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Amazon Bedrock API 金鑰提供了一種更簡單的驗證方法，無需完整的 AWS 認證。深入了解 Amazon Bedrock API 金鑰。

進階認證設定

Claude Code 支援 AWS SSO 和公司身分提供者的自動認證重新整理。將這些設定新增至您的 Claude Code 設定檔（請參閱設定以了解檔案位置）。

這兩個設定有不同的觸發條件：

• awsAuthRefresh：僅在 Claude Code 偵測到您的 AWS 認證已過期時執行，基於本機時間戳記或當 API 傳回認證錯誤時，然後使用重新整理的認證重試請求。
• awsCredentialExport：在工作階段開始時和每次認證重新載入時執行，即使您的 AWS 預設認證提供者鏈中的認證仍然有效。當您的 Amazon Bedrock 帳戶需要與預設提供者鏈會解析的認證不同的跨帳戶認證時，請使用此選項。

範例設定

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}

設定說明

awsAuthRefresh：用於修改 .aws 目錄的命令，例如更新認證、SSO 快取或設定檔。命令的輸出會顯示給使用者，但不支援互動式輸入。這適用於瀏覽器型 SSO 流程，其中 CLI 顯示 URL 或代碼，您在瀏覽器中完成驗證。

awsCredentialExport：僅在您無法修改 .aws 且必須直接傳回認證時使用。此命令在每次需要重新整理認證時執行，而不僅在認證過期時執行。輸出會被無聲地擷取，不會顯示給使用者。命令必須以此格式輸出 JSON：

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

{/* min-version: 2.1.181 */}自 Claude Code v2.1.181 起，aws configure export-credentials --format process 的平面輸出也被接受，具有相同的金鑰在頂層而不是巢狀在 Credentials 下。

Expiration 是選用的。{/* min-version: 2.1.176 */}自 Claude Code v2.1.176 起，當命令傳回有效的 ISO 8601 Expiration 時，Claude Code 會快取認證直到該時間前五分鐘。沒有它，或在較早版本上，認證會快取一小時。

3. 設定 Claude Code

設定下列環境變數以啟用 Amazon Bedrock：

# 啟用 Bedrock 整合
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # 如果您的 AWS 設定檔已設定區域，則為選用；如果您的設定檔沒有區域，則為必需

# 選用：覆寫小型/快速模型 (Bedrock 和 Mantle) 的 AWS 區域。
# 在 Bedrock 上，如果沒有設定 ANTHROPIC_DEFAULT_HAIKU_MODEL
# 或已棄用的 ANTHROPIC_SMALL_FAST_MODEL，則無效。
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# 選用：覆寫 Bedrock 端點 URL 以用於自訂端點或閘道
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

為 Claude Code 啟用 Amazon Bedrock 時，請記住以下事項：

• {/* min-version: 2.1.172 */}自 v2.1.172 起，您只需設定 AWS_REGION 以覆寫您的 AWS 設定檔的區域，或在您的設定檔沒有區域時設定。Claude Code 按此順序解析區域：

  • AWS_REGION
  • AWS_DEFAULT_REGION
  • 在您的作用中 AWS 設定檔上設定的 region，首先從 AWS 共用認證檔案讀取，然後從共用設定檔讀取，符合 AWS SDK 優先順序
  • us-east-1

  作用中設定檔是 AWS_PROFILE（如果已設定），否則為 default。設定 AWS_SHARED_CREDENTIALS_FILE 或 AWS_CONFIG_FILE 以指向非預設檔案路徑。執行 /status 以查看已解析的區域。當區域來自您的 AWS 設定檔或預設回退時，/status 也會記錄來源。在 v2.1.171 及更早版本上，Claude Code 不會讀取 AWS 設定檔，因此請明確設定 AWS_REGION。

• 使用 Amazon Bedrock 時，/logout 命令無法使用，因為驗證是透過 AWS 認證處理的。

• WebSearch 工具在 Amazon Bedrock 上無法使用。請參閱 WebSearch 工具行為。

• 您可以使用設定檔來設定環境變數，例如 AWS_PROFILE，您不想將其洩露給其他程序。請參閱設定以取得更多資訊。

4. 固定模型版本

將這些環境變數設定為特定的 Amazon Bedrock 模型 ID。

如果沒有這些變數，Amazon Bedrock 上的 opus 別名會解析為 Opus 4.8，sonnet 別名會解析為 Sonnet 4.5。將每個變數設定為特定版本以固定其別名：

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'

這些變數使用跨區域推論設定檔 ID（帶有 us. 前綴）。如果您使用不同的區域前綴或應用程式推論設定檔，請相應調整。在 AWS GovCloud 區域中，使用 us-gov. 前綴。如需目前和舊版模型 ID，請參閱模型概觀。請參閱模型設定以取得完整的環境變數清單。

Claude Code 使用這些預設模型，當未設定固定變數時：

背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Amazon Bedrock 上，Claude Code 預設為主要模型，因為 Haiku 可能不會在每個帳戶或區域中啟用。若要使用 Haiku 進行背景工作，請將 ANTHROPIC_DEFAULT_HAIKU_MODEL 設定為您帳戶中可用的模型 ID。

若要進一步自訂模型，請使用以下其中一種方法：

# 使用推論設定檔 ID
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# 使用應用程式推論設定檔 ARN
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# 選用：如果需要，停用 prompt caching
export DISABLE_PROMPT_CACHING=1

# 選用：要求 1 小時 prompt cache TTL 而不是 5 分鐘預設值
export ENABLE_PROMPT_CACHING_1H=1

1 小時快取 TTL 的計費費率高於 5 分鐘預設值。請參閱快取生命週期。

將每個模型版本對應至推論設定檔

ANTHROPIC_DEFAULT_*_MODEL 環境變數為每個模型系列設定一個推論設定檔。如果您的組織需要在 /model 選擇器中公開同一系列的多個版本，每個版本都路由到其自己的應用程式推論設定檔 ARN，請改用設定檔中的 modelOverrides 設定。

此範例將四個 Opus 版本對應至不同的 ARN，以便使用者可以在它們之間切換，而無需繞過您組織的推論設定檔：

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod",
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
    "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",
    "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"
  }
}

當使用者在 /model 中選取其中一個版本時，Claude Code 會使用對應的 ARN 呼叫 Amazon Bedrock。{/* min-version: 2.1.200 */}當您透過 --model 或 ANTHROPIC_MODEL 直接傳遞 Anthropic 模型 ID 時，相同的對應也適用。沒有覆寫的版本會回退到內建的 Amazon Bedrock 模型 ID 或在啟動時發現的任何相符推論設定檔。在 v2.1.200 之前，--model 和 ANTHROPIC_MODEL 值會直接到達 Amazon Bedrock，而不會通過覆寫對應。請參閱覆寫每個版本的模型 ID，以了解覆寫如何與 availableModels 和其他模型設定互動的詳細資訊。

啟動模型檢查

當 Claude Code 以 Amazon Bedrock 設定啟動時，它會驗證它打算使用的模型在您的帳戶中是否可存取。

如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的帳戶可以叫用較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的使用者設定檔並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。指向應用程式推論設定檔 ARN 的固定會被跳過，因為這些由您的管理員管理。

如果您尚未固定模型且目前預設值在您的帳戶中不可用，Claude Code 會在目前工作階段中回退到先前版本並顯示通知。回退不會被保留。在您的 Amazon Bedrock 帳戶中啟用較新模型或固定版本以使選擇永久化。

IAM 設定

建立具有 Claude Code 所需權限的 IAM 政策：

{
  "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"
        }
      }
    }
  ]
}

如需更嚴格的權限，您可以將資源限制為特定的推論設定檔 ARN。

bedrock:GetInferenceProfile 讓 Claude Code 將應用程式推論設定檔 ARN 解析為其支援的基礎模型，用於為該模型選擇正確的請求形狀。

如果權杖缺少此權限，Claude Code 會透過使用替代形狀重試一次來自動復原，因此請求仍會成功，但每個新模型都會增加額外的往返。授予權限可避免重試。這最常適用於 AWS_BEARER_TOKEN_BEDROCK 部署，其中權杖的政策通常比完整 IAM 角色更狹隘。

如需詳細資訊，請參閱 Amazon Bedrock IAM 文件。

1M 權杖內容視窗

Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Amazon Bedrock 上支援 1M 權杖內容視窗。Sonnet 5 透過 Mantle 端點提供，且始終以 1M 視窗執行，沒有 [1m] 變體可選擇。對於其他模型，當您選取 1M 模型變體時，Claude Code 會自動啟用擴展內容視窗。

設定精靈在固定模型時提供 1M 內容選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 [1m]。請參閱為第三方部署固定模型以取得詳細資訊。

服務層級

Amazon Bedrock 服務層級可讓您在成本和延遲之間進行權衡。將 ANTHROPIC_BEDROCK_SERVICE_TIER 設定為 default、flex 或 priority：

export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

Claude Code 在每個請求上將此作為 X-Amzn-Bedrock-Service-Tier 標頭傳送。層級可用性因模型和區域而異。保留容量使用佈建輸送量 ARN 作為模型 ID，而不是此設定。

AWS Guardrails

Amazon Bedrock Guardrails 可讓您為 Claude Code 實施內容篩選。在 Amazon Bedrock 主控台中建立 Guardrail，發佈版本，然後將 Guardrail 標頭新增至您的設定檔。如果您使用跨區域推論設定檔，請在 Guardrail 上啟用跨區域推論。

範例設定：

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"
  }
}

使用 Mantle 端點

Mantle 是一個 Amazon Bedrock 端點，透過原生 Anthropic API 形狀而不是 Amazon Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 認證、IAM 權限和本頁面前面所述的 awsAuthRefresh 設定。

啟用 Mantle

已設定 AWS 認證後，設定 CLAUDE_CODE_USE_MANTLE 以將請求路由到 Mantle 端點：

export CLAUDE_CODE_USE_MANTLE=1
export AWS_REGION=us-east-1

Claude Code 從 AWS 區域構造端點 URL。{/* min-version: 2.1.172 */}自 v2.1.172 起，區域的解析優先順序與上面的 Amazon Bedrock 相同；較早的版本僅使用 AWS_REGION。若要為自訂端點或閘道覆寫 URL，請設定 ANTHROPIC_BEDROCK_MANTLE_BASE_URL。

在 Claude Code 內執行 /status 以確認。當 Mantle 處於作用中時，提供者行會顯示 Amazon Bedrock (Mantle)。

選取 Mantle 模型

Mantle 使用以 anthropic. 為前綴且沒有版本尾碼的模型 ID，例如 anthropic.claude-sonnet-5 或 anthropic.claude-haiku-4-5。您的帳戶可用的模型取決於您的組織已被授予的內容；其他模型 ID 列在來自 AWS 的您的上線材料中。請聯絡您的 AWS 帳戶團隊以要求存取允許清單模型。

使用 --model 旗標或 Claude Code 內的 /model 設定模型：

claude --model anthropic.claude-haiku-4-5

與 Invoke API 並行執行 Mantle

您在 Mantle 上可用的模型可能不包括您今天使用的每個模型。設定 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_MANTLE 可讓 Claude Code 從同一工作階段呼叫兩個端點。符合 Mantle 格式的模型 ID 會路由到 Mantle，所有其他模型 ID 會進入 Amazon Bedrock Invoke API。

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

若要在 /model 選擇器中顯示 Mantle 模型，請在設定檔中的 availableModels 中列出其 ID。此設定也會將選擇器限制為列出的項目。列出 anthropic.claude-haiku-4-5 會從選擇器中移除裸 haiku 別名，因此也請列出版本前綴或您想保持可選的版本的完整 ID。Mantle ID 和 haiku 別名會解析為相同的模型系列，因此合併只會保留更具體的項目。請參閱合併行為：

{
  "availableModels": ["opus", "sonnet", "claude-haiku-4-5", "anthropic.claude-haiku-4-5"]
}

帶有 anthropic. 前綴的項目會新增為自訂選擇器選項並路由到 Mantle。將 anthropic.claude-haiku-4-5 替換為您的帳戶已被授予的模型 ID。請參閱限制模型選擇以了解 availableModels 如何與其他模型設定互動。

當兩個提供者都處於作用中時，/status 會顯示 Amazon Bedrock + Amazon Bedrock (Mantle)。

透過閘道路由 Mantle

如果您的組織透過集中式 LLM 閘道路由模型流量，該閘道在伺服器端注入 AWS 認證，請停用用戶端驗證，以便 Claude Code 傳送沒有 SigV4 簽名或 x-api-key 標頭的請求：

export CLAUDE_CODE_USE_MANTLE=1
export CLAUDE_CODE_SKIP_MANTLE_AUTH=1
export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com

Mantle 環境變數

這些變數特定於 Mantle 端點。請參閱環境變數以取得完整清單。

故障排除

使用 SSO 和公司代理的驗證迴圈

如果在使用 AWS SSO 時瀏覽器標籤頻繁開啟，請從您的設定檔中移除 awsAuthRefresh 設定。這可能發生在公司 VPN 或 TLS 檢查代理中斷 SSO 瀏覽器流程時。Claude Code 將中斷的連線視為驗證失敗，重新執行 awsAuthRefresh，並無限迴圈。

如果您的網路環境干擾自動瀏覽器型 SSO 流程，請在啟動 Claude Code 之前手動使用 aws sso login，而不是依賴 awsAuthRefresh。

區域問題

如果您遇到區域問題：

• 檢查模型可用性：aws bedrock list-inference-profiles --region your-region
• 切換至支援的區域：export AWS_REGION=us-east-1
• 考慮使用推論設定檔進行跨區域存取

如果您收到「不支援隨需輸送量」的錯誤：

• 將模型指定為推論設定檔 ID

Claude Code 使用 Amazon Bedrock Invoke API，不支援 Converse API。

/context 中的零權杖計數

/context 命令透過將工具架構傳送至 Amazon Bedrock count-tokens API 來計算每個工具群組的權杖。在 Claude Code v2.1.196 之前的版本中，Amazon Bedrock 拒絕了該請求，因為架構包含其 count-tokens API 不接受的欄位，因此每個工具群組都顯示 0 個權杖。分解中的其他列（例如訊息和記憶體檔案）不受影響。

更新至 v2.1.196 或更新版本。

Mantle 端點錯誤

如果在設定 CLAUDE_CODE_USE_MANTLE 後 /status 未顯示 Amazon Bedrock (Mantle)，則該變數未到達程序。確認它已在您啟動 claude 的 shell 中匯出，或在設定檔的 env 區塊中設定它。

來自 Mantle 端點的 403（具有有效認證）表示您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。

命名模型 ID 的 400 表示該模型未在 Mantle 上提供。Mantle 有其自己的模型陣容，與標準 Amazon Bedrock 目錄分開，因此推論設定檔 ID（例如 us.anthropic.claude-sonnet-4-6）將無法運作。使用 Mantle 格式的 ID，或啟用兩個端點，以便 Claude Code 將每個請求路由到模型可用的端點。

其他資源

• Amazon Bedrock 文件
• Amazon Bedrock 定價
• Amazon Bedrock 推論設定檔
• Amazon Bedrock 權杖燃盡和配額
• Amazon Bedrock 上的 Claude Code：快速設定指南
• Claude Code 監控實施 (Amazon Bedrock)