Como conectar qualquer modelo ao Claude Code: Gemini, GPT e Grok

O resumo direto

Conectar outro modelo ao Claude Code é manter o harness (interface, ferramentas, skills, hooks e MCP) e trocar só o cérebro que responde, apontando o endpoint da API para um roteador que traduz a chamada. O Claude Code fala um único protocolo, o da API Anthropic, mas aceita outro endereço pela variável ANTHROPIC_BASE_URL. Um roteador de código aberto como o 9router escuta nesse endereço, converte o pedido para Gemini, GPT/Codex, Grok e outros provedores e devolve a resposta no formato que o Claude Code espera. O harness fica, só o modelo muda. Vale para quem já vive no terminal e quer usar um modelo mais barato em leitura de código, ou uma segunda opinião de outro fornecedor, sem reaprender ferramenta. Não é caminho suportado pela Anthropic, e parte dos recursos do CLI deixa de valer quando o modelo do outro lado não é Claude.

1. Harness e modelo são coisas diferentes

Quem usa o Claude Code no dia a dia costuma chamar tudo de "o Claude". Na prática são duas camadas. O harness é o programa no terminal: lê e edita arquivo, roda comando, carrega skills, dispara hooks, conversa com servidores MCP e guarda o histórico da sessão. O modelo é quem decide o que fazer com isso tudo, a cada turno, do outro lado da rede.

O harness não sabe quem está respondendo. Ele monta um pedido no formato Anthropic Messages, manda para um endereço e espera eventos de streaming de volta. A doc oficial descreve que, com ANTHROPIC_BASE_URL apontado para um gateway, o Claude Code "treats the gateway as the Claude API and can't tell which upstream you forward to". É essa cegueira que permite a troca.

Por isso o seu investimento em configuração continua valendo. As regras do projeto, os servidores MCP que você já ligou (se ainda não ligou nenhum, o guia de MCP no Claude Code e no Cursor cobre o básico) e os hooks de validação seguem iguais. Só muda a qualidade, o custo e o estilo de quem pensa.

Um aviso sobre o "qualquer" do título: aqui ele quer dizer qualquer provedor que o roteador suporta. O README do 9router lista mais de 40 provedores por chave de API, entre eles OpenAI, Anthropic, Gemini e xAI. Fora dessa lista, não há tradução, e não há mágica.

2. Como o roteador entra no meio

O fluxo tem três peças:

1. O Claude Code manda o pedido para o endereço definido em ANTHROPIC_BASE_URL, no caminho /v1/messages, como a doc de compatibilidade descreve.
2. O roteador recebe, lê o ID do modelo pedido, escolhe o provedor e converte o corpo para o formato dele (Gemini, OpenAI, xAI).
3. A resposta volta convertida para eventos no padrão Anthropic, e o Claude Code segue o turno como se nada tivesse mudado.

O 9router faz isso localmente, na sua máquina ou numa VPS, com painel web para cadastrar provedores e gerar a chave que o Claude Code vai usar. Segundo o README, o projeto é MIT, não cobra nada e você paga direto a cada provedor. O valor que o painel mostra como custo é estimativa de comparação, não fatura.

Existe uma alternativa que não envolve roteador: a própria Anthropic oferece o Claude por Amazon Bedrock, Google Cloud Agent Platform e Microsoft Foundry. Esses são os backends oficiais. Só que todos servem modelos Claude. Se o objetivo é rodar Gemini ou Grok dentro do harness, o roteador é a única peça que resolve, e você assume a manutenção dela.

3. Instalar o 9router

O README oferece dois caminhos. Pelo npm, com Node.js 20 ou mais novo:

npm install -g 9router
9router

Pelo Docker, com os dados persistidos numa pasta da sua home:

docker run -d --name 9router -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data decolua/9router:latest

Nos dois casos o painel abre em http://localhost:20128/dashboard. A porta padrão é 20128. Se for rodar numa VPS, não exponha essa porta para a internet: deixe o roteador escutando só em localhost e acesse o painel por túnel SSH. Quem tem a chave do roteador gasta o crédito de todos os provedores cadastrados nele.

Antes de seguir, confira duas coisas no painel: que ele abriu sem erro e que existe a opção de gerar uma chave de acesso do próprio 9router. É essa chave, e não a do Gemini ou da xAI, que vai para o Claude Code.

4. Cadastrar os provedores

No painel, cada provedor entra com a credencial dele. O caminho seguro em todos é chave de API com cobrança por uso.

• Gemini: gere a chave da Gemini API no console do Google e cole no provedor Gemini do 9router. A tabela de preços oficial tem nível gratuito e nível pago; para trabalho de cliente, use o pago.
• Grok: entra por chave da API da xAI, cobrada por token. Sem chave da xAI não há Grok no roteador.
• Codex e GPT: a doc do Codex descreve dois logins, "Sign in with ChatGPT for subscription access" e chave de API, que a OpenAI cobra "at standard API rates". Use a chave de API.

Por que não usar a assinatura de consumidor

O README do 9router oferece login por OAuth em assinaturas (ChatGPT/Codex, Claude Code e outras). Tecnicamente funciona. Contratualmente é outra conversa. Os termos adicionais do Google Antigravity dizem com todas as letras: "Using third party software, tools, or services to access the Service (e.g. using OpenClaw with Antigravity OAuth) is a breach of this Agreement", e preveem suspensão ou encerramento das contas Antigravity e Gemini CLI. Do lado da OpenAI, a doc de autenticação do Codex lista onde o login do ChatGPT é suportado: o app desktop, o Codex CLI e a extensão de IDE. Roteador de terceiro não está na lista.

Resumo prático: assinatura de consumidor plugada num roteador pode ferir os termos do provedor e custar a conta. Chave de API paga por uso é o caminho sem dúvida, e a conta fica previsível porque cada token tem preço publicado.

5. Apontar o Claude Code com um lançador isolado

Não mexa no seu Claude Code principal. Crie um lançador que sobe uma instância separada, com diretório de configuração próprio. A doc oficial descreve CLAUDE_CONFIG_DIR exatamente para isso: troca o diretório padrão ~/.claude e é "Useful for running multiple accounts side by side". Login, settings, histórico e plugins ficam separados, e um não contamina o outro.

Salve como ~/bin/claude-roteado e dê permissão de execução:

#!/usr/bin/env bash
export CLAUDE_CONFIG_DIR="$HOME/.claude-roteado"
export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="$(cat "$HOME/.config/9router.key")"
exec claude "$@"

Três detalhes desse arquivo:

• ANTHROPIC_BASE_URL vai na raiz da porta. O Claude Code acrescenta /v1/messages sozinho, como mostra a doc de compatibilidade. O README do 9router cita o endpoint /v1 num exemplo de config.json; se o seu pedido cair em caminho duplicado, ajuste aqui.
• ANTHROPIC_AUTH_TOKEN leva a chave gerada no painel do 9router, enviada no cabeçalho Authorization com prefixo Bearer. A chave fica num arquivo legível só pelo seu usuário, nunca escrita no script nem versionada.
• Assinatura fora do caminho. A doc oficial explica que, com credencial de gateway ativa, os pedidos não usam o login claude.ai e os limites do plano não se aplicam: a cobrança é de quem é dono da credencial que o gateway repassa. No seu caso, de cada provedor cadastrado.

Se você mantém regras do projeto para mais de um agente, o artigo sobre Rulesync com uma fonte de regras para Claude Code, Codex e Cursor mostra como não duplicar instrução. Aqui o problema é outro: o mesmo CLAUDE.md passa a ser lido por modelos diferentes, e nem todos seguem regra longa com a mesma disciplina.

6. Escolher o modelo por variável ou por alias

O ID do modelo é o que o roteador usa para decidir o provedor. O README mostra o formato com prefixo, como cx/ para Codex. Copie o ID exato da lista de modelos do painel; não invente nome.

Para uma sessão inteira num modelo só, passe o ID na largada. A doc de configuração de modelo lista a ordem: /model dentro da sessão, --model na largada, ANTHROPIC_MODEL e o campo model das settings.

claude-roteado --model "<id-copiado-do-painel>"

O jeito mais confortável é remapear os aliases. As variáveis ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_HAIKU_MODEL dizem para onde apontam opus, sonnet e haiku. Acrescente ao lançador:

export ANTHROPIC_DEFAULT_OPUS_MODEL="<id-claude-no-painel>"
export ANTHROPIC_DEFAULT_SONNET_MODEL="<id-codex-no-painel>"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="<id-gemini-flash-no-painel>"

Com isso, o comando /model sonnet passa a chamar o Codex e /model haiku chama o Gemini Flash. O alias haiku também é o modelo das tarefas de fundo, segundo a doc, então título de sessão e resumo interno vão para o modelo mais barato. Para os subagentes, CLAUDE_CODE_SUBAGENT_MODEL define o padrão: a sessão principal pensa num modelo e os subagentes de busca rodam em outro.

Um detalhe do seletor: a descoberta automática de modelos do gateway só mantém IDs que contêm "claude" ou "anthropic". ID de Gemini ou Grok não aparece sozinho em /model. Para pôr um deles no menu, use ANTHROPIC_CUSTOM_MODEL_OPTION com o ID e ANTHROPIC_CUSTOM_MODEL_OPTION_NAME com um nome legível.

7. Quando cada modelo compensa

A divisão que faz sentido é por tipo de trabalho, não por fidelidade a marca:

• Gemini Flash para leitura barata. Varrer um repositório, resumir um módulo, achar onde uma função é chamada, explicar um log longo. É trabalho de muito token de entrada e pouca decisão, e o preço de entrada do Flash é o menor da tabela abaixo.
• Codex para script e segunda opinião. Um script de migração, um teste que falta, ou revisar um diff que o Claude escreveu. Outro fornecedor erra diferente, e isso pega bug que o mesmo modelo deixaria passar.
• Grok como alternativa de raciocínio geral, quando você quer comparar resposta em problema aberto.
• Claude para escrita e refatoração pesada. Mudança em muitos arquivos, refatoração com teste, trabalho longo com ferramenta. O harness foi desenhado em volta dele, e é o único caso em que effort, thinking adaptativo e cache funcionam como a doc descreve.

Preço por 1 milhão de tokens, conforme as páginas oficiais lidas em 07/10/2026:

A própria página do Google já anuncia reajuste do Flash a partir de 1º de janeiro de 2027. Confira a página de preço de cada fornecedor antes de fechar orçamento; tabela de artigo envelhece rápido.

8. Os limites reais

O primeiro limite é de suporte. A doc oficial é direta: a Anthropic "doesn't endorse, maintain, or audit third-party gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway". Se quebrar, o problema é seu e do projeto do roteador.

Depois, o que muda no comportamento, segundo o guia de compatibilidade e a página de variáveis de ambiente:

• Effort e thinking não valem para outro vendor. Os níveis de effort só são listados para modelos Claude. Para um ID que não reconhece, o Claude Code manda raciocínio adaptativo e effort mesmo assim, e o upstream pode rejeitar. Quando rejeita o effort, o CLI repete o pedido sem ele. Na prática, /effort vira enfeite.
• Cache de prompt depende do roteador. Se o cache_control não chega intacto, não há erro: cada turno é cobrado como entrada sem cache. Acompanhe o consumo no painel do provedor nos primeiros dias.
• Janela de contexto presumida. Para ID desconhecido, o Claude Code assume 200K tokens. Se o modelo tiver janela diferente, informe com CLAUDE_CODE_MAX_CONTEXT_TOKENS, ou a compactação acontece na hora errada.
• Recursos desligados. Com ANTHROPIC_BASE_URL fora da Anthropic, a busca de ferramentas MCP fica desligada por padrão e o Remote Control fica desativado desde a v2.1.196. Com muitos servidores MCP, todas as ferramentas carregam de uma vez e o contexto enche mais rápido.
• Recursos que dependem do modelo oficial. O classificador do modo automático de permissão, o fast mode (cuja checagem vai direto a api.anthropic.com) e o uso de ferramentas em sequência longa foram pensados para Claude. Com outro modelo, podem falhar ou se comportar diferente. Use permissão manual na instância roteada.
• Seguir instrução é desigual. Hooks e skills continuam rodando, mas a decisão de chamar a skill certa, respeitar o CLAUDE.md e parar na hora certa é do modelo. Comece com tarefas pequenas e revisáveis.

Por fim, os termos de uso, já tratados na seção 4. Roteador com chave de API paga por uso fica dentro do contrato de cada provedor. Roteador com login de assinatura de consumidor pode não ficar.

Prompt pronto para o seu agente

Cole o texto abaixo no Claude Code que você já usa. Ele instala o 9router, cria o lançador isolado deste artigo sem tocar na sua instalação principal e para nos passos que são seus, como cadastrar a chave de cada provedor no painel. Troque os campos entre < > ou responda quando ele perguntar.

Você vai ligar outros modelos ao Claude Code por um roteador local, seguindo este roteiro na ordem.
Dados meus: forma de instalação <MODO> (npm ou docker); provedores <PROVEDORES> (gemini, xai,
openai); IDs copiados da lista de modelos do painel: <ID_OPUS>, <ID_SONNET>, <ID_HAIKU>.

Regras:
- Nunca imprima, leia em voz alta, cole no chat ou grave em script a chave do 9router ou de
  qualquer provedor. A chave do roteador mora só em ~/.config/9router.key, legível só por mim.
- Use chave de API paga por uso. Não ligue login OAuth de assinatura de consumidor no roteador.
- Não mexa em ~/.claude nem no comando claude principal. Mostre cada comando antes de rodar.

1. Pré-requisitos: claude --version. Para npm, node -v precisa ser 20 ou mais novo; para
   docker, confira docker --version.
2. Instalação npm: npm install -g 9router e depois 9router.
   Instalação docker: docker run -d --name 9router -p 20128:20128
   -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data decolua/9router:latest
3. Rede: se for uma VPS, não exponha a porta 20128 na internet; deixe só em localhost e me
   explique como abrir o painel por túnel SSH.
4. Painel: me peça para abrir http://localhost:20128/dashboard, cadastrar cada provedor com a
   chave de API dele e gerar a chave de acesso do próprio 9router.
5. Chave do roteador: crie ~/.config/9router.key vazio com permissão 600 e me peça para colar
   a chave nele pelo editor. Confira só que o arquivo não está vazio (test -s), sem ler o conteúdo.
6. Lançador: crie ~/bin/claude-roteado, com permissão de execução, com estas linhas:
   #!/usr/bin/env bash
   export CLAUDE_CONFIG_DIR="$HOME/.claude-roteado"
   export ANTHROPIC_BASE_URL="http://localhost:20128"
   export ANTHROPIC_AUTH_TOKEN="$(cat "$HOME/.config/9router.key")"
   export ANTHROPIC_DEFAULT_OPUS_MODEL="<ID_OPUS>"
   export ANTHROPIC_DEFAULT_SONNET_MODEL="<ID_SONNET>"
   export ANTHROPIC_DEFAULT_HAIKU_MODEL="<ID_HAIKU>"
   exec claude "$@"
   Se o pedido cair em caminho /v1 duplicado, ajuste a ANTHROPIC_BASE_URL.
7. Ajustes: se um modelo tem janela diferente de 200K, acrescente CLAUDE_CODE_MAX_CONTEXT_TOKENS.
   Para um ID sem "claude" no nome aparecer no /model, use ANTHROPIC_CUSTOM_MODEL_OPTION e
   ANTHROPIC_CUSTOM_MODEL_OPTION_NAME.
8. Me lembre: na instância roteada, permissão manual; effort, fast mode e Remote Control não
   valem lá; acompanhe o consumo no painel de cada provedor nos primeiros dias.

Validação final: me peça para rodar claude-roteado --model "<ID_SONNET>" e mandar uma pergunta
curta. Confirme comigo que a resposta veio, que o pedido aparece no painel do 9router e que
/model sonnet e /model haiku apontam para os IDs que escolhi. Depois rode ls ~/.claude-roteado
para provar que a configuração ficou separada e claude --version no comando principal.
Só diga que terminou quando os três pontos estiverem confirmados.

Perguntas frequentes

Dá para usar o Claude Code com Gemini?

Dá, por um roteador que traduza o formato Anthropic Messages para a Gemini API, como o 9router. O Claude Code aponta para o roteador por ANTHROPIC_BASE_URL, e o roteador chama o Gemini com a sua chave de API. A Anthropic não dá suporte a essa configuração.

O que é ANTHROPIC_BASE_URL?

É a variável de ambiente que troca o endpoint da API usado pelo Claude Code. A doc oficial descreve o uso para rotear pedidos por proxy ou gateway. Sem uma credencial do gateway junto, um login claude.ai salvo continua sendo a credencial ativa.

Preciso pagar a API do Gemini, da OpenAI e da xAI?

Sim, se seguir o caminho seguro. O 9router é software livre e não cobra; você paga cada provedor pelo que consumir. O Gemini tem nível gratuito na página de preços, mas para código de cliente o nível pago é o indicado.

Posso usar minha assinatura do ChatGPT ou do Gemini no roteador?

O roteador aceita, mas o contrato do provedor pode não aceitar. Os termos do Google Antigravity chamam de violação o acesso por software de terceiro com o OAuth deles, com risco de suspensão. A OpenAI documenta o login do ChatGPT para os próprios clientes do Codex. Use chave de API.

O effort e o thinking continuam funcionando com outro modelo?

Não como no Claude. A doc lista níveis de effort só para modelos Claude, e o upstream de outro fornecedor pode rejeitar esses campos. O Claude Code tenta de novo sem effort quando recebe a rejeição.

Isso estraga a minha instalação principal do Claude Code?

Não, se você usar um lançador com CLAUDE_CONFIG_DIR próprio. Login, settings, histórico e plugins ficam em outro diretório, e a instância principal continua falando direto com a Anthropic.

Conclusão

O Claude Code vale pelo harness, e o harness não sabe quem responde. Com ANTHROPIC_BASE_URL, um roteador como o 9router e um lançador isolado, Gemini, Codex e Grok entram no mesmo fluxo de skills, hooks e MCP. O preço é assumir a manutenção do roteador, perder effort, a certeza de cache e alguns recursos, e ficar dentro dos termos usando chave de API. Se o que você precisa é o agente lendo o seu ERP, a sua loja ou o seu banco, isso é integração sob medida (MCP, webhook, fila) com agentes de IA e automação no terminal. Descreve o sistema e o que quer automatizar em oailton.dev/contato.