SpyBara
Go Premium

amazon-bedrock.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 133 additions and 70 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Amazon Bedrock의 Claude Code

Amazon Bedrock을 통한 Claude Code 구성, 설정, IAM 구성 및 문제 해결에 대해 알아봅니다.

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return

Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.
<a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

필수 조건

Claude Code를 Amazon Bedrock으로 구성하기 전에 다음을 확인하십시오:

  • Amazon Bedrock 액세스가 활성화된 AWS 계정
  • Amazon Bedrock에서 원하는 Claude 모델(예: Claude Sonnet 4.6)에 대한 액세스
  • AWS CLI 설치 및 구성(선택 사항 - 자격 증명을 얻을 다른 메커니즘이 없는 경우에만 필요)
  • 적절한 IAM 권한

자신의 Amazon Bedrock 자격 증명으로 로그인하려면 아래의 Bedrock으로 로그인을 따르십시오. 팀 전체에 Claude Code를 배포하려면 수동 설정 단계를 사용하고 롤아웃 전에 모델 버전 고정하십시오.

Bedrock으로 로그인

AWS 자격 증명이 있고 Amazon Bedrock을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. AWS 측 필수 조건을 계정당 한 번 완료하면 마법사가 Claude Code 측을 처리합니다.

1

AWS 계정에서 Anthropic 모델 활성화

Amazon Bedrock 콘솔에서 모델 카탈로그를 열고 Anthropic 모델을 선택한 후 사용 사례 양식을 제출합니다. 제출 후 즉시 액세스 권한이 부여됩니다. AWS Organizations의 경우 사용 사례 세부 정보 제출을 참조하고 역할에 필요한 권한은 IAM 구성을 참조합니다.

2

Claude Code를 시작하고 Amazon Bedrock 선택

claude를 실행합니다. 로그인 프롬프트에서 3rd-party platform을 선택한 후 Amazon Bedrock을 선택합니다. 이미 로그인되어 있고 채팅 프롬프트가 표시되면 /setup-bedrock을 실행하여 마법사를 엽니다. CLAUDE_CODE_USE_BEDROCK=1이 설정될 때까지 Claude Code는 명령 메뉴에서 명령을 숨깁니다. 전체 명령을 입력합니다.

3

마법사 프롬프트 따르기

AWS에 인증하는 방법을 선택합니다: ~/.aws 디렉토리에서 감지된 AWS 프로필, Amazon Bedrock API 키, 액세스 키 및 시크릿, 또는 환경에 이미 있는 자격 증명입니다. 마법사는 지역을 요청하고 계정이 호출할 수 있는 Claude 모델을 확인한 후 고정할 수 있게 합니다. 결과를 사용자 설정 파일의 env 블록에 저장하므로 환경 변수를 직접 내보낼 필요가 없습니다.

로그인한 후 언제든지 /setup-bedrock을 실행하여 마법사를 다시 열고 자격 증명, 지역 또는 모델 고정을 변경할 수 있습니다. 모델 고정 단계는 현재 고정된 모델에서 시작됩니다. 마법사는 ~/.claude/settings.json에 쓰거나 CLAUDE_CONFIG_DIR이 설정되어 있을 때 $CLAUDE_CONFIG_DIR/settings.json에 씁니다.

수동으로 설정

마법사 대신 환경 변수를 통해 Amazon Bedrock을 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃의 경우), 아래 단계를 따르십시오.

1. 사용 사례 세부 정보 제출

처음으로 Anthropic 모델을 호출하기 전에 사용 사례 세부 정보를 제출합니다. 이는 AWS 계정당 한 번 수행합니다.

  1. 아래에 설명된 올바른 IAM 권한이 있는지 확인합니다.
  2. Amazon Bedrock 콘솔로 이동합니다.
  3. Model catalog에서 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 프로필)

이 명령을 실행하기 전에 your-profile-name을 AWS 프로필의 이름으로 바꿉니다.

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

export AWS_PROFILE=your-profile-name

Claude Code는 프로필의 sso_region으로 명명된 IAM Identity Center 영역에서 역할 자격 증명을 요청합니다. 이는 Amazon Bedrock을 실행하는 영역과 일치할 필요가 없습니다. v2.1.207에서는 Amazon Bedrock 영역이 sso_region을 재정의했으므로 IAM Identity Center 인스턴스가 다른 영역에 있는 프로필은 Session token not found or invalid 오류로 인증에 실패했습니다.

옵션 D: AWS Management Console 자격 증명

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 기본 자격 증명 공급자 체인을 한 번 해결하고 해결된 자격 증명을 메모리에 유지합니다. 만료되기 5분 전까지 또는 만료 기한이 없을 때 1시간 동안 재사용하므로 SSO 기반 프로필은 자격 증명 수명당 약 한 번 IAM Identity Center에서 자격 증명을 요청합니다. API의 자격 증명 오류는 캐시를 지우고 재시도는 새로운 자격 증명을 해결합니다. Claude Code v2.1.207 이상이 필요합니다.

캐시는 공급자 체인을 사용하지 않는 Amazon Bedrock API 키를 제외한 위의 모든 자격 증명 옵션을 포함합니다. 대신 모든 요청에서 체인을 해결하려면 CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1을 설정합니다.

체인의 각 해결은 60초 후 시간 초과됩니다. 체인의 단계가 정지되면(예: 받을 수 없는 입력을 기다리는 credential_process 도우미), 요청은 AWS default-chain credential resolve timed out으로 실패합니다. 체인이 aws-vault와 같은 래퍼를 통한 MFA가 있는 브라우저 기반 SSO와 같이 합법적으로 더 오래 필요한 대화형 로그인을 실행하는 경우 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS를 사용하여 밀리초 단위로 제한을 높입니다. v2.1.207 이전에는 정지된 자격 증명 해결로 인해 요청이 무한정 대기했습니다.

고급 자격 증명 구성

Claude Code는 AWS SSO 및 회사 ID 공급자에 대한 자동 자격 증명 새로 고침을 지원합니다. Claude Code 설정 파일에 이러한 설정을 추가합니다(설정에서 파일 위치 참조).

이 두 설정은 다른 트리거 조건을 가집니다.

  • awsAuthRefresh: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탐프를 기반으로 로컬에서 또는 API가 자격 증명 오류를 반환할 때 실행되고 새로 고쳐진 자격 증명으로 요청을 재시도합니다.
  • awsCredentialExport: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Amazon Bedrock 계정이 기본 공급자 체인이 해결할 자격 증명과 다른 교차 계정 자격 증명을 요구할 때 이를 사용합니다.

awsAuthRefresh 명령을 실행하기 전에 Claude Code는 STS GetCallerIdentity 호출을 수행하여 자격 증명이 실제로 만료되었는지 확인하고 여전히 작동하는 경우 명령을 건너뜁니다. Claude Code는 프록시 구성을 통해 이 확인을 전송하여 HTTPS_PROXY 및 NO_PROXY를 준수합니다. v2.1.239 이전에는 Claude Code가 이 확인을 직접 전송했으며 프록시를 통해서만 송신을 허용하는 네트워크에서 시작 시 중단되었습니다.

예제 구성 
{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}
구성 설정 설명

awsAuthRefresh: .aws 디렉터리를 수정하는 명령(예: 자격 증명, SSO 캐시 또는 구성 파일 업데이트)에 이를 사용합니다. 명령의 출력이 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 이는 CLI가 URL 또는 코드를 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 SSO 흐름에 적합합니다.

awsCredentialExport: .aws를 수정할 수 없고 자격 증명을 직접 반환해야 하는 경우에만 이를 사용합니다. 출력은 자동으로 캡처되며 사용자에게 표시되지 않습니다. 명령은 다음 형식으로 JSON을 출력해야 합니다.

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

aws configure export-credentials --format process의 평면 출력도 허용되며, Credentials 아래에 중첩되지 않고 최상위 수준에 동일한 키가 있습니다.

Expiration은 선택 사항입니다. Claude Code v2.1.176부터 명령이 유효한 ISO 8601 Expiration을 반환하면 Claude Code는 해당 시간 5분 전까지 자격 증명을 캐시합니다. 없거나 이전 버전에서는 자격 증명이 1시간 동안 캐시됩니다.

awsCredentialExport를 awsAuthRefresh 없이 구성하면 Claude Code는 내보낸 자격 증명을 직접 사용하고 시작 시 AWS 기본 자격 증명 공급자 체인을 다시 해결하지 않습니다. Claude Code v2.1.206 이상이 필요합니다.

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을 활성화할 때 다음을 염두에 두십시오.

  • v2.1.172부터 AWS 프로필의 영역을 재정의하거나 프로필에 영역이 없을 때만 AWS_REGION을 설정하면 됩니다. Claude Code는 다음 순서로 영역을 해결합니다.

    • AWS_REGION
    • AWS_DEFAULT_REGION
    • AWS 공유 자격 증명 파일에서 먼저 읽은 다음 공유 구성 파일에서 읽은 활성 AWS 프로필에 설정된 region으로, AWS SDK 우선 순위와 일치합니다.
    • us-east-1

    이러한 소스의 값이 영역 이름처럼 형성되지 않으면 Claude Code는 이를 설정되지 않은 것으로 취급하고 순서를 계속 진행합니다. 예를 들어 Claude Code는 슬래시, 점 또는 공백을 포함하는 값을 설정되지 않은 것으로 취급합니다.

    활성 프로필은 설정된 경우 AWS_PROFILE이고, 그렇지 않으면 default입니다. AWS_SHARED_CREDENTIALS_FILE 또는 AWS_CONFIG_FILE을 설정하여 기본이 아닌 파일 경로를 가리킵니다.

    /status를 실행하여 해결된 영역을 확인합니다. 영역이 AWS 구성 파일 또는 기본 폴백에서 온 경우 Claude Code는 /status 출력에서 소스를 기록합니다. v2.1.171 이전에는 Claude Code가 AWS 구성 파일을 읽지 않으므로 AWS_REGION을 명시적으로 설정합니다.

  • Amazon Bedrock을 사용할 때 /logout 명령은 AWS 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.

  • WebSearch 도구는 Amazon Bedrock에서 사용할 수 없습니다. WebSearch 도구 동작을 참조하십시오.

  • 다른 프로세스에 유출되지 않으려는 AWS_PROFILE과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 설정을 참조하십시오.

4. 모델 버전 고정

이러한 환경 변수를 특정 Amazon Bedrock 모델 ID로 설정합니다.

ANTHROPIC_DEFAULT_OPUS_MODEL 없이 Amazon Bedrock의 opus 별칭은 Opus 5로 해결되고, ANTHROPIC_DEFAULT_SONNET_MODEL 없이 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. 접두사를 사용합니다.

기본 제공 기본 모델을 유지하고 선호하는 접두사만 변경하려면 고정 대신 ANTHROPIC_BEDROCK_REGION_PREFIX를 설정합니다. 차이는 opus 별칭이 해결되는 방식에 표시됩니다.

설정 opus 별칭이 해결되는 대상
ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8' us.anthropic.claude-opus-4-8, 고정한 정확한 ID
ANTHROPIC_BEDROCK_REGION_PREFIX=eu eu.anthropic.claude-opus-5, 선호하는 접두사가 있는 기본 제공 기본값

현재 및 레거시 모델 ID는 모델 개요를 참조하십시오. 고정 환경 변수의 전체 목록은 모델 구성을 참조하십시오.

고정 변수가 설정되지 않으면 Claude Code는 이러한 기본 모델을 사용합니다.

모델 유형 기본 모델
기본 모델 Opus 5, 예: us-* 영역의 us.anthropic.claude-opus-5
소형/빠른 모델 Sonnet 4.5, 예: us-* 영역의 us.anthropic.claude-sonnet-4-5-20250929-v1:0

세션 제목 생성과 같은 백그라운드 작업은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Amazon Bedrock에서 Claude Code는 모든 계정 또는 영역에서 Haiku를 사용하지 못할 수 있으므로 백그라운드 작업에 기본 Sonnet 모델을 사용합니다. 두 가지 선택이 어떤 모델이 이를 수행하는지 변경합니다.

  • --model, ANTHROPIC_MODEL 또는 model 설정으로 기본 모델을 선택하면 백그라운드 작업이 해당 모델을 사용합니다. Claude Code가 ANTHROPIC_DEFAULT_MODEL로 설정한 모델에서 세션을 시작하면 백그라운드 작업도 해당 모델을 사용합니다. ANTHROPIC_DEFAULT_SONNET_MODEL 없이 ANTHROPIC_DEFAULT_OPUS_MODEL을 설정하는 것도 선택으로 계산됩니다. 기본 제공 Sonnet 모델이 자체 Opus를 조종하는 계정에서 활성화되지 않을 수 있기 때문입니다.
  • 백그라운드 작업에 Haiku를 사용하려면 ANTHROPIC_DEFAULT_HAIKU_MODEL을 계정에서 사용 가능한 모델 ID로 설정합니다.

v2.1.207부터 v2.1.218에서 Amazon Bedrock의 기본 모델은 Opus 4.8로 기본값이 지정되었고 opus 별칭은 Opus 4.8로 해결되었습니다. v2.1.207 이전에는 기본 모델이 Sonnet 4.5로 기본값이 지정되었고, opus 별칭은 Opus 4.6으로 해결되었으며, 백그라운드 작업은 항상 기본 모델을 사용했습니다.

모델을 추가로 사용자 정의하려면 다음 방법 중 하나를 사용합니다.

# 추론 프로필 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'

# 선택 사항: 필요한 경우 프롬프트 캐싱 비활성화
# export DISABLE_PROMPT_CACHING=1

# 선택 사항: 5분 기본값 대신 1시간 프롬프트 캐시 TTL 요청
# export ENABLE_PROMPT_CACHING_1H=1

1시간 캐시 TTL은 5분 기본값보다 높은 요금으로 청구됩니다. 캐시 수명을 참조하십시오. 주 대화와 Claude Code가 외부에서 수행하는 요청에 대해 다른 TTL을 설정하려면 직접 TTL을 선택합니다.

각 모델 버전을 추론 프로필에 매핑

ANTHROPIC_DEFAULT_*_MODEL 환경 변수는 모델 제품군당 하나의 추론 프로필을 구성합니다. 조직이 /model 선택기에서 동일한 제품군의 여러 버전을 노출해야 하고 각각 자체 애플리케이션 추론 프로필 ARN으로 라우팅되는 경우 설정 파일에서 modelOverrides 설정을 대신 사용합니다.

이 예제는 4개의 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을 호출합니다. 동일한 매핑은 --model 또는 ANTHROPIC_MODEL을 통해 Anthropic 모델 ID를 직접 전달할 때 적용됩니다. 재정의가 없는 버전은 기본 제공 Amazon Bedrock 모델 ID 또는 시작 시 발견된 일치하는 추론 프로필로 폴백합니다. v2.1.200 이전에는 --model 및 ANTHROPIC_MODEL 값이 재정의 맵을 거치지 않고 Amazon Bedrock에 도달했습니다. 재정의가 availableModels 및 기타 모델 설정과 상호 작용하는 방식에 대한 자세한 내용은 버전별 모델 ID 재정의를 참조하십시오.

시작 모델 확인

Claude Code가 Amazon Bedrock으로 구성되어 시작될 때, 사용하려는 모델이 계정에서 액세스 가능한지 확인합니다.

이전 Claude Code 기본값보다 오래된 모델 버전을 고정했으며 계정에서 최신 버전을 호출할 수 있는 경우, Claude Code는 핀을 업데이트하도록 요청합니다. 수락하면 새 모델 ID가 사용자 설정 파일에 기록되고 Claude Code가 다시 시작됩니다. 거절하면 다음 기본 버전 변경까지 기억됩니다. 애플리케이션 추론 프로필 ARN을 가리키는 핀은 관리자가 관리하므로 건너뜁니다.

모델을 고정하지 않았으며 현재 기본값을 계정에서 사용할 수 없는 경우, Claude Code는 현재 세션에 대해 폴백하고 알림을 표시합니다. 먼저 기본 모델의 이전 버전을 시도하고, 기본값이 Opus 모델이며 사용 가능한 Opus 버전이 없을 때 기본 Sonnet 모델로 폴백합니다. 폴백은 유지되지 않습니다. Amazon Bedrock 계정에서 최신 모델을 활성화하거나 버전을 고정하여 선택을 영구적으로 만듭니다.

특정 Sonnet 또는 Opus 버전에서 세션을 시작할 때(예: --model, ANTHROPIC_MODEL 또는 model 설정을 사용하여), 해당 버전은 일치하는 sonnet 또는 opus 별칭에 대한 세션의 고정된 기본값으로 작동합니다. Claude Code는 모델이 대체하는 기본 제공 기본값에 대한 가용성 확인을 건너뛰고 구성한 모델에서 시작하며, 폴백 알림이 없습니다.

opus와 같은 모델 별칭은 핀으로 작동하지 않으며, Claude Code가 인식하지 못하는 모델 ID(예: 애플리케이션 추론 프로필 ARN)도 마찬가지입니다.

교차 지역 추론 프로필 접두사

Amazon Bedrock Invoke API에서 Claude Code는 기본 제공 기본 모델을 교차 지역 추론 프로필 ID로 확인합니다. 모델 버전을 자신의 추론 프로필을 통해 라우팅하려면 각 모델 버전을 추론 프로필에 매핑을 참조하십시오. 이 표는 Claude Code가 각 확인된 AWS 지역에 대해 선호하는 접두사를 보여줍니다:

AWS 지역 접두사
us-gov-* (AWS GovCloud) us-gov.
us-* us.
eu-* eu.
ap-* apac.
기타 모든 지역 global.

Claude Code가 먼저 시도할 접두사를 선택하려면 ANTHROPIC_BEDROCK_REGION_PREFIX를 설정하십시오. Claude Code가 프로필 가용성을 확인할 수 있고 모델에 대해 일치하는 프로필을 찾지 못하면 아래 설명된 확인 순서에 따라 폴백됩니다. 유효한 값은 us, eu, apac, jp, au, 및 global입니다. 예를 들어, 계정에 global. 프로필이 활성화되어 있지만 Claude Code가 AWS 지역에서 지역별 프로필을 도출할 때 이를 global로 설정하십시오. Claude Code v2.1.224 이상이 필요합니다.

이 예제는 기본 모델을 global. 프로필을 통해 라우팅합니다:

export ANTHROPIC_BEDROCK_REGION_PREFIX=global
# us-* 지역에서 기본 모델은 이제
# us.anthropic.claude-opus-5 대신
# global.anthropic.claude-opus-5로 확인됩니다

선호하는 접두사는 지역에서 오든 변수에서 오든 선호도이지 보장이 아닙니다. Claude Code가 이를 적용하는 방식은 계정의 프로필 가용성을 확인할 수 있는지 여부에 따라 달라집니다:

  • Claude Code가 계정의 추론 프로필을 나열할 수 있을 때, 각 모델을 다음 순서로 확인합니다:
    1. 선호하는 접두사가 있는 프로필입니다.
    2. 해당 접두사가 있는 프로필이 없는 모델에 대해 일치하는 모든 프로필입니다.
    3. 일치하는 프로필이 전혀 없는 모델에 대해 선호하는 접두사가 있는 기본 제공 모델 ID입니다. Claude Code는 이 단계에서 가용성을 확인하지 않고 이 ID를 적용합니다. 시작 모델 확인은 여전히 세션의 기본 모델을 포함합니다.
  • 프로필 검색을 사용할 수 없을 때, Claude Code는 가용성을 확인하지 않고 접두사를 적용합니다. 계정에 해당 접두사가 있는 추론 프로필이 활성화되어 있지 않으면 요청이 400 오류로 실패합니다.

Claude Code는 직접 구성한 Amazon Bedrock 추론 프로필 ID 또는 ARN을 다시 작성하지 않으며, modelOverrides 값도 다시 작성하지 않습니다. Anthropic 형식 모델 ID는 /model 선택기와 동일한 매핑을 통해 확인됩니다. Claude Code는 또한 두 가지 경우에 변수를 무시합니다:

  • AWS GovCloud 지역에서 Claude Code는 항상 us-gov.를 사용합니다. 이는 GovCloud 파티션 내에서 라우팅하는 유일한 접두사입니다.
  • 유효한 값 중 하나가 아닌 값을 설정할 때, Claude Code는 지역에서 도출된 선호하는 접두사로 폴백됩니다.

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는 대체 형태로 한 번 재시도하여 자동으로 복구되므로 요청은 여전히 성공하지만 각 새로운 모델은 추가 왕복을 추가합니다. 권한을 부여하면 재시도를 피할 수 있습니다. 이는 토큰의 정책이 일반적으로 전체 IAM 역할보다 좁은 AWS_BEARER_TOKEN_BEDROCK 배포에 가장 자주 적용됩니다.

자세한 내용은 Amazon Bedrock IAM 설명서를 참조하십시오.

1M 토큰 컨텍스트 윈도우

Claude Sonnet 5, Opus 4.6 이상 및 Sonnet 4.6은 Amazon Bedrock에서 1M 토큰 컨텍스트 윈도우를 지원합니다. Sonnet 5는 Invoke API와 Mantle 엔드포인트 모두에서 항상 1M 윈도우로 실행되며, 선택할 [1m] 변형이 없습니다. Invoke API의 다른 모델의 경우, Claude Code는 1M 모델 변형을 선택할 때 확장된 컨텍스트 윈도우를 자동으로 활성화합니다.

설정 마법사는 모델을 고정할 때 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"
  }
}

조직에서 Claude 앱 게이트웨이 정책을 통해 guardrail 헤더를 전달하는 경우, 이는 승인이 필요한 설정으로 계산됩니다.

Mantle 엔드포인트 사용

Mantle은 Bedrock Invoke API 대신 기본 Anthropic API 형태를 통해 Claude 모델을 제공하는 Amazon Bedrock 엔드포인트입니다. 이 페이지의 앞부분에서 설명한 동일한 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을 구성합니다. 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

Mantle 모델을 /model 선택기에 표시하려면 설정 파일의 availableModels에 ID를 나열하십시오. 이 설정은 선택기를 나열된 항목으로 제한하므로 유지하려는 버전 접두사 또는 전체 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 라우팅

조직이 모델 트래픽을 AWS 자격 증명을 서버 측에 주입하는 중앙 집중식 LLM 게이트웨이를 통해 라우팅하는 경우 클라이언트 측 인증을 비활성화하여 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 지역 재정의(Amazon Bedrock과 공유)

문제 해결

SSO 및 회사 프록시를 사용한 인증 루프

AWS SSO를 사용할 때 브라우저 탭이 반복적으로 생성되면 설정 파일에서 awsAuthRefresh 설정을 제거하십시오. 이는 회사 VPN 또는 TLS 검사 프록시가 SSO 브라우저 흐름을 중단할 때 발생할 수 있습니다. Claude Code는 중단된 연결을 인증 실패로 취급하고 awsAuthRefresh를 다시 실행하여 무한 루프를 발생시킵니다.

네트워크 환경이 자동 브라우저 기반 SSO 흐름을 방해하는 경우 awsAuthRefresh에 의존하는 대신 Claude Code를 시작하기 전에 aws sso login을 수동으로 사용하십시오.

지역 문제

지역 문제가 발생하는 경우:

  • 모델 가용성 확인: aws bedrock list-inference-profiles --region your-region
  • 지원되는 지역으로 전환: export AWS_REGION=us-east-1
  • 교차 지역 액세스를 위해 추론 프로필 사용 고려

"on-demand throughput isn't supported" 오류가 발생하는 경우:

Claude Code는 Amazon Bedrock Invoke API를 사용하며 Converse API를 지원하지 않습니다.

게이트웨이 또는 프록시 뒤의 스트리밍 오류

Amazon Bedrock은 InvokeModelWithResponseStream 응답을 Content-Type: application/vnd.amazon.eventstream 헤더가 있는 바이너리 이벤트 스트림 형식으로 스트리밍합니다. Claude Code와 Amazon Bedrock 사이의 게이트웨이 또는 프록시는 응답 본문과 Content-Type을 포함한 헤더를 Amazon Bedrock이 보낸 그대로 전달해야 합니다.

게이트웨이가 Content-Type을 다른 값으로 다시 쓰면 Claude Code는 Bedrock streaming response has content-type으로 시작하는 오류로 응답을 거부하며, 수신한 값을 이름으로 지정합니다. 일반적인 다시 쓰기는 스트림을 서버 전송 이벤트로 다시 내보내는 통합에서 text/event-stream입니다.

게이트웨이가 헤더를 삭제하거나 비우면 Claude Code는 본문이 Amazon Bedrock의 이벤트 스트림이라고 가정하고 디코딩하므로 게이트웨이가 수정되지 않은 상태로 전달한 본문은 계속 스트리밍됩니다.

헤더를 삭제하는 게이트웨이가 스트림을 서버 전송 이벤트로 다시 내보내면 Claude Code는 본문을 디코딩할 수 없고 모든 턴에서 더 느린 비스트리밍 경로로 폴백합니다. 각 응답은 스트리밍되는 대신 완료된 후에만 나타납니다. 이 경우 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT=1을 설정하여 Claude Code가 본문을 서버 전송 이벤트로 읽도록 하십시오.

오류 또는 폴백을 해결하려면 게이트웨이를 구성하여 InvokeModelWithResponseStream 응답 본문과 해당 Content-Type 헤더를 수정되지 않은 상태로 전달하십시오.

스트림을 서버 전송 이벤트로 변환하는 게이트웨이는 더 이상 Amazon Bedrock API를 제공하지 않습니다. Anthropic Messages API 요청도 수락하면 CLAUDE_CODE_USE_BEDROCK 대신 ANTHROPIC_BASE_URL을 사용하여 LLM 게이트웨이로 연결하십시오.

/context의 0 토큰 개수

/context 명령은 도구 스키마를 Amazon Bedrock count-tokens API로 전송하여 각 도구 그룹의 토큰을 계산합니다. v2.1.196 이전의 Claude Code 버전에서는 Amazon Bedrock이 스키마가 count-tokens API에서 허용하지 않는 필드를 포함하고 있어서 해당 요청을 거부했으므로 모든 도구 그룹이 0 토큰을 표시했습니다. 메시지 및 메모리 파일과 같은 분석의 다른 행은 영향을 받지 않습니다.

v2.1.196 이상으로 업데이트하십시오.

Mantle 엔드포인트 오류

CLAUDE_CODE_USE_MANTLE을 설정한 후 /status에 Amazon Bedrock (Mantle)이 표시되지 않으면 변수가 프로세스에 도달하지 않습니다. Claude Code를 시작한 셸에서 내보내졌는지 확인하거나 설정 파일의 env 블록에 설정하십시오.

유효한 자격 증명이 있는 Mantle 엔드포인트의 403은 AWS 계정이 요청한 모델에 대한 액세스 권한을 부여받지 않았음을 의미합니다. 액세스를 요청하려면 AWS 계정 팀에 문의하십시오.

모델 ID를 이름으로 지정하는 400은 해당 모델이 Mantle에서 제공되지 않음을 의미합니다. Mantle은 표준 Amazon Bedrock 카탈로그와 별개의 자체 모델 라인업을 가지고 있으므로 us.anthropic.claude-sonnet-4-6과 같은 추론 프로필 ID는 작동하지 않습니다. Mantle 형식 ID를 사용하거나 두 엔드포인트를 모두 활성화하여 Claude Code가 각 요청을 모델을 사용할 수 있는 엔드포인트로 라우팅하도록 하십시오.

추가 리소스