Claude Code no Claude Platform on AWS
Configure Claude Code para usar a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace.
export const ContactSalesCard = ({surface}) => {
const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content};
const iconArrowRight = (size = 13) => ;
const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } };
return
https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost">
View plans
<a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay">
Contact sales {iconArrowRight()}
export const Experiment = ({flag, treatment, children}) => {
const VID_KEY = 'exp_vid';
const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);
const fnv1a = s => {
let h = 0x811c9dc5;
for (let i = 0; i < s.length; i++) {
h ^= s.charCodeAt(i);
h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);
}
return h >>> 0;
};
const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';
const [decision] = useState(() => {
const params = new URLSearchParams(location.search);
const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];
const force = params.get('gb-force');
if (force) {
for (const p of force.split(',')) {
const [k, v] = p.split(':');
if (k === flag) return {
variant: v || 'treatment',
track: false
};
}
}
if (navigator.globalPrivacyControl) {
return {
variant: 'control',
track: false
};
}
const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);
if (prefsMatch) {
try {
if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {
return {
variant: 'control',
track: false
};
}
} catch {
return {
variant: 'control',
track: false
};
}
} else {
const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];
if (!country || CONSENT_COUNTRIES.has(country)) {
return {
variant: 'control',
track: false
};
}
}
let vid;
try {
const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);
if (ajsMatch) {
vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');
} else {
vid = localStorage.getItem(VID_KEY);
if (!vid) {
vid = crypto.randomUUID();
}
document.cookie = ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000;
}
try {
localStorage.setItem(VID_KEY, vid);
} catch {}
} catch {
return {
variant: 'control',
track: false
};
}
const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);
return {
variant,
track: true,
vid
};
});
useEffect(() => {
if (!decision.track) return;
fetch('https://api.anthropic.com/api/event_logging/v2/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-service-name': 'claude_code_docs'
},
body: JSON.stringify({
events: [{
event_type: 'GrowthbookExperimentEvent',
event_data: {
device_id: decision.vid,
anonymous_id: decision.vid,
timestamp: new Date().toISOString(),
experiment_id: flag,
variation_id: decision.variant === 'treatment' ? 1 : 0,
environment: 'production'
}
}]
}),
keepalive: true
}).catch(() => {});
}, []);
return decision.variant === 'treatment' ? treatment : children;
};
<Experiment flag="docs-contact-sales-cta" treatment={
Claude Platform on AWS é a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace. As solicitações chegam diretamente à API da Anthropic, portanto você obtém os mesmos modelos e recursos de API que a Claude API no mesmo cronograma de lançamento. Você se autentica com credenciais AWS ou uma chave de API do workspace, e paga através do AWS Marketplace.
Os recursos do lado do cliente que Claude Code ativa através do serviço de sinalizadores de recursos da Anthropic estão desativados por padrão, e a ferramenta advisor não está disponível. Consulte a matriz de disponibilidade de recursos para obter a lista completa.
Use este guia para apontar Claude Code para um workspace que você já provisionou através do Claude Platform on AWS. Para a assinatura AWS e configuração do workspace que vem antes disso, consulte a documentação do Claude Platform on AWS.
Pré-requisitos
Antes de configurar Claude Code, você precisa de:
- Uma assinatura ativa do Claude Platform on AWS através do AWS Marketplace
- Um workspace em sua organização Anthropic vinculada ao AWS, com seu ID de workspace
- Um principal IAM com permissão para invocar o serviço Anthropic, ou uma chave de API com escopo para o workspace
- Credenciais AWS em seu ambiente, em
~/.aws/credentials, ou de uma função IAM anexada se você quiser autenticação SigV4. A AWS CLI é necessária apenas para o fluxo de login SSO.
Configuração
1. Configure credenciais AWS
Claude Code suporta dois métodos de autenticação para Claude Platform on AWS. Escolha o método que se adequa à forma como sua equipe gerencia o acesso.
Opção A: Credenciais AWS com SigV4
Claude Code assina solicitações com SigV4 usando a cadeia de credenciais AWS padrão: variáveis de ambiente, credenciais compartilhadas em ~/.aws/credentials, funções IAM, sessões AWS SSO e qualquer outra fonte que o AWS SDK suporte.
Para uso local, faça login com a AWS CLI antes de iniciar Claude Code. O exemplo abaixo usa um perfil SSO, mas qualquer método que produza credenciais nos locais padrão funciona.
aws sso login --profile my-profile
export AWS_PROFILE=my-profile
Para CI e automação, dê ao executor uma função IAM com permissão para invocar o serviço Anthropic e defina AWS_REGION. A cadeia de credenciais pega a função automaticamente.
Se suas credenciais SSO expirarem durante a sessão, configure awsAuthRefresh para que Claude Code execute novamente seu comando de login e tente novamente em vez de falhar. A atualização automática no Claude Platform on AWS requer Claude Code v2.1.198 ou posterior; versões anteriores param com um prompt para executar /login, que não pode atualizar credenciais AWS. Adicione o comando ao seu arquivo de configurações, como ~/.claude/settings.json:
{
"awsAuthRefresh": "aws sso login --profile my-profile"
}
Claude Code também executa este comando na inicialização quando não consegue validar suas credenciais AWS existentes e mostra a saída do comando em um painel Authentication até que o login seja concluído.
Com awsAuthRefresh configurado, execute /login, selecione plataforma de terceiros, depois selecione Claude Platform on AWS · atualizar credenciais em Usando plataformas de terceiros. Claude Code executa o comando configurado e relê suas credenciais AWS sem uma reinicialização. Esta opção requer Claude Code v2.1.186 ou posterior.
Opção B: Chave de API do Workspace
Uma chave de API do workspace é um segredo de longa duração, útil quando você não quer gerenciar credenciais AWS federadas. Gere uma no Console AWS em Claude Platform on AWS → API keys e defina-a como ANTHROPIC_AWS_API_KEY:
export ANTHROPIC_AWS_API_KEY=sk-ant-xxxxx
A chave é enviada como x-api-key e tem precedência sobre SigV4, portanto qualquer credencial AWS em seu ambiente é ignorada. Chaves de API de uma organização Claude Console separada não funcionarão aqui.
Trate chaves de API do workspace como qualquer outra credencial de produção. O bloco env do arquivo de configurações do usuário é uma maneira conveniente de escopar a chave para sua máquina sem exportá-la globalmente.
2. Configure Claude Code
Defina as variáveis de ambiente que rotearão Claude Code através do Claude Platform on AWS em vez da API Anthropic padrão.
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export AWS_REGION=us-east-1
ANTHROPIC_AWS_WORKSPACE_ID é obrigatório. Claude Code o envia em cada solicitação como o cabeçalho anthropic-workspace-id. Substitua o valor de exemplo wrkspc_01ABCDEFGHIJKLMN pelo seu próprio ID de workspace da sua configuração Claude Platform on AWS.
Claude Code calcula a URL base como https://aws-external-anthropic.{region}.api.aws a partir da região AWS, que ele resolve com a mesma precedência que Amazon Bedrock. Para substituir a URL diretamente, defina ANTHROPIC_AWS_BASE_URL.
Claude Platform on AWS é opt-in mesmo quando credenciais AWS estão presentes em seu ambiente. Amazon Bedrock e Microsoft Foundry têm precedência no roteamento de provedores, portanto desdefina CLAUDE_CODE_USE_BEDROCK e CLAUDE_CODE_USE_FOUNDRY se estiverem definidas.
3. Fixe versões de modelo
Claude Platform on AWS usa os mesmos IDs de modelo que a API Claude direta.
Os aliases padrão fable, opus, sonnet e haiku resolvem para os padrões integrados do Claude Code para Claude Platform on AWS, que podem ficar atrás da versão mais recente. Sem ANTHROPIC_DEFAULT_OPUS_MODEL, o alias opus resolve para Opus 5.5. Antes da v2.1.280, ele resolvia para Opus 5 a partir da v2.1.219, para Opus 4.8 a partir da v2.1.207 e para Opus 4.7 antes disso.
Se você implantar Claude Code para uma equipe, fixe os IDs de modelo explicitamente para que um novo lançamento não mova todos de uma vez:
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
Para a lista completa de IDs de modelo e aliases, consulte Visão geral de modelos. Para outras variáveis relacionadas a modelos, consulte Configuração de modelo.
Prompt caching é ativado automaticamente. Para solicitar um TTL de cache de 1 hora em vez do padrão de 5 minutos, defina ENABLE_PROMPT_CACHING_1H=1. A API cobra gravações de cache de 1 hora a uma taxa mais alta. Consulte preços de prompt caching para as taxas.
Para definir TTLs diferentes para sua conversa principal e para as solicitações que Claude Code faz fora dela, escolha o TTL você mesmo.
4. Inicie e verifique
Inicie Claude Code e confirme o roteamento:
claude
O banner de inicialização mostra Claude Platform on AWS quando o provedor está ativo. Execute /status para verificar os detalhes: a linha API provider lê Claude Platform on AWS e a saída inclui seu Workspace ID, a AWS region e a Claude Platform on AWS base URL se você definir uma substituição.
Use o Agent SDK
O Agent SDK lê as mesmas variáveis de ambiente que a CLI, portanto qualquer programa que gere o subprocesso Claude Code pode direcionar Claude Platform on AWS exportando CLAUDE_CODE_USE_ANTHROPIC_AWS, ANTHROPIC_AWS_WORKSPACE_ID e ANTHROPIC_AWS_API_KEY ou credenciais AWS antes da chamada.
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);
}
Este exemplo depende da cadeia de credenciais AWS ambiente para SigV4. Para autenticar com uma chave de API do workspace em vez disso, defina ANTHROPIC_AWS_API_KEY da mesma forma. Para a superfície mais ampla do Agent SDK, consulte Visão geral do Agent SDK.
Rotear através de um proxy corporativo
Para rotear tráfego através de um proxy ou gateway LLM, defina ANTHROPIC_AWS_BASE_URL para o endereço do proxy. Claude Code envia solicitações para essa URL com os mesmos cabeçalhos de workspace e autenticação, portanto qualquer gateway que os encaminhe inalterados funciona.
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export ANTHROPIC_AWS_BASE_URL=https://anthropic-proxy.example.com
Se seu gateway assina solicitações em si, defina CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1 para que Claude Code envie solicitações não assinadas e deixe o gateway adicionar cabeçalhos SigV4 antes de encaminhar para AWS. Se o gateway requer seu próprio token, defina-o em 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
Troubleshooting
Execute /status para ver o provedor resolvido e qualquer ID de workspace, região, substituição de URL base e configuração de salto de autenticação explicitamente configurados. Esta é a maneira mais rápida de confirmar que Claude Code está direcionando Claude Platform on AWS.
`403 Forbidden` ou `AccessDenied` em cada solicitação
O principal IAM que Claude Code resolveu provavelmente não tem permissão para invocar o serviço Anthropic em seu workspace. Verifique a função anexada ao seu perfil AWS ou ao executor que iniciou Claude Code, e verifique se ela tem as ações aws-external-anthropic documentadas na referência de ação IAM.
Se você definir ANTHROPIC_AWS_API_KEY, a chave tem precedência sobre SigV4 e uma chave obsoleta produz o mesmo erro. Regenere a chave no Console AWS em Claude Platform on AWS → API keys ou desdefina a variável para voltar às suas credenciais AWS.
Solicitações falham com um erro de workspace ausente
ANTHROPIC_AWS_WORKSPACE_ID provavelmente está desdefido ou vazio. Cada solicitação do Claude Platform on AWS deve incluir o ID do workspace. Não é implícito por suas credenciais AWS. Encontre o ID em sua configuração do Claude Platform on AWS e exporte-o antes de iniciar Claude Code.
Solicitações ainda vão para `api.anthropic.com`
CLAUDE_CODE_USE_ANTHROPIC_AWS provavelmente está desdefido ou definido para um valor que não é analisado como verdadeiro. Defina-o como 1 e execute /status para confirmar o provedor resolvido. Se CLAUDE_CODE_USE_BEDROCK ou CLAUDE_CODE_USE_FOUNDRY também estiver definido, esses têm precedência sobre Claude Platform on AWS.
Recursos adicionais
A assinatura do Claude Platform on AWS, configuração de workspace e IAM que vem antes de configurar Claude Code é coberta na documentação da plataforma:
- Visão geral do Claude Platform on AWS: assinatura, configuração de workspace e referência de produto
- Referência de ação IAM: permissões e políticas gerenciadas