메인 콘텐츠로 건너뛰기

​
필수 조건

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

​
설정

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

Anthropic 모델의 첫 사용자는 모델을 호출하기 전에 사용 사례 세부 정보를 제출해야 합니다. 이는 계정당 한 번 수행됩니다.
  1. 올바른 IAM 권한이 있는지 확인하세요(아래에서 자세히 알아보기)
  2. Amazon Bedrock 콘솔로 이동하세요
  3. Chat/Text playground 선택
  4. 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: 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가 브라우저에 입력할 코드를 표시하는 브라우저 기반 인증 흐름에 적합합니다. 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. 모델 구성

Claude Code는 Bedrock에 대해 다음 기본 모델을 사용합니다:
모델 유형기본값
기본 모델global.anthropic.claude-sonnet-4-5-20250929-v1:0
소형/빠른 모델us.anthropic.claude-haiku-4-5-20251001-v1:0
Bedrock 사용자의 경우 Claude Code는 Haiku 3.5에서 Haiku 4.5로 자동 업그레이드되지 않습니다. 최신 Haiku 모델로 수동으로 전환하려면 ANTHROPIC_DEFAULT_HAIKU_MODEL 환경 변수를 전체 모델 이름(예: us.anthropic.claude-haiku-4-5-20251001-v1:0)으로 설정하세요.
모델을 사용자 정의하려면 다음 방법 중 하나를 사용하세요: 
# 추론 프로필 ID 사용
export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0'
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
프롬프트 캐싱은 모든 지역에서 사용 가능하지 않을 수 있습니다

​
5. 출력 토큰 구성

Amazon Bedrock과 함께 Claude Code를 사용할 때 다음 토큰 설정을 권장합니다: 
# Bedrock에 권장되는 출력 토큰 설정
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
export MAX_THINKING_TOKENS=1024
이러한 값을 사용하는 이유:
  • CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096: Bedrock의 번다운 스로틀링 로직은 최소 4096 토큰을 max_token 페널티로 설정합니다. 이를 더 낮게 설정해도 비용이 줄어들지 않지만 긴 도구 사용을 중단하여 Claude Code 에이전트 루프가 지속적으로 실패할 수 있습니다. Claude Code는 일반적으로 확장 사고 없이 4096개 미만의 출력 토큰을 사용하지만 상당한 파일 생성 또는 Write 도구 사용과 관련된 작업을 위해 이 여유 공간이 필요할 수 있습니다.
  • MAX_THINKING_TOKENS=1024: 이는 도구 사용 응답을 중단하지 않으면서 확장 사고를 위한 공간을 제공하면서도 집중된 추론 체인을 유지합니다. 이 균형은 특히 코딩 작업에 항상 도움이 되지 않는 궤적 변화를 방지하는 데 도움이 됩니다.

​
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 bedrock list-inference-profiles --region your-region
  • 지원되는 지역으로 전환: export AWS_REGION=us-east-1
  • 교차 지역 액세스를 위해 추론 프로필 사용 고려
“on-demand throughput isn’t supported” 오류가 발생하면: Claude Code는 Bedrock Invoke API를 사용하며 Converse API를 지원하지 않습니다.

​
추가 리소스