Claude Code on Claude Platform on AWS

Claude Code on Claude Platform on AWS

Claude Platform on AWS는 AWS 인증·IAM 접근 제어·AWS Marketplace 청구로 Anthropic이 운영하는 Claude API를 쓰는 방식이에요. 요청이 Anthropic API에 직접 도달하므로 같은 모델과 API 기능을 같은 릴리스 일정으로 받아요. AWS 자격 증명이나 워크스페이스 API 키로 인증하고 AWS Marketplace로 결제해요. 이 가이드는 이미 프로비저닝한 워크스페이스에 Claude Code를 연결하는 방법을 다뤄요.

출처: 공식문서

본문

전제조건

  • AWS Marketplace를 통한 활성 Claude Platform on AWS 구독
  • AWS 연결 Anthropic 조직의 워크스페이스와 워크스페이스 ID
  • Anthropic 서비스 호출 권한이 있는 IAM 프린시펄 또는 워크스페이스로 한정된 API 키
  • 환경·~/.aws/credentials·IAM 역할의 AWS 자격 증명(SigV4 인증용; AWS CLI는 SSO 로그인 흐름에만 필요)

참고: AWS Marketplace 구독은 AWS 계정에 묶인 새 Anthropic 조직을 프로비저닝해요. 이 조직은 기존 Anthropic 조직과 분리되고 자격 증명도 이전되지 않아요. 기존 Claude Console 계정이 아니라 AWS 연결 조직의 워크스페이스 ID와 API 키를 쓰세요.

설정하기

1. AWS 자격 증명 구성 — 두 가지 인증 방법이 있어요.

Option A: SigV4를 쓰는 AWS 자격 증명 — Claude Code는 표준 AWS credential chain으로 SigV4 서명해요(환경변수, ~/.aws/credentials 공유 자격 증명, IAM 역할, AWS SSO 세션 등). 로컬에선 Claude Code 시작 전 AWS CLI로 로그인해요.

aws sso login --profile my-profile
export AWS_PROFILE=my-profile

CI·자동화에선 러너에 Anthropic 서비스 호출 권한 IAM 역할을 주고 AWS_REGION을 설정하세요. 세션 중 SSO 자격 증명이 만료되면 awsAuthRefresh를 구성해서 로그인 명령을 재실행·재시도하게 해요(자동 갱신은 v2.1.198+).

{
  "awsAuthRefresh": "aws sso login --profile my-profile"
}

Option B: 워크스페이스 API 키 — 페더레이션 AWS 자격 증명을 관리하고 싶지 않을 때 유용한 장기 시크릿. AWS Console의 Claude Platform on AWS → API keys에서 생성해 ANTHROPIC_AWS_API_KEY로 설정.

export ANTHROPIC_AWS_API_KEY=sk-...

이 키는 x-api-key로 전송되고 SigV4보다 우선하므로 환경의 AWS 자격 증명은 무시돼요. 별도 Claude Console 조직의 API 키는 여기서 동작하지 않아요.

2. Claude Code 구성

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export AWS_REGION=us-east-1

ANTHROPIC_AWS_WORKSPACE_ID는 필수예요. Claude Code가 매 요청마다 anthropic-workspace-id 헤더로 보내요. 기본 URL은 AWS 지역에서 https://aws-external-anthropic.{region}.api.aws로 계산되고, 직접 덮어쓰려면 ANTHROPIC_AWS_BASE_URL. Amazon Bedrock·Microsoft Foundry가 제공자 라우팅에서 우선하므로 CLAUDE_CODE_USE_BEDROCK·CLAUDE_CODE_USE_FOUNDRY가 설정돼 있으면 해제하세요.

3. 모델 버전 고정 — Claude Platform on AWS는 직접 Claude API와 같은 모델 ID를 써요. fable·opus·sonnet·haiku 기본 별칭이 내장 기본값으로 해석되는데 최신 릴리스보다 늦을 수 있어요. 팀에 배포한다면 명시적으로 고정하세요.

export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

프롬프트 캐싱은 자동 활성화. 1시간 TTL은 ENABLE_PROMPT_CACHING_1H=1(높은 요율로 청구).

4. 실행·확인 — claude 실행. 시작 배너에 Claude Platform on AWS가 떠야 해요. /status에서 API provider 줄이 Claude Platform on AWS, 출력에 Workspace ID·AWS region·(오버라이드 시)Claude Platform on AWS base URL이 포함돼요.

Agent SDK 사용

Agent SDK는 CLI와 같은 환경변수를 읽어요. Claude Code 서브프로세스를 실행하는 어떤 프로그램이든 CLAUDE_CODE_USE_ANTHROPIC_AWS·ANTHROPIC_AWS_WORKSPACE_ID·ANTHROPIC_AWS_API_KEY 또는 AWS 자격 증명을 export하면 Claude Platform on AWS를 타게 돼요.

import { query } from "@anthropic-ai/claude-agent-sdk";

process.env.CLAUDE_CODE_USE_ANTHROPIC_AWS = "1";
process.env.ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN";
process.env.AWS_REGION = "us-east-1";

for await (const msg of query({ prompt: "What's in this repo?" })) {
  console.log(msg);
}

기업 프록시 경유

프록시나 LLM 게이트웨이로 트래픽을 보내려면 ANTHROPIC_AWS_BASE_URL에 프록시 주소를 설정해요. 게이트웨이가 자체적으로 서명한다면 CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1로 서명 없는 요청을 보내 게이트웨이가 SigV4 헤더를 추가하게 할 수 있어요. 게이트웨이가 자체 토큰을 요구하면 ANTHROPIC_AUTH_TOKEN에 설정.

트러블슈팅

  • 모든 요청에 403 Forbidden/AccessDenied: IAM 프린시펄에 워크스페이스에서 Anthropic 서비스를 호출할 권한이 없을 가능성. aws-external-anthropic 액션 확인. ANTHROPIC_AWS_API_KEY를 설정했다면 그게 SigV4보다 우선하므로 낡은 키도 같은 오류를 만들 수 있어요.
  • 워크스페이스 누락 오류: ANTHROPIC_AWS_WORKSPACE_ID가 설정 안 됐거나 비어 있음. 모든 요청에 워크스페이스 ID가 필요해요.
  • 요청이 여전히 api.anthropic.com으로 감: CLAUDE_CODE_USE_ANTHROPIC_AWS가 미설정 또는 truthy로 해석 안 됨. 1로 설정하고 /status 확인. CLAUDE_CODE_USE_BEDROCK·CLAUDE_CODE_USE_FOUNDRY가 우선하므로 확인.

더 알아보기