Amazon Bedrock에서 Claude Code

설정, IAM 구성 및 문제 해결을 포함하여 Amazon Bedrock을 통해 Claude Code를 구성하는 방법을 알아보세요.

전제 조건

Bedrock으로 Claude Code를 구성하기 전에 다음 사항을 확인하세요:

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

설정

1. 모델 액세스 활성화

먼저 AWS 계정에서 필요한 Claude 모델에 대한 액세스 권한이 있는지 확인하세요:

1. Amazon Bedrock 콘솔로 이동
2. 왼쪽 탐색에서 Model access로 이동
3. 원하는 Claude 모델(예: Claude Sonnet 4)에 대한 액세스 요청
4. 승인 대기 (대부분의 지역에서 일반적으로 즉시 승인)

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 설정 파일에 이러한 설정을 추가하세요 (파일 위치는 Settings 참조).

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을 사용할 때 인증이 AWS 자격 증명을 통해 처리되므로 /login 및 /logout 명령이 비활성화됩니다.
• 다른 프로세스에 누출되지 않도록 하려는 AWS_PROFILE과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 Settings를 참조하세요.

4. 모델 구성

Claude Code는 Bedrock에 대해 다음 기본 모델을 사용합니다:

모델 유형	기본값
기본 모델	us.anthropic.claude-3-7-sonnet-20250219-v1:0
소형/고속 모델	us.anthropic.claude-3-5-haiku-20241022-v1:0

모델을 사용자 정의하려면 다음 방법 중 하나를 사용하세요:

# 추론 프로필 ID 사용
export ANTHROPIC_MODEL='us.anthropic.claude-opus-4-1-20250805-v1:0'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-3-5-haiku-20241022-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": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*"
      ]
    }
  ]
}

더 제한적인 권한의 경우 Resource를 특정 추론 프로필 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” 오류가 발생하는 경우:

• 모델을 추론 프로필 ID로 지정

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

추가 리소스

• Bedrock 문서
• Bedrock 가격
• Bedrock 추론 프로필
• Claude Code on Amazon Bedrock: Quick Setup Guide