Source: https://aiprimetech.io/pt/blog/cc-switch-claude-code-account-provider-manager/ Jul 22, 2026 · 6 min · Ferramentas # CC Switch para Claude Code: gerenciamento de contas, provedores e configurações A Por [AI Prime Tech](https://aiprimetech.io/pt/) · Com auxílio de IA Às 9:05 da manhã, você direciona o Claude Code para um gateway da empresa. Às 11:30, precisa de uma conta pessoal da Anthropic. Depois do almoço, um repositório de cliente exige seus próprios servidores MCP e aliases de modelos. Ao fim do dia, ~/.claude/settings.json foi editado três vezes, um shell ainda contém um token antigo e ninguém tem certeza de qual endpoint a próxima solicitação acessará. O CC Switch resolve esse problema operacional com perfis nomeados gerenciados por um aplicativo de desktop. Em vez de mover manualmente credenciais, URLs de provedores, definições de MCP e arquivos de configuração específicos de cada agente, você seleciona o perfil que deve ficar ativo. O detalhe importante de engenharia é que isso é gerenciamento de configuração, não virtualização de contas: o Claude Code continua lendo seus arquivos locais e configurações de ambiente habituais, enquanto o CC Switch coordena o que é gravado neles. Essa conveniência é significativa, mas a fronteira de confiança também é. Um utilitário capaz de alternar entre contas de desenvolvedor precisa poder ler ou gravar credenciais de desenvolvedor. Antes de adotá-lo, você deve entender exatamente quais arquivos ele altera, onde fica seu próprio banco de dados e como esses arquivos são protegidos. ## O que o gerenciamento do Claude Code pelo CC Switch realmente faz O CC Switch é um gerenciador de configurações de código aberto para desktop voltado a agentes de programação. As integrações compatíveis foram ampliadas ao longo do tempo, portanto consulte o repositório atual e as notas de versão antes de padronizar uma lista fixa. O Claude Code é uma das principais integrações; as versões atuais também contemplam outros agentes de programação de linha de comando, como Codex e Gemini CLI. Para o Claude Code, um perfil de provedor geralmente combina: - Um endpoint de API compatível com Anthropic - Uma chave de API ou um token de autenticação - Mapeamentos de modelos ou valores de ambiente relacionados a modelos - Variáveis de ambiente adicionais - Definições de servidores MCP - Configurações do Claude Code que devem acompanhar o perfil Isso é útil quando “conta” não significa simplesmente um login da Anthropic. Em implantações reais, os desenvolvedores podem alternar entre: - Acesso direto à API da Anthropic - Um gateway de API autenticado de uma organização - Um provedor terceirizado compatível com Anthropic - Contas de faturamento separadas para uso pessoal, homologação e produção - Um proxy local ou remoto que expõe uma semântica de requisições compatível O CC Switch centraliza essas opções e ativa a configuração selecionada. Ele não faz com que todos os endpoints compatíveis se comportem de forma idêntica. As diferenças em nomes de modelos, cabeçalhos de autenticação, limites de requisições, cache de prompts e campos de API não compatíveis continuam sendo responsabilidade do provedor. | Abordagem | Esforço para alternar | Credenciais expostas a | Gerenciamento de MCP | Mais indicado para | Exportações no shell | Baixo no início, sujeito a erros depois | Shell, histórico, processos filhos | Manual | Uma conta temporária | Arquivos de configuração editados manualmente | Moderado | Editor, backups, arquivos locais | Manual | Configuração estável com um único provedor | Scripts de encapsulamento | Baixo após a configuração | Script ou gerenciador de segredos | Depende do script | Equipes dispostas a manter ferramentas | Perfis do CC Switch | Baixo pela interface de desktop | CC Switch e arquivos de configuração do agente | Interface centralizada | Várias contas, provedores ou agentes | Gerenciador de segredos externo com scripts de encapsulamento | Maior custo de configuração | Gerenciador de segredos e processo em execução | Personalizado | Controles empresariais rigorosos A tabela evidencia a contrapartida: o CC Switch reduz os erros do operador, mas se torna mais uma aplicação local com privilégios. ## Instalação e suporte a plataformas O CC Switch é distribuído pela página de Releases do projeto no GitHub. O repositório atualmente descreve suporte a desktop para macOS, Windows e Linux, com artefatos de lançamento que variam por plataforma e versão. Verifique os arquivos anexados à versão que você pretende implantar; a existência de código-fonte não garante que todas as versões de sistema operacional, arquiteturas de CPU ou formatos de pacote tenham compilações disponíveis em cada lançamento. No macOS, o projeto oferece um fluxo de instalação por cask do Homebrew: ``` brew tap farion1231/cc-switch brew install --cask cc-switch ``` Antes de usar um binário baixado em um ambiente gerenciado, verifique o que o Homebrew instalou: ``` brew info --cask cc-switch brew list --cask cc-switch codesign -dv --verbose=4 "/Applications/CC Switch.app" 2>&1 ``` Usuários de Windows e Linux devem obter o instalador ou pacote nos arquivos publicados da versão. Os nomes dos pacotes e os canais podem mudar, por isso evito incluir um comando potencialmente desatualizado de winget, Scoop, .deb ou AppImage em scripts de preparação de estações de trabalho sem fixar e testar a versão exata. Para uma implantação controlada: - Fixe uma versão do CC Switch. - Registre a soma de verificação esperada da versão. - Teste-a com uma configuração descartável do Claude Code. - Faça um inventário de todos os arquivos alterados durante a ativação do perfil. - Defina um processo de atualização em vez de acompanhar silenciosamente a versão mais recente. Uma captura simples do estado anterior à instalação ajuda: ``` mkdir -p /tmp/claude-config-before cp -R ~/.claude /tmp/claude-config-before/ 2>/dev/null || true # Install CC Switch, create a test profile, and activate it. diff -ru /tmp/claude-config-before/.claude ~/.claude || true ``` Isso identifica comportamentos que a documentação pode deixar passar, incluindo reformatações, campos removidos ou entradas MCP mescladas em um escopo inesperado. ## Criação e alternância de perfis de provedor Um perfil deve representar um contexto coerente de segurança e faturamento. Uso nomes que deixam claro o impacto, como: - anthropic-personal - company-gateway-dev - customer-a-restricted - local-proxy-test Evite rótulos como default-2. Quando ocorrer um incidente em produção, o nome do perfil ativo deve responder à pergunta “para onde esta requisição será enviada?” sem que seja preciso abrir um editor. Um perfil do Claude Code baseado em um gateway compatível com Anthropic pode produzir configurações conceitualmente semelhantes a: ``` { "env": { "ANTHROPIC_BASE_URL": "https://ai-gateway.example.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "${TOKEN_MANAGED_BY_PROFILE}", "ANTHROPIC_MODEL": "company-claude-default" }, "permissions": { "defaultMode": "default" } } ``` As variáveis exatas necessárias dependem do provedor e da versão do Claude Code. Alguns serviços esperam ANTHROPIC_API_KEY; algumas integrações com gateways usam ANTHROPIC_AUTH_TOKEN. Não preencha ambas apenas para tornar “mais provável” que a autenticação funcione. Determine qual credencial o Claude Code priorizará, pois um valor desatualizado com maior precedência pode encaminhar requisições pela conta errada. Após alternar, inicie um novo processo do Claude Code: ``` claude ``` É fácil entender incorretamente o que de fato acontece quando você alterna enquanto o Claude Code já está em execução. O utilitário pode atualizar arquivos em disco, mas não consegue substituir de forma confiável valores de ambiente já herdados por um processo em execução. Por isso, as sessões existentes podem continuar usando o provedor original até serem reiniciadas. Valide a configuração efetiva sem imprimir segredos: ``` python3 - <<'PY' import json from pathlib import Path path = Path.home() / ".claude" / "settings.json" data = json.loads(path.read_text()) env = data.get("env", {}) for key, value in sorted(env.items()): if "KEY" in key or "TOKEN" in key or "SECRET" in key: value = "" print(f"{key}={value}") PY ``` Uma armadilha comum é testar apenas se o Claude responde. Um proxy compatível pode retornar uma resposta válida enquanto mapeia silenciosamente o modelo solicitado para outro modelo. Verifique os logs de requisições do provedor ou a trilha de auditoria do gateway quando a identidade do modelo for importante. ## Configurações de MCP entre agentes É na configuração de MCP que a centralização se torna mais útil do que um seletor de tokens. Um desenvolvedor pode ter servidores de sistema de arquivos, rastreamento de issues, banco de dados e navegador configurados em vários agentes, cada um com seu próprio esquema ou local de armazenamento. Uma definição típica de servidor MCP contém um comando e argumentos: ``` { "mcpServers": { "project-files": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/alex/work/customer-a" ] } } } ``` Trate isso como uma configuração executável. Ativar o perfil pode permitir que um agente inicie npx, execute um pacote e exponha o diretório especificado à camada de ferramentas acessível ao modelo. Na prática, separo os perfis MCP de acordo com a sensibilidade do repositório: - Um perfil geral expõe documentação e ferramentas de baixo risco. - Um perfil de cliente expõe apenas o diretório de trabalho desse cliente. - Servidores de banco de dados e de controle de produção não são habilitados globalmente. - Os tokens usados pelos servidores MCP têm escopos definidos independentemente do token do provedor de modelos. Compare também o resultado gerado pelo CC Switch com o comando MCP nativo do agente, quando disponível. Para o Claude Code, inspecione os servidores ativos após alternar: ``` claude mcp list ``` Não presuma que um objeto MCP JSON possa ser copiado sem alterações para todos os agentes de programação. O CC Switch pode uniformizar o gerenciamento em sua interface, mas cada agente integrado ainda tem seu próprio esquema, regras de escopo e comportamento de ciclo de vida. ## Onde as credenciais são armazenadas Há duas camadas de armazenamento a auditar: - Os dados da aplicação CC Switch, usados para manter os perfis. - A configuração nativa do agente de programação, gravada ou atualizada quando um perfil é ativado. O CC Switch usa armazenamento local da aplicação em vez de um serviço de contas hospedado. O caminho exato depende da plataforma e mudou conforme a aplicação evoluiu, portanto determine-o a partir da compilação instalada em vez de confiar em um caminho copiado de uma issue antiga. Os diretórios raiz comuns de dados de aplicações nos sistemas operacionais são: ``` macOS: ~/Library/Application Support/ Windows: %APPDATA% Linux: ~/.local/share/ or an XDG data directory ``` Pesquise sem despejar o conteúdo das credenciais: ``` find "$HOME/Library/Application Support" \ -maxdepth 3 -iname '*cc*switch*' -print 2>/dev/null find "${XDG_DATA_HOME:-$HOME/.local/share}" \ -maxdepth 3 -iname '*cc*switch*' -print 2>/dev/null ``` Para o Claude Code, revise ~/.claude/, especialmente settings.json, além da configuração do Claude no nível do projeto, quando aplicável. Outros agentes costumam usar diretórios separados, como ~/.codex/ ou ~/.gemini/, mas os nomes de arquivos e os formatos de credenciais são específicos de cada versão do agente. Não presuma que “armazenado localmente” significa “criptografado”. A menos que a versão instalada do CC Switch use explicitamente um cofre de credenciais do sistema operacional para o segredo em questão, considere que o banco de dados da aplicação e os arquivos de agente gerados podem ser lidos em texto simples pela sua conta de usuário. Confirme isso inspecionando os arquivos e revisando o código do repositório, tomando cuidado para não colar segredos em terminais, chamados ou sessões de chat. ## Implicações de segurança do acesso a tokens no desktop O CC Switch opera necessariamente com as permissões do seu usuário no desktop. Se essa conta puder ler um token, um malware ou outro processo executado como o mesmo usuário também poderá lê-lo. O CC Switch não elimina os requisitos de segurança dos dispositivos. Os principais riscos são: - Concentração de credenciais: Tokens de vários provedores podem coexistir em um único armazenamento local de perfis. - Sobrescrita de configuração: A ativação de um perfil pode substituir ou mesclar arquivos usados por um agente. - Vazamento por backups: Dados da aplicação e arquivos de configuração ocultos podem acabar em backups não criptografados. - Herança de processos: Terminais antigos e agentes em execução podem manter credenciais anteriores. - Execução de MCP: Um perfil pode ativar comandos com acesso ao sistema de arquivos ou à rede. - Exposição na cadeia de suprimentos: A instalação de atualizações permite que novo código de desktop acesse os tokens armazenados. - Divulgação em telas e logs: Diagnósticos da interface ou relatórios de erros podem revelar dados de endpoints e credenciais. Aplique controles de privilégio mínimo ao utilitário: ``` chmod 700 ~/.claude chmod 600 ~/.claude/settings.json ``` Prefira tokens de gateway de curta duração ou revogáveis quando o provedor oferecer suporte a eles. Nunca coloque uma credencial administrativa de produção em um perfil de conveniência. Faça a rotação dos tokens após retirar uma máquina de serviço; excluir um perfil não comprova que a credencial nunca foi copiada para outro lugar. Para uma implantação empresarial, eu exigiria: - Versões fixadas e revisadas - Criptografia de disco completo - Manuseio restrito de backups - Limites de gastos e logs de auditoria no provedor - Tokens separados por desenvolvedor e ambiente - Um procedimento de revogação documentado - Revisão periódica dos comandos MCP e dos caminhos expostos O CC Switch é uma opção prática para fluxos de trabalho locais com vários provedores. Ele não é automaticamente adequado para ambientes em que as políticas exigem segredos protegidos por hardware, credenciais efêmeras ou configuração imposta centralmente. Nesses casos, um gateway corporativo e um inicializador integrado a um gerenciador de segredos podem ser uma arquitetura mais defensável. ## Recomendações Práticas - Use o CC Switch quando edições manuais repetidas estiverem causando erros de conta, endpoint ou MCP. - Confirme os artefatos de cada plataforma na versão atual do projeto no GitHub antes da implantação. - Dê a cada perfil um nome que identifique seu provedor, responsável e ambiente. - Reinicie o Claude Code após a troca, pois os processos em execução podem manter valores antigos. - Inspecione os arquivos gerados e use claude mcp list para verificar o estado efetivo. - Trate os dados locais do CC Switch e as configurações dos agentes que os utilizam como armazenamentos de credenciais sensíveis. - Defina o escopo dos servidores MCP com o mesmo cuidado usado para tokens de API; eles podem executar comandos e expor arquivos. - Fixe as versões, teste as diferenças de configuração e mantenha um meio de revogar tokens. - Mantenha credenciais de produção de alto impacto fora de ferramentas de troca no desktop, a menos que os controles ao redor delas deem suporte explícito a esse risco. [Programação](/pt/blog/tag/coding/)[Claude](/pt/blog/tag/claude/)[API](/pt/blog/tag/api/) A [AI Prime Tech](https://aiprimetech.io/pt/) A AI Prime Tech publica este blog. Os artigos são redigidos com assistência de IA; confira detalhes específicos de cada versão, como IDs de modelos, preços e limites, na documentação oficial antes de se basear neles. Obtenha acesso mais barato à API do Claude Uma única chave de API para Claude Opus 5.5, Sonnet 5, Haiku 4.5 e Fable 5.1, além de GPT-6 modelos. Pague conforme o uso, sem assinatura. [Obtenha Sua Chave de API →](/register) A AI Prime Tech é um gateway de API independente de terceiros. Claude™ e Anthropic® são marcas comerciais da Anthropic, PBC. Não há afiliação nem endosso implícitos.