Amazon Bedrock에서 Claude Code 사용하기

설정, IAM 구성, 문제 해결을 포함하여 Amazon Bedrock을 통해 Claude Code를 구성하는 방법을 알아봅니다.

사전 요구 사항

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

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: 자격 증명, SSO 캐시 또는 설정 파일 업데이트와 같이 .aws 디렉토리를 수정하는 명령에 사용합니다. 명령의 출력은 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. CLI가 URL이나 코드를 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 SSO 흐름에 적합합니다.

awsCredentialExport: .aws를 수정할 수 없고 자격 증명을 직접 반환해야 하는 경우에만 사용하세요. 출력은 조용히 캡처되며 사용자에게 표시되지 않습니다. 명령은 다음 형식의 JSON을 출력해야 합니다:

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value"
  }
}

3. Claude Code 구성

Bedrock을 활성화하려면 다음 환경 변수를 설정하세요:

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # or your preferred region

# Optional: Override the region for the small/fast model (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이 업데이트를 출시할 때 Claude Code가 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. 접두사 포함)를 사용합니다. 다른 리전 접두사나 애플리케이션 추론 프로필을 사용하는 경우 적절히 조정하세요. 현재 및 레거시 모델 ID에 대해서는 모델 개요를 참조하세요. 환경 변수의 전체 목록은 모델 구성을 참조하세요.

고정 변수가 설정되지 않은 경우 Claude Code가 사용하는 기본 모델은 다음과 같습니다:

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

모델을 추가로 커스터마이즈하려면 다음 방법 중 하나를 사용하세요:

# Using inference profile ID
export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# Using application inference profile ARN
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# Optional: Disable prompt caching if needed
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으로 제한할 수 있습니다.

자세한 내용은 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는 지원하지 않습니다.

추가 리소스

Amazon Bedrock에서 Claude Code 사용하기

설정, IAM 구성, 문제 해결을 포함하여 Amazon Bedrock을 통해 Claude Code를 구성하는 방법을 알아봅니다.

사전 요구 사항

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

aws login에 대해 자세히 알아보세요.

옵션 E: Bedrock API 키

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API 키는 전체 AWS 자격 증명 없이도 더 간단한 인증 방법을 제공합니다. Bedrock API 키에 대해 자세히 알아보세요.

고급 자격 증명 구성

구성 예시

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

구성 설정 설명

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value"
  }
}

3. Claude Code 구성

Bedrock을 활성화하려면 다음 환경 변수를 설정하세요:

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # or your preferred region

# Optional: Override the region for the small/fast model (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이 업데이트를 출시할 때 Claude Code가 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'

고정 변수가 설정되지 않은 경우 Claude Code가 사용하는 기본 모델은 다음과 같습니다:

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

모델을 추가로 커스터마이즈하려면 다음 방법 중 하나를 사용하세요:

# Using inference profile ID
export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# Using application inference profile ARN
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# Optional: Disable prompt caching if needed
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으로 제한할 수 있습니다.

자세한 내용은 Bedrock IAM 문서를 참조하세요.

참고: 비용 추적 및 접근 제어를 간소화하려면 Claude Code 전용 AWS 계정을 생성하세요.

AWS Guardrails

구성 예시:

{
  "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는 지원하지 않습니다.

32. Amazon Bedrock에서 Claude Code 사용하기

Amazon Bedrock에서 Claude Code 사용하기

사전 요구 사항

설정

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

2. AWS 자격 증명 구성

고급 자격 증명 구성

구성 예시

구성 설정 설명

3. Claude Code 구성

4. 모델 버전 고정

IAM 구성

AWS Guardrails

문제 해결

추가 리소스

32. Amazon Bedrock에서 Claude Code 사용하기

Amazon Bedrock에서 Claude Code 사용하기

사전 요구 사항

설정

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

2. AWS 자격 증명 구성

고급 자격 증명 구성

구성 예시

구성 설정 설명

3. Claude Code 구성

4. 모델 버전 고정

IAM 구성

AWS Guardrails

문제 해결

추가 리소스