Tool Integrations29 de junho de 2026Flatkey

Configuração do Roteador da API Claude Code: URL Base, Modelos e Registros de Uso

A configuração de um roteador da API Claude Code não é o mesmo que alterar uma URL base do SDK da OpenAI. O Claude Code utiliza o formato do gateway Anthropic Messages, então as verificações importantes são a raiz do roteador, o cabeçalho de credenciais, o nome do modelo que o Claude Code enviará e os registros de uso que comprovam que as solicitações estão sendo recebidas.

Uma configuração de roteador da API Claude Code não é o mesmo que alterar uma URL base do SDK da OpenAI. O Claude Code utiliza o formato do gateway Anthropic Messages, então as verificações importantes são a raiz do roteador, o cabeçalho da credencial, o nome do modelo que o Claude Code enviará e os registros de uso que comprovam que as solicitações estão chegando à conta correta.

Este guia fornece uma configuração Flatkey orientada para produção para desenvolvedores, equipes de produtos de IA, criadores de automação, engenheiros de plataforma, operadores financeiros e revisores de aquisições. Ele aborda a URL base, a verificação prévia de um token, nomes de modelos, descoberta de modelos do gateway, registros de uso e modos de falha antes de você mover o trabalho de codificação diário para um roteador da API Claude Code.

Nota da fonte: isto foi verificado em 29 de junho de 2026 com base na documentação oficial dos gateways LLM do Claude Code, guia de conexão do gateway Claude Code, referência do protocolo do gateway, documentação de configuração de modelos, documentação de monitoramento e nas páginas públicas atuais da Flatkey. Nenhuma chave Flatkey específica de conta foi usada para um teste de fumaça ao vivo do Claude Code, então os trechos abaixo são modelos para executar com sua própria chave e modelo aprovado.

Resposta rápida: configuração do roteador da API Claude Code

Para uma configuração de roteador da API Claude Code com a Flatkey, configure o Claude Code com a raiz do roteador Claude Code da Flatkey, uma chave Flatkey e um nome de modelo Claude exato que sua conta pode chamar. Em seguida, teste o endpoint Anthropic Messages antes de iniciar uma longa sessão de codificação.

Campo de configuração	Valor ou verificação Flatkey	Por que é importante
URL Base	`https://router.flatkey.ai` para o caso de uso do Claude Code, a menos que sua conta Flatkey mostre um valor mais recente específico para o Claude Code	O Claude Code anexa `/v1/messages`. Não cole uma base do SDK da OpenAI terminando em `/v1`, a menos que seu teste confirme que isso não cria `/v1/v1/messages`.
Credencial	`ANTHROPIC_AUTH_TOKEN` para roteamento de token de portador (bearer-token), ou `ANTHROPIC_API_KEY` quando o gateway espera `x-api-key`	Os documentos oficiais do Claude Code mapeiam cada variável para um cabeçalho HTTP diferente. Uma chave funcional na variável errada ainda retorna `401`.
Verificação prévia do endpoint	`$ANTHROPIC_BASE_URL/v1/messages`	A página de preços atual da Flatkey lista `/v1/messages` no mapa de endpoints, que é o caminho que o Claude Code precisa para o tráfego do Anthropic Messages.
Modelo	Use um ID de modelo Claude exato ou um alias do Claude Code que resolva para uma rota Flatkey habilitada	A seleção do modelo é separada do roteamento da URL base. O roteador decide para onde o tráfego vai; o Claude Code ainda envia um nome de modelo.
Comprovação de uso	Verifique o uso da Flatkey e a telemetria do Claude Code após o primeiro prompt	Uma saída bem-sucedida não é suficiente. As equipes precisam de evidências de chave, modelo, carimbo de data/hora, sessão, custo e tokens.

Essa é a versão curta. O restante deste guia do roteador da API Claude Code transforma esses campos em um manual de configuração repetível.

O que os documentos oficiais do gateway Claude Code confirmam

A visão geral oficial do gateway Claude Code define um gateway LLM como um proxy entre o Claude Code e um provedor de modelo. O Claude Code envia o tráfego da API para o gateway, e o gateway o encaminha com uma credencial de provedor controlada pela organização. A mesma página lista os benefícios do gateway, como credenciais centralizadas, rastreamento de uso, controles de custo, registro de auditoria e troca de provedor.

A regra da URL base é específica. O Claude Code normalmente envia solicitações para a API da Anthropic, mas definir ANTHROPIC_BASE_URL aponta essas solicitações para o gateway. O guia de conexão então verifica a rota postando para $ANTHROPIC_BASE_URL/v1/messages com anthropic-version: 2023-06-01.

A referência do protocolo do gateway adiciona os detalhes do lado do operador. Para o formato Anthropic Messages, um gateway selecionado por ANTHROPIC_BASE_URL deve servir /v1/messages e, opcionalmente, /v1/messages/count_tokens. Ele também diz que as respostas de inferência devem ser transmitidas (stream), porque o Claude Code consome eventos enviados pelo servidor (server-sent events) à medida que chegam.

Para um roteador da API Claude Code, isso significa que você deve validar o caminho do Anthropic Messages, não apenas um caminho de conclusões de chat compatível com OpenAI. Uma rota OpenAI pode funcionar para outras ferramentas enquanto o Claude Code ainda falha se /v1/messages, a transmissão (streaming) ou os cabeçalhos Anthropic necessários estiverem ausentes.

Valores Flatkey verificados para esta configuração

A página inicial da Flatkey, verificada em 29 de junho de 2026, tem o título One API gateway for production AI teams e uma meta descrição dizendo que a Flatkey unifica o acesso a modelos, roteamento, faturamento, análise de uso e controles operacionais. A mesma página inicial ainda mostra exemplos no estilo OpenAI usando https://console.flatkey.ai/v1 e /v1/chat/completions, que são úteis para ferramentas compatíveis com OpenAI, mas não são o padrão de URL base do Claude Code.

A página atual de caso de uso do Flatkey Claude Code diz que o Claude Code é configurado com https://router.flatkey.ai e uma chave de API da Flatkey. Ela também informa aos usuários para criar ou copiar a chave em https://console.flatkey.ai/keys antes de executar o instalador. Use essa raiz do roteador específica do Claude Code para a configuração manual abaixo, a menos que sua conta Flatkey forneça um valor mais recente.

A página de preços da Flatkey, verificada em 29 de junho de 2026, publica preços renderizados no servidor para 635 modelos de IA de 23 provedores. Seu mapa de endpoints inclui /v1/messages, /v1/chat/completions, /v1/responses, /v1/images/generations, /v1/video/generations e /v1beta/models/{model}:generateContent. Este artigo trata isso como evidência pública datada da cobertura de endpoints, não como uma garantia de que toda conta pode chamar todos os modelos.

Configuração passo a passo com a Flatkey

Crie ou escolha uma chave Flatkey. Use uma chave pertencente à pessoa, equipe ou ambiente correto. Mantenha-a fora de capturas de tela, prompts, repositórios e comentários de issues.
Comece com exportações do shell. Não persista as configurações até que a verificação preliminar de um token funcione.
Use a raiz do roteador do Claude Code. Para a página atual do Flatkey Claude Code, esse valor é https://router.flatkey.ai.
Escolha a variável de credencial. Use ANTHROPIC_AUTH_TOKEN quando a chave deve ser enviada como Authorization: Bearer. Use ANTHROPIC_API_KEY somente quando o gateway esperar x-api-key.
Defina um modelo para o primeiro teste. Use um ID de modelo Claude atual habilitado para sua conta Flatkey. Se o modelo não estiver visível no seletor do Claude Code, use a descoberta do gateway ou adicione uma opção de modelo personalizado após a verificação preliminar funcionar.
Execute a verificação preliminar com curl. Uma solicitação de um token separa o roteamento da Flatkey do estado da interface do usuário do Claude Code.
Inicie o Claude Code a partir do mesmo shell. Isso faz com que a CLI herde as variáveis que você acabou de testar.
Execute /status. Confirme se a linha da URL base da Anthropic mostra o roteador da Flatkey e se a linha da credencial nomeia a variável que você definiu.
Envie um prompt pequeno. Em seguida, verifique o uso da Flatkey e qualquer telemetria do Claude Code que você tenha habilitado.

Configuração do shell

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_AUTH_TOKEN="fk_replace_with_your_flatkey_key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"

Se as instruções do seu gateway disserem explicitamente x-api-key, troque ANTHROPIC_AUTH_TOKEN por ANTHROPIC_API_KEY e atualize o cabeçalho da verificação preliminar. Não defina ambos para o primeiro teste; fontes de credenciais mistas tornam as falhas mais difíceis de isolar.

Configurações persistentes após o teste passar

Depois que o teste do shell funcionar, você pode colocar as mesmas variáveis no bloco env de ~/.claude/settings.json. Não coloque credenciais em um arquivo .claude/settings.json de projeto comitado.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
    "ANTHROPIC_AUTH_TOKEN": "fk_replace_with_your_flatkey_key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

Faça uma verificação preliminar da rota Messages antes de iniciar o Claude Code

A verificação mais rápida do roteador da API Claude Code é uma solicitação Messages de um token. Se isso falhar, corrija a chave Flatkey, a URL base, o caminho de rede ou o modelo antes de alterar as configurações do Claude Code.

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1,
    "messages": [
      {"role": "user", "content": "."}
    ]
  }'

Uma resposta JSON que começa com um ID de mensagem e inclui um campo de conteúdo significa que a rota e a credencial estão funcionando. A documentação oficial também observa que um erro de modelo desconhecido ainda prova que o gateway autenticou a solicitação antes de rejeitar o nome do modelo. Um 401 significa que a credencial foi rejeitada ou enviada no cabeçalho errado.

Observe a URL resolvida com atenção. Com ANTHROPIC_BASE_URL=https://router.flatkey.ai, o teste alcança https://router.flatkey.ai/v1/messages. Se o seu comando criar /v1/v1/messages, você copiou uma URL base do SDK do cliente em um campo de gateway do Claude Code.

Nomes de modelos: aliases, descoberta e entradas personalizadas

Nomes de modelos são a segunda fonte comum de falhas do roteador da API Claude Code. A URL base envia o tráfego para a Flatkey, mas o Claude Code ainda precisa de um valor de modelo para enviar na solicitação.

A documentação de configuração de modelos diz que o Claude Code suporta configurações de modelos integradas como default, best, sonnet, opus, haiku e variantes de contexto longo como sonnet[1m] e opus[1m]. A mesma documentação diz que ANTHROPIC_MODEL se aplica apenas à sessão que você inicia com ele, enquanto /model pode salvar uma escolha interativa para sessões posteriores.

Para uma rota Flatkey, a regra segura é começar com um ID de modelo Claude completo que a Flatkey tenha habilitado para sua chave e, em seguida, decidir se deve expô-lo no seletor. Não presuma que um nome de família genérico, um rótulo de marketing ou o título de uma linha de provedor seja aceito como o ID do modelo da solicitação.

Necessidade de configuração do modelo	Mecanismo do Claude Code	Verificação do Flatkey
Teste de sessão única	`ANTHROPIC_MODEL` ou `claude --model`	Use um ID de modelo Claude habilitado para Flatkey e mantenha o teste pequeno.
Seleção interativa	`/model`	Confirme se o nome selecionado é o ID real que o Flatkey espera.
Lista de modelos fornecida pelo gateway	`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`	O gateway deve servir `/v1/models` rapidamente na URL base configurada.
Entrada manual no seletor	`ANTHROPIC_CUSTOM_MODEL_OPTION`	Use isso quando a descoberta estiver desabilitada ou não retornar o modelo que você precisa.
Fallback de disponibilidade	`--fallback-model` ou `fallbackModel`	O fallback não corrige erros de autenticação, faturamento, limite de taxa, tamanho da solicitação ou transporte.

Descoberta de modelos do gateway

O Claude Code pode consultar o endpoint /v1/models de um gateway na inicialização quando ANTHROPIC_BASE_URL aponta para um gateway Anthropic Messages e a descoberta está habilitada. A documentação do protocolo diz que a solicitação é GET /v1/models?limit=1000 com um tempo limite de 3 segundos, e o Claude Code lê o id mais o display_name opcional da resposta.

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude --debug

A descoberta está desativada por padrão para que uma chave compartilhada não exponha todos os modelos acessíveis a todos os usuários. Se a descoberta falhar, o Claude Code recorre ao seletor em cache ou integrado. Se sua conta Flatkey servir um modelo sob um alias que a descoberta não mostra, adicione uma opção personalizada.

Opção de modelo personalizado

export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-sonnet-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet via Flatkey"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Claude model routed through the Flatkey API router"

A opção de modelo personalizado ignora a validação do lado do cliente para esse ID de modelo, sendo útil para um piloto controlado. Não é um substituto para a solicitação de preflight. Se uma lista de permissões da organização estiver ativa, inclua o ID do modelo personalizado lá também.

Registros de uso: o que verificar após o primeiro prompt

Uma configuração confiável do roteador da API Claude Code termina com evidências de uso, não apenas com uma resposta bem-sucedida. O posicionamento público do Flatkey diz que ele unifica faturamento, análise de uso e controles operacionais; a documentação do gateway Claude Code também enquadra o rastreamento de uso e os controles de custo como benefícios do gateway. Use ambas as camadas intencionalmente.

Fonte do registro	O que inspecionar	Por que é importante
Uso do Flatkey	Proprietário da chave, carimbo de data/hora, modelo, família de endpoints, uso de tokens e registro de custo, quando disponível	Confirma que a solicitação chegou à conta do gateway pretendida e pode ser reconciliada por operações ou finanças.
Claude Code `/status`	URL base da Anthropic e fonte de credencial ativa	Confirma que a sessão em execução está usando a rota do Flatkey em vez de um login salvo do claude.ai.
Métricas do OpenTelemetry	`claude_code.cost.usage`, `claude_code.token.usage`, contagem de sessões, tempo ativo e ponto de entrada	Cria observabilidade no nível da equipe para as sessões do Claude Code.
Registros/eventos do OpenTelemetry	Eventos de prompt, resultados de ferramentas, erros de API e campos de custo quando configurados	Ajuda a depurar falhas no nível da solicitação, mas deve ser controlado porque registros detalhados podem expor conteúdo sensível.
Cabeçalhos do gateway	`x-claude-code-session-id`, IDs de agente e cabeçalhos de roteamento personalizados	Permite o agrupamento de solicitações por sessão ou subagente sem analisar os corpos completos das solicitações.

Para a telemetria do Claude Code, habilite o OpenTelemetry apenas com uma configuração de privacidade deliberada. A documentação de monitoramento diz que o texto do prompt é redigido por padrão, enquanto configurações como OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 e OTEL_LOG_RAW_API_BODIES adicionam detalhes sensíveis. Mantenha o registro do corpo bruto fora da configuração padrão do desenvolvedor, a menos que sua revisão de segurança o aprove.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Use OTEL_RESOURCE_ATTRIBUTES para campos de propriedade de baixa cardinalidade, como departamento, ID da equipe ou centro de custo. Evite nomes de projetos ou IDs de tickets inseridos pelo usuário como rótulos, a menos que seu backend de observabilidade possa lidar com a cardinalidade e o impacto na privacidade.

Modos de falha para depurar primeiro

Sintoma	Causa provável	Primeira correção
`401` ou token inválido	A chave foi rejeitada, expirou, foi copiada para a variável errada ou enviada em um cabeçalho que o gateway não lê.	Alterne entre `ANTHROPIC_AUTH_TOKEN` e `ANTHROPIC_API_KEY` somente após confirmar qual cabeçalho o Flatkey espera.
Conexão recusada ou tempo limite esgotado	URL base incorreta, caminho de rede bloqueado, problema de VPN ou um endpoint do roteador que não está acessível a partir da máquina do desenvolvedor.	Execute a verificação prévia com curl e verifique a URL com as instruções da sua conta Flatkey.
Resposta malformada com HTTP 200	Um proxy ou página de login retornou HTML em vez de JSON da API.	Inspecione o corpo da resposta da verificação prévia e corrija a rota do gateway que retorna algo diferente de JSON.
`400` nomeando `context_management` ou campos extras	O gateway encaminhou campos de solicitação no formato Anthropic para um upstream que os rejeita.	Encaminhe o par cabeçalho/corpo beta corretamente ou defina `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` como uma mitigação temporária.
`400` nomeando `thinking` ou `adaptive`	A compilação do modelo upstream não aceita o raciocínio adaptativo solicitado para modelos Claude mais recentes.	Atualize a rota upstream ou use a flag de desativação de pensamento adaptativo documentada apenas onde for aplicável.
Modelo ausente em `/model`	O modelo não está no seletor integrado do Claude Code e a descoberta está desativada ou falhando.	Ative a descoberta de modelos do gateway ou adicione `ANTHROPIC_CUSTOM_MODEL_OPTION`.
O Claude Code solicita login após o sucesso do curl	A CLI não recebeu uma credencial onde a configuração de primeira execução possa lê-la.	Defina a credencial no shell, em `~/.claude/settings.json`, ou em configurações gerenciadas antes da inicialização.
O uso não pode ser reconciliado	A configuração não possui proprietário da chave, nome do modelo, ambiente, ID da sessão ou rótulos de telemetria.	Adicione uma linha ao runbook antes que mais desenvolvedores usem a rota.

Lista de verificação de produção para equipes

Antes de padronizar um roteador da API Claude Code em uma equipe, registre os fatos operacionais que um futuro incidente ou revisão financeira precisará.

Item da lista de verificação	Registre isto
URL Base	O valor exato salvo no shell, configurações gerenciadas, configurações do VS Code, CI ou configuração do SDK do Agente.
Origem da credencial	Proprietário da chave Flatkey, ambiente, proprietário da rotação e se é estática ou vem de um `apiKeyHelper`.
Nomes dos modelos	ID do modelo solicitado, rótulo do seletor, cadeia de fallback, regra da lista de permissões e data do teste.
Prova do endpoint	Resultado de um token de `/v1/messages`, carimbo de data/hora da solicitação e qualquer ID de solicitação retornado pelo gateway.
Revisão de uso	Visualização de uso do Flatkey, backend de telemetria do Claude Code, rótulos e proprietário do painel.
Portões de privacidade	Se prompts, detalhes de ferramentas, corpos brutos da API ou conteúdo de ferramentas são permitidos na telemetria.
Reversão	Login anterior do Claude Code ou caminho do provedor, modelo anterior e quem pode desdefinir as variáveis do gateway.

Caminho de migração interna

Se o Flatkey está se tornando a rota compartilhada para várias ferramentas de desenvolvedor, mantenha a configuração do Claude Code alinhada com o restante do cluster de integração. Use o guia de migração da API compatível com OpenAI para padrões de URL base de SDK, mas lembre-se de que o Claude Code usa a rota Anthropic Messages em vez de /v1/chat/completions.

Para configuração de cliente de desktop, compare o guia de configuração da API do Cherry Studio. Para padrões de roteamento de máquina de desenvolvedor adjacentes ao Claude Code, consulte a configuração cc-switch do Claude Code. Depois que o primeiro prompt funcionar, revise os preços dos modelos Flatkey e, em seguida, Obtenha uma chave para qualquer ambiente adicional que precise de um limite de credencial separado.

FAQ

Qual URL Base devo usar para um roteador da API Claude Code com o Flatkey?

Use a raiz do roteador Flatkey específica do Claude Code mostrada para sua conta. Em 29 de junho de 2026, a página de caso de uso do Claude Code do Flatkey informava que o Claude Code é configurado com https://router.flatkey.ai. A verificação prévia deve alcançar exatamente um caminho /v1/messages.

Devo usar `ANTHROPIC_AUTH_TOKEN` ou `ANTHROPIC_API_KEY`?

Use ANTHROPIC_AUTH_TOKEN quando o gateway espera um token bearer no cabeçalho Authorization. Use ANTHROPIC_API_KEY quando ele espera x-api-key. Se você tentou adivinhar e recebeu um 401, troque as variáveis e teste novamente.

Posso usar uma URL base do Flatkey compatível com OpenAI para o Claude Code?

Não diretamente como um campo copiado. Ferramentas compatíveis com OpenAI geralmente usam uma URL base terminada em /v1, enquanto o Claude Code anexa /v1/messages a ANTHROPIC_BASE_URL. Use o valor do roteador Claude Code do Flatkey e verifique a URL final.

Como adiciono modelos do Flatkey ao seletor de modelos do Claude Code?

Habilite CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 quando o gateway servir /v1/models, ou adicione uma linha de seletor manual com ANTHROPIC_CUSTOM_MODEL_OPTION. Em ambos os casos, confirme se o ID exato do modelo está habilitado para sua chave Flatkey.

Quais registros de uso devo verificar após a configuração?

Verifique o uso do Flatkey para a chave, modelo, família de endpoint, carimbo de data/hora, tokens e custo, quando disponíveis. Use também o /status do Claude Code e as métricas do OpenTelemetry, como claude_code.cost.usage e claude_code.token.usage, quando a telemetria da organização estiver habilitada.

Conclusão

Uma configuração confiável do roteador da API Claude Code tem quatro pontos de comprovação: a URL base do Claude Code do Flatkey, o cabeçalho de credencial correto, um nome de modelo testado e um rastro de uso que as equipes de finanças e plataforma possam revisar. Comece com uma verificação preliminar de um token em /v1/messages, confirme o /status e, em seguida, dimensione a rota somente após os registros e a reversão estarem documentados. Quando estiver pronto para rotear o Claude Code por meio de um gateway compartilhado, obtenha uma chave e teste primeiro o menor prompt.