Configuração do CC Switch Claude Code com Flatkey e NewAPI

Se você está procurando por CC Switch Claude Code, provavelmente já tem o assistente de codificação instalado. O problema de configuração é mais restrito: você precisa que o CC Switch escreva a configuração correta do provedor Claude Code, use a chave Flatkey correta, aponte para a URL base correta, escolha modelos que sua chave realmente consiga acessar e verifique a solicitação nos logs de uso.

Este guia cobre o caminho prático para o roteamento do CC Switch Claude Code com Flatkey e o fluxo de um clique no estilo NewAPI. A documentação atual do CC Switch da NewAPI descreve uma importação por deep link ccswitch:// a partir da página de token da New API. Usuários do Flatkey podem usar manualmente a mesma superfície de configuração do CC Switch: adicionar um provedor Claude Code, colar uma chave de API Flatkey, definir a URL base do gateway Claude Code, buscar modelos, salvar o perfil e verificar a rota.

O guia é somente texto. Ele não usa capturas de tela do app porque o fluxo atual da interface do CC Switch e do Flatkey deve ser revisado por captura de tela antes de publicar imagens do passo a passo.

Resposta rápida: definições do CC Switch Claude Code para Flatkey

Para uma configuração CC Switch Claude Code com backend Flatkey, crie um provedor Claude Code no CC Switch e use o roteador Flatkey como gateway. Para solicitações no estilo Anthropic Messages do Claude Code, use a URL raiz do gateway, não o caminho de chat-completions da OpenAI.

CC Switch Field Or Config	Flatkey Value	What To Verify
Application	Claude or Claude Code	Do not configure the Codex or Gemini app when the target is Claude Code.
Provider tab	App-specific Provider for Claude Code, or Universal Provider if you also sync Codex/Gemini	Universal providers need a post-sync check because each app may expect a different URL shape.
Name	Flatkey Claude Code	Use a name that will be clear in CC Switch tray switching later.
API Key	Your Flatkey API key	Create or copy it from the Flatkey dashboard. Never paste a real key into shared docs.
Claude Code base URL	https://router.flatkey.ai	Use this for ANTHROPIC_BASE_URL. Claude Code then reaches paths such as /v1/messages.
OpenAI-compatible base URL	https://router.flatkey.ai/v1	Use this for OpenAI-compatible clients and model-fetch checks that call /v1/models.
Main/Sonnet/Opus/Haiku models	Model IDs from the CC Switch fetch result, Flatkey console, or pricing catalog	Use exact model IDs. Do not use marketing names or model-family labels.
Verification	Run a tiny Claude Code prompt and review Flatkey usage logs	The setup is not finished until the request appears in the Flatkey dashboard.

If your CC Switch form exposes an advanced JSON editor, the Claude Code profile should resolve to a shape like this. Use a placeholder in documentation; never store a live key in a repo.

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-fk-your-flatkey-key",
    "ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
    "ANTHROPIC_MODEL": "your-claude-model-id"
  }
}

Claude Code também suporta ANTHROPIC_API_KEY. Use uma variável de autenticação, não ambas, a menos que você entenda intencionalmente a precedência. Para roteamento de gateway no estilo bearer, ANTHROPIC_AUTH_TOKEN mantém o mapeamento explícito porque o Claude Code o envia como o valor do cabeçalho Authorization.

Onde o NewAPI se Encaixa no Fluxo de Trabalho do CC Switch

A documentação atual do CC Switch do NewAPI diz que o console do New API pode adicionar um atalho de Configurações do Chat com este JSON:

{ "CC Switch": "ccswitch" }

Depois disso, a página de gerenciamento de tokens do New API pode exibir uma opção do CC Switch que inicia o CC Switch por meio do deep link ccswitch:// e abre a caixa de diálogo de importação do provedor. A documentação do NewAPI descreve os campos da caixa de diálogo como tipo de aplicação, nome, modelo principal e seleções de modelo Haiku/Sonnet/Opus.

No caso do Flatkey, use o mesmo conceito sem afirmar uma importação na página de token do NewAPI. Se a sua chave for uma chave Flatkey, adicione o provedor diretamente no CC Switch. Se a sua chave estiver em uma implantação do NewAPI, use a importação com um clique do NewAPI. A distinção importante é simples: o CC Switch gerencia a configuração local do Claude Code, enquanto o Flatkey ou o NewAPI lida com a camada de roteamento upstream.

Antes de Começar

Antes de alterar o provedor CC Switch Claude Code, confirme estes pré-requisitos:

• O CC Switch está instalado na máquina onde o Claude Code é executado.
• O Claude Code já está instalado e pode ser aberto normalmente.
• Você pode entrar no Flatkey e abrir o dashboard.
• Você tem uma chave de API do Flatkey para esta estação de trabalho ou desenvolvedor.
• Você conhece pelo menos um ID de modelo Claude disponível para sua conta Flatkey.
• Você pode revisar os logs de uso do Flatkey após a primeira solicitação de teste.

Não use uma chave de produção compartilhada para o primeiro teste. Crie uma chave limitada com o nome da ferramenta e do proprietário, como cc-switch-lee ou claude-code-devbox. Isso mantém o primeiro teste rápido do CC Switch Claude Code fácil de auditar e fácil de revogar.

Etapa 1: Criar ou Copiar uma Chave de API Flatkey

Abra o painel do Flatkey e crie uma chave para uso com o Claude Code através do CC Switch. Copie-a uma vez e armazene-a no seu gerenciador de senhas ou no gerenciador de segredos da equipe.

O campo Chave de API do CC Switch deve conter a chave do Flatkey. Não cole uma chave da Anthropic, OpenAI, Google ou específica de um provedor neste perfil, a menos que você esteja configurando intencionalmente esse provedor direto em vez do Flatkey.

Para equipes, crie chaves separadas por usuário, dispositivo ou ambiente. Uma chave compartilhada pode funcionar tecnicamente, mas torna a revisão de uso e a revogação mais difíceis depois.

Passo 2: Adicionar um provedor Claude Code no CC Switch

Abra o CC Switch e vá para a área de provedores do Claude Code. O manual do usuário do CC Switch descreve dois caminhos para adicionar: provedores específicos do app para o app selecionado e o Universal Provider para uma configuração compartilhada entre Claude Code, Codex e Gemini.

Para a primeira configuração CC Switch Claude Code da Flatkey, comece com um provedor Claude Code específico do app:

1. Abra o CC Switch.
2. Selecione Claude ou Claude Code no seletor de aplicativos.
3. Clique no botão + para adicionar um provedor.
4. Escolha um caminho de provedor personalizado se não houver um preset da Flatkey.
5. Defina o nome do provedor como Flatkey Claude Code.
6. Cole sua chave de API da Flatkey.
7. Defina a URL base do gateway do Claude Code como https://router.flatkey.ai.
8. Escolha os IDs dos modelos para Main, Sonnet, Opus e Haiku somente depois de confirmar que eles estão disponíveis para sua conta.

Se você usar um Universal Provider, preencha Name, API Key e Endpoint URL, e então marque os apps que deseja sincronizar. Após a sincronização, inspecione a configuração gerada do Claude Code. Para o Claude Code, a base ativa deve ser https://router.flatkey.ai. Para configurações de apps compatíveis com OpenAI, https://router.flatkey.ai/v1 geralmente é a URL base esperada.

Etapa 3: Buscar Modelos Antes de Escolher Main, Sonnet, Opus e Haiku

O CC Switch documenta uma ação Buscar Modelos ao lado dos campos de modelo. Ela usa a chave de API configurada para chamar um endpoint /v1/models compatível com a OpenAI e, em seguida, permite selecionar os IDs de modelo retornados em um menu suspenso.

Para este artigo, uma verificação datada do Flatkey em 11 de junho de 2026 retornou HTTP 200 de https://router.flatkey.ai/v1/models com uma resposta de lista de modelos para a chave de teste configurada. Os exemplos retornados incluíam IDs de modelo da família Claude, como claude-sonnet-4-6, claude-sonnet-4-5, claude-opus-4-7 e claude-haiku-4-5. Trate esses exemplos como uma captura atual, não como uma recomendação permanente de modelo.

Use esta regra de seleção de modelo:

• Main Model: escolha o modelo Claude que você quer que o Claude Code use por padrão.
• Sonnet Model: escolha o modelo equilibrado que sua equipe espera para codificação diária.
• Opus Model: escolha um modelo de maior capacidade apenas se seu orçamento e acesso permitirem.
• Haiku Model: escolha um modelo leve para tarefas mais rápidas ou em segundo plano, se उपलब्ध disponível.

Se a Busca de Modelos falhar, não chute. Abra o console do Flatkey ou o catálogo de preços, copie um ID de modelo exatamente compatível com o Claude e teste primeiro apenas com esse modelo.

Etapa 4: Salvar, Sincronizar e Verificar a Configuração Gerada do Claude Code

Depois de salvar o provedor, o CC Switch grava a configuração ativa do provedor para o Claude Code. O caminho exato do arquivo pode variar conforme a versão do CC Switch e o escopo do aplicativo, mas a documentação oficial de configurações do Claude Code confirma que variáveis de ambiente podem ser configuradas por meio de settings.json sob a chave env.

Verifique se a configuração gerada não contém valores de autenticação conflitantes. Um perfil Flatkey limpo deve ter um destes padrões:

# Estilo de gateway com token Bearer
ANTHROPIC_AUTH_TOKEN=sk-fk-your-flatkey-key
ANTHROPIC_BASE_URL=https://router.flatkey.ai

ou:

# Estilo de chave de API
ANTHROPIC_API_KEY=sk-fk-your-flatkey-key
ANTHROPIC_BASE_URL=https://router.flatkey.ai

Não deixe uma antiga chave direta da Anthropic ativa no seu shell enquanto testa um novo perfil CC Switch Claude Code. Se o shell ainda exportar um ANTHROPIC_API_KEY diferente, isso pode dificultar a solução de problemas porque o processo ativo pode não estar usando o perfil do CC Switch que você acha que está usando.

Passo 5: Verifique no Claude Code e nos logs de uso do Flatkey

Abra um terminal novo após habilitar o provedor Flatkey no CC Switch. O Claude Code pode suportar troca dinâmica em alguns caminhos do CC Switch, mas um terminal novo elimina a confusão de estado do shell durante o primeiro teste.

1. Inicie o Claude Code.
2. Verifique o modelo ativo ou o status no Claude Code.
3. Envie um prompt pequeno, como pedir para responder com uma frase curta.
4. Abra o painel do Flatkey.
5. Revise os logs de uso para o horário da solicitação, o ID do modelo e o nome da chave.

A configuração do CC Switch Claude Code só estará concluída quando as três camadas concordarem: o CC Switch mostrar o provedor Flatkey como ativo, o Claude Code usar o modelo/base URL esperados e os logs do Flatkey mostrarem a solicitação.

Solucionando problemas do CC Switch Claude Code com Flatkey

Problema	Causa provável	Correção
Erro de autenticação	A chave está errada, desativada, copiada com espaços ou não é uma chave Flatkey.	Crie uma nova chave no Flatkey, cole-a novamente e verifique se você está usando ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY, e não valores conflitantes.
404 ou caminho de endpoint incorreto	A URL inclui a estrutura de caminho errada para o Claude Code.	Para o Claude Code, use https://router.flatkey.ai. Para busca de modelos compatíveis com OpenAI ou outros clientes, use https://router.flatkey.ai/v1.
Falha ao buscar modelos	A chave não consegue chamar /v1/models, a URL base está errada ou o endpoint está temporariamente indisponível.	Use https://router.flatkey.ai/v1 para o caminho de busca de modelos e, em seguida, recorra aos IDs exatos dos modelos no console do Flatkey.
Claude Code ainda usa o provedor antigo	Um processo antigo no terminal ou uma exportação do shell está substituindo o perfil do CC Switch.	Abra um novo terminal, verifique as variáveis de ambiente do shell e certifique-se de que o provedor Flatkey esteja ativado no CC Switch.
A seleção de modelo funciona, mas as requisições falham	O modelo selecionado está listado, mas não está disponível para sua chave, grupo, saldo ou política atual da conta.	Teste primeiro um modelo com acesso conhecido. Revise o acesso à conta Flatkey, o saldo, as cotas e os registros de uso.
A busca de ferramentas MCP altera o comportamento	O Claude Code trata URLs base que não são de primeira parte como roteamento de gateway.	Siga as orientações de gateway do Claude Code antes de ativar o comportamento avançado de busca de ferramentas por meio de um proxy. Não ative flags específicas de gateway, a menos que seu gateway encaminhe os blocos necessários.

A maioria das falhas do CC Switch Claude Code se resume a quatro campos: chave, URL base, ID do modelo e perfil ativo. Verifique esses itens antes de reconstruir todo o banco de dados do CC Switch.

CC Switch Vs A Claude Code Router

CC Switch e um roteador Claude Code resolvem partes diferentes do fluxo de trabalho. O CC Switch é o gerenciador de configuração local. O Flatkey é a camada de roteamento e acesso.

Camada	O Que Faz	O Que Não Faz
CC Switch	Armazena perfis de provedores, alterna configurações do Claude Code/Codex/Gemini, gerencia campos de modelo e pode importar provedores por meio de deep links.	Não é a conta de modelo upstream, o sistema de cobrança ou o roteador.
Claude Code	Executa o assistente de codificação e lê os valores ativos de ambiente/configuração.	Não gerencia sozinho as chaves multi-provedor da sua equipe nem a cobrança.
Flatkey	Fornece uma chave, endpoints de gateway, acesso a modelos, visibilidade de uso, roteamento e controles de cobrança para modelos compatíveis.	Não substitui a interface local de troca de perfis do CC Switch.

Se você só precisa de uma configuração permanente de gateway, pode configurar o Claude Code diretamente. Se você alterna entre vários provedores, estações de trabalho ou níveis de modelo, o fluxo de trabalho CC Switch Claude Code oferece uma superfície de controle mais limpa. Se você também está migrando código de aplicativo para um gateway, leia o guia de migração de API compatível com OpenAI. Se você está decidindo entre um proxy apenas para Claude e um gateway mais amplo, leia proxy Claude API vs roteador.

Implantação Recomendada para a Equipe

Para um desenvolvedor, uma chave Flatkey e um provedor CC Switch são suficientes. Para uma equipe, trate a configuração do CC Switch Claude Code como uma pequena implantação de controle de acesso.

• Crie uma chave Flatkey nomeada por desenvolvedor, estação de trabalho ou ambiente.
• Documente os IDs aprovados dos modelos Claude e qual nível cada um mapeia no CC Switch.
• Use cotas antes de convidar mais usuários para a mesma configuração de roteamento.
• Revise os registros de uso após o primeiro dia, e não apenas depois de uma surpresa na cobrança.
• Mantenha capturas de tela fora da documentação pública até que a interface atual esteja confirmada pelo revisor.
• Use a importação com um clique do NewAPI apenas para chaves gerenciadas no NewAPI; use a configuração manual do provedor Flatkey para chaves Flatkey.

FAQ

O que é uma configuração CC Switch Claude Code?

Uma configuração CC Switch Claude Code é um perfil de provedor no CC Switch que define o endpoint, a chave e as configurações de modelo que o Claude Code deve usar. Com a Flatkey, esse perfil aponta o Claude Code para o roteador da Flatkey e usa uma chave da Flatkey.

O URL base do Claude Code da Flatkey deve incluir /v1?

Para o ANTHROPIC_BASE_URL do Claude Code, use https://router.flatkey.ai. Para clientes de app compatíveis com OpenAI e verificações de busca de modelos que chamam explicitamente /v1/models, use https://router.flatkey.ai/v1.

O importação com um clique do NewAPI configura a Flatkey automaticamente?

Não. O caminho de CC Switch com um clique do NewAPI é documentado para a página de gerenciamento de tokens do New API. Para a Flatkey, adicione o provedor manualmente no CC Switch, a menos que a Flatkey publique depois um link de importação dedicado ccswitch://.

O CC Switch consegue buscar os modelos da Flatkey?

Sim, quando a chave configurada pode acessar a lista de modelos da Flatkey compatível com OpenAI. Uma verificação de 11 de junho de 2026 para este artigo retornou HTTP 200 de https://router.flatkey.ai/v1/models e uma resposta de lista de modelos para a chave de teste configurada.

Devo usar ANTHROPIC_API_KEY ou ANTHROPIC_AUTH_TOKEN?

O Claude Code documenta ambos. ANTHROPIC_API_KEY é enviado como um cabeçalho de chave de API, enquanto ANTHROPIC_AUTH_TOKEN é enviado pelo caminho de autorização. Use um método claro para o perfil da Flatkey e evite deixar os dois definidos com valores diferentes.

Como sei que a configuração funcionou?

A configuração funcionou quando o CC Switch mostra o provedor Flatkey como ativo, o Claude Code usa o modelo esperado, um pequeno prompt de teste é concluído com sucesso e a solicitação aparece nos registros de uso da Flatkey.

Verificação Final

Seu setup Flatkey do CC Switch Claude Code está pronto quando esta checklist for aprovada:

1. O CC Switch tem um provider Flatkey claramente nomeado sob o Claude Code.
2. A chave de API é uma chave Flatkey do dashboard.
3. ANTHROPIC_BASE_URL resolve para https://router.flatkey.ai.
4. Os IDs de modelo selecionados são IDs exatos disponíveis para a sua chave.
5. Fetch Models ou a entrada manual de modelo é bem-sucedida.
6. O Claude Code executa um pequeno prompt de teste.
7. Os logs de uso do Flatkey mostram a requisição.

Obtenha uma chave para rotear o Claude Code através da Flatkey e, em seguida, use o CC Switch para manter o perfil do provider local fácil de alternar, inspecionar e reverter.