메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

AWS의 Claude Platform은 AWS 인증, IAM 액세스 제어 및 AWS Marketplace 청구를 지원하는 Anthropic 운영 Claude API입니다. 요청은 Anthropic의 API에 직접 도달하므로 동일한 릴리스 일정에 따라 Claude API와 동일한 모델 및 기능을 사용할 수 있습니다. AWS 자격 증명 또는 워크스페이스 API 키로 인증하며, AWS Marketplace를 통해 비용을 지불합니다. 이 가이드를 사용하여 Claude Platform on AWS를 통해 이미 프로비저닝한 워크스페이스를 가리키도록 Claude Code를 설정합니다. 이 전에 필요한 AWS 구독 및 워크스페이스 설정은 Claude Platform on AWS 설명서를 참조하십시오.
AWS Marketplace를 통해 구독하면 AWS 계정에 연결된 새로운 Anthropic 조직이 프로비저닝됩니다. 이 조직은 Anthropic에서 이미 보유한 모든 조직과 별개이며, 자격 증명은 조직 간에 전송되지 않습니다. AWS 연결 조직의 워크스페이스 ID 및 API 키를 사용하고, 기존 Claude Console 계정의 키는 사용하지 마십시오.

​
필수 조건

Claude Code를 구성하기 전에 다음이 필요합니다.
  • AWS Marketplace를 통한 활성 Claude Platform on AWS 구독
  • AWS 연결 Anthropic 조직의 워크스페이스 및 해당 워크스페이스 ID
  • Anthropic 서비스를 호출할 수 있는 권한이 있는 IAM 주체 또는 워크스페이스로 범위가 지정된 API 키
  • 환경, ~/.aws/credentials 또는 SigV4 인증을 원하는 경우 연결된 IAM 역할의 AWS 자격 증명. AWS CLI는 SSO 로그인 흐름에만 필요합니다.

​
설정

​
1. AWS 자격 증명 구성

Claude Code는 Claude Platform on AWS에 대해 두 가지 인증 방법을 지원합니다. 팀이 액세스를 관리하는 방식에 맞는 방법을 선택하십시오. 옵션 A: SigV4를 사용한 AWS 자격 증명 Claude Code는 표준 AWS 자격 증명 체인을 사용하여 SigV4로 요청에 서명합니다. 환경 변수, ~/.aws/credentials의 공유 자격 증명, IAM 역할, AWS SSO 세션 및 AWS SDK가 지원하는 기타 소스입니다. 로컬 사용의 경우 Claude Code를 시작하기 전에 AWS CLI로 로그인하십시오. 아래 예제는 SSO 프로필을 사용하지만 표준 위치에 자격 증명을 생성하는 모든 방법이 작동합니다. 
aws sso login --profile my-profile
export AWS_PROFILE=my-profile
CI 및 자동화의 경우 Anthropic 서비스를 호출할 수 있는 권한이 있는 IAM 역할을 실행기에 제공하고 AWS_REGION을 설정하십시오. 자격 증명 체인이 역할을 자동으로 선택합니다. SSO 자격 증명이 세션 중에 만료되면 awsAuthRefresh를 구성하여 Claude Code가 로그인 명령을 다시 실행하고 실패하는 대신 재시도하도록 합니다. settings.json에 명령을 추가하십시오. 
{
  "awsAuthRefresh": "aws sso login --profile my-profile"
}
옵션 B: 워크스페이스 API 키 워크스페이스 API 키는 장기 보안 비밀이며, 페더레이션된 AWS 자격 증명을 관리하지 않으려는 경우에 유용합니다. AWS Console의 Claude Platform on AWS → API keys 아래에서 생성하고 ANTHROPIC_AWS_API_KEY로 설정하십시오. 
export ANTHROPIC_AWS_API_KEY=sk-ant-xxxxx
키는 x-api-key로 전송되며 SigV4보다 우선하므로 환경의 모든 AWS 자격 증명이 무시됩니다. 별도의 Claude Console 조직의 API 키는 여기서 작동하지 않습니다. 워크스페이스 API 키를 다른 프로덕션 자격 증명처럼 취급하십시오. 사용자 설정 파일 env 블록은 전역으로 내보내지 않고 키를 컴퓨터로 범위를 지정하는 편리한 방법입니다.
/login 및 /logout 명령은 Claude Platform on AWS 인증을 변경하지 않습니다. 인증은 Claude.ai 구독이 아닌 AWS 자격 증명 또는 워크스페이스 API 키를 통해 실행됩니다.

​
2. Claude Code 구성

Claude Code를 기본 Anthropic API 대신 Claude Platform on AWS를 통해 라우팅하는 환경 변수를 설정하십시오. 
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export AWS_REGION=us-east-1
ANTHROPIC_AWS_WORKSPACE_ID는 필수이며 모든 요청에서 anthropic-workspace-id 헤더로 전송됩니다. 기본 URL은 AWS_REGION에서 https://aws-external-anthropic.{region}.api.aws로 계산됩니다. URL을 직접 재정의하려면 ANTHROPIC_AWS_BASE_URL을 설정하십시오. Claude Platform on AWS는 환경에 AWS 자격 증명이 있어도 선택 사항입니다. Bedrock 및 Foundry는 공급자 라우팅에서 우선하므로 설정된 경우 CLAUDE_CODE_USE_BEDROCK 및 CLAUDE_CODE_USE_FOUNDRY를 해제하십시오.

​
3. 모델 버전 고정

Claude Platform on AWS는 직접 Claude API와 동일한 모델 ID를 사용합니다. 기본 별칭 opus, sonnet 및 haiku는 워크스페이스에서 사용 가능한 최신 버전으로 확인됩니다. Claude Code를 팀에 배포하는 경우 모델 ID를 명시적으로 고정하여 새 릴리스가 모든 사람을 한 번에 이동하지 않도록 하십시오. 
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
모델 ID 및 별칭의 전체 목록은 모델 개요를 참조하십시오. 기타 모델 관련 변수는 모델 구성을 참조하십시오. 프롬프트 캐싱은 자동으로 활성화됩니다. 1시간 캐시 쓰기는 5분 쓰기보다 높은 요금으로 청구됩니다. 5분 기본값 대신 1시간 캐시 TTL을 요청하려면 ENABLE_PROMPT_CACHING_1H=1을 설정하십시오.

​
Agent SDK 사용

Agent SDK는 CLI와 동일한 환경 변수를 읽으므로 Claude Code 하위 프로세스를 생성하는 모든 프로그램은 호출 전에 CLAUDE_CODE_USE_ANTHROPIC_AWS, ANTHROPIC_AWS_WORKSPACE_ID 및 ANTHROPIC_AWS_API_KEY 또는 AWS 자격 증명을 내보내 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);
}
이 예제는 SigV4에 대한 주변 AWS 자격 증명 체인을 사용합니다. 대신 워크스페이스 API 키로 인증하려면 동일한 방식으로 ANTHROPIC_AWS_API_KEY를 설정하십시오. 더 광범위한 Agent SDK 표면은 Agent SDK 개요를 참조하십시오.

​
기업 프록시를 통해 라우팅

프록시 또는 LLM 게이트웨이를 통해 트래픽을 라우팅하려면 ANTHROPIC_AWS_BASE_URL을 프록시의 주소로 설정하십시오. Claude Code는 동일한 워크스페이스 및 인증 헤더를 사용하여 해당 URL로 요청을 보내므로 변경되지 않은 상태로 전달하는 모든 게이트웨이가 작동합니다. 
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export ANTHROPIC_AWS_BASE_URL=https://anthropic-proxy.example.com
게이트웨이가 요청 자체에 서명하는 경우 CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1을 설정하여 Claude Code가 서명되지 않은 요청을 보내고 게이트웨이가 AWS로 전달하기 전에 SigV4 헤더를 추가하도록 합니다. 게이트웨이가 자체 토큰을 요구하는 경우 ANTHROPIC_AUTH_TOKEN에 설정하십시오. 
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export ANTHROPIC_AWS_BASE_URL=https://anthropic-proxy.example.com

​
문제 해결

/status를 실행하여 확인된 공급자 및 명시적으로 구성된 워크스페이스 ID, 지역, 기본 URL 재정의 및 인증 건너뛰기 설정을 확인하십시오. 이것이 Claude Code가 Claude Platform on AWS를 대상으로 하는지 확인하는 가장 빠른 방법입니다.

​
모든 요청에서 403 Forbidden 또는 AccessDenied

Claude Code가 확인한 IAM 주체는 워크스페이스에서 Anthropic 서비스를 호출할 수 있는 권한이 없을 가능성이 높습니다. AWS 프로필에 연결된 역할 또는 Claude Code를 시작한 실행기를 확인하고 IAM 작업 참조에 설명된 aws-external-anthropic 작업이 있는지 확인하십시오. ANTHROPIC_AWS_API_KEY를 설정한 경우 키가 SigV4보다 우선하고 오래된 키는 동일한 오류를 생성합니다. AWS Console의 Claude Platform on AWS → API keys 아래에서 키를 다시 생성하거나 변수를 해제하여 AWS 자격 증명으로 돌아가십시오.

​
요청이 누락된 워크스페이스 오류로 실패합니다.

ANTHROPIC_AWS_WORKSPACE_ID가 설정되지 않았거나 비어 있을 가능성이 높습니다. 모든 Claude Platform on AWS 요청에는 워크스페이스 ID가 포함되어야 합니다. AWS 자격 증명에 의해 암시되지 않습니다. AWS Console 서비스 페이지의 Workspaces 아래에서 ID를 찾고 Claude Code를 시작하기 전에 내보내십시오.

​
요청이 여전히 api.anthropic.com으로 이동합니다.

CLAUDE_CODE_USE_ANTHROPIC_AWS가 설정되지 않았거나 truthy로 구문 분석되지 않는 값으로 설정되었을 가능성이 높습니다. 1로 설정하고 /status를 실행하여 확인된 공급자를 확인하십시오. CLAUDE_CODE_USE_BEDROCK 또는 CLAUDE_CODE_USE_FOUNDRY도 설정된 경우 Claude Platform on AWS보다 우선합니다.

​
추가 리소스

Claude Code 구성 전에 필요한 Claude Platform on AWS 구독, 워크스페이스 및 IAM 설정은 플랫폼 설명서에서 다룹니다.