[Claude Code] AWS Bedrock 연결 사용 가이드
Claude Code는 기본적으로 Anthropic 구독(요금제)으로 사용하지만, 회사 AWS 계정의 Amazon Bedrock을 통해 사용할 수도 있습니다.
(알아두기) 비유하자면, 구독 방식은 "통신사 정액 요금제"이고 Bedrock 방식은 "쓴 만큼만 내는 종량제 + 회사 법인카드 결제"입니다. 비용이 AWS 청구서에 합산되고, 데이터도 회사 AWS 환경 안에서 처리됩니다.
Prerequisite
본 가이드를 진행하기 전에 다음 항목이 준비되어 있어야 합니다:
- AWS 계정 접근 권한: Bedrock 콘솔에 접근하여 API 키를 생성할 수 있는 IAM 권한이 필요합니다.
- 로컬 PC에 Claude Code 설치: 터미널에서
claude명령어가 실행 가능해야 합니다.
Process
1. Bedrock API Key 발급
Claude Code가 사용할 "출입증(열쇠)"을 발급받는 단계입니다.
(알아두기) 예전에는 모델마다 액세스 요청을 해서 승인받아야 했지만, 현재는 모든 Bedrock 파운데이션 모델 액세스가 기본적으로 활성화되어 있어 이 단계가 생략되었습니다. 단, Anthropic 모델을 계정에서 처음 사용하는 경우 최초 1회 사용 사례(Use case) 입력 폼이 나타날 수 있으며, 간단히 작성하면 됩니다. (예: "AI-assisted software development")
-
AWS Console에서 Amazon Bedrock 서비스로 이동합니다.
-
좌측 네비게이션 메뉴에서 API 키(API keys)를 클릭합니다.
-
장기 API 키(Long-term API keys) 탭에서 장기 API 키 생성을 클릭합니다.
-
만료 기간(예: 30일)을 선택하고 생성을 클릭합니다.
-
(중요) 생성된 API 키를 복사하여 안전한 곳에 저장합니다. 이 화면을 벗어나면 다시 확인할 수 없습니다.
(Notice) 단기 API 키는 콘솔 세션 종료 시(최대 12시간) 만료되므로, 일상적인 개발 용도로는 장기 키가 편리합니다. 장기 키는 탐색/개발 용도로 권장되며, 프로덕션 환경에서는 IAM 역할 등 단기 자격 증명 사용이 권장됩니다.
2. API Key 등록
발급받은 열쇠를 로컬 터미널에 등록하는 단계입니다. AWS IAM 자격 증명(Access Key) 없이 Bedrock 전용 키만으로 인증됩니다.
셸 설정 파일(~/.zshrc 또는 ~/.bashrc)에 아래 내용을 추가합니다.
export AWS_BEARER_TOKEN_BEDROCK=[Bedrock_API_키]
3. Claude Code에 Bedrock 연결
방법 A: 로그인 마법사 사용 (권장, 가장 간단)
-
터미널에서
claude를 실행합니다.
-
로그인 화면에서 3rd-party platform → Amazon Bedrock을 선택합니다.
-
인증 방식(AWS 프로필 / Bedrock API Key / Access Key 등)을 선택하면, 마법사가 리전 확인과 모델 선택까지 자동으로 처리하고 설정 파일에 저장합니다.
(알아두기) 이미 구독으로 로그인된 상태라면 Claude Code 안에서 /setup-bedrock 명령어로 언제든 마법사를 열어 전환할 수 있습니다.
방법 B: 환경변수 직접 설정
셸 설정 파일(~/.zshrc 또는 ~/.bashrc)에 아래 내용을 추가합니다.
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=ap-northeast-2
export ANTHROPIC_MODEL='[사용할_모델_ID]'
예시:
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=ap-northeast-2
export ANTHROPIC_MODEL='apac.anthropic.claude-sonnet-4-5-20250929-v1:0'
CLAUDE_CODE_USE_BEDROCK=1: "Anthropic 서버 말고 Bedrock으로 전화 걸어라"라는 스위치입니다.AWS_REGION: 필수 값입니다. Claude Code는 이 값을.aws설정 파일에서 읽지 않으므로 반드시 직접 지정해야 합니다.ANTHROPIC_MODEL: Bedrock에서 활성화한 모델의 추론 프로필 ID를 입력합니다. (서울 등 아시아 리전은apac.접두사가 붙은 크로스 리전 프로필 사용)
설정 후 터미널을 재시작하거나 source ~/.zshrc를 실행합니다.
4. 접속 확인
- 터미널에서
claude를 실행합니다. - Claude Code 내에서
/status명령어를 입력합니다.
- Provider 항목에 Amazon Bedrock이 표시되면 연결 성공입니다!
(알아두기) Bedrock 사용 시 /login, /logout 명령어는 비활성화됩니다. 인증이 AWS 자격 증명으로 대체되기 때문입니다.
Trouble Shooting
403 Forbidden 에러
원인: 계정에서 Anthropic 모델의 최초 사용 사례 제출이 완료되지 않았거나, API 키가 만료되었거나, 리전이 일치하지 않는 경우입니다.
해결 방법:
- Bedrock 콘솔의 모델 카탈로그에서 사용할 Claude 모델을 열어 사용 사례 폼 제출이 필요한지 확인합니다.
- Bedrock 콘솔 → API 키에서 키가 만료되지 않았는지 확인하고, 만료되었다면 재발급합니다.
AWS_REGION값이 API 키를 발급한 리전과 일치하는지 확인합니다.
Unable to locate credentials
원인: AWS 자격 증명(Bedrock API Key)이 설정되지 않았거나, 터미널에 환경변수가 반영되지 않았습니다.
해결 방법:
echo $AWS_BEARER_TOKEN_BEDROCK을 실행하여 키 값이 출력되는지 확인합니다.- 값이 비어 있다면 셸 설정 파일(
~/.zshrc또는~/.bashrc)에export AWS_BEARER_TOKEN_BEDROCK=[Bedrock_API_키]를 추가하고source ~/.zshrc를 실행하거나 터미널을 재시작합니다.
429 Throttling (요청 제한) 에러
원인: Bedrock은 계정 단위로 분당 요청 수(RPM)/토큰 수(TPM) 쿼터가 있습니다. 도로에 차선이 정해져 있는 것과 같아서, 팀원들이 같은 계정을 쓰면 금방 정체가 발생합니다.
해결 방법:
- AWS Service Quotas에서 해당 모델의 쿼터 상향을 요청합니다.
- 경량 작업은 Haiku 등 저비용 모델로 분산합니다.