O Claude Code é a ferramenta de programação em linha de comando da Anthropic e, por padrão, conecta-se à interface oficial da Anthropic. Na prática, equipes costumam apontá-lo para gateways próprios ou de terceiros para resolver estabilidade de acesso, cobrança unificada e gestão de cotas. "Integrar uma API personalizada" significa, no fundo, mudar apenas três coisas: para onde a requisição vai (Base URL), qual identidade é usada (Key) e qual modelo é chamado (nome do modelo).

Este artigo percorre, na ordem, instalação, variáveis de ambiente, arquivo de configuração, escolha de modelo, verificação de conexão, implantação em equipe e segurança. Os comandos são voltados a macOS e Linux; Windows é indicado separadamente.

Nota: Claude e Anthropic são marcas de seus titulares. Este artigo é apenas uma explicação técnica de integração e não implica vínculo com os fornecedores. O Claude Code é atualizado com frequência, e variáveis, opções e nomes de menu podem mudar entre versões; consulte claude --help, a documentação oficial e as instruções de integração do site.

1. Três pontos a confirmar antes de integrar

O Claude Code usa o protocolo Anthropic Messages, não o Chat Completions da OpenAI. Por isso, uma API personalizada precisa atender a pelo menos dois requisitos: oferecer um endpoint /v1/messages compatível com Anthropic e usar nomes de modelo iguais aos que o gateway realmente disponibiliza. Um gateway que só tem entrada compatível com OpenAI não pode ser configurado diretamente no Claude Code, a menos que também ofereça uma rota compatível com Anthropic.

Antes de começar, prepare três itens:

  • Base URL: o endereço raiz do gateway, por exemplo https://ai.zhongshangqihang.com. Incluir /v1 ou não depende da implementação do gateway; siga as instruções de integração do site.
  • API Key: criada no console, com limite de cota e validade definidos; não use uma Key permanente e sem limite para testes.
  • Nome do modelo: copie do console ou da página de preços, não digite de memória; um caractere errado em maiúsculas ou hífen pode gerar erro de modelo inexistente.

Se ainda não tem conta, comece pela página de cadastro e crie uma Key de teste com cota baixa.

2. Instalar o Claude Code

O Claude Code é distribuído normalmente via npm, mas também oferece outras formas de instalação. O fluxo mais comum é:

  1. Confirme que o Node.js está instalado. Prefira uma versão LTS ainda mantida; a versão mínima exata está na documentação oficial.
  2. Execute npm install -g @anthropic-ai/claude-code para instalar globalmente.
  3. Execute claude --version para confirmar que o comando funciona e anote a versão.
  4. Entre em um diretório de projeto de teste, rode claude e conclua a configuração inicial, como tema e confiança no diretório.
  5. Se a equipe exige controle de versão, fixe a versão e registre-a no guia de onboarding; valide as atualizações em um projeto de teste antes de liberar.
node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /caminho/do/seu-projeto
claude

Com API personalizada, normalmente não é preciso entrar na conta Anthropic, mas pular o login depende da versão e da forma de configuração. Se o login ainda for solicitado, verifique primeiro se as variáveis de ambiente estão ativas no mesmo shell que inicia o Claude Code.

3. Variáveis de ambiente: BASE_URL e AUTH_TOKEN

O Claude Code lê duas variáveis de autenticação comuns:

  • ANTHROPIC_BASE_URL: endereço raiz das requisições.
  • ANTHROPIC_AUTH_TOKEN: enviado como Authorization: Bearer, comum em gateways.
  • ANTHROPIC_API_KEY: enviado como x-api-key, próximo do modo nativo da Anthropic.

Use apenas uma das duas variáveis de credencial. Se o gateway autentica por Bearer, use ANTHROPIC_AUTH_TOKEN; se autentica no modo nativo, use ANTHROPIC_API_KEY. Quando as duas estão definidas, versões diferentes podem dar prioridade diferente e causar o clássico "está tudo certo, mas retorna 401"; mantenha só uma.

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-sua-chave"
claude

Gravar em ~/.zshrc ou ~/.bashrc mantém a configuração entre sessões; depois de editar, rode source ~/.zshrc. No Windows PowerShell, use $env:ANTHROPIC_BASE_URL="...", que vale só para a janela atual; para persistir, use a interface de variáveis do sistema ou setx e reabra o terminal.

Não coloque os exports em um script do projeto nem faça commit. Depois que uma chave entra no histórico do Git, apagar o arquivo não apaga o registro.

4. settings.json: fixar a configuração em arquivo

Variáveis de ambiente servem para trocas temporárias; para uso contínuo, prefira o arquivo de settings do Claude Code. Há três níveis comuns:

  • Usuário: ~/.claude/settings.json, válido para todos os projetos da máquina.
  • Projeto: .claude/settings.json, que pode ir para o repositório e compartilhar configurações não sensíveis com a equipe.
  • Projeto local: .claude/settings.local.json, sem commit, para sobreposições individuais.

Exemplo:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-sua-chave"
  },
  "model": "claude-sonnet-4-5"
}

Atenção: a Key em settings.json fica em texto puro. Isso pode ser aceitável em um computador pessoal, mas não em máquinas compartilhadas, CI ou repositórios. No arquivo de projeto, coloque apenas Base URL e nome do modelo; deixe a Key em variável de ambiente ou em um gestor de segredos. A prioridade de configuração, em linhas gerais, é: configuração corporativa, argumentos de linha de comando, projeto local, projeto e usuário, nessa ordem de sobreposição; consulte a documentação da versão atual.

5. Escolha de modelo por faixa

Os modelos Claude costumam ser divididos em três faixas, adequadas a tarefas diferentes:

Faixa Uso típico Trade-off
Opus Refatorações complexas, análise entre arquivos, agentes de cadeia longa Mais capacidade, custo geralmente maior e velocidade possivelmente menor
Sonnet Codificação cotidiana, correção de bugs, revisão de código Equilíbrio entre capacidade e custo; boa escolha padrão
Haiku Completação simples, formatação, pequenas tarefas em lote Rápido e econômico, mas limitado em tarefas complexas

No Claude Code, ANTHROPIC_MODEL define o modelo principal, e ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_HAIKU_MODEL podem mapear cada faixa separadamente. Versões diferentes podem aceitar variáveis diferentes; consulte claude --help ou a documentação antes de configurar.

O nome do modelo deve coincidir com o catálogo do gateway. O gateway pode usar nomes próprios para modelos upstream, e o nome da documentação oficial pode não existir ali. Modelos disponíveis e cobrança estão na página de preços; os valores mudam conforme a versão do modelo e a política do upstream.

6. Verificar a conexão: primeiro curl, depois Claude Code

Contorne o Claude Code e use curl para verificar se o gateway responde:

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Responda apenas OK"}]
  }'

Se o gateway usa autenticação Bearer, troque x-api-key por Authorization: Bearer $ANTHROPIC_AUTH_TOKEN. Um retorno 200 com conteúdo normal indica que Base URL, Key e modelo formam pelo menos uma combinação válida.

Volte então ao Claude Code e verifique na ordem:

  1. claude --version para confirmar que o cliente executa.
  2. No diretório do projeto, rode claude doctor (se a versão oferecer o comando) para checar instalação e configuração.
  3. Inicie claude e use /status para ver o modelo atual e as informações da conta.
  4. Envie uma tarefa de baixo risco, como "explique a estrutura deste diretório sem alterar arquivos".
  5. Observe se a resposta chega normalmente e se aparecem erros 401, 404 ou modelo inexistente.

Referência rápida de sintomas:

Sintoma Verificar primeiro Ação
401 Key, nome da variável, cabeçalho Copie a Key de novo; mantenha só uma variável de autenticação
404 /v1 a mais ou a menos na Base URL Ajuste para o endereço raiz ou a entrada compatível indicada pelo gateway
model not found Nome do modelo fora do catálogo do gateway Copie do console ou da página de preços
Timeout Rede, DNS, proxy Teste outra rede; verifique se o proxy reescreve cabeçalhos
429 Limite de concorrência ou de cota Reduza a concorrência; verifique o limite da Key

7. Implantação em equipe: uma Key por pessoa, entrada unificada

Não é recomendável compartilhar uma única Key na equipe. O caminho mais seguro é:

  • Uma Key por pessoa, com nome ou finalidade no rótulo, desativada assim que alguém sai.
  • Limites de cota por projeto ou ambiente, separando produção e testes.
  • Um gateway unificado para ver uso, distribuição de modelos e chamadas anômalas.
  • Configuração corporativa distribuindo Base URL e modelos permitidos, para reduzir erros de configuração manual.
  • Um guia de onboarding com os passos de integração, comandos de verificação e erros comuns.
  • Revisão semanal ou mensal do uso, com tratamento imediato de Keys anômalas.

Se a empresa tem processos de compras e conformidade, confirme antes o fluxo de dados: trechos de código são enviados ao gateway e aos modelos upstream. Se há retenção, por quanto tempo e se os dados são usados para treinamento depende dos termos de serviço; não presuma.

8. Limites de segurança: Keys, código e dados

Algumas regras finais:

  • A Key não entra no Git, em imagens, no código de front-end, em capturas de tela nem em conversas.
  • Adicione .gitignore ao projeto cobrindo ao menos .env, .env.* e .claude/settings.local.json.
  • Em caso de suspeita de vazamento, revogue a Key antiga primeiro e depois investigue o uso; não troque apenas a senha.
  • Defina expiração para as Keys e faça rotação quando houver mudança de pessoal.
  • Em máquinas compartilhadas, use um gestor de segredos ou apiKeyHelper; não deixe texto puro no settings.json.
  • Instale o Claude Code apenas de fontes confiáveis e leia as notas de versão antes de atualizar.

Perguntas frequentes

O Claude Code exige login na conta Anthropic?

Não necessariamente. Com Base URL e variável de autenticação válidas, o cliente pode usar diretamente a API personalizada; ainda assim, a configuração inicial de tema e confiança em diretórios pode aparecer. A necessidade de login depende da versão e da configuração; se houver problema, verifique se as variáveis estão ativas no shell que inicia o cliente.

Qual é a diferença entre ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN?

A primeira costuma ser enviada no cabeçalho x-api-key; a segunda, em Authorization: Bearer. A escolha depende do modo de autenticação do gateway; configure apenas uma para evitar conflito de cabeçalhos.

A Base URL deve ser o endereço raiz ou incluir /v1?

O Claude Code geralmente recebe o endereço raiz e monta /v1/messages por conta própria; alguns gateways exigem a entrada compatível completa. O teste é simples: chame com curl o endereço raiz mais /v1/messages; se funcionar, use o endereço raiz; caso contrário, ajuste conforme a documentação do gateway.

Por que o curl funciona e o Claude Code dá erro?

As causas comuns são variáveis do shell que não chegam à interface gráfica ou ao terminal integrado da IDE, ou duas variáveis de autenticação definidas ao mesmo tempo. No mesmo terminal que inicia o Claude Code, rode echo $ANTHROPIC_BASE_URL para confirmar.

A equipe pode compartilhar uma Key?

Tecnicamente sim, mas não é recomendável. Uma Key compartilhada não permite distinguir o uso por pessoa e dificulta identificar responsáveis após um vazamento. Uma Key por pessoa, com cota e expiração, custa menos para administrar.

Próximo passo

Se ainda não tem uma conta de gateway utilizável, comece pela página de cadastro, crie uma Key de teste com cota baixa e siga as duas etapas de verificação deste artigo: curl e Claude Code. Modelos e cobrança estão na página de preços; os valores podem mudar, e vale a informação em tempo real da página.

Leituras relacionadas: