Documentação

Claude Code

O Claude Code trata qualquer endpoint no formato Anthropic como um gateway. Duas variáveis o direcionam à Kunavo, outras três fixam modelos oferecidos pela Kunavo, a instalação permanece intacta e cada sessão é cobrada por token do seu saldo, em vez de uma assinatura.

Duas variáveis de ambiente — ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN — colocam o Claude Code em pagamento conforme o uso sem alterar a instalação.

# One terminal session
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # origin, no /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves. Claude Code's default and its opus/sonnet aliases
# follow Anthropic's newest models; the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, /model sonnet 404s.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

claude

ANTHROPIC_BASE_URL é a origem. O Claude Code acrescenta /v1/messages por conta própria — o próprio comando de verificação da Anthropic é curl "$ANTHROPIC_BASE_URL/v1/messages" —, portanto um valor terminado em /v1 gera solicitações para /v1/v1/messages e retorna 404. Essa é a falha de configuração mais comum; a página de ANTHROPIC_BASE_URL aborda as demais.

Fixe os modelos. O padrão integrado do Claude Code é o Opus mais recente (Opus 5.5 em setembro de 2026, segundo a documentação de configuração de modelos da Anthropic), e um modelo que o Kunavo ainda não oferece retorna 404 na primeira solicitação. O alias sonnet solicita o Sonnet 5.5, que o Kunavo não oferece; portanto, /model sonnet retorna 404, a menos que também seja fixado. ANTHROPIC_MODEL define o modelo da sessão; ANTHROPIC_DEFAULT_OPUS_MODEL cobre /model opus (o Opus 5.5 requer o Claude Code v2.1.280 ou posterior), ANTHROPIC_DEFAULT_SONNET_MODEL cobre /model sonnet, e ANTHROPIC_DEFAULT_HAIKU_MODEL as chamadas em segundo plano. Qualquer ID de GET /v1/models funciona.

Use ANTHROPIC_AUTH_TOKEN, não ANTHROPIC_API_KEY. As duas variáveis escolhem um cabeçalho: AUTH_TOKEN envia Authorization: Bearer, e API_KEY envia x-api-key. A Kunavo aceita ambos, mas API_KEY exige uma solicitação única de aprovação em uma sessão interativa antes de entrar em vigor; AUTH_TOKEN não exige.

Prefere não editar variáveis de ambiente manualmente? O CC Switch pode salvar a Kunavo como provedor do Claude Code — com a mesma raiz de serviço e a mesma chave bearer mencionadas acima; a configuração campo a campo está na página do CC Switch.

Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de Claude Code.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
Exporte as variáveis acima para a sessão ou salve-as no bloco env de ~/.claude/settings.json: {"env":{"ANTHROPIC_BASE_URL":"https://api.kunavo.com","ANTHROPIC_AUTH_TOKEN":"sk-kn-...","ANTHROPIC_MODEL":"claude-sonnet-5","ANTHROPIC_DEFAULT_OPUS_MODEL":"claude-opus-5-5","ANTHROPIC_DEFAULT_SONNET_MODEL":"claude-sonnet-5","ANTHROPIC_DEFAULT_HAIKU_MODEL":"claude-haiku-4-5"}}. A documentação da Anthropic deixa claro que a credencial não deve ficar no .claude/settings.json de um projeto — esse arquivo é enviado ao repositório.
Execute claude e abra a aba Status. Uma linha que mencione Auth token confirma que a credencial do gateway está ativa; uma linha Login method que mencione uma conta claude.ai indica que a variável não foi reconhecida.
Para a extensão do VS Code, as variáveis devem estar em claudeCode.environmentVariables nas próprias configurações de usuário do VS Code — a extensão verifica as credenciais antes de iniciar, então ~/.claude/settings.json chega ao processo iniciado, mas não a essa verificação.

Verificado em “Conectar o Claude Code a um gateway de LLM” da Anthropic em 3 de outubro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Esta é a versão resumida. O guia completo — escolha do modelo, custo de uma sessão real e modos de falha — está em guia de chave de API do Claude Code.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Claude Code.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

ID do modelo	Entrada / saída da Kunavo	Onde se encaixa em Claude Code
`claude-sonnet-5`	$1.40 / $7.00	o modelo de trabalho padrão — definido com /model ou ANTHROPIC_MODEL
`claude-opus-5-5`	$2.80 / $14.00	planejamento e edições no nível da arquitetura
`claude-haiku-4-5`	$0.70 / $3.50	o nível menor e mais rápido que o Claude Code usa para o trabalho em segundo plano
`claude-fable-5`	$7.00 / $35.00	o nível de ponta, para planos que justificam sua tarifa

A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

Perguntas frequentes

Como uso o Claude Code sem uma assinatura Claude?

Defina ANTHROPIC_BASE_URL como um endpoint no formato Anthropic e ANTHROPIC_AUTH_TOKEN como a chave desse endpoint; fixe ANTHROPIC_MODEL em um modelo oferecido pelo endpoint — o padrão integrado do Claude Code pode não estar disponível. O Claude Code passa a se autenticar no endpoint, em vez de claude.ai, e o uso é cobrado por token por quem controla essa credencial, não em um plano de assinatura. A Anthropic documenta esse modo como modo gateway; o login salvo do claude.ai permanece no disco, sem uso, e volta a ser usado assim que as variáveis são removidas.

ANTHROPIC_BASE_URL deve incluir /v1?

Não. O Claude Code acrescenta a rota por conta própria, então a variável deve conter a origem — https://api.kunavo.com, não https://api.kunavo.com/v1. O próprio comando de verificação da Anthropic é curl "$ANTHROPIC_BASE_URL/v1/messages", que mostra diretamente a concatenação. Uma URL base que já termine em /v1 envia solicitações para /v1/v1/messages e retorna 404.

Qual é a diferença entre ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY?

Elas colocam a credencial em cabeçalhos HTTP diferentes: ANTHROPIC_AUTH_TOKEN envia Authorization: Bearer; ANTHROPIC_API_KEY envia x-api-key. Se a chave estiver na variável errada, ela chega ao endpoint em um cabeçalho que ele não lê, e a solicitação falha com 401. Se a documentação do gateway disser "bearer token", use ANTHROPIC_AUTH_TOKEN; se disser "API key" ou "x-api-key", use ANTHROPIC_API_KEY.

Quais recursos do Claude Code deixam de funcionar com uma URL base personalizada?

O Remote Control e a ditagem por voz precisam de uma identidade claude.ai e ficam indisponíveis enquanto uma credencial de gateway estiver definida; além disso, o Remote Control é desativado sempre que ANTHROPIC_BASE_URL aponta para um host que não seja da Anthropic. A verificação de disponibilidade do modo rápido também acessa diretamente api.anthropic.com, sem seguir a URL base. Todo o ciclo principal — agente, ferramentas, subagentes e servidores MCP — usa a API Messages e não é afetado.