Nota do autor: tanto o magpie quanto o CC Switch alteram os arquivos de configuração dos Agents no seu computador. Este artigo compara os dois em termos de arquitetura, ritmo de lançamentos, recursos e público-alvo, além de explicar por que apenas um deles deve ficar responsável por gravar as configurações.
O arquivo ~/.claude/settings.json está numa situação delicada. O CC Switch cuida dele há mais de um ano: ao trocar de provedor, altera apenas os campos de conexão e mantém o restante intacto. O magpie também quer gravar nesse arquivo, alterando o endereço de conexão para 127.0.0.1:3425. Como os dois programas escrevem nele, vale a última alteração: a anterior é sobrescrita silenciosamente. Por isso, só um programa deve controlar esse arquivo de configuração por vez.
O ritmo dos dois projetos é bem diferente. Até 28/10/2026, o repositório de lançamentos do magpie já acumulava mais de 1.000 números de versão desde sua criação, em 23/09/2026. Só em 27/10/2026, a API do GitHub registrou 87. Já o CC Switch foi da v3.19.0 (30/07/2026) à v4.0.21 (26/10/2026), com 30 versões oficiais em três meses, todas acompanhadas de notas de lançamento em chinês. Em inglês, “magpie” significa pega-rabuda: esse pássaro anuncia dezenas de atualizações por dia.
A comunidade também está dividida sobre o magpie. Em 10/10/2026, uma publicação no linux.do tinha o título: “Usar o magpie é uma bagunça; não recomendo a troca para quem está acostumado com o CC Switch”. No dia seguinte, apareceu outra: “Por que todo mundo está recomendando o magpie? Baixei e não vi nenhuma grande vantagem”. Algumas pessoas temem que o CC Switch seja substituído. Nossa conclusão é que isso não vai acontecer, mas o magpie de fato atraiu parte dos usuários.
Este artigo não é um tutorial de instalação e também não pretende declarar um vencedor absoluto. A ideia é esclarecer as diferenças entre as duas abordagens e ajudar você a decidir com qual ficar.
Ritmo de lançamentos do Magpie vs. CC Switch: dezenas de pacotes por dia vs. 30 versões em três meses
A diferença mais evidente entre os dois está no ritmo de lançamentos, então vale começar por aí. O magpie continua na série 0.1.x, mas o número de patches cresce rapidamente. Nas 25 horas entre 03/10/2026 às 13h e 04/10 às 14h, ele passou da v0.1.756 para a v0.1.859, com exatamente 100 versões. Em 28/10/2026, a versão mais recente era a v0.1.1801. A API do GitHub retorna no máximo os primeiros 1.000 registros de lançamento; os mais antigos já não aparecem, e o total continua crescendo.
Vale explicar o que esses números representam. São números de patch gerados por builds automáticos: quase todo commit gera um pacote, o que não significa que houve 1.000 melhorias de funcionalidades. Essa frequência mostra duas coisas: a manutenção é ativa e as correções chegam rápido; ao mesmo tempo, a série 0.1.x ainda está numa fase de experimentação intensa, e o próprio número da versão indica que não dá para esperar muita estabilidade.
| Indicador (até 28/10/2026) | magpie | CC Switch |
|---|---|---|
| Criação do repositório | 23/09/2026 | 04/08/2025 |
| Versão mais recente | v0.1.1801 | v4.0.21 (26/10/2026) |
| Ritmo de lançamentos | Até 87 em um único dia, mais de 1.000 no total | 30 versões oficiais em três meses |
| Estrelas no GitHub | Cerca de 23,8 mil | Cerca de 149 mil |
| Ferramentas compatíveis | O README lista 68 agentes | 12 ferramentas, cada uma com uma predefinição própria |
| Modelo de manutenção | Não aceita PRs externos; só mantenedores podem abri-los | Aberto à colaboração via issues e PRs |
Ao colocar lado a lado 149 mil estrelas e 100 pacotes em um dia, dá para perceber que os projetos estão em fases diferentes: o CC Switch já tem uma base enorme de usuários, enquanto o magpie ainda passa por iterações rápidas. Não é uma questão de qual equipe trabalha mais, mas de ritmos e tolerâncias a risco diferentes. Segundo o autor do CC Switch, mais de 500 issues antigos foram fechados durante a refatoração da versão 4.0. O magpie chegou a cerca de 23,8 mil estrelas em pouco mais de um mês, mas popularidade e estabilidade são coisas diferentes.
Outro detalhe: a página do CC Switch no site de documentação da APIYI (tutorial de uso em docs.apiyi.com) ainda menciona a v3.12.0 e 5 ferramentas. Ela está desatualizada em relação ao repositório oficial, que lista 12 ferramentas e a v4.0.21. Para confirmar as versões, consulte o GitHub.
Magpie VS CC Switch: mudar os arquivos de configuração ou passar primeiro pelo gateway local
A diferença fundamental está na abordagem: o CC Switch é centrado nos agentes, enquanto o magpie é centrado no gateway.
Ao fazer uma troca, o CC Switch substitui apenas os campos de conexão nos arquivos de configuração de cada ferramenta: endereço de requisição, chave e modelo. Plugins, Hooks, MCP, configurações adicionadas por você e comentários permanecem intactos. Antes da primeira alteração, ele também cria automaticamente um backup do arquivo original. Claude Code, Codex e Gemini CLI usam o modo de troca, no qual apenas um provedor fica ativo por vez. OpenCode, OpenClaw, Hermes e Pi usam o modo de coexistência, que registra vários provedores ao mesmo tempo na configuração da própria ferramenta. O CC Switch também oferece roteamento local, mas é preciso ativá-lo manualmente. Quando ativado, ele permite converter protocolos entre Anthropic Messages, OpenAI Chat Completions, OpenAI Responses e Gemini Native, além de oferecer uma fila de failover e um circuit breaker.
Já o magpie direciona primeiro as conexões de todos os agentes para 127.0.0.1:3425. As chaves ficam centralizadas no magpie, e o gateway encaminha as requisições aos provedores. O gateway converte entre quatro protocolos, incluindo saída em streaming, chamadas de ferramentas e conteúdo de raciocínio. Ele também altera os campos essenciais na configuração dos agentes. Como diz o README, o magpie “edita a única chave que importa na configuração do próprio agente”, usando gravação atômica e preservando comentários, ordem e formatação. Se você preferir que ele não altere os arquivos de configuração, pode apontar OPENAI_BASE_URL, ANTHROPIC_BASE_URL e GOOGLE_GEMINI_BASE_URL para o gateway local e preencher a chave com magpie.
| Aspecto | magpie | CC Switch |
|---|---|---|
| Proposta | Gateway local + alternador | Gerenciador de configurações para desktop + roteamento local opcional |
| Como faz a troca | A requisição passa por 127.0.0.1:3425 antes de ser enviada |
Altera os campos de conexão na configuração de cada ferramenta |
| Tolerância a falhas de contas | Cinco modos de grupos de roteamento + failover entre contas + Daily warm-up | Fila de failover + circuit breaker + monitoramento de integridade |
| Gerenciamento diário | Library: configure instruções, MCP, skills e subagentes uma única vez | Painel MCP + Skills + biblioteca de comandos + gerenciador de sessões |
| Sessões | Lista mostra o custo de cada sessão e permite reabri-la no terminal com um clique | Converte em conteúdo estruturado, resumos por turno, exportação e comandos de recuperação |
| Formas de uso | Desktop, TUI, CLI, Web UI, Docker, Termux | Desktop + bandeja do sistema |
Vantagens do magpie: roteamento, tolerância a falhas e migração
Os principais atrativos do magpie são:
- Baixo custo de migração: a função Import, na página de fornecedores, permite importar diretamente os fornecedores do CC Switch. A migração leva apenas alguns minutos. Esse é o ponto de impacto mais direto para o CC Switch.
- Grupos de roteamento: é possível disponibilizar um grupo como se fosse um modelo para o agente, por exemplo,
group/daily-coding. Cada grupo oferece cinco modos: smart, order, rotate, usage e pace. Sessões que se beneficiam do cache permanecem na conta que respondeu a elas inicialmente. - Assinaturas como fornecedores: assinaturas do Claude, ChatGPT, Copilot e outros serviços com login ativo podem ser usadas como fornecedores por outros agentes. Essa função pode ser desativada nas configurações de privacidade.
- Mascaramento de dados: chaves, tokens, e-mails e outras informações são substituídos localmente por marcadores antes do envio. A função vem desativada por padrão. Quando ativada, se o mascaramento deveria ter sido aplicado, mas falhar, a solicitação retorna diretamente o erro 503, sem enviar o texto original.
- Compartilhamento na rede local e implantação: é possível atribuir uma chave de gateway e definir um limite de gastos para cada cliente, além de executar o sistema em um NAS usando Docker.
Vantagens do CC Switch: gerenciamento mais detalhado no dia a dia
O CC Switch oferece recursos mais detalhados para o gerenciamento diário:
- Painel unificado de MCP: permite selecionar quais ferramentas sincronizar e importar as configurações existentes de cada uma.
- Gerenciamento de Skills: permite instalar Skills do GitHub ou de um arquivo ZIP com um clique e atualizar todas de uma vez.
- Biblioteca de comandos: ao ativar um comando, ele é gravado em CLAUDE.md / AGENTS.md. Antes disso, o conteúdo existente no arquivo é salvo na biblioteca de comandos.
- Gerenciador de sessões: cada rodada é compactada em uma linha de resumo, etapas com falha aparecem em vermelho e é possível copiar o comando de recuperação para continuar a conversa.
- Snapshots de projeto: fornecedores, MCP, Skills e comandos podem ser trocados como um conjunto completo para cada projeto.
A v4.0.21 também adicionou a troca entre várias contas de assinaturas oficiais do Claude. O login segue o fluxo oficial, e os tokens são armazenados apenas no local usado pelo próprio Claude Code. O CC Switch não os registra nem os envia e também deixa claro que não faz rotação automática com base na cota. É uma abordagem mais conservadora, exatamente o oposto da adotada pelo magpie.
As ferramentas só encaminham as requisições: o modelo e a chave API por trás do Magpie e do CC Switch
Independentemente da ferramenta escolhida, ela só encaminha as requisições. O modelo e a chave API precisam ser obtidos separadamente. Para que tudo funcione sem problemas, você precisa de uma chave API estável e válida para o claude-opus-5-5. A APIYI (apiyi.com) oferece endpoints compatíveis tanto com Anthropic quanto com OpenAI, aos quais ambas as ferramentas podem se conectar diretamente.
| Item de conexão | Valor | Observações |
|---|---|---|
| Endereço compatível com Anthropic | https://api.apiyi.com |
Sem /v1, indicado para o Claude Code |
| Endereço compatível com OpenAI | https://api.apiyi.com/v1 |
Indicado para Codex e outras ferramentas que usam o protocolo OpenAI |
| Nome do modelo | claude-opus-5-5 |
A versão thinking, claude-opus-5-5-thinking, tem o mesmo preço |
| Preço (por milhão de tokens) | Entrada: US$ 4 / saída: US$ 20 / leitura de cache: US$ 0,20 | Em 28/10/2026. Consulte a lista de modelos da plataforma para confirmar os modelos e preços |
| Endpoints e grupos | chat, messages; grupos ClaudeCode, Default, SVIP, entre outros | Escolha o grupo de acordo com seu uso |
Vale lembrar que as duas ferramentas leem a mesma configuração do Agent. O CC Switch grava a chave API em ~/.claude/settings.json, enquanto o Magpie a armazena no gateway. No fim, ambos usam a mesma conta no provedor. Por isso, basta trocar a chave API uma vez no console da APIYI. O saldo e o uso também ficam disponíveis no mesmo lugar, sem precisar preencher a chave separadamente nas duas ferramentas.
Magpie VS CC Switch: qual manter e quando trocar
Quem deve continuar com o CC Switch
Se você usa principalmente o Claude Code, tem apenas um ou dois provedores, prioriza a estabilidade e não quer investigar problemas depois de cada atualização, o CC Switch é a melhor opção. Ele faz poucas alterações, tem um mecanismo de backup robusto e, quando algo dá errado, basta abrir o arquivo de configuração para entender o motivo. Quem costuma organizar MCP, Skills e comandos, ou precisa consultar o histórico de sessões, também tende a se sentir mais à vontade com a interface e o fluxo de trabalho do CC Switch.
O autor do post de 10-10 foi direto: “Não faz o menor sentido trocar por isso, com os provedores todos misturados. É muito bagunçado. Pior ainda: depois que o modelo passa por esse software e você faz a seleção, não dá mais para trocar de modelo no CLI”. No mesmo post, outra pessoa comentou: “Até agora não vi nenhum recurso exclusivo capaz de desbancar o CCS”. Para quem só precisa trocar de provedor com um clique, o CC Switch já resolve.
Quem deve migrar para o magpie
Se você usa vários agentes ao mesmo tempo, como Codex, Gemini CLI, OpenCode e Pi, tem várias assinaturas e chaves, quer alternar automaticamente quando uma cota acabar e também precisa de um painel de custos, a abordagem de gateway do magpie combina mais com você. No mesmo dia, alguém comentou no post: “Acabei de trocar do ccswitcg para o magpie esta tarde. Finalmente não preciso mais testar a disponibilidade de cada serviço proxy de API”. No post de 10-11, um usuário também defendeu a ferramenta: “No magpie, tanto adicionar quanto alternar é mais prático do que no ccs, e ele ainda tem regras de roteamento bem poderosas”. Outra pessoa mencionou que, no app do Codex, o CC Switch não conseguia exibir os modelos nem alternar entre eles corretamente.
Os comentários negativos sobre o magpie precisam ser analisados com cuidado. Uma pessoa relatou que, depois de integrar o magpie, o cache do Claude parecia ter deixado de funcionar e os custos aumentaram. No post, outra pessoa disse suspeitar que a camada intermediária havia adicionado uma revisão de comandos, levando à rejeição de solicitações. Ambos são relatos isolados, sem um procedimento para reproduzir o problema; portanto, não dá para concluir com base neles que o magpie tenha esses problemas. As informações deste artigo se dividem em três categorias: declarações oficiais dos projetos, relatos isolados de terceiros e questões ainda sem conclusão. É importante tratar cada uma separadamente.
Magpie VS CC Switch: qual escolher para cada perfil
| Sua situação | Recomendação | Motivo |
|---|---|---|
| Só usa Claude Code com um ou dois provedores e quer estabilidade | CC Switch | Faz poucas alterações, tem backup e mantém um ritmo estável: 30 versões oficiais em três meses |
| Usa vários agentes e contas e quer tolerância automática a falhas e painel de custos | magpie | Grupos de roteamento + failover + estatísticas de uso |
| Suas principais necessidades são MCP, Skills, comandos e consulta de sessões | CC Switch | Painel de gerenciamento mais detalhado e análise de sessões mais completa |
| Quer compartilhar na rede local, executar em um NAS ou converter protocolos para agentes sem suporte | magpie | Oferece gateway e implantação via Docker |
| Quer usar os dois | Deixe apenas um gravar a configuração | Veja a próxima seção |
💡 Dica para escolher: se estiver em dúvida, experimente cada ferramenta por uma tarde usando a mesma chave. As etapas para configurar o CC Switch estão no tutorial da APIYI em
docs.apiyi.com/scenarios/programming/cc-switch. Para configurar o gateway unificado do magpie, consultehelp.apiyi.com/magpie-unify-claude-code-codex-pi-hermes-api-gateway.html. É só seguir os tutoriais, sem precisar descobrir tudo do zero.
O problema de instalar os dois: apenas um programa pode gerenciar o settings.json
Voltando à questão inicial: magpie e CC Switch reescrevem os mesmos arquivos, como ~/.claude/settings.json e ~/.codex/config.toml. Quando os dois estão em execução, trocar de provedor em um deles pode sobrescrever silenciosamente as configurações do outro, sem nenhum aviso. O provedor que o Claude Code usará depois disso depende de qual ferramenta gravou por último.
Para que os dois coexistam, é preciso definir quem controla os arquivos de configuração: um fica responsável pela gravação, enquanto o outro apenas lê ou é encerrado após o uso. Por exemplo, você pode manter o CC Switch para gerenciar MCP e comandos e deixar toda a troca de provedores para o magpie, ou fazer o contrário. Não deixe os dois programas gravando configurações ao mesmo tempo de forma contínua. Se quiser migrar, use a função Import do magpie para importar os provedores do CC Switch e, depois de confirmar que está tudo certo, feche a ferramenta antiga para evitar gravações simultâneas.
Riscos e bloqueio de conta: faça backup antes de usar Magpie ou CC Switch
Alguns pontos importantes antes de começar:
- Ambos são ferramentas de código aberto de terceiros (com licença MIT) e reescrevem os arquivos de configuração dos agentes no seu computador. Antes de instalar, faça backup manual de arquivos como
~/.claude/settings.jsone~/.codex/config.toml. Não dependa apenas do backup oferecido pelas ferramentas. - Usar assinaturas fora dos clientes oficiais pode violar os termos de serviço: usar assinaturas do Claude, ChatGPT ou Copilot fora dos clientes oficiais pode infringir os termos dos fornecedores. A própria documentação do CC Switch traz um aviso semelhante. A função do magpie que permite usar assinaturas como provedores pode ser desativada em Settings → Privacy.
- Você assume as consequências: configurações sobrescritas, perda de créditos e riscos à conta são de responsabilidade do leitor. Este artigo não endossa nenhuma das ferramentas. Recomendamos testá-las primeiro em uma conta secundária ou em um projeto menos importante.
Perguntas frequentes FAQ
Q1: Posso instalar o Magpie e o CC Switch ao mesmo tempo?
Sim, mas eles não podem gravar configurações ao mesmo tempo. Os dois modificam o mesmo arquivo `~/.claude/settings.json`, então é preciso definir qual deles ficará responsável pela gravação. O outro deve ficar em modo somente leitura ou ser fechado.
Q2: O magpie lançou mais de mil versões em pouco mais de um mês. Isso significa que ele é instável?
Esses números são, em sua maioria, versões de patch geradas por builds automáticos, o que indica manutenção frequente e correções rápidas. Ainda assim, a versão 0.1.x está em fase de experimentação. Quem precisa de muita estabilidade pode preferir esperar um pouco.
Q3: O magpie pode invalidar o cache e aumentar os custos?
Até agora, há apenas relatos isolados, sem um procedimento para reproduzir o problema, então não dá para tirar uma conclusão. Se você estiver preocupado, pode comparar o painel de uso antes e depois da troca.
Q4: Ao trocar de ferramenta, preciso solicitar uma nova chave API?
Não. As duas ferramentas apenas encaminham as solicitações, então você pode continuar usando a mesma chave API. Gerencie a chave no console da APIYI em apiyi.com e use-a tanto no CC Switch quanto no magpie.
Q5: Qual endereço devo usar para o claude-opus-5-5?
O Claude Code usa o protocolo Anthropic, então informe o endereço sem `/v1`. Para o Codex e outras ferramentas que usam o protocolo OpenAI, informe o endereço com `/v1`. Em 28/10/2026, os preços eram de US$ 4 para entrada, US$ 20 para saída e US$ 0,20 para leitura de cache, por milhão de tokens. Consulte a lista de modelos em apiyi.com para conferir os valores.
Q6: O magpie vai substituir o CC Switch?
Não. Eles atuam em camadas diferentes: o CC Switch gerencia e alterna as configurações dos agentes, enquanto o magpie faz todas as solicitações passarem primeiro por um gateway local. Os usuários do CC Switch mais afetados são aqueles que só precisam trocar de provedor com um clique.
Magpie vs. CC Switch: principais pontos
- Abordagens diferentes: o CC Switch altera os arquivos de configuração; o magpie faz as requisições passarem primeiro pelo gateway local
127.0.0.1:3425. - Ritmos diferentes: até 28/10/2026, o magpie acumulava mais de 1.000 números de versão; o CC Switch lançou 30 versões oficiais em três meses.
- Cada um tem seus pontos fortes: o magpie se destaca em roteamento, tolerância a falhas e conversão entre protocolos; o CC Switch, em MCP, Skills e gerenciamento de sessões.
- Não podem gravar ao mesmo tempo: os dois alteram o mesmo settings.json, então só um deles pode ter permissão de escrita.
- Os relatos negativos são casos isolados: comentários sobre cache, censura e outros problemas não trazem instruções para reproduzi-los, então não podem ser tratados como conclusões.
- A chave só precisa ser gerenciada uma vez: troque-a no console da APIYI; as duas ferramentas leem a mesma configuração do Agent.
Conclusão
A comparação entre magpie e CC Switch é, no fundo, uma comparação entre duas abordagens: de um lado, um gateway com ciclos rápidos de desenvolvimento; do outro, uma ferramenta centrada na configuração do Agent, aprimorada de forma gradual. O magpie atraiu parte dos usuários que só queriam trocar de provider com um clique, enquanto o CC Switch continua oferecendo recursos mais completos para o gerenciamento diário. O debate na comunidade deve continuar por algum tempo, mas, para quem usa as ferramentas individualmente, a escolha é bem simples.
O arquivo ~/.claude/settings.json só pode ser gerenciado por um programa de cada vez. Escolha uma ferramenta com base nos cinco cenários acima e use-a a longo prazo, sem precisar ficar alternando entre as duas.
Você pode preparar o modelo e a chave pela APIYI em apiyi.com. Com a mesma chave, é possível acessar o claude-opus-5-5 diretamente, independentemente da ferramenta escolhida.
📚 Referências
- Repositório do magpie no GitHub: gateway local unificado de IA e alternador de modelos
- Link:
github.com/yetone/magpie -
Descrição: o README inclui uma lista de 68 agentes e informações sobre o gateway. A versão em chinês é o README.zh-CN.md.
-
Documentação oficial do magpie: recursos e configurações
- Link:
usemagpie.ai/docs -
Descrição: informações detalhadas sobre grupos de roteamento, mascaramento de dados privados, compartilhamento em rede local e outros recursos.
-
Repositório do CC Switch no GitHub: gerenciador multiplataforma tudo em um
- Link:
github.com/farion1231/cc-switch -
Descrição: notas de lançamento e registros detalhados de correções. Consulte o repositório para confirmar as versões.
-
Site oficial do CC Switch: apresentação e download do produto
- Link:
ccswitch.io - Descrição: lista de ferramentas compatíveis e instruções de uso.
Autoria: equipe técnica da APIYI
Contato técnico: entre em contato pela página inicial do site da APIYI. Para mais informações sobre integração, acesse a central de documentação em docs.apiyi.com.
