Claude Code on Amazon Bedrock

Claude Code를 Amazon Bedrock을 통해 사용하도록 구성하는 방법을 다루는 가이드예요. AWS 계정과 IAM 설정, 모델 버전 고정, 트러블슈팅까지 포함해요. 자신의 Bedrock 자격 증명으로 로그인하려면 로그인 마법사를, 팀 전체에 배포하려면 수동 설정과 모델 버전 고정을 먼저 확인하세요.

출처: 공식문서

본문

전제조건

Amazon Bedrock 접근이 활성화된 AWS 계정
Amazon Bedrock에서 원하는 Claude 모델(예: Claude Sonnet 4.6) 접근 권한
AWS CLI 설치·구성(선택, 다른 자격 증명 메커니즘이 있으면 불필요)
적절한 IAM 권한

Bedrock으로 로그인

AWS 자격 증명이 있고 Claude Code를 Bedrock으로 쓰기 시작하려면 로그인 마법사가 안내해요. AWS 쪽 전제조건은 계정당 한 번, 마법사가 Claude Code 쪽을 처리해요.

AWS 계정에서 Anthropic 모델 활성화 — Amazon Bedrock 콘솔의 Model catalog에서 Anthropic 모델을 선택하고 use case form 제출(제출 즉시 승인).
Claude Code 실행 후 Amazon Bedrock 선택 — claude 실행 후 로그인 프롬프트에서 3rd-party platform → Amazon Bedrock. 이미 로그인돼 있으면 /setup-bedrock으로 마법사 실행. CLAUDE_CODE_USE_BEDROCK=1이 설정되기 전엔 이 명령이 커맨드 메뉴에 숨겨지니 전체 입력.
마법사 프롬프트 따라가기 — ~/.aws에서 감지된 AWS 프로필, Bedrock API 키, access key/secret, 환경의 기존 자격 증명 중 선택. 지역 확인, 계정이 호출 가능한 Claude 모델 검증, 고정(pin) 허용. 결과를 사용자 설정 파일의 env 블록에 저장하므로 환경변수를 직접 export할 필요 없어요.

로그인 후엔 /setup-bedrock으로 언제든 자격 증명·지역·모델 고정을 바꿀 수 있어요. 마법사는 ~/.claude/settings.json(또는 CLAUDE_CONFIG_DIR 설정 시 $CLAUDE_CONFIG_DIR/settings.json)에 써요.

수동 설정

원문대로 CI·스크립트 배포 등 환경변수로 구성하려면 아래를 따라요.

1. use case 세부정보 제출 — Anthropic 모델을 처음 호출하기 전에 계정당 한 번. Bedrock 콘솔 → Model catalog → Anthropic 모델 선택 → form 작성(즉시 승인). AWS Organizations를 쓰면 관리 계정에서 PutUseCaseForModelAccess API로 한 번 제출하고 자식 계정에 자동 승인할 수 있어요(bedrock:PutUseCaseForModelAccess IAM 권한 필요).

2. AWS 자격 증명 구성 — Claude Code는 기본 AWS SDK credential chain을 사용해요.

Option A (AWS CLI): aws configure
Option B (환경변수 access key): export AWS_ACCESS_KEY_ID=..., AWS_SECRET_ACCESS_KEY=..., AWS_SESSION_TOKEN=...
Option C (SSO 프로필): aws sso login --profile=your-profile-name + export AWS_PROFILE=your-profile-name. Claude Code는 프로필의 sso_region으로 명명된 IAM Identity Center 지역에서 역할 자격 증명을 요청하는데, Bedrock을 실행하는 지역과 일치할 필요는 없어요.
Option D (콘솔 자격 증명): aws login
Option E (Bedrock API 키): export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key — 전체 AWS 자격 증명 없이 더 간단한 인증 제공.

자격 증명 캐싱·해석 타임아웃: Claude Code는 AWS 기본 credential provider chain을 한 번 해석해 메모리에 보관하고, 만료 5분 전까지 또는 만료가 없을 때 1시간 동안 재사용해요. API의 자격 증명 오류는 캐시를 지우고 재시도가 새 자격 증명을 해석해요(v2.1.207+). 매 요청마다 chain을 해석하려면 CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1. 각 chain 해석은 60초 후 타임아웃. 인터랙티브 서명(예: MFA 있는 브라우저 SSO)이 더 필요하면 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS로 밀리초 한도를 올려요.

고급 자격 증명 구성:

awsAuthRefresh: AWS 자격 증명이 만료됐을 때만 실행(타임스탬프 기반 또는 API credential error), 그 후 갱신된 자격 증명으로 요청 재시도.
awsCredentialExport: 세션 시작·자격 증명 재로드마다 실행(기본 chain 자격 증명이 유효해도). .aws를 수정할 수 없고 자격 증명을 직접 반환해야 할 때만 사용. 출력은 다음 JSON 형식이어야 해요.

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

Expiration은 선택(ISO 8601이면 만료 5분 전까지 캐시, 없으면 1시간). v2.1.181부터 aws configure export-credentials --format process의 flat 출력도 허용.

예시:

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

3. Claude Code 구성

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # optional if your AWS profile already sets a region

# Optional: Override the AWS region for the small/fast model (Bedrock and Mantle).
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

AWS_REGION은 프로필 지역을 덮어쓰거나 프로필에 지역이 없을 때만 설정하면 돼요. 지역 해석 순서: AWS_REGION → AWS_DEFAULT_REGION → 활성 AWS 프로필의 region(공유 자격 증명 파일 먼저, 그다음 공유 설정 파일) → us-east-1. 활성 프로필은 AWS_PROFILE(설정 시) 또는 default. /status로 해석된 지역을 확인할 수 있어요. 유의점: Bedrock 사용 시 /logout은 사용 불가(AWS 자격 증명으로 인증하므로), WebSearch 도구는 Bedrock에서 사용 불가.

4. 모델 버전 고정

여러 사용자에게 배포할 땐 특정 모델 버전을 고정해야 해요. 고정하지 않으면 sonnet·opus 같은 별칭이 Bedrock용 내장 기본값으로 해석되는데, 최신 릴리스보다 늦을 수 있고 계정에서 아직 활성화되지 않았을 수 있어요. 예시:

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를 설정하세요. 고정하지 않았을 때 기본: Primary model = Opus 5(예: us-* 지역에서 us.anthropic.claude-opus-5), Small/fast model = Sonnet 4.5.

백그라운드 작업(세션 제목 생성)은 보통 Haiku급 small/fast 모델을 쓰는데, Bedrock에선 Haiku가 모든 계정/지역에 활성화돼 있지 않을 수 있어 기본 Sonnet 모델을 써요. --model/ANTHROPIC_MODEL/model 설정으로 primary 모델을 선택하거나 ANTHROPIC_DEFAULT_HAIKU_MODEL로 Haiku를 지정하면 바꿀 수 있어요.

프롬프트 캐싱은 자동 활성화. 끄려면 DISABLE_PROMPT_CACHING=1, 1시간 TTL은 ENABLE_PROMPT_CACHING_1H=1(높은 요율로 청구).

모델 버전을 추론 프로필에 매핑: ANTHROPIC_DEFAULT_*_MODEL은 모델 패밀리당 하나의 추론 프로필을 구성해요. 같은 패밀리의 여러 버전을 각각 다른 애플리케이션 추론 프로필 ARN으로 /model 피커에 노출해야 한다면 modelOverrides 설정을 쓰세요. 예:

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

5. 시작 시 모델 검사 — Claude Code가 Bedrock으로 시작할 때 의도한 모델이 계정에서 접근 가능한지 검증해요. 고정 버전이 현재 기본보다 오래되고 계정이 새 버전을 호출할 수 있으면 고정 업데이트를 제안해요. 고정하지 않았고 기본이 계정에서 없으면 이번 세션에 한해 폴백(기본의 이전 버전 먼저, Opus->Sonnet)하고 알림을 보여줘요.

크로스리전 추론 프로필 접두사: Bedrock Invoke API에서 Claude Code는 내장 기본 모델을 크로스리전 추론 프로필 ID로 해석해요. 지역별 기본 접두사: us-gov-*→us-gov., us-*→us., eu-*→eu., ap-*→apac., 기타→global.. ANTHROPIC_BEDROCK_REGION_PREFIX로 먼저 시도할 접두사를 고를 수 있고(유효값 us,eu,apac,jp,au,global, v2.1.224+). GovCloud에선 항상 us-gov..

6. IAM 구성 — 다음 권한을 포함하는 IAM 정책을 만들어요: bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, bedrock:ListInferenceProfiles, bedrock:GetInferenceProfile, aws-marketplace:ViewSubscriptions, aws-marketplace:Subscribe(조건 aws:CalledViaLast: bedrock.amazonaws.com). bedrock:GetInferenceProfile은 애플리케이션 추론 프로필 ARN을 백업 foundation model로 해석하는 데 쓰여요. 더 제한하려면 Resource를 특정 추론 프로필 ARN으로 한정하세요.

1M 토큰 컨텍스트 창: Claude Sonnet 5, Opus 4.6+, Sonnet 4.6은 Bedrock에서 1M 토큰 컨텍스트 창을 지원해요. Sonnet 5는 항상 1M 창으로 실행(선택할 [1m] 변형 없음). 수동 고정 모델에선 모델 ID에 [1m]을 붙이면 돼요.

서비스 티어: ANTHROPIC_BEDROCK_SERVICE_TIER를 default, flex, priority로 설정해 비용과 지연을 트레이드오프할 수 있어요. 각 요청의 X-Amzn-Bedrock-Service-Tier 헤더로 전송.

AWS Guardrails: Amazon Bedrock Guardrails로 콘텐츠 필터링을 구현할 수 있어요. Guardrail을 만들고 버전 발행 후 설정 파일에 헤더를 추가해요.

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

Mantle 엔드포인트: Mantle은 네이티브 Anthropic API 형태로 Claude 모델을 서빙하는 Bedrock 엔드포인트예요(Invoke API 대신). CLAUDE_CODE_USE_MANTLE=1로 활성화. 모델은 anthropic. 접두사에 버전 접미사 없는 ID(예: anthropic.claude-sonnet-5, anthropic.claude-haiku-4-5)를 써요. --model anthropic.claude-haiku-4-5처럼 선택. CLAUDE_CODE_USE_BEDROCK=1과 CLAUDE_CODE_USE_MANTLE=1을 함께 설정하면 같은 세션에서 두 엔드포인트를 호출하고, Mantle 형식 ID는 Mantle로, 나머지는 Invoke API로 라우팅돼요.

트러블슈팅

SSO·기업 프록시 인증 루프: 브라우저 탭이 반복해서 뜨면 awsAuthRefresh 설정을 제거하세요(VPN·TLS 검사 프록시가 SSO 흐름을 방해). 자동 SSO가 방해받으면 aws sso login을 수동으로 실행하세요.
지역 문제: 모델 가용성 확인 aws bedrock list-inference-profiles --region your-region, 지원 지역으로 전환 export AWS_REGION=us-east-1, on-demand throughput isn't supported 오류면 모델을 추론 프로필 ID로 지정.
게이트웨이 뒤 스트리밍 오류: Bedrock은 Content-Type: application/vnd.amazon.eventstream의 바이너리 이벤트 스트림으로 응답해요. 게이트웨이가 이 헤더를 바꾸면 Claude Code가 거부하고, text/event-stream으로 다시 내보내면 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT=1로 SSE로 읽히게 할 수 있어요. 게이트웨이가 Anthropic Messages API도 받는다면 CLAUDE_CODE_USE_BEDROCK 대신 ANTHROPIC_BASE_URL로 LLM 게이트웨이로 연결하세요.
/context의 0 토큰: v2.1.196 이전 버전은 도구 스키마 필드 때문에 카운트 API가 거부돼 0이었어요. v2.1.196 이상으로 업데이트.

더 알아보기

Amazon Bedrock documentation
Amazon Bedrock pricing
Amazon Bedrock inference profiles
Claude Code on Amazon Bedrock: Quick Setup Guide
Model configuration: 모델 고정·기본값