Como usar o CC-Switch-CLI
O CC-Switch-CLI é uma ferramenta de alternância de provedores para linha de comando, ideal para servidores sem interface gráfica, ambientes SSH ou para quem precisa alternar provedores rapidamente entre Claude Code, Codex, Gemini CLI, OpenCode e OpenClaw.
Para quem é indicado
Se você é um usuário comum de desktop, priorize a interface gráfica do CC Switch; se já está acostumado com o terminal ou precisa gerenciar configurações em lote, consulte esta página. Os blocos de código a seguir contêm apenas comandos, com explicações fora deles para evitar copiar textos explicativos junto com os comandos.
Instalação e inicialização
Usuários de macOS / Linux podem seguir a documentação oficial para usar o script de instalação ou o pacote dos Releases; para usuários de Windows, recomenda-se baixar o arquivo compactado correspondente nos Releases e executá-lo no diretório do programa após a descompactação.
curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash cc-switch.\cc-switch.exeAo digitar diretamente cc-switch você entrará na interface interativa, ideal para iniciantes explorarem o menu primeiro; os comandos a seguir são indicados para quando você já sabe o que quer fazer e deseja executar diretamente.
Verificação do ambiente
| O que verificar | Como verificar | Por quê |
|---|---|---|
| CC Switch ou a versão CLI está instalada | O terminal reconhece o comando correspondente | Qualquer comando de configuração falhará se não estiver instalado. |
| A CLI de destino está instalada | Claude Code, Codex e Gemini CLI conseguem pelo menos iniciar individualmente | O CC-Switch-CLI não instala a ferramenta de destino para você |
| As informações do provedor estão completas | Prepare a Base URL, a API Key e o nome do modelo | A configuração por linha de comando não possui avisos visuais, e a falta de um item pode facilmente causar falhas. |
| Valide primeiro em um diretório de teste | Não alterne em lote diretamente em projetos reais | Mais fácil de reverter caso a configuração esteja incorreta |
cc-switch env tools cc-switch env check cc-switch provider current cc-switch --app codex provider currentComandos de Provider
Um Provider é uma configuração de provedor. Antes de adicionar um Provider, prepare a Base URL, a API Key e o nome do modelo a partir do painel do provedor; ao editar ou alternar, confirme primeiro o número usando o comando de listagem.
cc-switch provider list cc-switch provider add cc-switch provider edit <id> cc-switch provider fetch-models <id>cc-switch provider switch <id> cc-switch provider stream-check <id> cc-switch provider fetch-models <id>< id> precisa ser substituído pelo número exibido em cc-switch provider list. Não execute diretamente com < id> de forma literal.Gerenciamento por aplicativo
Se você quiser ver apenas a configuração de uma ferramenta de destino específica, adicione --app. Isso é muito útil para diagnosticar problemas no Claude Code, Codex e Gemini CLI separadamente.
cc-switch --app claude provider list cc-switch --app codex provider list cc-switch --app gemini provider list cc-switch --app opencode provider list cc-switch --app openclaw provider listcc-switch --app claude provider current cc-switch --app codex provider current cc-switch --app gemini provider currentDepois de confirmar que o aplicativo de destino e o provedor atual estão corretos, faça a alternância. Concluída a troca, reinicie o terminal e use a ferramenta de destino para enviar uma pergunta de teste bem curta.
claude "Please reply only: Claude Code is active" codex "Please reply only: Codex is active" gemini "Please reply only: Gemini is active"Sincronização de MCP
Nem todo iniciante precisa de MCP. Lide com isso apenas se você já usa MCP no Claude Code, Codex ou Gemini CLI e precisa de sincronização entre ferramentas. Na primeira vez, é recomendável entrar no menu da TUI para conferir a área de MCP, em vez de copiar comandos avançados diretamente de tutoriais antigos.
cc-switch cc-switch --app codexFluxo de configuração
- Primeiro, confirme a ferramenta de destino que deseja alternar: Claude Code, Codex, Gemini CLI ou outra CLI.
- Prepare a Base URL, a API Key e o nome do modelo a partir do painel do provedor.
- Adicione ou selecione um Provider no CC-Switch-CLI.
- Aplique o Provider à ferramenta de destino.
- Depois de reabrir o terminal, faça um teste com uma pergunta bem curta na CLI de destino.
- Assim que confirmar o funcionamento, aplique o mesmo Provider a outras ferramentas de destino.
| Cenários | Recomendações |
|---|---|
| Uso local no desktop | Dê preferência à interface gráfica do CC Switch; campos e status são mais intuitivos |
| Servidor remoto / SSH | Nesse caso, use o CC-Switch-CLI; confira os comandos da versão atual antes de executar |
| Alternância de configurações em lote | Valide primeiro com sucesso em um projeto de teste antes de aplicar em projetos reais |
| Várias pessoas compartilhando a mesma máquina | Não grave sua Key na configuração pública; confirme primeiro o escopo do arquivo de configuração |
Solução de problemas para iniciantes
| Sintoma | O que checar primeiro | Soluções |
|---|---|---|
| Comando não encontrado | Verifique se está instalado e se foi adicionado ao PATH | Reabra o terminal ou volte às instruções oficiais de instalação para confirmar o local instalado |
| A ferramenta de destino não mudou após a alternância | Se o terminal foi reaberto e se a ferramenta de destino correta foi selecionada | Feche a janela atual do terminal, abra-a novamente e teste de novo |
| 401 / Unauthorized | Se a Key está completa e se não expirou | Copie a Key novamente, garantindo que não haja espaços extras |
| Modelo não encontrado (model not found) | Se o nome do modelo foi copiado exatamente como está no painel | Preencha novamente de acordo com a lista de modelos do provedor |