Claude Code: como trocar de provedor com CC Switch em 5 minutos

Este tutorial usa o CC Switch v4.0.26 (novembro de 2026). Os rótulos dos botões podem mudar em versões futuras; o modelo de configuração permanece estável.

Trocar de provedor no Claude Code geralmente significa editar ~/.claude/settings.json: a URL base, a chave de API e, às vezes, o modelo. Com um provedor, isso é administrável. Com dois ou três, vira uma pequena tarefa de manutenção — e o problema pode passar despercebido, porque uma variável ANTHROPIC_* antiga exportada no shell pode substituir o arquivo que você acabou de editar.

O CC Switch transforma a troca em um cartão no qual você clica. A predefinição integrada do AiHubMix preenche o endpoint, e você cola uma chave de API. Em geral, o Claude Code recarrega a alteração sem precisar reiniciar. Este tutorial mostra a configuração completa e, em seguida, explica o que o CC Switch grava, a armadilha das variáveis de ambiente e quando o modo direto é suficiente.

Se quiser apenas a versão resumida: instale o CC Switch, crie uma chave do AIHubMix, escolha a predefinição do AiHubMix em Claude Code, cole a chave, adicione ANTHROPIC_MODEL=claude-sonnet-5-5 ao provedor, clique em Trocar e execute claude -p "1+1, output only the answer" --model claude-sonnet-5-5. O restante desta publicação explica essas etapas em detalhes.

O que é o CC Switch

O CC Switch é um aplicativo de desktop de código aberto (MIT, Tauri + Rust + React) para gerenciar configurações de provedores no Claude Code, Codex, Gemini CLI, OpenCode e outras ferramentas de programação. Ele inclui mais de 90 predefinições de provedores e oferece suporte a provedores personalizados.

Ele faz mais do que apenas trocar chaves:

• Modo direto substitui os campos de chave no arquivo de configuração do cliente e permite que o cliente se comunique com o provedor.
• Modo de roteamento executa um gateway local em 127.0.0.1:15721, com conversão de formatos de API, failover, verificações de integridade e registros de solicitações.
• Modo de agregação reúne modelos de vários provedores em uma única lista /model.

O repositório e o manual do usuário estão em github.com/farion1231/cc-switch. Apenas ccswitch.io e a página GitHub Releases são fontes oficiais de download; qualquer site que solicite pagamento ou credenciais de conta não é oficial.

Antes de começar

Você precisa de três coisas:

• Claude Code instalado e executável no terminal. Confira com claude --version. Se não estiver instalado, use o instalador oficial: curl -fsSL https://claude.ai/install.sh | bash ou npm i -g @anthropic-ai/claude-code com Node.js 22 ou posterior.
• Uma conta e uma chave de API do AIHubMix. Crie uma no console do AIHubMix. Em geral, a chave começa com sk-.
• Um instalador do CC Switch. Baixe-o em ccswitch.io ou em GitHub Releases.

Etapa 1: instalar o CC Switch

Na primeira inicialização, o CC Switch importa a configuração existente do Claude Code como um provedor chamado default e adiciona um provedor oficial. Sua configuração original não se perde; você pode voltar a ela a qualquer momento.

Se o Claude Code ainda não estiver instalado, a página Apps do CC Switch permite instalá-lo ou atualizá-lo.

Etapa 2: criar uma chave de API do AIHubMix

Abra a página de chaves de API do AIHubMix, crie uma chave e copie-a.

O marcador AIHUBMIX_API_KEY usado na documentação não é uma chave real. Se você o colar literalmente, a solicitação falhará com 401 invalid key: AIHUBMIX_API_KEY.

Etapa 3: adicionar o AIHubMix ao Claude Code

1. Selecione Claude Code na barra lateral esquerda.
2. Clique no botão + no canto superior direito.
3. Pesquise AiHubMix ou encontre-o na categoria de plataformas de terceiros.
4. O nome e o endpoint são preenchidos automaticamente: https://aihubmix.com. Cole sua chave em API Key.
5. Clique em Adicionar.

A predefinição armazena duas variáveis de ambiente:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com"
  }
}

A predefinição não define um modelo. O guia do AIHubMix considera ANTHROPIC_MODEL uma variável essencial; portanto, adicione-a ao mesmo bloco env antes de trocar de provedor:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

Sem um modelo definido, o Claude Code envia seu próprio ID de modelo padrão, que talvez não esteja disponível no AIHubMix.

Vale a pena conhecer dois detalhes.

Não acrescente /v1 à URL base. O Claude Code usa o protocolo Anthropic Messages e monta o caminho da solicitação por conta própria. https://aihubmix.com está correto; https://aihubmix.com/v1 é a URL base compatível com OpenAI para outros clientes, e o Claude Code acrescentaria a ela seu próprio /v1/messages.

A predefinição usa ANTHROPIC_API_KEY, enquanto o guia do próprio AIHubMix para Claude Code usa ANTHROPIC_AUTH_TOKEN. O AIHubMix aceita ambas: ANTHROPIC_AUTH_TOKEN envia um cabeçalho Bearer, enquanto ANTHROPIC_API_KEY envia x-api-key. Escolha uma. Não preencha ambas com valores diferentes. Os detalhes de configuração do AIHubMix, os IDs de modelo e a referência de erros estão na documentação do AIHubMix para Claude Code.

Se a predefinição não estiver disponível — por exemplo, em uma versão mais antiga ou depois que você excluir o cartão — escolha Custom Configuration e cole o JSON acima. O gerenciador de endpoints do cartão do provedor pode testar a latência; a predefinição também inclui https://api.aihubmix.com como endpoint alternativo, caso aihubmix.com não seja resolvido.

Etapa 4: trocar de provedor e verificar

Na aba Direct, clique em Trocar no cartão do AiHubMix. Quando a configuração for gravada, o botão mudará para Em uso.

O Claude Code recarrega a configuração automaticamente; normalmente, não é preciso reiniciar. Se a sessão atual continuar usando o provedor antigo, encerre-a e inicie-a novamente.

Verifique o fluxo completo:

claude -p "1+1, output only the answer" --model claude-sonnet-5-5

Uma resposta 2 significa que a solicitação chegou ao AIHubMix. Em uma sessão interativa, a linha Anthropic base URL em /status deve mostrar https://aihubmix.com.

Para trocas rápidas, use a bandeja do sistema: clique com o botão direito no ícone do CC Switch, abra o submenu Claude Code e clique em um provedor. O título do submenu mostra o provedor ativo e um resumo da cota.

Para voltar ao provedor oficial, troque para Claude Official, reinicie o Claude Code e conclua o processo de login.

O que a troca realmente altera

No modo direto, o CC Switch substitui apenas os campos de conexão e compatibilidade em ~/.claude/settings.json: ANTHROPIC_*, AWS_*, seletores de protocolo como CLAUDE_CODE_USE_BEDROCK, model, apiKeyHelper e algumas opções de compatibilidade específicas do provedor, como CLAUDE_CODE_DISABLE_ARTIFACT e a janela de contexto.

permissions, hooks, enabledPlugins, statusLine, a configuração MCP, os comentários e quaisquer outros elementos que você adicionou permanecem intactos. A lista completa está na referência do arquivo de configuração.

Antes da primeira alteração no arquivo de configuração de uma ferramenta, o CC Switch faz uma cópia de segurança do original em ~/.cc-switch/backups/live-first-write/. Se o JSON estiver malformado, ele se recusa a gravar, informa a linha e a coluna e mantém o arquivo inalterado.

A armadilha: variáveis ANTHROPIC_* antigas

Este é o problema que dá a impressão de que o CC Switch não funcionou.

Se você já seguiu um guia de configuração manual e adicionou export ANTHROPIC_BASE_URL=... ou export ANTHROPIC_AUTH_TOKEN=... a ~/.zshrc ou ~/.bash_profile, essas variáveis podem substituir os valores gravados pelo CC Switch. Você troca o cartão para AIHubMix, mas as solicitações continuam indo para o endpoint antigo.

O CC Switch detecta o conflito. Um aviso amarelo no alto da janela informa que as variáveis de ambiente podem substituir sua configuração; os detalhes mostram o nome, o valor e a origem da variável. Excluir selecionadas as remove e, antes disso, grava uma cópia de segurança em ~/.cc-switch/backups/env-backup-<timestamp>.json.

Para verificar manualmente:

grep -n "ANTHROPIC" ~/.zshrc ~/.bash_profile 2>/dev/null

Comente as exportações antigas e execute source ~/.zshrc ou abra um novo terminal. A documentação do próprio AIHubMix recomenda remover as variáveis globais ANTHROPIC_* quando o CC Switch gerencia a configuração. O processo completo para resolver conflitos está na referência de variáveis de ambiente.

Aliases de modelo e troca

Com ANTHROPIC_MODEL definido, o modelo padrão do Claude Code é o Sonnet 5.5. Os aliases de /model (opus, sonnet, haiku, fable) ainda precisam ser mapeados para serem associados aos IDs de modelo do AIHubMix. Adicione estas chaves dentro de env:

A configuração completa do provedor fica assim:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1"
  }
}

Ordem de prioridade para a seleção do modelo, da mais alta para a mais baixa: /model <name> → claude --model <name> → ANTHROPIC_MODEL → o campo model em settings.json. Copie os IDs de modelo da lista de modelos do AIHubMix; eles diferenciam maiúsculas de minúsculas.

Quando usar o modo de roteamento ou de agregação

O modo direto é a opção padrão recomendada para o AIHubMix. O endpoint já usa o protocolo Anthropic Messages, então não é necessária nenhuma conversão de protocolo.

Use o modo de roteamento se quiser uma fila de failover ou precisar conectar ao Claude Code um provedor que use o formato OpenAI. O roteamento aponta o Claude Code para http://127.0.0.1:15721, substitui a chave na configuração por PROXY_MANAGED e injeta a chave real a partir do CC Switch. O aplicativo precisa continuar em execução; ao fechar o CC Switch, a configuração direta é restaurada. Assinaturas oficiais do Claude não passam pelo roteamento; para elas, use o modo direto.

Use agregação quando quiser modelos de vários provedores em uma única lista de /model. O provedor padrão processa as solicitações sem prefixo; os modelos dos outros provedores aparecem com o prefixo ccs-. A agregação não faz failover. Ela está disponível apenas para Claude Code e Codex, e as assinaturas oficiais do Claude não são compatíveis com a agregação. A lista de modelos ccs- exige o Claude Code 2.1.243 ou posterior. O Claude Code aplica as alterações na lista de modelos imediatamente; o Codex precisa ser totalmente reiniciado.

O que mais o CC Switch gerencia

• Uso: o painel combina os registros de solicitações roteadas com os registros de sessões locais. A varredura de sessões funciona sem roteamento e calcula os preços com base no modelo registrado; as solicitações roteadas são registradas separadamente.
• MCP: um painel unificado para servidores MCP, sincronizado com os aplicativos que você selecionar.
• Skills: encontre, instale e remova skills em um só lugar.
• Sessões: pesquise, visualize, exporte e retome sessões locais.
• Projetos: salve o provedor, os servidores MCP, as skills e os arquivos de memória de um projeto como um instantâneo e alterne todo esse conjunto por projeto.

Os dados ficam em ~/.cc-switch/, com um banco de dados SQLite como elemento central. Os backups automáticos mantêm os 10 mais recentes por padrão, e há sincronização via WebDAV ou compatível com S3. O banco de dados e os backups exportados incluem configurações de provedores, inclusive chaves; trate-os como segredos.

Solução de problemas

As mensagens de erro abaixo foram citadas da documentação do Claude Code da AIHubMix.

Para sintomas que não sejam erros:

• Tela de login ou Not logged in: verifique /status; ative Skip Claude Code first-run confirmation em Settings → App config → Claude Code; reinicie; confirme que a chave foi preenchida.
• A troca não surte efeito: há uma variável de shell desatualizada ou uma sessão em cache; abra um novo terminal ou reinicie o Claude Code.
• O teste de conexão do cartão é aprovado, mas as solicitações falham: o teste verifica a conectividade, não a chave nem o modelo; execute o comando de ponta a ponta claude -p.
• Você quer voltar ao provedor oficial: mude para Claude Official, reinicie o Claude Code e faça login novamente.

Se o comando claude não for encontrado no macOS, o instalador oficial geralmente o coloca em ~/.local/bin/claude. Adicione export PATH="$HOME/.local/bin:$PATH" ao perfil do shell e abra um novo terminal.

Lista de verificação

• [ ] Instale o CC Switch pelo ccswitch.io ou em GitHub Releases.
• [ ] Crie uma chave de API no console da AIHubMix.
• [ ] No Claude Code → + → AiHubMix → cole a chave → Adicionar.
• [ ] Adicione ANTHROPIC_MODEL=claude-sonnet-5-5 ao JSON do provedor.
• [ ] Clique em Switch e confirme que o cartão mostra Em uso.
• [ ] Remova as exportações ANTHROPIC_* desatualizadas do perfil do shell.
• [ ] Execute claude -p "1+1, output only the answer" --model claude-sonnet-5-5 e verifique se a resposta é 2.

Se o último comando retornar 2, a troca de provedor foi concluída. O que falta é adicionar os aliases de modelo que você quiser e decidir se precisa de roteamento ou agregação; para a maioria dos usuários da AIHubMix, o modo direto é suficiente.

Perguntas frequentes

O CC Switch é gratuito?
Sim. É um software de código aberto com licença MIT. Você paga apenas ao provedor cuja API usa.

A troca exclui meus hooks, servidores MCP ou plugins?
Não. A troca direta substitui o endpoint, a chave, o modelo e algumas opções específicas do provedor. Hooks, permissões, servidores MCP, plugins e configurações da linha de status permanecem no arquivo.

O CC Switch envia minha chave de API?
As configurações dos provedores são armazenadas localmente em ~/.cc-switch/cc-switch.db. Se você ativar a sincronização via WebDAV ou S3, elas serão sincronizadas com o armazenamento que você controla. Bancos de dados e backups contêm chaves; trate-os como segredos.

Preciso manter o CC Switch em execução?
Não no modo direto. O roteamento e a agregação exigem que o aplicativo esteja em execução; ao sair do CC Switch, o cliente volta ao modo direto.

Posso usar Claude Official e AIHubMix ao mesmo tempo?
No modo direto, só pode haver um provedor ativo por vez. A agregação pode reunir os modelos de vários provedores em uma lista, mas a assinatura oficial do Claude não é compatível com esse modo; volte ao modo direto para usá-la.

Funciona no Windows?
Sim. O CC Switch é compatível com Windows 10 e versões posteriores, com instalador .msi ou versão portátil. No Linux, é necessário glibc 2.35+ e WebKitGTK 4.1.

Por que o cartão do provedor indica uma conexão saudável, mas o Claude Code ainda falha?
O teste de conectividade do cartão verifica se o endpoint está acessível. Ele não valida a chave de API nem o modelo. Use o comando de ponta a ponta claude -p para testar o fluxo completo.

Fontes

• Repositório do CC Switch
• Manual do usuário do CC Switch: Adicionar provedor
• Manual do usuário do CC Switch: Trocar de provedor
• Manual do usuário do CC Switch: Arquivos de configuração
• Documentação da AIHubMix: Claude Code