Amazon Bedrock 통합

Amazon Bedrock을 통해 Claude Code를 배포하면 AWS 네이티브 인프라에서 IAM 정책, CloudTrail 감사 로그, AWS Cost Explorer를 활용한 비용 추적을 사용할 수 있습니다. 이 가이드는 Bedrock 통합의 전체 설정 과정을 안내합니다.

사전 요구사항

Amazon Bedrock으로 Claude Code를 구성하기 전에 다음을 준비해야 합니다.

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

옵션 E: Bedrock API 키

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API 키는 전체 AWS 자격증명 없이도 더 간단한 인증 방법을 제공합니다.

고급 자격증명 구성 (자동 갱신)

Claude Code는 AWS SSO 및 기업용 ID 제공업체에 대한 자동 자격증명 갱신을 지원합니다. Claude Code 설정 파일에 다음 설정을 추가합니다.

Claude Code가 AWS 자격증명이 만료된 것을 감지하면(로컬 타임스탬프 기반 또는 Bedrock이 자격증명 오류를 반환할 때), 요청을 재시도하기 전에 구성된 awsAuthRefresh 및/또는 awsCredentialExport 명령을 자동으로 실행하여 새 자격증명을 획득합니다.

예시 구성 (claude_code_settings.json):

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

구성 설정 설명:

awsAuthRefresh: 자격증명, SSO 캐시, 또는 구성 파일 업데이트 등 .aws 디렉터리를 수정하는 명령에 사용합니다. 명령 출력은 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 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

Bedrock에서 Claude Code를 활성화할 때 다음 사항을 유의합니다.

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

4단계: 모델 버전 고정

모든 배포에 특정 모델 버전을 고정해야 합니다. 버전을 고정하지 않고 모델 별칭(sonnet, opus, haiku)을 사용하면, Anthropic이 업데이트를 출시할 때 Bedrock 계정에서 사용 불가능한 새 모델 버전을 사용하려 시도하여 기존 사용자에게 장애가 발생할 수 있습니다.

다음 환경 변수를 특정 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. 접두사 포함)를 사용합니다. 다른 리전 접두사나 애플리케이션 추론 프로필을 사용하는 경우 그에 맞게 조정합니다.

버전 고정 미설정 시 기본 모델:

모델 유형	기본값
기본 모델	`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

프롬프트 캐싱은 모든 리전에서 사용 가능하지 않을 수 있습니다.

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

더 제한적인 권한을 위해 Resource를 특정 추론 프로필 ARN으로 제한할 수 있습니다.

비용 추적 및 접근 제어를 간소화하려면 Claude Code 전용 AWS 계정을 생성하는 것을 권장합니다.

AWS Guardrails 구성

Amazon Bedrock Guardrails를 사용하면 Claude Code에 대한 콘텐츠 필터링을 구현할 수 있습니다.

Amazon Bedrock 콘솔에서 Guardrail을 생성합니다.
버전을 게시합니다.
설정 파일에 Guardrail 헤더를 추가합니다.

교차 리전 추론 프로필을 사용하는 경우 Guardrail에서 교차 리전 추론을 활성화해야 합니다.

예시 구성 (claude_code_settings.json):

{
  "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로 지정하세요.

API 관련 참고사항

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

추가 리소스

다음 단계

Amazon Bedrock 통합을 완료한 후:

팀 배포: 팀원들에게 환경 변수 설정 방법을 안내하고, 조직 전체에 일관된 구성을 적용합니다.
모델 버전 관리: 정기적으로 새 모델 버전을 검토하고, 테스트 후 계획적으로 버전을 업데이트합니다.
비용 모니터링: AWS Cost Explorer를 사용하여 팀별 사용량을 추적하고 예산을 관리합니다.
보안 감사: CloudTrail을 활용하여 Claude Code 사용 패턴을 모니터링하고 보안 정책을 시행합니다.
엔터프라이즈 배포 전략: 서드파티 통합 및 엔터프라이즈 배포 가이드에서 조직 전체 배포 모범 사례를 참조합니다.