Amazon Bedrock의 Claude Code

Amazon Bedrock을 통한 Claude Code 구성, 설정, IAM 구성 및 문제 해결에 대해 알아봅니다.

필수 조건

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

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

Bedrock 자격 증명으로 로그인하려면 아래의 Bedrock으로 로그인을 따르십시오. 팀 전체에 Claude Code를 배포하려면 수동 설정 단계를 사용하고 롤아웃 전에 모델 버전을 고정하십시오.

AWS 자격 증명이 있고 Bedrock을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. AWS 측 필수 조건은 계정당 한 번 완료하며, 마법사가 Claude Code 측을 처리합니다.

AWS 계정에서 Anthropic 모델 활성화

Amazon Bedrock 콘솔에서 모델 카탈로그를 열고 Anthropic 모델을 선택한 후 사용 사례 양식을 제출하십시오. 제출 후 즉시 액세스가 부여됩니다. AWS Organizations의 경우 사용 사례 세부 정보 제출을 참조하고 권한의 경우 IAM 구성을 참조하십시오.

Claude Code를 시작하고 Bedrock 선택

claude를 실행하십시오. 로그인 프롬프트에서 3rd-party platform을 선택한 후 Amazon Bedrock을 선택하십시오.

마법사 프롬프트 따르기

AWS에 인증하는 방법을 선택하십시오: ~/.aws 디렉토리에서 감지된 AWS 프로필, Bedrock API 키, 액세스 키 및 시크릿, 또는 환경에 이미 있는 자격 증명. 마법사가 지역을 선택하고 계정이 호출할 수 있는 Claude 모델을 확인한 후 고정할 수 있도록 합니다. 결과를 사용자 설정 파일의 env 블록에 저장하므로 환경 변수를 직접 내보낼 필요가 없습니다.

로그인한 후 언제든지 /setup-bedrock을 실행하여 마법사를 다시 열고 자격 증명, 지역 또는 모델 고정을 변경할 수 있습니다.

수동으로 설정

예를 들어 CI 또는 스크립트된 엔터프라이즈 롤아웃에서 마법사 대신 환경 변수를 통해 Bedrock을 구성하려면 아래 단계를 따르십시오.

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

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

아래에 설명된 올바른 IAM 권한이 있는지 확인하십시오
Amazon Bedrock 콘솔로 이동하십시오
모델 카탈로그에서 Anthropic 모델을 선택하십시오
사용 사례 양식을 완료하십시오. 제출 후 즉시 액세스가 부여됩니다.

AWS Organizations를 사용하는 경우 관리 계정에서 PutUseCaseForModelAccess API를 사용하여 양식을 한 번 제출할 수 있습니다. 이 호출에는 bedrock:PutUseCaseForModelAccess IAM 권한이 필요합니다. 승인은 자동으로 하위 계정으로 확장됩니다.

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 설정 파일에 이러한 설정을 추가하십시오(설정에서 파일 위치 참조).

이 두 설정은 서로 다른 트리거 조건을 가집니다:

awsAuthRefresh: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 Bedrock이 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.
awsCredentialExport: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.

예제 구성

{
  "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  # 또는 선호하는 지역

# 선택 사항: 소형/빠른 모델(Bedrock 및 Mantle)의 AWS 지역 재정의
# Bedrock에서는 ANTHROPIC_DEFAULT_HAIKU_MODEL
# 또는 더 이상 사용되지 않는 ANTHROPIC_SMALL_FAST_MODEL이 설정되지 않으면 효과가 없습니다.
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# 선택 사항: 사용자 정의 엔드포인트 또는 게이트웨이를 위한 Bedrock 엔드포인트 URL 재정의
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

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

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

4. 모델 버전 고정

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

ANTHROPIC_DEFAULT_OPUS_MODEL이 없으면 Bedrock의 opus 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정하십시오:

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

모델 유형	기본값
기본 모델	`us.anthropic.claude-sonnet-4-5-20250929-v1:0`
소형/빠른 모델	기본 모델과 동일

세션 제목 생성과 같은 백그라운드 작업은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Bedrock에서 Claude Code는 모든 계정 또는 지역에서 Haiku를 사용할 수 없을 수 있으므로 기본적으로 이를 기본 모델로 설정합니다. 백그라운드 작업에 Haiku를 사용하려면 ANTHROPIC_DEFAULT_HAIKU_MODEL을 계정에서 사용 가능한 모델 ID로 설정하십시오.

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

# 추론 프로필 ID 사용
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_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분 기본값 대신 1시간 프롬프트 캐시 TTL 요청
export ENABLE_PROMPT_CACHING_1H=1

1시간 캐시 TTL은 5분 기본값보다 높은 요금으로 청구됩니다. 캐시 수명을 참조하십시오.

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

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

이 예제는 네 개의 Opus 버전을 고유한 ARN에 매핑하므로 사용자는 조직의 추론 프로필을 우회하지 않고 버전 간에 전환할 수 있습니다:

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod",
    "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 재정의를 참조하십시오.

시작 모델 확인

Claude Code가 Bedrock으로 구성되어 시작되면 사용하려는 모델이 계정에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.94 이상이 필요합니다.

현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 계정이 최신 버전을 호출할 수 있는 경우 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 사용자 설정 파일에 쓰고 Claude Code를 다시 시작합니다. 거부하면 다음 기본 버전 변경까지 기억됩니다. 애플리케이션 추론 프로필 ARN을 가리키는 고정은 관리자가 관리하므로 건너뜁니다.

모델을 고정하지 않았고 현재 기본값을 계정에서 사용할 수 없는 경우 Claude Code는 현재 세션에서 이전 버전으로 폴백하고 알림을 표시합니다. 폴백은 유지되지 않습니다. Bedrock 계정에서 최신 모델을 활성화하거나 버전을 고정하여 선택을 영구적으로 만드십시오.

IAM 구성

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles",
        "bedrock:GetInferenceProfile"
      ],
      "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:GetInferenceProfile을 사용하면 Claude Code가 애플리케이션 추론 프로필 ARN을 해당 백업 기초 모델로 확인할 수 있으며, 이는 해당 모델에 대한 올바른 요청 형태를 선택하는 데 사용됩니다.

토큰에 이 권한이 없으면 Claude Code는 대체 형태로 한 번 재시도하여 자동으로 복구되므로 요청은 여전히 성공하지만 각 새로운 모델은 추가 왕복을 추가합니다. 권한을 부여하면 재시도를 피할 수 있습니다. 이는 토큰의 정책이 일반적으로 전체 IAM 역할보다 좁은 AWS_BEARER_TOKEN_BEDROCK 배포에 가장 자주 적용됩니다.

자세한 내용은 Bedrock IAM 설명서를 참조하십시오.

1M 토큰 컨텍스트 윈도우

Claude Opus 4.6 이상 및 Sonnet 4.6은 Amazon Bedrock에서 1M 토큰 컨텍스트 윈도우를 지원합니다. Claude Code는 1M 모델 변형을 선택할 때 확장된 컨텍스트 윈도우를 자동으로 활성화합니다.

설정 마법사는 모델을 고정할 때 1M 컨텍스트 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 [1m]을 추가하십시오. 자세한 내용은 타사 배포를 위한 모델 고정을 참조하십시오.

서비스 계층

Amazon Bedrock 서비스 계층을 사용하면 비용과 지연 시간을 절충할 수 있습니다. ANTHROPIC_BEDROCK_SERVICE_TIER를 default, flex 또는 priority로 설정하십시오:

export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

Claude Code는 이를 각 요청의 X-Amzn-Bedrock-Service-Tier 헤더로 보냅니다. 계층 가용성은 모델 및 지역에 따라 다릅니다. 예약된 용량은 이 설정 대신 프로비저닝된 처리량 ARN을 모델 ID로 사용합니다.

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

Mantle 엔드포인트 사용

Mantle은 Bedrock Invoke API 대신 기본 Anthropic API 형태를 통해 Claude 모델을 제공하는 Amazon Bedrock 엔드포인트입니다. 이 페이지의 앞부분에서 설명한 동일한 AWS 자격 증명, IAM 권한 및 awsAuthRefresh 구성을 사용합니다.

Mantle 활성화

AWS 자격 증명이 이미 구성되어 있으면 CLAUDE_CODE_USE_MANTLE을 설정하여 요청을 Mantle 엔드포인트로 라우팅하십시오:

export CLAUDE_CODE_USE_MANTLE=1
export AWS_REGION=us-east-1

Claude Code는 AWS_REGION에서 엔드포인트 URL을 구성합니다. 사용자 정의 엔드포인트 또는 게이트웨이를 위해 재정의하려면 ANTHROPIC_BEDROCK_MANTLE_BASE_URL을 설정하십시오.

Claude Code 내에서 /status를 실행하여 확인하십시오. Mantle이 활성화되면 제공자 줄에 Amazon Bedrock (Mantle)이 표시됩니다.

Mantle 모델 선택

Mantle은 anthropic. 접두사가 있고 버전 접미사가 없는 모델 ID를 사용합니다(예: anthropic.claude-haiku-4-5). 계정에서 사용 가능한 모델은 조직에 부여된 것에 따라 다르며, 추가 모델 ID는 AWS의 온보딩 자료에 나열됩니다. 허용 목록에 있는 모델에 대한 액세스를 요청하려면 AWS 계정 팀에 문의하십시오.

--model 플래그 또는 Claude Code 내의 /model로 모델을 설정하십시오:

claude --model anthropic.claude-haiku-4-5

Invoke API와 함께 Mantle 실행

Mantle에서 사용 가능한 모델이 현재 사용하는 모든 모델을 포함하지 않을 수 있습니다. CLAUDE_CODE_USE_BEDROCK 및 CLAUDE_CODE_USE_MANTLE을 모두 설정하면 Claude Code가 동일한 세션에서 두 엔드포인트를 모두 호출할 수 있습니다. Mantle 형식과 일치하는 모델 ID는 Mantle으로 라우팅되고 다른 모든 모델 ID는 Bedrock Invoke API로 이동합니다.

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

Mantle 모델을 /model 선택기에 표시하려면 설정 파일의 availableModels에 ID를 나열하십시오. 이 설정은 선택기를 나열된 항목으로 제한하므로 유지하려는 모든 별칭을 포함하십시오:

{
  "availableModels": ["opus", "sonnet", "haiku", "anthropic.claude-haiku-4-5"]
}

anthropic. 접두사가 있는 항목은 사용자 정의 선택기 옵션으로 추가되고 Mantle으로 라우팅됩니다. anthropic.claude-haiku-4-5를 계정에 부여된 모델 ID로 바꾸십시오. availableModels가 다른 모델 설정과 상호 작용하는 방식에 대한 자세한 내용은 모델 선택 제한을 참조하십시오.

두 공급자가 모두 활성화되면 /status는 Amazon Bedrock + Amazon Bedrock (Mantle)을 표시합니다.

게이트웨이를 통해 Mantle 라우팅

조직이 모델 트래픽을 AWS 자격 증명을 서버 측에 주입하는 중앙 집중식 LLM 게이트웨이를 통해 라우팅하는 경우 클라이언트 측 인증을 비활성화하여 Claude Code가 SigV4 서명 또는 x-api-key 헤더 없이 요청을 보내도록 하십시오:

export CLAUDE_CODE_USE_MANTLE=1
export CLAUDE_CODE_SKIP_MANTLE_AUTH=1
export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com

Mantle 환경 변수

이러한 변수는 Mantle 엔드포인트에만 해당됩니다. 전체 목록은 환경 변수를 참조하십시오.

변수	목적
`CLAUDE_CODE_USE_MANTLE`	Mantle 엔드포인트를 활성화합니다. `1` 또는 `true`로 설정하십시오.
`ANTHROPIC_BEDROCK_MANTLE_BASE_URL`	기본 Mantle 엔드포인트 URL 재정의
`CLAUDE_CODE_SKIP_MANTLE_AUTH`	프록시 설정을 위해 클라이언트 측 인증 건너뛰기
`ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`	Haiku 클래스 모델의 AWS 지역 재정의(Bedrock과 공유)

문제 해결

SSO 및 회사 프록시를 사용한 인증 루프

AWS SSO를 사용할 때 브라우저 탭이 반복적으로 생성되면 설정 파일에서 awsAuthRefresh 설정을 제거하십시오. 이는 회사 VPN 또는 TLS 검사 프록시가 SSO 브라우저 흐름을 중단할 때 발생할 수 있습니다. Claude Code는 중단된 연결을 인증 실패로 취급하고 awsAuthRefresh를 다시 실행하여 무한 루프를 발생시킵니다.

네트워크 환경이 자동 브라우저 기반 SSO 흐름을 방해하는 경우 awsAuthRefresh에 의존하는 대신 Claude Code를 시작하기 전에 aws sso login을 수동으로 사용하십시오.

지역 문제

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

모델 가용성 확인: 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를 지원하지 않습니다.

Mantle 엔드포인트 오류

CLAUDE_CODE_USE_MANTLE을 설정한 후 /status에 Amazon Bedrock (Mantle)이 표시되지 않으면 변수가 프로세스에 도달하지 않습니다. Claude Code를 시작한 셸에서 내보내졌는지 확인하거나 설정 파일의 env 블록에 설정하십시오.

유효한 자격 증명이 있는 Mantle 엔드포인트의 403은 AWS 계정이 요청한 모델에 대한 액세스 권한을 부여받지 않았음을 의미합니다. 액세스를 요청하려면 AWS 계정 팀에 문의하십시오.

모델 ID를 이름으로 지정하는 400은 해당 모델이 Mantle에서 제공되지 않음을 의미합니다. Mantle은 표준 Bedrock 카탈로그와 별개의 자체 모델 라인업을 가지고 있으므로 us.anthropic.claude-sonnet-4-6과 같은 추론 프로필 ID는 작동하지 않습니다. Mantle 형식 ID를 사용하거나 두 엔드포인트를 모두 활성화하여 Claude Code가 각 요청을 모델을 사용할 수 있는 엔드포인트로 라우팅하도록 하십시오.

추가 리소스

amazon-bedrock.md +89 −104

6 6

7> Amazon Bedrock을 통한 Claude Code 구성, 설정, IAM 구성 및 문제 해결에 대해 알아봅니다.7> Amazon Bedrock을 통한 Claude Code 구성, 설정, IAM 구성 및 문제 해결에 대해 알아봅니다.

8 8

~~9export const ContactSalesCard = ({surface}) => {~~9<h2 id="prerequisites">

~~10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;~~10 필수 조건

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">11</h2>

~~12 <line x1="5" y1="12" x2="19" y2="12" />~~

~~13 <polyline points="12 5 19 12 12 19" />~~

~~14 </svg>;~~

~~15 const STYLES = `~~

~~16.cc-cs {~~

~~17 --cs-slate: #141413;~~

~~18 --cs-clay: #d97757;~~

~~19 --cs-clay-deep: #c6613f;~~

~~20 --cs-gray-000: #ffffff;~~

~~21 --cs-gray-700: #3d3d3a;~~

~~22 --cs-border-default: rgba(31, 30, 29, 0.15);~~

~~23 font-family: inherit;~~

~~24}~~

~~25.dark .cc-cs {~~

~~26 --cs-slate: #f0eee6;~~

~~27 --cs-gray-000: #262624;~~

~~28 --cs-gray-700: #bfbdb4;~~

~~29 --cs-border-default: rgba(240, 238, 230, 0.14);~~

~~30}~~

~~31.cc-cs-card {~~

~~32 display: flex; align-items: center; justify-content: space-between;~~

~~33 gap: 16px; padding: 14px 16px; margin: 0;~~

~~34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);~~

~~35 border-radius: 8px; flex-wrap: wrap;~~

~~36}~~

~~37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }~~

~~38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }~~

~~39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }~~

~~40.cc-cs-btn-clay {~~

~~41 display: inline-flex; align-items: center; gap: 8px;~~

~~42 background: var(--cs-clay-deep); color: #fff; border: none;~~

~~43 border-radius: 8px; padding: 8px 14px;~~

~~44 font-size: 13px; font-weight: 500;~~

~~45 transition: background-color 0.15s; white-space: nowrap;~~

~~46}~~

~~47.cc-cs-btn-clay:hover { background: var(--cs-clay); }~~

~~48.cc-cs-btn-ghost {~~

~~49 display: inline-flex; align-items: center; gap: 8px;~~

~~50 background: transparent; color: var(--cs-gray-700);~~

~~51 border: 0.5px solid var(--cs-border-default);~~

~~52 border-radius: 8px; padding: 8px 14px;~~

~~53 font-size: 13px; font-weight: 500;~~

~~54}~~

~~55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }~~

~~56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }~~

~~57@media (max-width: 720px) {~~

~~58 .cc-cs-actions { width: 100%; }~~

~~59}~~

~~60`;~~

~~61 return <div className="cc-cs not-prose">~~

~~62 <style>{STYLES}</style>~~

~~63 <div className="cc-cs-card">~~

~~64 <div className="cc-cs-text">~~

~~65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.~~

~~66 </div>~~

~~67 <div className="cc-cs-actions">~~

~~68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">~~

~~69 View plans~~

~~70 </a>~~

~~71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">~~

~~72 Contact sales {iconArrowRight()}~~

~~73 </a>~~

~~74 </div>~~

~~75 </div>~~

~~76 </div>;~~

~~77};~~

~~79<ContactSalesCard surface="bedrock" />~~

~~81## 필수 조건~~

82 12

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

84 14

89 19

90Bedrock 자격 증명으로 로그인하려면 아래의 [Bedrock으로 로그인](#sign-in-with-bedrock)을 따르십시오. 팀 전체에 Claude Code를 배포하려면 [수동 설정](#set-up-manually) 단계를 사용하고 롤아웃 전에 [모델 버전을 고정](#4-pin-model-versions)하십시오.20Bedrock 자격 증명으로 로그인하려면 아래의 [Bedrock으로 로그인](#sign-in-with-bedrock)을 따르십시오. 팀 전체에 Claude Code를 배포하려면 [수동 설정](#set-up-manually) 단계를 사용하고 롤아웃 전에 [모델 버전을 고정](#4-pin-model-versions)하십시오.

91 21

~~92## Bedrock으로 로그인~~22<h2 id="sign-in-with-bedrock">

23 Bedrock으로 로그인

24</h2>

93 25

94AWS 자격 증명이 있고 Bedrock을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. AWS 측 필수 조건은 계정당 한 번 완료하며, 마법사가 Claude Code 측을 처리합니다.26AWS 자격 증명이 있고 Bedrock을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. AWS 측 필수 조건은 계정당 한 번 완료하며, 마법사가 Claude Code 측을 처리합니다.

95 27

109 41

110로그인한 후 언제든지 `/setup-bedrock`을 실행하여 마법사를 다시 열고 자격 증명, 지역 또는 모델 고정을 변경할 수 있습니다.42로그인한 후 언제든지 `/setup-bedrock`을 실행하여 마법사를 다시 열고 자격 증명, 지역 또는 모델 고정을 변경할 수 있습니다.

111 43

112## 수동으로 설정44<h2 id="set-up-manually">

45 수동으로 설정

46</h2>

113 47

114예를 들어 CI 또는 스크립트된 엔터프라이즈 롤아웃에서 마법사 대신 환경 변수를 통해 Bedrock을 구성하려면 아래 단계를 따르십시오.48예를 들어 CI 또는 스크립트된 엔터프라이즈 롤아웃에서 마법사 대신 환경 변수를 통해 Bedrock을 구성하려면 아래 단계를 따르십시오.

115 49

116### 1. 사용 사례 세부 정보 제출50<h3 id="1-submit-use-case-details">

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

52</h3>

117 53

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

119 55

124 60

125AWS Organizations를 사용하는 경우 관리 계정에서 [`PutUseCaseForModelAccess` API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_PutUseCaseForModelAccess.html)를 사용하여 양식을 한 번 제출할 수 있습니다. 이 호출에는 `bedrock:PutUseCaseForModelAccess` IAM 권한이 필요합니다. 승인은 자동으로 하위 계정으로 확장됩니다.61AWS Organizations를 사용하는 경우 관리 계정에서 [`PutUseCaseForModelAccess` API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_PutUseCaseForModelAccess.html)를 사용하여 양식을 한 번 제출할 수 있습니다. 이 호출에는 `bedrock:PutUseCaseForModelAccess` IAM 권한이 필요합니다. 승인은 자동으로 하위 계정으로 확장됩니다.

126 62

127### 2. AWS 자격 증명 구성63<h3 id="2-configure-aws-credentials">

64 2. AWS 자격 증명 구성

65</h3>

128 66

129Claude Code는 기본 AWS SDK 자격 증명 체인을 사용합니다. 다음 방법 중 하나를 사용하여 자격 증명을 설정하십시오:67Claude Code는 기본 AWS SDK 자격 증명 체인을 사용합니다. 다음 방법 중 하나를 사용하여 자격 증명을 설정하십시오:

130 68

166 104

167Bedrock API 키는 전체 AWS 자격 증명이 필요 없는 더 간단한 인증 방법을 제공합니다. [Bedrock API 키에 대해 자세히 알아보기](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/).105Bedrock API 키는 전체 AWS 자격 증명이 필요 없는 더 간단한 인증 방법을 제공합니다. [Bedrock API 키에 대해 자세히 알아보기](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/).

168 106

169#### 고급 자격 증명 구성107<h4 id="advanced-credential-configuration">

108 고급 자격 증명 구성

109</h4>

170 110

171Claude Code는 AWS SSO 및 회사 ID 공급자에 대한 자동 자격 증명 새로 고침을 지원합니다. Claude Code 설정 파일에 이러한 설정을 추가하십시오([설정](/ko/settings)에서 파일 위치 참조).111Claude Code는 AWS SSO 및 회사 ID 공급자에 대한 자동 자격 증명 새로 고침을 지원합니다. Claude Code 설정 파일에 이러한 설정을 추가하십시오([설정](/ko/settings)에서 파일 위치 참조).

172 112

175* **`awsAuthRefresh`**: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 Bedrock이 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.115* **`awsAuthRefresh`**: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 Bedrock이 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.

176* **`awsCredentialExport`**: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.116* **`awsCredentialExport`**: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.

177 117

178##### 예제 구성118<h5 id="example-configuration">

119 예제 구성

120</h5>

179 121

180```json theme={null}122```json theme={null}

181{123{

186}128}

187```129```

188 130

189##### 구성 설정 설명131<h5 id="configuration-settings-explained">

132 구성 설정 설명

133</h5>

190 134

191**`awsAuthRefresh`**: `.aws` 디렉토리를 수정하는 명령(예: 자격 증명, SSO 캐시 또는 구성 파일 업데이트)에 사용하십시오. 명령의 출력이 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 이는 CLI가 URL 또는 코드를 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 SSO 흐름에 적합합니다.135**`awsAuthRefresh`**: `.aws` 디렉토리를 수정하는 명령(예: 자격 증명, SSO 캐시 또는 구성 파일 업데이트)에 사용하십시오. 명령의 출력이 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 이는 CLI가 URL 또는 코드를 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 SSO 흐름에 적합합니다.

192 136

202}146}

203```147```

204 148

205### 3. Claude Code 구성149<h3 id="3-configure-claude-code">

150 3. Claude Code 구성

151</h3>

206 152

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

208 154

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

224 170

225* `AWS_REGION`은 필수 환경 변수입니다. Claude Code는 이 설정에 대해 `.aws` 구성 파일을 읽지 않습니다.171* `AWS_REGION`은 필수 환경 변수입니다. Claude Code는 이 설정에 대해 `.aws` 구성 파일을 읽지 않습니다.

226* Bedrock을 사용할 때 `/login` 및 `/logout` 명령은 AWS 자격 증명을 통해 인증이 처리되므로 비활성화됩니다.172* Bedrock을 사용할 때 `/logout` 명령은 AWS 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.

173* WebSearch 도구는 Bedrock에서 사용할 수 없습니다. [WebSearch 도구 동작](/ko/tools-reference#websearch-tool-behavior)을 참조하십시오.

227* 다른 프로세스에 유출되지 않도록 하려는 `AWS_PROFILE`과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 [설정](/ko/settings)을 참조하십시오.174* 다른 프로세스에 유출되지 않도록 하려는 `AWS_PROFILE`과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 [설정](/ko/settings)을 참조하십시오.

228 175

229### 4. 모델 버전 고정176<h3 id="4-pin-model-versions">

177 4. 모델 버전 고정

178</h3>

230 179

231<Warning>180<Warning>

232 여러 사용자에게 배포할 때 특정 모델 버전을 고정하십시오. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 최신 버전으로 확인되며, Anthropic이 업데이트를 출시할 때 Bedrock 계정에서 아직 사용할 수 없을 수 있습니다. Claude Code는 [시작 시](#startup-model-checks) 최신 버전을 사용할 수 없을 때 이전 버전으로 폴백하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.181 여러 사용자에게 배포할 때 특정 모델 버전을 고정하십시오. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 최신 버전으로 확인되며, Anthropic이 업데이트를 출시할 때 Bedrock 계정에서 아직 사용할 수 없을 수 있습니다. Claude Code는 [시작 시](#startup-model-checks) 최신 버전을 사용할 수 없을 때 이전 버전으로 폴백하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.

234 183

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

236 185

237`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Bedrock의 `opus` 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.7 ID로 설정하십시오:186`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Bedrock의 `opus` 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정하십시오:

238 187

239```bash theme={null}188```bash theme={null}

240export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-7'189export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'

241export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'190export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

242export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'191export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

243```192```

270export ENABLE_PROMPT_CACHING_1H=1219export ENABLE_PROMPT_CACHING_1H=1

271```220```

272 221

273<Note>[프롬프트 캐싱](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)은 모든 지역에서 사용할 수 없을 수 있습니다. 1시간 TTL이 있는 캐시 쓰기는 5분 쓰기보다 높은 요금으로 청구됩니다.</Note>2221시간 캐시 TTL은 5분 기본값보다 높은 요금으로 청구됩니다. [캐시 수명](/ko/prompt-caching#cache-lifetime)을 참조하십시오.

223

224<Note>프롬프트 캐싱은 모든 Bedrock 지역에서 사용할 수 없을 수 있습니다. 캐시 토큰 수가 0으로 유지되면 Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하십시오.</Note>

274 225

275#### 각 모델 버전을 추론 프로필에 매핑226<h4 id="map-each-model-version-to-an-inference-profile">

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

228</h4>

276 229

277`ANTHROPIC_DEFAULT_*_MODEL` 환경 변수는 모델 제품군당 하나의 추론 프로필을 구성합니다. 조직이 `/model` 선택기에서 동일한 제품군의 여러 버전을 노출하고 각각 자신의 애플리케이션 추론 프로필 ARN으로 라우팅해야 하는 경우 [설정 파일](/ko/settings#settings-files)에서 `modelOverrides` 설정을 대신 사용하십시오.230`ANTHROPIC_DEFAULT_*_MODEL` 환경 변수는 모델 제품군당 하나의 추론 프로필을 구성합니다. 조직이 `/model` 선택기에서 동일한 제품군의 여러 버전을 노출하고 각각 자신의 애플리케이션 추론 프로필 ARN으로 라우팅해야 하는 경우 [설정 파일](/ko/settings#settings-files)에서 `modelOverrides` 설정을 대신 사용하십시오.

278 231

291 244

292사용자가 `/model`에서 이러한 버전 중 하나를 선택하면 Claude Code는 매핑된 ARN으로 Bedrock을 호출합니다. 재정의가 없는 버전은 기본 제공 Bedrock 모델 ID 또는 시작 시 발견된 일치하는 추론 프로필로 폴백됩니다. 재정의가 `availableModels` 및 기타 모델 설정과 상호 작용하는 방식에 대한 자세한 내용은 [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하십시오.245사용자가 `/model`에서 이러한 버전 중 하나를 선택하면 Claude Code는 매핑된 ARN으로 Bedrock을 호출합니다. 재정의가 없는 버전은 기본 제공 Bedrock 모델 ID 또는 시작 시 발견된 일치하는 추론 프로필로 폴백됩니다. 재정의가 `availableModels` 및 기타 모델 설정과 상호 작용하는 방식에 대한 자세한 내용은 [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하십시오.

293 246

294## 시작 모델 확인247<h2 id="startup-model-checks">

248 시작 모델 확인

249</h2>

295 250

296Claude Code가 Bedrock으로 구성되어 시작되면 사용하려는 모델이 계정에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.94 이상이 필요합니다.251Claude Code가 Bedrock으로 구성되어 시작되면 사용하려는 모델이 계정에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.94 이상이 필요합니다.

297 252

299 254

300모델을 고정하지 않았고 현재 기본값을 계정에서 사용할 수 없는 경우 Claude Code는 현재 세션에서 이전 버전으로 폴백하고 알림을 표시합니다. 폴백은 유지되지 않습니다. Bedrock 계정에서 최신 모델을 활성화하거나 [버전을 고정](#4-pin-model-versions)하여 선택을 영구적으로 만드십시오.255모델을 고정하지 않았고 현재 기본값을 계정에서 사용할 수 없는 경우 Claude Code는 현재 세션에서 이전 버전으로 폴백하고 알림을 표시합니다. 폴백은 유지되지 않습니다. Bedrock 계정에서 최신 모델을 활성화하거나 [버전을 고정](#4-pin-model-versions)하여 선택을 영구적으로 만드십시오.

301 256

302## IAM 구성257<h2 id="iam-configuration">

258 IAM 구성

259</h2>

303 260

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

305 262

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

353</Note>310</Note>

354 311

355## 1M 토큰 컨텍스트 윈도우312<h2 id="1m-token-context-window">

313 1M 토큰 컨텍스트 윈도우

314</h2>

356 315

357Claude Opus 4.7, Opus 4.6 및 Sonnet 4.6은 Amazon Bedrock에서 [1M 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)를 지원합니다. Claude Code는 1M 모델 변형을 선택할 때 확장된 컨텍스트 윈도우를 자동으로 활성화합니다.316Claude Opus 4.6 이상 및 Sonnet 4.6은 Amazon Bedrock에서 [1M 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 지원합니다. Claude Code는 1M 모델 변형을 선택할 때 확장된 컨텍스트 윈도우를 자동으로 활성화합니다.

358 317

359[설정 마법사](#sign-in-with-bedrock)는 모델을 고정할 때 1M 컨텍스트 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 `[1m]`을 추가하십시오. 자세한 내용은 [타사 배포를 위한 모델 고정](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.318[설정 마법사](#sign-in-with-bedrock)는 모델을 고정할 때 1M 컨텍스트 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 `[1m]`을 추가하십시오. 자세한 내용은 [타사 배포를 위한 모델 고정](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.

360 319

361## 서비스 계층320<h2 id="service-tiers">

321 서비스 계층

322</h2>

362 323

363[Amazon Bedrock 서비스 계층](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)을 사용하면 비용과 지연 시간을 절충할 수 있습니다. `ANTHROPIC_BEDROCK_SERVICE_TIER`를 `default`, `flex` 또는 `priority`로 설정하십시오:324[Amazon Bedrock 서비스 계층](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)을 사용하면 비용과 지연 시간을 절충할 수 있습니다. `ANTHROPIC_BEDROCK_SERVICE_TIER`를 `default`, `flex` 또는 `priority`로 설정하십시오:

364 325

368 329

369Claude Code는 이를 각 요청의 `X-Amzn-Bedrock-Service-Tier` 헤더로 보냅니다. 계층 가용성은 모델 및 지역에 따라 다릅니다. 예약된 용량은 이 설정 대신 [프로비저닝된 처리량](https://docs.aws.amazon.com/bedrock/latest/userguide/prov-throughput.html) ARN을 모델 ID로 사용합니다.330Claude Code는 이를 각 요청의 `X-Amzn-Bedrock-Service-Tier` 헤더로 보냅니다. 계층 가용성은 모델 및 지역에 따라 다릅니다. 예약된 용량은 이 설정 대신 [프로비저닝된 처리량](https://docs.aws.amazon.com/bedrock/latest/userguide/prov-throughput.html) ARN을 모델 ID로 사용합니다.

370 331

371## AWS Guardrails332<h2 id="aws-guardrails">

333 AWS Guardrails

334</h2>

372 335

373[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)를 사용하면 Claude Code에 대한 콘텐츠 필터링을 구현할 수 있습니다. [Amazon Bedrock 콘솔](https://console.aws.amazon.com/bedrock/)에서 Guardrail을 만들고 버전을 게시한 다음 Guardrail 헤더를 [설정 파일](/ko/settings)에 추가하십시오. 교차 지역 추론 프로필을 사용하는 경우 Guardrail에서 교차 지역 추론을 활성화하십시오.336[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)를 사용하면 Claude Code에 대한 콘텐츠 필터링을 구현할 수 있습니다. [Amazon Bedrock 콘솔](https://console.aws.amazon.com/bedrock/)에서 Guardrail을 만들고 버전을 게시한 다음 Guardrail 헤더를 [설정 파일](/ko/settings)에 추가하십시오. 교차 지역 추론 프로필을 사용하는 경우 Guardrail에서 교차 지역 추론을 활성화하십시오.

374 337

382}345}

383```346```

384 347

385## Mantle 엔드포인트 사용348<h2 id="use-the-mantle-endpoint">

349 Mantle 엔드포인트 사용

350</h2>

386 351

387Mantle은 Bedrock Invoke API 대신 기본 Anthropic API 형태를 통해 Claude 모델을 제공하는 Amazon Bedrock 엔드포인트입니다. 이 페이지의 앞부분에서 설명한 동일한 AWS 자격 증명, IAM 권한 및 `awsAuthRefresh` 구성을 사용합니다.352Mantle은 Bedrock Invoke API 대신 기본 Anthropic API 형태를 통해 Claude 모델을 제공하는 Amazon Bedrock 엔드포인트입니다. 이 페이지의 앞부분에서 설명한 동일한 AWS 자격 증명, IAM 권한 및 `awsAuthRefresh` 구성을 사용합니다.

388 353

390 Mantle에는 Claude Code v2.1.94 이상이 필요합니다. `claude --version`을 실행하여 확인하십시오.355 Mantle에는 Claude Code v2.1.94 이상이 필요합니다. `claude --version`을 실행하여 확인하십시오.

391</Note>356</Note>

392 357

393### Mantle 활성화358<h3 id="enable-mantle">

359 Mantle 활성화

360</h3>

394 361

395AWS 자격 증명이 이미 구성되어 있으면 `CLAUDE_CODE_USE_MANTLE`을 설정하여 요청을 Mantle 엔드포인트로 라우팅하십시오:362AWS 자격 증명이 이미 구성되어 있으면 `CLAUDE_CODE_USE_MANTLE`을 설정하여 요청을 Mantle 엔드포인트로 라우팅하십시오:

396 363

403 370

404Claude Code 내에서 `/status`를 실행하여 확인하십시오. Mantle이 활성화되면 제공자 줄에 `Amazon Bedrock (Mantle)`이 표시됩니다.371Claude Code 내에서 `/status`를 실행하여 확인하십시오. Mantle이 활성화되면 제공자 줄에 `Amazon Bedrock (Mantle)`이 표시됩니다.

405 372

406### Mantle 모델 선택373<h3 id="select-a-mantle-model">

374 Mantle 모델 선택

375</h3>

407 376

408Mantle은 `anthropic.` 접두사가 있고 버전 접미사가 없는 모델 ID를 사용합니다(예: `anthropic.claude-haiku-4-5`). 계정에서 사용 가능한 모델은 조직에 부여된 것에 따라 다르며, 추가 모델 ID는 AWS의 온보딩 자료에 나열됩니다. 허용 목록에 있는 모델에 대한 액세스를 요청하려면 AWS 계정 팀에 문의하십시오.377Mantle은 `anthropic.` 접두사가 있고 버전 접미사가 없는 모델 ID를 사용합니다(예: `anthropic.claude-haiku-4-5`). 계정에서 사용 가능한 모델은 조직에 부여된 것에 따라 다르며, 추가 모델 ID는 AWS의 온보딩 자료에 나열됩니다. 허용 목록에 있는 모델에 대한 액세스를 요청하려면 AWS 계정 팀에 문의하십시오.

409 378

413claude --model anthropic.claude-haiku-4-5382claude --model anthropic.claude-haiku-4-5

414```383```

415 384

416### Invoke API와 함께 Mantle 실행385<h3 id="run-mantle-alongside-the-invoke-api">

386 Invoke API와 함께 Mantle 실행

387</h3>

417 388

418Mantle에서 사용 가능한 모델이 현재 사용하는 모든 모델을 포함하지 않을 수 있습니다. `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_MANTLE`을 모두 설정하면 Claude Code가 동일한 세션에서 두 엔드포인트를 모두 호출할 수 있습니다. Mantle 형식과 일치하는 모델 ID는 Mantle으로 라우팅되고 다른 모든 모델 ID는 Bedrock Invoke API로 이동합니다.389Mantle에서 사용 가능한 모델이 현재 사용하는 모든 모델을 포함하지 않을 수 있습니다. `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_MANTLE`을 모두 설정하면 Claude Code가 동일한 세션에서 두 엔드포인트를 모두 호출할 수 있습니다. Mantle 형식과 일치하는 모델 ID는 Mantle으로 라우팅되고 다른 모든 모델 ID는 Bedrock Invoke API로 이동합니다.

419 390

434 405

435두 공급자가 모두 활성화되면 `/status`는 `Amazon Bedrock + Amazon Bedrock (Mantle)`을 표시합니다.406두 공급자가 모두 활성화되면 `/status`는 `Amazon Bedrock + Amazon Bedrock (Mantle)`을 표시합니다.

436 407

437### 게이트웨이를 통해 Mantle 라우팅408<h3 id="route-mantle-through-a-gateway">

409 게이트웨이를 통해 Mantle 라우팅

410</h3>

438 411

439조직이 모델 트래픽을 AWS 자격 증명을 서버 측에 주입하는 중앙 집중식 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅하는 경우 클라이언트 측 인증을 비활성화하여 Claude Code가 SigV4 서명 또는 `x-api-key` 헤더 없이 요청을 보내도록 하십시오:412조직이 모델 트래픽을 AWS 자격 증명을 서버 측에 주입하는 중앙 집중식 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅하는 경우 클라이언트 측 인증을 비활성화하여 Claude Code가 SigV4 서명 또는 `x-api-key` 헤더 없이 요청을 보내도록 하십시오:

440 413

444export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com417export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com

445```418```

446 419

447### Mantle 환경 변수420<h3 id="mantle-environment-variables">

421 Mantle 환경 변수

422</h3>

448 423

449이러한 변수는 Mantle 엔드포인트에만 해당됩니다. 전체 목록은 [환경 변수](/ko/env-vars)를 참조하십시오.424이러한 변수는 Mantle 엔드포인트에만 해당됩니다. 전체 목록은 [환경 변수](/ko/env-vars)를 참조하십시오.

450 425

457 432

458## 문제 해결433<h2 id="troubleshooting">

434 문제 해결

435</h2>

459 436

460### SSO 및 회사 프록시를 사용한 인증 루프437<h3 id="authentication-loop-with-sso-and-corporate-proxies">

438 SSO 및 회사 프록시를 사용한 인증 루프

439</h3>

461 440

462AWS SSO를 사용할 때 브라우저 탭이 반복적으로 생성되면 [설정 파일](/ko/settings)에서 `awsAuthRefresh` 설정을 제거하십시오. 이는 회사 VPN 또는 TLS 검사 프록시가 SSO 브라우저 흐름을 중단할 때 발생할 수 있습니다. Claude Code는 중단된 연결을 인증 실패로 취급하고 `awsAuthRefresh`를 다시 실행하여 무한 루프를 발생시킵니다.441AWS SSO를 사용할 때 브라우저 탭이 반복적으로 생성되면 [설정 파일](/ko/settings)에서 `awsAuthRefresh` 설정을 제거하십시오. 이는 회사 VPN 또는 TLS 검사 프록시가 SSO 브라우저 흐름을 중단할 때 발생할 수 있습니다. Claude Code는 중단된 연결을 인증 실패로 취급하고 `awsAuthRefresh`를 다시 실행하여 무한 루프를 발생시킵니다.

463 442

464네트워크 환경이 자동 브라우저 기반 SSO 흐름을 방해하는 경우 `awsAuthRefresh`에 의존하는 대신 Claude Code를 시작하기 전에 `aws sso login`을 수동으로 사용하십시오.443네트워크 환경이 자동 브라우저 기반 SSO 흐름을 방해하는 경우 `awsAuthRefresh`에 의존하는 대신 Claude Code를 시작하기 전에 `aws sso login`을 수동으로 사용하십시오.

465 444

466### 지역 문제445<h3 id="region-issues">

446 지역 문제

447</h3>

467 448

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

469 450

477 458

478Claude Code는 Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)를 사용하며 Converse API를 지원하지 않습니다.459Claude Code는 Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)를 사용하며 Converse API를 지원하지 않습니다.

479 460

480### Mantle 엔드포인트 오류461<h3 id="mantle-endpoint-errors">

462 Mantle 엔드포인트 오류

463</h3>

481 464

482`CLAUDE_CODE_USE_MANTLE`을 설정한 후 `/status`에 `Amazon Bedrock (Mantle)`이 표시되지 않으면 변수가 프로세스에 도달하지 않습니다. Claude Code를 시작한 셸에서 내보내졌는지 확인하거나 [설정 파일](/ko/settings)의 `env` 블록에 설정하십시오.465`CLAUDE_CODE_USE_MANTLE`을 설정한 후 `/status`에 `Amazon Bedrock (Mantle)`이 표시되지 않으면 변수가 프로세스에 도달하지 않습니다. Claude Code를 시작한 셸에서 내보내졌는지 확인하거나 [설정 파일](/ko/settings)의 `env` 블록에 설정하십시오.

483 466

485 468

486모델 ID를 이름으로 지정하는 `400`은 해당 모델이 Mantle에서 제공되지 않음을 의미합니다. Mantle은 표준 Bedrock 카탈로그와 별개의 자체 모델 라인업을 가지고 있으므로 `us.anthropic.claude-sonnet-4-6`과 같은 추론 프로필 ID는 작동하지 않습니다. Mantle 형식 ID를 사용하거나 [두 엔드포인트를 모두 활성화](#run-mantle-alongside-the-invoke-api)하여 Claude Code가 각 요청을 모델을 사용할 수 있는 엔드포인트로 라우팅하도록 하십시오.469모델 ID를 이름으로 지정하는 `400`은 해당 모델이 Mantle에서 제공되지 않음을 의미합니다. Mantle은 표준 Bedrock 카탈로그와 별개의 자체 모델 라인업을 가지고 있으므로 `us.anthropic.claude-sonnet-4-6`과 같은 추론 프로필 ID는 작동하지 않습니다. Mantle 형식 ID를 사용하거나 [두 엔드포인트를 모두 활성화](#run-mantle-alongside-the-invoke-api)하여 Claude Code가 각 요청을 모델을 사용할 수 있는 엔드포인트로 라우팅하도록 하십시오.

487 470

488## 추가 리소스471<h2 id="additional-resources">

472 추가 리소스

473</h2>

489 474

490* [Bedrock 설명서](https://docs.aws.amazon.com/bedrock/)475* [Bedrock 설명서](https://docs.aws.amazon.com/bedrock/)

491* [Bedrock 가격](https://aws.amazon.com/bedrock/pricing/)476* [Bedrock 가격](https://aws.amazon.com/bedrock/pricing/)

amazon-bedrock.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

Amazon Bedrock의 Claude Code

필수 조건

Bedrock으로 로그인

AWS 계정에서 Anthropic 모델 활성화

Claude Code를 시작하고 Bedrock 선택

마법사 프롬프트 따르기

수동으로 설정

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

2. AWS 자격 증명 구성

고급 자격 증명 구성

예제 구성

구성 설정 설명

3. Claude Code 구성

4. 모델 버전 고정

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

시작 모델 확인

IAM 구성

1M 토큰 컨텍스트 윈도우

서비스 계층

AWS Guardrails

Mantle 엔드포인트 사용

Mantle 활성화

Mantle 모델 선택

Invoke API와 함께 Mantle 실행

게이트웨이를 통해 Mantle 라우팅

Mantle 환경 변수

문제 해결

SSO 및 회사 프록시를 사용한 인증 루프

지역 문제

Mantle 엔드포인트 오류

추가 리소스