Guia Completo do CC-Switch: Aprenda a gerenciar múltiplas configurações de API do Claude Code em 5 minutos

Codar com o Claude Code é sensacional, mas a API oficial é muito cara? Quer mudar para um proxy de API de terceiros, mas não sabe como alterar o arquivo de configuração? O CC-Switch foi criado justamente para resolver essa dor. Este artigo vai te mostrar como dominar a instalação e o uso do CC-Switch em 5 minutos, gerenciando facilmente a API de quatro assistentes de programação por IA: Claude Code, Codex, OpenCode e Gemini CLI.

Valor central: Ao ler este artigo, você aprenderá a usar o CC-Switch para gerenciar visualmente vários provedores de API, alternar configurações com um clique e dar adeus à chatice de editar arquivos JSON manualmente.

O que é o CC-Switch? Por que você precisa dele?

O CC-Switch é um aplicativo de desktop multiplataforma de código aberto, projetado especificamente para unificar o gerenciamento das configurações de assistentes de programação por IA. Ele foi criado pelo desenvolvedor farion1231 e está disponível no GitHub.

Posicionamento central do CC-Switch

De forma simples, o CC-Switch é o "Centro de Gerenciamento de Configurações" para suas ferramentas de IA:

As 4 grandes ferramentas de IA suportadas pelo CC-Switch

🚀 Início Rápido: O CC-Switch suporta o acesso a proxies de terceiros como o APIYI (apiyi.com). Ao configurar o Provedor, você pode usar ferramentas como o Claude Code com um custo muito menor, aproveitando a conveniência da troca rápida.

Detalhamento das Funcionalidades Principais do CC-Switch

O CC-Switch não é apenas um alternador de configurações; é uma plataforma completa de gerenciamento de ferramentas de IA:

Funcionalidade 1: Gerenciamento de Providers (Recurso Principal)

Esta é a funcionalidade mais utilizada do CC-Switch, oferecendo suporte para:

Exemplo de Configuração de Provider:

{
  "name": "APIYI",
  "baseUrl": "https://api.apiyi.com",
  "apiKey": "sk-sua-chave-apiyi",
  "models": {
    "claude-sonnet-4-20250514": "claude-sonnet-4-20250514",
    "claude-opus-4-20250514": "claude-opus-4-20250514"
  }
}

Funcionalidade 2: Gerenciamento de Servidores MCP

O MCP (Model Context Protocol) é o protocolo de extensão do Claude Code. O CC-Switch oferece uma interface de gerenciamento MCP unificada:

• Suporte para três tipos de transporte: stdio, http e sse
• Configuração unificada entre aplicações (Claude/Codex/Gemini)
• Adição, edição e exclusão visual de servidores MCP

Funcionalidade 3: Gerenciamento de Habilidades (Skills)

O CC-Switch pode descobrir e instalar automaticamente as Claude Skills:

• Varredura automática de Skills em repositórios do GitHub
• Instalação com um clique no diretório ~/.claude/skills/
• Suporte para varredura recursiva de diretórios aninhados

Funcionalidade 4: Gerenciamento de Comandos do Sistema (System Prompts)

Crie presets de comandos (prompts) do sistema para diferentes cenários:

• Quantidade ilimitada de presets de comandos
• Suporte para arquivos CLAUDE.md, AGENTS.md e GEMINI.md
• Troca rápida entre diferentes modos de trabalho

Funcionalidade 5: Proxy de API Local (v3.9.0+)

O CC-Switch possui um servidor proxy local integrado que oferece recursos avançados:

💡 Dica Técnica: A funcionalidade de proxy local funciona ainda melhor quando utilizada em conjunto com o APIYI (apiyi.com). O APIYI fornece interfaces estáveis compatíveis com OpenAI, e a função de failover do CC-Switch pode realizar a troca automática durante oscilações de rede, garantindo que sua experiência de programação não seja interrompida.

Guia de Instalação do CC-Switch

O CC-Switch é compatível com Windows, macOS e Linux, oferecendo diversas formas de instalação.

Instalação no Windows

Opção 1: Instalador MSI (Recomendado)

Baixe o arquivo .msi no GitHub Releases e dê um duplo clique para instalar.

Opção 2: Versão Portátil

Baixe a versão portátil em .zip, extraia o conteúdo e execute diretamente, sem necessidade de instalação.

Instalação no macOS

Opção 1: Homebrew (Recomendado)

brew install --cask cc-switch

Opção 2: Instalação Manual

Baixe o arquivo .dmg ou .zip e arraste-o para a pasta Applications (Aplicativos).

Nota: Na primeira inicialização, você pode encontrar um aviso do Gatekeeper. Se isso acontecer, será necessário permitir a execução em 「Ajustes do Sistema → Segurança e Privacidade」.

Instalação no Linux

O CC-Switch oferece vários formatos de pacotes para Linux:

Verificando a Instalação

Após concluir a instalação, abra o CC-Switch. Você deverá ver o status das ferramentas de CLI detectadas na interface principal.

Guia de Início Rápido do CC-Switch

Passo 1: Adicionar o Provider APIYI

1. Clique no botão 「Add Provider」 na interface principal.
2. Selecione 「Custom」 para uma configuração personalizada.
3. Preencha as seguintes informações:

名称: APIYI
Base URL: https://api.apiyi.com
API Key: sk-your-apiyi-key  # 从 apiyi.com 获取

4. Configure o mapeamento de modelos (opcional):

{
  "claude-sonnet-4-20250514": "claude-sonnet-4-20250514",
  "claude-opus-4-20250514": "claude-opus-4-20250514",
  "gpt-4o": "gpt-4o"
}

5. Clique em 「Save」 para salvar a configuração.

Obtendo a API Key: Acesse o site do APIYI em apiyi.com e registre uma conta para obter sua chave de API. A plataforma oferece créditos de teste gratuitos e suporte para os principais Modelos de Linguagem Grande, como Claude, GPT e Gemini.

Passo 2: Alternar o Provider

Com a configuração salva, localize a lista de Providers na interface principal:

1. Encontre o provider 「APIYI」 que você acabou de adicionar.
2. Clique em 「Switch」 ou clique diretamente sobre o provider.
3. O CC-Switch modificará automaticamente os arquivos de configuração das ferramentas correspondentes.
4. Reinicie o Claude Code ou outras ferramentas de CLI para que as novas configurações entrem em vigor.

Passo 3: Testar a Conexão

Use a função de teste de velocidade do CC-Switch para validar sua configuração:

1. Clique no botão 「Test」 ao lado do provider.
2. Aguarde a conclusão do teste de latência.
3. Verifique o tempo de resposta e o indicador de status.

Se o teste passar, abra o terminal e execute o Claude Code:

claude

Se conseguir conversar normalmente, a configuração foi concluída com sucesso!

Exemplo de Configuração Minimalista

{
  "id": "apiyi-provider",
  "name": "APIYI (推荐)",
  "baseUrl": "https://api.apiyi.com",
  "apiKey": "sk-your-apiyi-key",
  "enabled": true,
  "models": {
    "claude-sonnet-4-20250514": {
      "id": "claude-sonnet-4-20250514",
      "name": "Claude Sonnet 4",
      "maxTokens": 64000
    },
    "claude-opus-4-20250514": {
      "id": "claude-opus-4-20250514",
      "name": "Claude Opus 4",
      "maxTokens": 32000
    },
    "gpt-4o": {
      "id": "gpt-4o",
      "name": "GPT-4o",
      "maxTokens": 16384
    },
    "gpt-4o-mini": {
      "id": "gpt-4o-mini",
      "name": "GPT-4o Mini",
      "maxTokens": 16384
    }
  },
  "healthCheck": {
    "enabled": true,
    "interval": 60
  }
}

Recursos Avançados do CC-Switch

Estratégias de Gerenciamento de Múltiplos Provedores

O CC-Switch suporta a configuração de vários Provedores (Providers), permitindo estratégias de uso flexíveis:

┌─────────────────────────────────────────────────┐
│          Lista de Provedores CC-Switch          │
├─────────────────────────────────────────────────┤
│  ⭐ APIYI (Principal)   Latência: 120ms  ✓ Ativo   │
│  📦 OpenRouter (Reserva) Latência: 280ms  ✓ Ativo   │
│  🏢 Claude Oficial (Contingência) Lat: 350ms ✓ Ativo│
└─────────────────────────────────────────────────┘

Configuração Recomendada:

• Principal: APIYI – Preço acessível e acesso rápido.
• Reserva: OpenRouter – Grande variedade de modelos e estabilidade internacional.
• Contingência: Login Oficial – Para garantir que o serviço esteja sempre disponível.

Configuração de Sincronização na Nuvem

O CC-Switch permite sincronizar suas configurações com armazenamento em nuvem:

1. Vá em Settings → Storage (Configurações → Armazenamento)
2. Selecione a pasta de sincronização na nuvem (Dropbox, OneDrive, iCloud Drive)
3. O CC-Switch sincronizará automaticamente as configurações dos Provedores.

Dessa forma, você pode compartilhar as mesmas configurações de API entre vários dispositivos.

Configurações Avançadas de Proxy Local

Ao habilitar o proxy local, o CC-Switch irá:

1. Iniciar um servidor proxy localmente.
2. Modificar automaticamente a configuração da CLI para apontar para o proxy local.
3. O servidor proxy encaminha as requisições para o Provedor real.

Vantagens:

• Todas as requisições passam por um ponto único, facilitando o monitoramento.
• Failover automático: se um Provedor cair, ele alterna automaticamente.
• Registro de logs de requisição, facilitando o diagnóstico de problemas.

# Fluxo de requisição no modo proxy
Claude Code → localhost:8080 → Proxy do CC-Switch → APIYI → API do Claude

Recurso Claude Rectifier

O novo recurso Claude Rectifier, adicionado na v3.10.0, serve para corrigir problemas de compatibilidade com APIs de terceiros:

• Corrige automaticamente o formato da "assinatura de pensamento" (thinking signature).
• Melhora a compatibilidade com APIs não oficiais.
• Reduz erros do tipo "falha de formato".

Perguntas Frequentes (FAQ) do CC-Switch

# Opção 1: Feche o terminal atual e abra-o novamente
# Opção 2: Digite /exit no Claude Code para sair e depois inicie novamente
claude  # Iniciar novamente

# Remova a configuração personalizada para restaurar o oficial
rm ~/.claude/settings.json
claude  # Faça o login novamente na conta oficial

Comparativo: CC-Switch vs. Configuração Manual

🎯 Dica de escolha: Se você precisa alternar com frequência entre diferentes API Providers ou utiliza várias ferramentas de programação com IA ao mesmo tempo, o CC-Switch vai aumentar muito a sua produtividade. Usando junto com a APIYI (apiyi.com), você garante a melhor experiência com baixo custo e praticidade.

Comparativo de Ferramentas Relacionadas ao CC-Switch

Além do CC-Switch, existem outras ferramentas similares no ecossistema:

Combo recomendado: CC-Switch (gestão de configurações) + APIYI (ponte de API) = O melhor custo-benefício do mercado.

Referências

Resumo

O CC-Switch é uma ferramenta indispensável para gerenciar configurações de assistentes de programação de IA, resolvendo os seguintes problemas:

1. Configuração complexa: Interface visual em vez de edição manual de JSON.
2. Troca difícil: Alterne entre vários provedores com apenas um clique.
3. Ferramentas dispersas: Gestão unificada para Claude Code, Codex, OpenCode e Gemini CLI.
4. Impossibilidade de medir velocidade: Teste de latência integrado para escolher o provedor mais rápido.
5. Perda de configuração: Backup automático e sincronização na nuvem, garantindo que suas configurações nunca sejam perdidas.

Para desenvolvedores que utilizam ferramentas de programação com IA frequentemente, a combinação CC-Switch + APIYI é a solução recomendada:

• CC-Switch: Oferece um gerenciamento de configuração prático e ágil.
• APIYI (apiyi.com): Oferece serviços de API estáveis e com preços acessíveis.

Acesse APIYI (apiyi.com) para registrar sua conta, obtenha sua Chave de API (API Key) e, em seguida, adicione o provedor no CC-Switch para começar a aproveitar uma experiência de programação com IA totalmente fluida.

📝 Autor: Equipe Técnica APIYI | APIYI apiyi.com – Tornando as chamadas de API de IA mais simples