Base URL do Claude Code: como configurar ANTHROPIC_BASE_URL do jeito certo

Wokey Team · 2026-09-24

Resposta curta: a base URL do Claude Code é definida com a variável de ambiente ANTHROPIC_BASE_URL. Use só a origem do gateway, sem /v1. Para a Wokey, é https://api.wokey.ai; o Claude Code acrescenta /v1/messages sozinho. Coloque sua chave em ANTHROPIC_AUTH_TOKEN, que é enviada como Authorization: Bearer. Se você definir a base URL mas não a chave, o Claude Code continua usando seu login salvo do claude.ai.

Configuração mínima

export ANTHROPIC_BASE_URL="https://api.wokey.ai"
export ANTHROPIC_AUTH_TOKEN="your Wokey API key"
claude

Dentro do Claude Code, rode /status. As requisições estão passando pela Wokey quando a aba Status mostra:

• Anthropic base URL definido como https://api.wokey.ai
• uma linha Auth token citando ANTHROPIC_AUTH_TOKEN

Se a linha Anthropic base URL não aparecer, a variável nunca chegou à sessão.

Por que /v1 quebra tudo

O Claude Code trata ANTHROPIC_BASE_URL como prefixo e requisita $ANTHROPIC_BASE_URL/v1/messages. Defina como https://api.wokey.ai/v1 e a requisição vai para /v1/v1/messages, que a Wokey responde com:

{"message":"Route POST:/v1/v1/messages not found","error":"Not Found","statusCode":404}

Clientes compatíveis com OpenAI, como Cursor ou Cherry Studio, por convenção usam .../v1. O Claude Code segue a convenção da Anthropic, e as duas não se misturam. Também não adicione /v1/messages nem uma barra no final.

AUTH_TOKEN ou API_KEY

A Wokey aceita os dois cabeçalhos. A diferença está do lado do Claude Code:

• ANTHROPIC_AUTH_TOKEN vale imediatamente.
• ANTHROPIC_API_KEY pede uma aprovação única no modo interativo antes de passar a valer. Uma chave que você recusou antes é ignorada silenciosamente.

Não defina as duas com valores diferentes. Quando os dois cabeçalhos trazem chaves diferentes, a Wokey rejeita a requisição:

{"error":{"code":"conflicting_api_key_headers","message":"conflicting_api_key_headers","type":"invalid_request_error"}}

A mesma chave nos dois cabeçalhos não tem problema.

O que acontece com só a base URL definida

Uma base URL não é uma credencial. Com só ANTHROPIC_BASE_URL definida e sem AUTH_TOKEN ou API_KEY, o Claude Code continua enviando as requisições com seu login salvo do claude.ai. A Wokey não reconhece isso como uma chave da Wokey e retorna 401.

Depois que uma credencial do gateway é definida, seu login do claude.ai continua salvo, mas sem uso; remova a variável para voltar a ele.

Você pode ver um aviso na inicialização terminando em auth may not work as expected. Versões mais antigas mostram Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set em vez disso. Os dois significam que existem ao mesmo tempo uma credencial do gateway e um login salvo. Para usar só o gateway, rode /logout dentro do Claude Code para apagar o login salvo.

Deixe permanente no settings.json

Um export só vale para o terminal atual, e editores abertos pelo Dock ou pelo menu Iniciar não o enxergam. Para o uso diário, coloque os valores no bloco env de ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.wokey.ai",
    "ANTHROPIC_AUTH_TOKEN": "your Wokey API key"
  }
}

• Quando o shell e um arquivo de configuração definem a mesma variável, o arquivo de configuração prevalece. Se uma variável do shell que você mudou parece não ter efeito, confira aqui primeiro.
• Para um único projeto, use o .claude/settings.local.json desse projeto e garanta que ele esteja no gitignore.
• Nunca coloque a chave no .claude/settings.json de um projeto. Esse arquivo vai para o repositório no commit.

Escolhendo modelos

A Wokey usa os mesmos IDs de modelo do Claude que a Anthropic, como claude-opus-5, claude-sonnet-5 e claude-haiku-4-5. Troque durante a sessão com /model. Para fixar qual modelo cada nível Opus, Sonnet e Haiku do Claude Code usa, adicione ao env:

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

ANTHROPIC_DEFAULT_HAIKU_MODEL também define o modelo das tarefas em segundo plano, como os títulos das sessões.

Extensão do VS Code e app desktop

A extensão do VS Code não usa variáveis do shell na verificação de login. Defina-as nas próprias configurações de usuário do VS Code: rode Preferences: Open User Settings (JSON) pela paleta de comandos e adicione:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.wokey.ai" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "your Wokey API key" }
  ]
}

Os valores em ~/.claude/settings.json chegam ao processo que a extensão inicia, mas não à verificação de login da própria extensão. Se a extensão continuar pedindo para você entrar, use a configuração acima.

O app desktop do Claude não lê ANTHROPIC_BASE_URL nem settings.json. Para definir um gateway:

1. Abra Help → Troubleshooting → Enable Developer Mode.
2. Abra Developer → Configure Third-Party Inference e informe o endereço do gateway.

Veja o guia de configuração do Claude Desktop para o passo a passo completo.

Teste com curl primeiro

No mesmo terminal, teste sem o Claude Code no meio:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

O que a resposta indica:

• Começa com {"id":"msg_: a URL e a chave estão certas; o problema está na sua configuração do Claude Code.
• 401 com código invalid_api_key: a chave está ausente, digitada errado ou foi excluída.
• 404 citando /v1/v1/messages: a base URL tem um /v1 sobrando.
• O curl funciona, mas o Claude Code continua pedindo login: o Claude Code não tem credencial própria. Confira se as variáveis foram definidas no mesmo terminal em que você iniciou o claude, ou mova-as para ~/.claude/settings.json.