Documentação

ANTHROPIC_BASE_URL

A variável de ambiente que direciona o Claude Code e os SDKs da Anthropic para um endpoint diferente de api.anthropic.com — referência completa das variáveis, configuração por cliente e os dois problemas que causam quase todas as falhas.

ANTHROPIC_BASE_URL informa aos SDKs da Anthropic e ao Claude Code para qual host enviar as solicitações à API, substituindo o padrão https://api.anthropic.com. Defina uma origem sem caminho — o cliente acrescenta /v1/messages por conta própria — e use junto com ANTHROPIC_AUTH_TOKEN, que é enviado no cabeçalho Authorization: Bearer.

~/.zshrc

# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

Depois, abra um novo terminal: o Claude Code e os SDKs leem essas variáveis ao iniciar o processo, então uma sessão que já estava em execução mantém o endpoint anterior.

Não inclua /v1 em ANTHROPIC_BASE_URL. Os clientes da Anthropic acrescentam o caminho por conta própria, então https://api.kunavo.com/v1 gera solicitações para /v1/v1/messages e todas as chamadas retornam 404. O SDK da OpenAI usa a convenção oposta e exige /v1 em sua base_url — essa diferença é o erro de configuração mais comum neste caso.

Todas as variáveis e o que fazem

A lista completa das variáveis lidas pelo Claude Code está na referência de variáveis de ambiente da Anthropic. Estas são as que importam ao redirecionar o endpoint.

Variável	Valor	O que controla
`ANTHROPIC_BASE_URL`	`https://api.kunavo.com`	A origem para a qual todas as solicitações são enviadas. Sem caminho e sem barra final.
`ANTHROPIC_AUTH_TOKEN`	`sk-kn-…`	Credencial enviada como Authorization: Bearer. É esta que um gateway exige.
`ANTHROPIC_API_KEY`	`sk-ant-…`	Credencial enviada no cabeçalho x-api-key, como espera api.anthropic.com. Defina esta variável OU o token acima, não ambos.
`ANTHROPIC_MODEL`	`claude-sonnet-5`	O modelo principal usado pelo Claude Code na conversa.
`ANTHROPIC_DEFAULT_OPUS_MODEL`	`claude-opus-5-5`	O modelo por trás do alias opus (/model opus). O padrão próprio do Claude Code é o Opus mais recente, portanto fixe-o em um modelo servido pelo endpoint. O Opus 5.5 requer o Claude Code v2.1.280 ou posterior.
`ANTHROPIC_DEFAULT_SONNET_MODEL`	`claude-sonnet-5`	O modelo por trás do alias sonnet (/model sonnet). Por padrão, o alias solicita o Sonnet 5.5, portanto fixe-o em um Sonnet servido pelo endpoint.
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`claude-haiku-4-5`	O modelo usado pelo alias haiku (/model haiku e subagentes configurados com haiku) também é o que o Claude Code usa para as próprias chamadas em segundo plano. A partir da v2.1.293, o alias aponta para o Haiku 5.5; por isso, fixe-o em um modelo Haiku oferecido pelo endpoint.

Os nomes dos modelos devem corresponder aos modelos realmente disponibilizados pelo endpoint. Apontar para um gateway e manter um ID de modelo que ele não oferece é a segunda falha mais comum, e ela resulta em 404 model_not_found, não em erro de autenticação. Os IDs de modelo do Kunavo estão listados na página de modelos e são retornados em tempo real por GET /v1/models.

Configuração por cliente

Claude Code

Adicione as exportações ao perfil do shell a partir do qual o Claude Code é iniciado e abra um novo terminal. Nada muda na instalação nem no fluxo de trabalho.

~/.zshrc

# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
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

Execute /status dentro do Claude Code para confirmar qual endpoint a sessão atual está usando. Instruções passo a passo, incluindo onde gerar a chave: definir uma chave de API no Claude Code.

SDK da Anthropic (Python / TypeScript)

Os SDKs leem as mesmas variáveis de ambiente, e também é possível passar ambas as configurações ao construtor — útil quando um processo se comunica com mais de um endpoint.

anthropic_sdk.py

from anthropic import Anthropic

# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
    base_url="https://api.kunavo.com",
    auth_token="sk-kn-...",          # sets the Authorization: Bearer header
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)

SDK da OpenAI — a outra convenção

Se seu código já usa a API da OpenAI, você não precisa de ANTHROPIC_BASE_URL. Aponte base_url para o caminho compatível com OpenAI — desta vez, incluindo /v1 — e chame os mesmos modelos Claude por meio de /v1/chat/completions.

openai_sdk.py

from openai import OpenAI

# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)

Cline, Roo Code, Kilo Code, Cursor

Na maioria dos agentes de editor, as mesmas duas configurações ficam na interface própria do produto, em vez de serem definidas pelo ambiente: um campo de "URL base" ou "endpoint personalizado" e um campo de chave de API. As regras não mudam — origem sem /v1 para um provedor no estilo Anthropic, e a chave no campo de chave de API. Guias por cliente: Cline, Roo Code, Kilo Code.

Verifique se funcionou

Uma chamada curl confirma a URL base e a credencial ao mesmo tempo. Uma resposta 200 com um corpo JSON significa que ambas estão corretas.

# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

# In Claude Code, /status shows the endpoint the session is actually using.

Quando não funciona

Sintoma	Causa	Correção
404 em todas as solicitações	`/v1` no fim de `ANTHROPIC_BASE_URL`	Defina apenas a origem. O cliente acrescenta /v1/messages.
401 / invalid x-api-key	Credencial definida como `ANTHROPIC_API_KEY` quando o endpoint autentica com tokens bearer	Use `ANTHROPIC_AUTH_TOKEN` em vez disso — veja a diferença completa
Ainda acessando api.anthropic.com	Variáveis exportadas depois que a sessão foi iniciada ou definidas em um perfil que o shell não lê	Abra um novo terminal; confirme com echo $ANTHROPIC_BASE_URL no mesmo shell que inicia o cliente.
404 model_not_found	ID de modelo não disponibilizado pelo endpoint	Defina `ANTHROPIC_MODEL` como um ID de `GET /v1/models`
O Claude Code informa que o saldo de créditos está baixo demais	As solicitações estão chegando ao endpoint e sendo cobradas da chave, não da assinatura	É esperado — adicione créditos ou remova o token para voltar ao plano. Consulte créditos insuficientes

O que acontece com uma assinatura Pro ou Max

Enquanto uma variável de credencial estiver definida, o Claude Code cobra a chave em vez da assinatura conectada: os limites do plano deixam de se aplicar e o uso é cobrado de quem possui a chave. A assinatura em si não é afetada — remova a variável, abra um novo terminal e o Claude Code volta ao plano. Os dois nunca se combinam; o cálculo dos custos entre eles está em preços do Claude Code.

Perguntas frequentes

O que é ANTHROPIC_BASE_URL?

ANTHROPIC_BASE_URL é a variável de ambiente que informa aos SDKs da Anthropic e ao Claude Code para qual host enviar as solicitações à API, em vez do padrão https://api.anthropic.com. Defina apenas a origem, sem caminho — o cliente acrescenta /v1/messages por conta própria — e use junto com ANTHROPIC_AUTH_TOKEN, que é enviado no cabeçalho Authorization: Bearer. Qualquer endpoint compatível com a Anthropic funciona; no Kunavo, o valor é https://api.kunavo.com.

ANTHROPIC_BASE_URL deve incluir /v1?

Não. ANTHROPIC_BASE_URL deve conter apenas a origem — https://api.kunavo.com, e não https://api.kunavo.com/v1 — porque os SDKs da Anthropic e o Claude Code acrescentam o caminho /v1/messages por conta própria. Incluir /v1 gera solicitações para /v1/v1/messages, que retornam 404. O SDK da OpenAI segue a convenção oposta e exige /v1 em sua base_url. Por isso, o mesmo gateway é representado de duas maneiras diferentes, dependendo do cliente que o chama.

Qual é a diferença entre ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY?

ANTHROPIC_AUTH_TOKEN envia a credencial no cabeçalho Authorization: Bearer, enquanto ANTHROPIC_API_KEY a envia no cabeçalho x-api-key, que api.anthropic.com espera. Um gateway que autentica com tokens bearer precisa de ANTHROPIC_AUTH_TOKEN; definir ANTHROPIC_API_KEY em vez dele é a causa mais comum de um erro 401 após alterar ANTHROPIC_BASE_URL. Defina um ou outro, não ambos — quando os dois estão presentes, o comportamento depende da versão do cliente.

Como defino uma URL base personalizada no Claude Code?

Exporte ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN no perfil do shell a partir do qual o Claude Code é iniciado (~/.zshrc ou ~/.bashrc) e abra um novo terminal para que as variáveis sejam herdadas. O Claude Code as lê ao iniciar, então uma sessão que já estava em execução mantém o endpoint anterior. Execute /status dentro do Claude Code para confirmar qual endpoint a sessão atual está usando.

Definir ANTHROPIC_BASE_URL desativa minha assinatura Claude Pro ou Max?

Enquanto uma variável de credencial, como ANTHROPIC_AUTH_TOKEN, estiver definida, o Claude Code cobra a chave em vez da assinatura conectada. Assim, os limites dos planos Pro e Max deixam de se aplicar, e o uso é cobrado de quem possui a chave. A assinatura em si não é afetada nem cancelada — remova a variável e abra um novo terminal para o Claude Code voltar ao plano.