Claude Code CLI — Configuration with OmniRoute (Português (Brasil))

Início rápido

# Inicie o Claude Code com um OmniRoute local (detecta automaticamente o contexto ativo)
omniroute launch

# Com um OmniRoute remoto (após `omniroute connect <host>`, isso é automático)
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Gere perfis por modelo e, em seguida, inicie um deles
omniroute setup-claude            # grava ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # Claude Code usando glm/glm-5.2 via OmniRoute

---

Como o Claude Code se conecta a um gateway

O Claude Code se comunica com a Anthropic Messages API e é direcionado para um endpoint personalizado por meio de variáveis de ambiente (ele não possui a opção --base-url):

Variável	Finalidade
ANTHROPIC_BASE_URL	URL raiz do gateway (o Claude Code acrescenta /v1/messages). Sem o sufixo /v1.
ANTHROPIC_AUTH_TOKEN	Enviado como Authorization: Bearer … — use seu token de acesso/chave de API do OmniRoute
ANTHROPIC_API_KEY	Alternativa: enviado como x-api-key. Se ambos estiverem definidos, ANTHROPIC_AUTH_TOKEN prevalece
ANTHROPIC_MODEL	Força um modelo específico (substitui o padrão do seletor /model)
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY	1 → o seletor nativo /model lista modelos claude*/anthropic* de /v1/models
CLAUDE_CODE_MAX_OUTPUT_TOKENS	Limita os tokens de saída por resposta (por exemplo, 65536)
CLAUDE_CODE_AUTO_COMPACT_WINDOW	Limite de tokens para compactação automática

As variáveis de ambiente são lidas uma única vez na inicialização — reinicie o Claude Code após alterá-las.

omniroute launch define tudo isso para você: ele resolve a URL base + o token a partir do contexto ativo (portanto, basta executar omniroute connect <vps> e depois omniroute launch), verifica a integridade do servidor e executa claude.

---

Aliases de descoberta — exiba modelos que não são Claude no seletor /model

A descoberta de modelos do gateway do Claude Code lista apenas IDs que começam com claude ou anthropic; portanto, com CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, o seletor nativo /model normalmente mostra apenas os modelos Claude/Anthropic do OmniRoute — um kimi/kimi-k2.6 ou glm/glm-5.2 nunca aparece, embora o roteamento funcione normalmente.

O OmniRoute pode espelhar qualquer modelo habilitado (e combinação) sob um ID claude/… para que ele passe por esse filtro e apareça no seletor:

kimi/kimi-k2.6            →  claude/kimi/kimi-k2.6      "Kimi K2.6 (OmniRoute)"
glm/glm-5.2              →  claude/glm/glm-5.2         "GLM 5.2 (OmniRoute)"
<combo "custo-otimizado"> →  claude/combo/custo-otimizado

Quando você seleciona um deles no Claude Code, o OmniRoute remove o prefixo claude/ e restaura o ID real antes do roteamento — um ID claude/<real-claude-model> genuíno (o provedor OAuth real do Claude) é sempre mantido intacto.

Isso fica desativado por padrão e é controlado por uma hierarquia de três níveis (o mais específico prevalece), para que uma instalação comum do OmniRoute nunca duplique seu catálogo para clientes que não usam o Claude Code:

Nível	Onde
Modelo	Página de detalhes do provedor → opção “Expor no Claude Code” por modelo
Provedor	Página de detalhes do provedor → opção no nível do provedor (abrange todos os seus modelos)
Global	Configurações → Sinalizadores de recursos → EXPOSE_CC_DISCOVERY_ALIASES (desativado por padrão)

A variável de ambiente EXPOSE_CC_DISCOVERY_ALIASES força a ativação do nível global e tem precedência sobre a configuração do painel (a tela de Sinalizadores de recursos mostra uma observação “ativo via variável de ambiente” quando isso ocorre). As opções por provedor e por modelo refinam essa configuração — por exemplo, global desativado + provedor Kimi ativado expõe apenas os modelos da Kimi.

⚠️ Divergência de janela em modelos que não são Claude. O Claude Code presume uma janela de contexto de 200K para qualquer ID que não reconheça (ele não consegue ler a janela real em /v1/models). Para um modelo com uma janela maior (por exemplo, os 256K do Kimi K2), defina CLAUDE_CODE_AUTO_COMPACT_WINDOW com um valor abaixo da janela real do modelo para que a compactação automática não seja acionada prematuramente. Os perfis gerados acima já fazem isso para cada modelo.

---

Bloco de integração no painel

O cartão da ferramenta Claude (Painel → Código da CLI) renderiza o fragmento exato de settings.json para esta instância, ao lado do botão de informações do alias de descoberta, com um botão para copiar:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<seu OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<sua chave de API do OmniRoute>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}

A URL base é a resolvida pelo cartão (incluindo uma substituição personalizada que você digitou), já normalizada — sem o sufixo /v1 e sem barra final. A chave nunca é renderizada: o bloco inclui um placeholder, portanto uma captura de tela ou um trecho colado não pode expô-la. Substitua-o pela sua chave.

Adicione CLAUDE_CODE_AUTO_COMPACT_WINDOW no mesmo bloco env para qualquer modelo cuja janela de contexto real não seja de 200K — o Claude Code presume 200K para todo id que não reconhece, portanto a compactação automática seria acionada no ponto errado (consulte o aviso na seção anterior). O gerador de trechos também aceita esse valor, portanto um chamador que conheça a janela do modelo de destino pode emiti-lo diretamente.

Fonte: src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet (gerador puro, testado com testes unitários) renderizado por ClaudeGatewayOnboardingBlock.

---

Perfis (CLAUDE_CONFIG_DIR)

O Claude Code não possui arquivos de perfil nativos (ao contrário do ~/.codex/<name>.config.toml do Codex). O mecanismo idiomático é CLAUDE_CONFIG_DIR — um diretório de configuração separado para cada perfil, cada um com seu próprio settings.json, credenciais, histórico e cache.

omniroute setup-claude busca o catálogo /v1/models ativo e grava um perfil por modelo em ~/.claude/profiles/<name>/settings.json, reutilizando os mesmos nomes de setup-codex (glm52, kimi-k27, deepseek-pro, …):

~/.claude/profiles/glm52/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "glm/glm-5.2",
  "effortLevel": "xhigh",
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
    "ANTHROPIC_MODEL": "glm/glm-5.2",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  },
}

O token de autenticação nunca é gravado no perfil. Inicie com omniroute launch --profile <name> (ele injeta ANTHROPIC_AUTH_TOKEN a partir do contexto ativo) ou exporte ANTHROPIC_AUTH_TOKEN por conta própria e execute CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude.

Sincronização automática após a descoberta de modelos (opcional). O OmniRoute pode gerar novamente esses mesmos arquivos ~/.claude/profiles/<name>/settings.json automaticamente sempre que uma sincronização dos modelos de um provedor alterar o catálogo ativo — assim, modelos novos ou renomeados recebem perfis sem que seja necessário executar o comando novamente. Esse recurso fica desativado por padrão: ative-o no painel Código da CLI (“Sincronização automática de perfis da CLI” → Claude Code) ou defina OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true (ele também respeita CLI_ALLOW_CONFIG_WRITES, ativado por padrão). Quando habilitado, ele grava apenas os arquivos de perfil; nunca altera a configuração ativa/padrão do Claude, a autenticação ou o ~/.claude/settings.json.

Como gerar e usar perfis

# OmniRoute local
omniroute setup-claude

# VPS remoto (incorpora a URL do VPS em cada perfil)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Apenas alguns provedores
omniroute setup-claude --only glm,kimi

# Visualizar sem gravar
omniroute setup-claude --dry-run

# Iniciar um perfil
omniroute launch --profile kimi-k27

---

Níveis de modelo (opcional)

O Claude Code direciona as solicitações para níveis de capacidade. Mapeie cada nível para um modelo do OmniRoute por meio de variáveis de ambiente / configurações caso queira usar provedores diferentes por nível:

export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"

Caso contrário, um único ANTHROPIC_MODEL (definido pelos perfis) será usado para tudo.

---

Modo remoto

Depois de executar omniroute connect <host> (consulte Modo remoto), omniroute launch e omniroute setup-claude passam a usar automaticamente esse servidor remoto e seu token de acesso com escopo — sem necessidade de flags adicionais. Substitua esses valores em cada execução com --remote / --api-key.

---

Solução de problemas

O Claude Code ignora o gateway — confirme que ANTHROPIC_BASE_URL não contém /v1 e reinicie o claude (as variáveis de ambiente são lidas apenas uma vez na inicialização). omniroute launch cuida disso para você.

O seletor /model está vazio / não exibe os modelos do gateway — requer o Claude Code v2.1.219+ e CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Somente IDs de modelos claude* / anthropic* aparecem no seletor; force qualquer outro modelo com ANTHROPIC_MODEL=<id> (é isso que os perfis fazem).

400 Ambiguous model 'claude-…' — o Claude Code sempre envia IDs de modelo sem prefixo (por exemplo, claude-opus-4-8), portanto, quando os provedores Claude Code (cc/…) e Claude (claude/…) estão conectados, o ID sem prefixo corresponde a duas rotas e o OmniRoute se recusa a escolher uma delas. Corrija isso de uma destas formas: fixe um ID com prefixo usando ANTHROPIC_MODEL=cc/claude-opus-4-8 ou habilite Preferir o Claude Code para modelos Claude sem prefixo — a opção na página do provedor Claude, ou OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true (desabilitado por padrão; consulte Ambiente) — que direciona IDs claude-* sem prefixo para o Claude Code. Prefixos explícitos de provedores sempre têm prioridade.

Erros de autenticação — o perfil não armazena nenhum token. Use omniroute launch --profile (que o injeta) ou exporte ANTHROPIC_AUTH_TOKEN.

Os perfis não ficam isolados — cada perfil é um CLAUDE_CONFIG_DIR distinto; verifique se echo $CLAUDE_CONFIG_DIR, dentro da sessão, aponta para ~/.claude/profiles/<name>.

---

Código-fonte do OmniRoute (a58000c7685f)