Amazon Bedrock 上的 Claude Code

先決條件

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

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

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

使用 Bedrock 登入

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

在您的 AWS 帳戶中啟用 Anthropic 模型

在 Amazon Bedrock 主控台中，開啟模型目錄，選取 Anthropic 模型，然後提交使用案例表單。提交後立即授予存取權限。請參閱提交使用案例詳細資訊以了解 AWS Organizations，以及IAM 設定以了解您的角色所需的權限。

啟動 Claude Code 並選擇 Bedrock

執行 claude。在登入提示處，選取第三方平台，然後選取 Amazon Bedrock。

遵循精靈提示

選擇您如何向 AWS 進行驗證：從您的 ~/.aws 目錄偵測到的 AWS 設定檔、Bedrock API 金鑰、存取金鑰和密碼，或已在您的環境中的認證。精靈會選取您的區域，驗證您的帳戶可以叫用哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的使用者設定檔的 env 區塊，因此您不需要自己匯出環境變數。

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

手動設定

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

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

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

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

如果您使用 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：Bedrock API 金鑰

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

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

進階認證設定

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

awsAuthRefresh：僅在 Claude Code 偵測到您的 AWS 認證已過期時執行，基於本機時間戳記或當 Bedrock 傳回認證錯誤時，然後使用重新整理的認證重試請求。
awsCredentialExport：在工作階段開始時和每次認證重新載入時執行，即使您的 AWS 預設認證提供者鏈中的認證仍然有效。當您的 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"
  }
}

3. 設定 Claude Code

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

# 啟用 Bedrock 整合
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # 或您偏好的區域

# 選用：覆寫小型/快速模型 (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 啟用 Bedrock 時，請記住以下事項：

AWS_REGION 是必需的環境變數。Claude Code 不會從 .aws 設定檔讀取此設定。
使用 Bedrock 時，/login 和 /logout 命令會被停用，因為驗證是透過 AWS 認證處理的。
您可以使用設定檔來設定環境變數，例如 AWS_PROFILE，您不想將其洩露給其他程序。請參閱設定以取得更多資訊。

4. 固定模型版本

在部署給多個使用者時固定特定的模型版本。如果不固定，模型別名（例如 sonnet 和 opus）會解析為最新版本，當 Anthropic 發佈更新時，該版本可能在您的 Bedrock 帳戶中尚不可用。Claude Code 在啟動時會在最新版本不可用時回退到先前版本，但固定可讓您控制使用者何時移至新模型。

將這些環境變數設定為特定的 Bedrock 模型 ID。如果沒有 ANTHROPIC_DEFAULT_OPUS_MODEL，Bedrock 上的 opus 別名會解析為 Opus 4.6。將其設定為 Opus 4.7 ID 以使用最新模型：

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-7'
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. 前綴）。如果您使用不同的區域前綴或應用程式推論設定檔，請相應調整。如需目前和舊版模型 ID，請參閱模型概觀。請參閱模型設定以取得完整的環境變數清單。未設定固定變數時，Claude Code 使用這些預設模型：

模型類型	預設值
主要模型	`us.anthropic.claude-sonnet-4-5-20250929-v1:0`
小型/快速模型	與主要模型相同

背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 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

Prompt caching 可能不適用於所有區域。使用 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 呼叫 Bedrock。沒有覆寫的版本會回退到內建的 Bedrock 模型 ID 或在啟動時發現的任何相符推論設定檔。請參閱覆寫每個版本的模型 ID，以了解覆寫如何與 availableModels 和其他模型設定互動的詳細資訊。

啟動模型檢查

當 Claude Code 以 Bedrock 設定啟動時，它會驗證它打算使用的模型在您的帳戶中是否可存取。此檢查需要 Claude Code v2.1.94 或更新版本。如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的帳戶可以叫用較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的使用者設定檔並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。指向應用程式推論設定檔 ARN 的固定會被跳過，因為這些由您的管理員管理。如果您尚未固定模型且目前預設值在您的帳戶中不可用，Claude Code 會在目前工作階段中回退到先前版本並顯示通知。回退不會被保留。在您的 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 角色更狹隘。如需詳細資訊，請參閱 Bedrock IAM 文件。

為 Claude Code 建立專用的 AWS 帳戶，以簡化成本追蹤和存取控制。

1M 權杖內容視窗

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Amazon Bedrock 上支援 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 形狀而不是 Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 認證、IAM 權限和本頁面前面所述的 awsAuthRefresh 設定。

Mantle 需要 Claude Code v2.1.94 或更新版本。執行 claude --version 以檢查。

啟用 Mantle

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

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

Claude Code 從 AWS_REGION 構造端點 URL。若要為自訂端點或閘道覆寫它，請設定 ANTHROPIC_BEDROCK_MANTLE_BASE_URL。在 Claude Code 內執行 /status 以確認。當 Mantle 處於作用中時，提供者行會顯示 Amazon Bedrock (Mantle)。

選取 Mantle 模型

Mantle 使用以 anthropic. 為前綴且沒有版本尾碼的模型 ID，例如 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 會進入 Bedrock Invoke API。

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

若要在 /model 選擇器中顯示 Mantle 模型，請在設定檔中的 availableModels 中列出其 ID。此設定也會將選擇器限制為列出的項目，因此請包括您想保持可用的每個別名：

{
  "availableModels": ["opus", "sonnet", "haiku", "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 端點。請參閱環境變數以取得完整清單。

變數	目的
`CLAUDE_CODE_USE_MANTLE`	啟用 Mantle 端點。設定為 `1` 或 `true`。
`ANTHROPIC_BEDROCK_MANTLE_BASE_URL`	覆寫預設 Mantle 端點 URL
`CLAUDE_CODE_SKIP_MANTLE_AUTH`	跳過用戶端驗證以進行代理設定
`ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`	覆寫 Haiku 級模型的 AWS 區域（與 Bedrock 共用）

故障排除

使用 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 使用 Bedrock Invoke API，不支援 Converse API。

Mantle 端點錯誤

如果在設定 CLAUDE_CODE_USE_MANTLE 後 /status 未顯示 Amazon Bedrock (Mantle)，則該變數未到達程序。確認它已在您啟動 claude 的 shell 中匯出，或在設定檔的 env 區塊中設定它。來自 Mantle 端點的 403（具有有效認證）表示您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。命名模型 ID 的 400 表示該模型未在 Mantle 上提供。Mantle 有其自己的模型陣容，與標準 Bedrock 目錄分開，因此推論設定檔 ID（例如 us.anthropic.claude-sonnet-4-6）將無法運作。使用 Mantle 格式的 ID，或啟用兩個端點，以便 Claude Code 將每個請求路由到模型可用的端點。

設定與存取

部署

使用情況和成本

外掛程式發佈

安全性和資料

採用

Amazon Bedrock 上的 Claude Code

先決條件

使用 Bedrock 登入

手動設定

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

2. 設定 AWS 認證

進階認證設定

範例設定

設定說明

3. 設定 Claude Code

4. 固定模型版本

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

啟動模型檢查

IAM 設定

1M 權杖內容視窗

服務層級

AWS Guardrails

使用 Mantle 端點

啟用 Mantle

選取 Mantle 模型

與 Invoke API 並行執行 Mantle

透過閘道路由 Mantle

Mantle 環境變數

故障排除

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

區域問題

Mantle 端點錯誤

其他資源

設定與存取

部署

使用情況和成本

外掛程式發佈

安全性和資料

採用

Documentation Index

​先決條件

​使用 Bedrock 登入

​手動設定

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

​2. 設定 AWS 認證

​進階認證設定

範例設定

設定說明

​3. 設定 Claude Code

​4. 固定模型版本

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

​啟動模型檢查

​IAM 設定

​1M 權杖內容視窗

​服務層級

​AWS Guardrails

​使用 Mantle 端點

​啟用 Mantle

​選取 Mantle 模型

​與 Invoke API 並行執行 Mantle

​透過閘道路由 Mantle

​Mantle 環境變數

​故障排除

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

​區域問題

​Mantle 端點錯誤

​其他資源

先決條件

使用 Bedrock 登入

手動設定

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

2. 設定 AWS 認證

進階認證設定

3. 設定 Claude Code

4. 固定模型版本

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

啟動模型檢查

IAM 設定

1M 權杖內容視窗

服務層級

AWS Guardrails

使用 Mantle 端點

啟用 Mantle

選取 Mantle 模型

與 Invoke API 並行執行 Mantle

透過閘道路由 Mantle

Mantle 環境變數

故障排除

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

區域問題

Mantle 端點錯誤

其他資源