Amazon Bedrock의 Claude Code

필수 조건

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

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

Claude Code를 여러 사용자에게 배포하는 경우 Anthropic이 새 모델을 출시할 때 중단을 방지하기 위해 모델 버전을 고정하십시오.

설정

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

Anthropic 모델의 첫 사용자는 모델을 호출하기 전에 사용 사례 세부 정보를 제출해야 합니다. 이는 계정당 한 번 수행됩니다.

올바른 IAM 권한이 있는지 확인하십시오(아래에서 자세히 알아보기)
Amazon Bedrock 콘솔로 이동하십시오
Chat/Text playground를 선택하십시오
모든 Anthropic 모델을 선택하면 사용 사례 양식을 작성하라는 메시지가 표시됩니다

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 Management Console 자격 증명

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 및 회사 ID 공급자에 대한 자동 자격 증명 새로 고침을 지원합니다. Claude Code 설정 파일에 이러한 설정을 추가하십시오(설정에서 파일 위치 참조). Claude Code가 AWS 자격 증명이 만료되었음을 감지하면(타임스탬프를 기반으로 로컬에서 또는 Bedrock이 자격 증명 오류를 반환할 때), 요청을 다시 시도하기 전에 새 자격 증명을 얻기 위해 구성된 awsAuthRefresh 및/또는 awsCredentialExport 명령을 자동으로 실행합니다.

예제 구성

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

3. Claude Code 구성

Bedrock을 활성화하려면 다음 환경 변수를 설정하십시오:

# Bedrock 통합 활성화
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # 또는 선호하는 지역

# 선택 사항: 소형/빠른 모델(Haiku)의 지역 재정의
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

Claude Code에 대해 Bedrock을 활성화할 때 다음을 염두에 두십시오:

AWS_REGION은 필수 환경 변수입니다. Claude Code는 이 설정에 대해 .aws 구성 파일을 읽지 않습니다.
Bedrock을 사용할 때 /login 및 /logout 명령은 AWS 자격 증명을 통해 인증이 처리되므로 비활성화됩니다.
다른 프로세스에 유출되지 않도록 하려는 AWS_PROFILE과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 설정을 참조하십시오.

4. 모델 버전 고정

모든 배포에 대해 특정 모델 버전을 고정하십시오. 모델 별칭(sonnet, opus, haiku)을 고정하지 않고 사용하면 Claude Code가 Bedrock 계정에서 사용할 수 없는 최신 모델 버전을 사용하려고 시도하여 Anthropic이 업데이트를 출시할 때 기존 사용자가 중단될 수 있습니다.

이러한 환경 변수를 특정 Bedrock 모델 ID로 설정하십시오:

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'
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는 이러한 기본 모델을 사용합니다:

모델 유형	기본값
기본 모델	`global.anthropic.claude-sonnet-4-6`
소형/빠른 모델	`us.anthropic.claude-haiku-4-5-20251001-v1:0`

모델을 추가로 사용자 정의하려면 다음 방법 중 하나를 사용하십시오:

# 추론 프로필 ID 사용
export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'
export ANTHROPIC_SMALL_FAST_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

프롬프트 캐싱은 모든 지역에서 사용할 수 없을 수 있습니다.

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

ANTHROPIC_DEFAULT_*_MODEL 환경 변수는 모델 제품군당 하나의 추론 프로필을 구성합니다. 조직이 /model 선택기에서 동일한 제품군의 여러 버전을 노출하고 각각 자신의 애플리케이션 추론 프로필 ARN으로 라우팅해야 하는 경우 설정 파일에서 modelOverrides 설정을 대신 사용하십시오. 이 예제는 세 개의 Opus 버전을 고유한 ARN에 매핑하므로 사용자는 조직의 추론 프로필을 우회하지 않고 버전 간에 전환할 수 있습니다:

{
  "modelOverrides": {
    "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 또는 시작 시 발견된 일치하는 추론 프로필로 폴백됩니다. 재정의가 availableModels 및 기타 모델 설정과 상호 작용하는 방식에 대한 자세한 내용은 버전별 모델 ID 재정의를 참조하십시오.

IAM 구성

Claude Code에 필요한 권한이 있는 IAM 정책을 만드십시오:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles"
      ],
      "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 IAM 설명서를 참조하십시오.

비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code용 전용 AWS 계정을 만드십시오.

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

문제 해결

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

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

“on-demand throughput isn’t supported” 오류가 발생하는 경우:

모델을 추론 프로필 ID로 지정하십시오

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

배포

​필수 조건

​설정

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

​2. AWS 자격 증명 구성

​고급 자격 증명 구성

예제 구성

구성 설정 설명

​3. Claude Code 구성

​4. 모델 버전 고정

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

​IAM 구성

​AWS Guardrails

​문제 해결

​추가 리소스

필수 조건

설정

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

2. AWS 자격 증명 구성

고급 자격 증명 구성

3. Claude Code 구성

4. 모델 버전 고정

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

IAM 구성

AWS Guardrails

문제 해결

추가 리소스