Claude Code × Amazon Bedrock 연동 가이드

Claude Code × Amazon Bedrock
완전 연동 가이드 (2026. 05)

안녕하세요! 오늘은 개발자들의 필수 도구로 자리 잡은 Claude Code를 Amazon Bedrock과 연동하는 방법을 준비했습니다. Anthropic 직접 구독 없이도 AWS의 강력한 인프라 안에서 보안과 비용 효율성을 챙기며 Claude를 사용할 수 있는 아주 실용적인 방법이죠.

연동 방식 개요

Claude Code는 내부적으로 Bedrock Invoke API를 호출합니다. 복잡한 설정 없이 CLAUDE_CODE_USE_BEDROCK=1이라는 환경변수 하나로 엔드포인트가 전환됩니다. 인증 또한 기존에 사용하시던 IAM, SSO, Access Key 등 AWS 자격증명 체계를 그대로 따르기 때문에 도입 장벽이 매우 낮습니다.

빠른 시작: 수동 설정 4단계

1단계 — AWS 사전 준비

• AWS 계정에서 Amazon Bedrock 콘솔에 접속합니다.
• 모델 카탈로그에서 Anthropic 모델을 선택하고 사용 사례 양식을 제출하세요. (제출 즉시 액세스 권한이 부여됩니다.)
• 다음의 IAM 권한 정책을 부여해야 합니다.

{
  "Action": [
    "bedrock:InvokeModel",
    "bedrock:InvokeModelWithResponseStream",
    "bedrock:ListInferenceProfiles",
    "bedrock:GetInferenceProfile"
  ],
  "Resource": [
    "arn:aws:bedrock:*:*:inference-profile/*",
    "arn:aws:bedrock:*:*:foundation-model/*"
  ]
}

2단계 — AWS 자격증명 구성

방법	명령 / 변수
AWS CLI 구성	aws configure
액세스 키	AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
SSO 프로필	aws sso login --profile <name>
Bedrock API 키	AWS_BEARER_TOKEN_BEDROCK=your-key

3단계 — 환경변수 설정

# 필수 설정
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=ap-northeast-2

# 모델 버전 고정 (2026년 권장 버전)
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'

# 선택 사항: 캐시 및 토큰 제한
export ENABLE_PROMPT_CACHING_1H=1
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096

💡 팁: ~/.claude/settings.json의 env 블록에 작성하면 매번 export할 필요가 없어 편리합니다.

4단계 — 로그인 마법사 (개인용)

• 터미널에서 claude를 실행합니다.
• 로그인 프롬프트에서 3rd-party platform → Amazon Bedrock을 선택하세요.
• 마법사가 리전과 모델을 자동으로 잡아줍니다. 추후 /setup-bedrock 명령으로 재설정도 가능합니다.

Bedrock 연동 시 핵심 특장점

• 비용 최적화: 사용량 기반 과금 방식이며, 프롬프트 캐싱을 통해 비용을 최대 90%, 레이턴시를 85%까지 줄일 수 있습니다.
• 강력한 보안: 데이터가 모델 학습에 사용되지 않으며, VPC Endpoint를 통해 공개 인터넷을 거치지 않는 프라이빗 네트워크 구성이 가능합니다.
• Guardrails: 사내 정책에 맞춰 PII(개인정보) 필터링이나 프롬프트 인젝션 차단을 강제할 수 있습니다.
• IAM 권한 제어: 개발자 직급별로 접근 가능한 모델을 세분화하여 관리할 수 있습니다.
• 대규모 컨텍스트: Bedrock에서도 이제 1M(100만) 토큰 컨텍스트 윈도우를 지원하여 거대한 코드베이스 분석이 원활합니다.

고급 구성: LLM Gateway 패턴

개발팀 규모가 100명이 넘는다면 LiteLLM Proxy와 SSO를 결합한 게이트웨이 아키텍처를 추천합니다. 이를 통해 사용자별 비용 추적과 예산 제한이 가능해집니다.

기능	Bedrock 직접 연결	LLM Gateway
사용량 추적	IAM 역할 단위	개인/팀/프로젝트 단위
예산 관리	불가	월별 예산 설정 가능
인증	IAM 직접 관리	SSO 통합 자동화

⚠️ 주의사항

• AWS_REGION은 필수입니다. .aws 설정 파일에서 자동으로 읽지 않으니 꼭 명시해 주세요.
• Bedrock 연동 중에는 /login, /logout 명령이 비활성화됩니다.
• 에러 발생 시 모델명을 반드시 추론 프로필 ID(us.anthropic.claude-...) 형식으로 지정했는지 확인하세요.