Guia Completo de Variáveis de Ambiente do Claude Code: Resolva Erros de Compatibilidade do AWS Bedrock com Apenas 1 Configuração

Nota do autor: Detalhamento do papel e dos métodos de configuração de todas as mais de 60 variáveis de ambiente do Claude Code, com foco em como a CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS resolve o erro de header anthropic-beta em plataformas de terceiros.

Ao usar o Claude Code para se conectar ao AWS Bedrock, Google Vertex AI ou outros gateways de Modelo de Linguagem Grande de terceiros, você muito provavelmente já encontrou este erro: "Unexpected value(s) for the anthropic-beta header". A raiz desse problema é que o Claude Code, por padrão, envia cabeçalhos Beta experimentais específicos da API da Anthropic, que plataformas como o AWS Bedrock não reconhecem.

A solução requer apenas uma linha de configuração: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Mas as variáveis de ambiente do Claude Code vão muito além dessa — a documentação oficial lista mais de 60 variáveis de ambiente, cobrindo configuração de autenticação, seleção de modelo, ajuste de performance, chaves de funcionalidade e muito mais. Este artigo organizará sistematicamente essas variáveis para ajudar você a localizar e resolver rapidamente diversos problemas de configuração no Claude Code.

Valor central: Ao ler este artigo, você dominará o sistema completo de variáveis de ambiente do Claude Code, será capaz de resolver rapidamente problemas de compatibilidade com AWS Bedrock/Vertex AI e aprenderá a otimizar a experiência de uso e os custos através dessas configurações.

Pontos Centrais das Variáveis de Ambiente do Claude Code

As mais de 60 variáveis de ambiente do Claude Code podem ser divididas em 6 categorias principais. Aqui estão as variáveis essenciais que você deve conhecer:

Duas Formas de Configurar Variáveis de Ambiente no Claude Code

Método 1: Variável de Ambiente do Shell (Efeito Temporário)

Configure no terminal antes de iniciar o Claude Code; válido apenas para a sessão atual:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_API_KEY="sua-chave-api"
claude

Método 2: Configuração no settings.json (Efeito Permanente)

Configure o campo env em ~/.claude/settings.json; carregado automaticamente em cada inicialização:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "sua-chave-api"
  }
}

🎯 Recomendação: Para configurações que devem ser permanentes (como chave API ou correções de compatibilidade de plataforma), sugerimos o uso do arquivo settings.json para evitar o export manual toda vez. Se a sua chave API vier de uma plataforma de terceiros como a APIYI (apiyi.com), basta configurá-la aqui também.

Guia de Variáveis de Ambiente do Claude Code: Resolvendo Problemas de Compatibilidade com AWS Bedrock

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS em Detalhes

Este é o protagonista deste artigo. Quando você utiliza o Claude Code através do AWS Bedrock, Google Vertex AI, LiteLLM ou outros gateways de terceiros, o Claude Code adiciona automaticamente identificadores Beta experimentais da Anthropic nos cabeçalhos da requisição, como por exemplo:

anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20

Esses identificadores Beta são funcionalidades exclusivas da API direta da Anthropic. Plataformas de terceiros, como o AWS Bedrock, não conseguem reconhecê-los, o que resulta no erro:

Error: Unexpected value(s) for the anthropic-beta header

Como resolver:

# Opção 1: Comando no Shell
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Opção 2: No arquivo settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Ao definir como 1, o Claude Code deixará de enviar esses cabeçalhos Beta experimentais, garantindo compatibilidade com todas as plataformas de terceiros.

Problemas Conhecidos e Soluções Temporárias

De acordo com os registros de Issues no GitHub, algumas versões do Claude Code (posteriores à 2.1.18) apresentam um problema onde esta variável de ambiente não funciona perfeitamente — mesmo com CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, alguns novos cabeçalhos Beta (como advanced-tool-use-2025-11-20) ainda podem ser enviados.

Se você continuar enfrentando problemas, tente estas medidas adicionais:

• Fazer o downgrade da versão do Claude Code: Volte para uma versão estável conhecida, como a 2.1.68.
• Usar o gateway LiteLLM: O LiteLLM oferece o arquivo de configuração anthropic_beta_headers_config.json, que permite um controle refinado sobre quais cabeçalhos Beta são encaminhados.
• Configurar DISABLE_PROMPT_CACHING simultaneamente: Desativar o cache de comandos evita o envio de cabeçalhos Beta relacionados ao prompt-caching-scope.

# Configuração de compatibilidade total
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

Referência Rápida de Variáveis de Ambiente do Claude Code

Categoria 1: Autenticação e Configuração de API

Esta é a categoria mais básica e comum, que controla como o Claude Code se conecta ao serviço de API:

🎯 Atenção usuários de plataformas de terceiros: Ao usar plataformas como APIYI apiyi.com, você precisa configurar tanto ANTHROPIC_API_KEY quanto ANTHROPIC_BASE_URL. O Claude Code priorizará a chave API das variáveis de ambiente, mesmo que você já tenha feito login com uma conta de assinatura da Anthropic.

Categoria 2: Seleção e Configuração de Modelo

Controla qual modelo o Claude Code utiliza e os parâmetros de comportamento do modelo:

Categoria 3: Compatibilidade de Plataforma e Gateways

Estas variáveis resolvem especificamente problemas de compatibilidade entre o Claude Code e diferentes plataformas de nuvem ou gateways de LLM:

Categoria 4: Chaves de Funcionalidade (Toggles)

Desative funções específicas usando os prefixos DISABLE_ ou CLAUDE_CODE_DISABLE_ definidos como 1:

Categoria 5: Gerenciamento de Contexto e Performance

Controla como o Claude Code gerencia a janela de contexto e o uso de recursos:

🎯 Dica de Otimização de Performance: Se você notar que o Claude Code compacta o contexto com muita frequência em conversas longas, pode definir CLAUDE_AUTOCOMPACT_PCT_OVERRIDE para um valor menor (como 50). Isso faz com que a compactação ocorra mais cedo, reduzindo a perda súbita de informações. Essas configurações também são suportadas ao fazer chamadas via APIYI apiyi.com.

Guia Rápido de Variáveis de Ambiente do Claude Code

Exemplo minimalista: Configurando o Claude Code para conectar a plataformas de API de terceiros

# Inicie o Claude Code após definir as variáveis de ambiente no terminal
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com/v1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": []
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1",
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1"
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://my-resource.services.ai.azure.com/anthropic",
    "ANTHROPIC_FOUNDRY_API_KEY": "your-foundry-key",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Dica: Se você não quer perder tempo com as configurações complexas do AWS Bedrock ou Azure, pode usar toda a linha de modelos Claude diretamente através da APIYI (apiyi.com). Basta configurar as variáveis de chave API e Base URL, sem precisar lidar com autenticação de plataformas de nuvem ou problemas de compatibilidade.

Perguntas Frequentes

Resumo

Pontos principais das variáveis de ambiente do Claude Code:

1. Resolvendo erros do AWS Bedrock: Defina CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 para desativar os cabeçalhos Beta experimentais. Essa configuração de uma única linha resolve o erro "Unexpected value(s) for the anthropic-beta header".
2. Mais de 60 variáveis em 6 categorias: Autenticação, seleção de modelo, compatibilidade de plataforma, chaves de funcionalidade, gerenciamento de contexto e outras configurações.
3. Duas formas de configuração: Shell export (temporário) e settings.json (permanente). Recomendamos priorizar a configuração permanente no arquivo settings.json.
4. Solução simplificada via plataformas de terceiros: Usando plataformas de API unificadas como a APIYI (apiyi.com), você só precisa configurar as variáveis ANTHROPIC_API_KEY e ANTHROPIC_BASE_URL, eliminando a complexidade de autenticação de nuvens e problemas de compatibilidade com cabeçalhos Beta.

Recomendamos utilizar a APIYI (apiyi.com) para uma integração rápida com o Claude Code. A plataforma oferece créditos gratuitos e uma interface unificada, evitando as dificuldades comuns de configuração encontradas no AWS Bedrock ou Vertex AI.

📚 Referências

1. Documentação Oficial do Claude Code – Variáveis de Ambiente: Lista completa de variáveis e descrições.

   • Link: code.claude.com/docs/en/env-vars
   • Descrição: Referência oficial para todas as mais de 60 variáveis de ambiente.

2. Documentação Oficial do Claude Code – Configurações: Escopos de configuração e especificações do settings.json.

   • Link: code.claude.com/docs/en/settings
   • Descrição: Entenda o sistema de hierarquia de quatro níveis (Managed/User/Project/Local).

3. Documentação Oficial do Claude Code – Amazon Bedrock: Guia de integração com AWS Bedrock.

   • Link: code.claude.com/docs/en/amazon-bedrock
   • Descrição: Configurações específicas para Bedrock e resolução de problemas comuns.

4. GitHub Issue #22893 – DISABLE_EXPERIMENTAL_BETAS não funciona totalmente: Relato de bug da comunidade.

   • Link: github.com/anthropics/claude-code/issues/22893
   • Descrição: Informações sobre limitações conhecidas desta variável e soluções temporárias.

5. LiteLLM – Gerenciamento de Cabeçalhos Beta do Claude Code: Solução de filtragem de cabeçalhos Beta na camada de gateway.

   • Link: docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • Descrição: Como realizar um controle refinado dos cabeçalhos Beta ao usar o gateway LiteLLM.

Autor: Equipe Técnica APIYI
Troca de conhecimentos: Sinta-se à vontade para discutir suas experiências de configuração do Claude Code nos comentários. Para mais tutoriais, visite nossa central de documentação em docs.apiyi.com.