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

🌐 **Languages:** 🇺🇸 [English](../../../../guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇹 [am](../../../am/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇦 [ar](../../../ar/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇿 [az](../../../az/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇬 [bg](../../../bg/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇩 [bn](../../../bn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇦 [bs](../../../bs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇿 [cs](../../../cs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇰 [da](../../../da/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇪 [de](../../../de/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇷 [el](../../../el/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇸 [es](../../../es/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇪 [et](../../../et/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇷 [fa](../../../fa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇮 [fi](../../../fi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇷 [fr](../../../fr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇪 [ga](../../../ga/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [gu](../../../gu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ha](../../../ha/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇱 [he](../../../he/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [hi](../../../hi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇷 [hr](../../../hr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇺 [hu](../../../hu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇲 [hy](../../../hy/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇩 [id](../../../id/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ig](../../../ig/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇹 [it](../../../it/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇯🇵 [ja](../../../ja/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇪 [ka](../../../ka/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇭 [km](../../../km/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [kn](../../../kn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇷 [ko](../../../ko/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇹 [lt](../../../lt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇻 [lv](../../../lv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ml](../../../ml/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [mr](../../../mr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇾 [ms](../../../ms/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇹 [mt](../../../mt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇲 [my](../../../my/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇵 [ne](../../../ne/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇱 [nl](../../../nl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇴 [no](../../../no/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [or](../../../or/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [pa](../../../pa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇭 [phi](../../../phi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇱 [pl](../../../pl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇴 [ro](../../../ro/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇺 [ru](../../../ru/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇰 [si](../../../si/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇰 [sk](../../../sk/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇮 [sl](../../../sl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇸 [sr](../../../sr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇪 [sv](../../../sv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇪 [sw](../../../sw/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ta](../../../ta/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [te](../../../te/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇭 [th](../../../th/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇷 [tr](../../../tr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇰 [ur](../../../ur/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇿 [uz](../../../uz/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇻🇳 [vi](../../../vi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [yo](../../../yo/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CLAUDE-CODE-CONFIGURATION.md)

---

Aponte a CLI do **Claude Code** (`claude`) para o OmniRoute — localmente ou num VPS remoto —
com perfis por modelo, replicando a configuração do Codex.

---

## Início rápido

```bash
# Iniciar o Claude Code com um OmniRoute local (deteta automaticamente o contexto ativo)
omniroute launch

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

# Gerar perfis por modelo e, em seguida, iniciar um deles
omniroute setup-claude            # escreve em ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # Claude Code a utilizar glm/glm-5.2 através do OmniRoute
```

---

## Como o Claude Code se liga a um gateway

O Claude Code comunica através da **Anthropic Messages API** e é direcionado para um
endpoint personalizado através de variáveis de ambiente (não tem 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 …` — utilize o 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 a predefinição do seletor `/model`)                             |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` → o seletor nativo `/model` apresenta 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 no arranque** — reinicie o Claude Code depois de as alterar.

`omniroute launch` define tudo isto por si: resolve o URL base + token
a partir do contexto ativo (pelo que `omniroute connect <vps>` seguido de `omniroute launch`
funciona de imediato), verifica o estado do servidor e executa `claude`.

---

## Aliases de descoberta — apresentar modelos que não são Claude no seletor `/model`

A descoberta de modelos do gateway do Claude Code apresenta apenas ids que começam por `claude`
ou `anthropic`, pelo que, com `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`, o seletor
nativo `/model` apresenta normalmente **apenas** os modelos Claude/Anthropic do OmniRoute — um
`kimi/kimi-k2.6` ou `glm/glm-5.2` nunca aparece, apesar de o encaminhamento funcionar corretamente.

O OmniRoute pode espelhar qualquer modelo ativo (e combinação) sob um id `claude/…`, para que este
passe pelo 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 seleciona um destes modelos no Claude Code, o OmniRoute remove o prefixo `claude/`
e repõe o id real antes do encaminhamento — um id `claude/<real-claude-model>` genuíno
(o fornecedor OAuth real do Claude) permanece sempre inalterado.

**Esta funcionalidade está desativada por predefinição** e é controlada por uma hierarquia de três níveis (o mais específico
prevalece), para que uma instalação normal do OmniRoute nunca duplique o respetivo catálogo para clientes que não utilizam
o Claude Code:

| Nível      | Localização                                                                                     |
| ---------- | ----------------------------------------------------------------------------------------------- |
| Modelo     | Página de detalhes do fornecedor → opção "Expose in Claude Code" por modelo                     |
| Fornecedor | Página de detalhes do fornecedor → opção ao nível do fornecedor (abrange todos os seus modelos) |
| Global     | Settings → Feature Flags → `EXPOSE_CC_DISCOVERY_ALIASES` (desativado por predefiniçã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 (o ecrã Feature Flags apresenta
uma nota "active via environment variable" quando isso acontece). As opções por fornecedor e
por modelo permitem refinar a partir daí — por exemplo, global desativado + fornecedor Kimi ativado expõe
apenas os modelos da Kimi.

> ⚠️ **Incompatibilidade da janela em modelos que não são Claude.** O Claude Code assume uma janela de contexto de 200K
> para qualquer id que não reconheça (não consegue obter a janela real a partir de
> `/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 inferior à janela real do modelo, para que
> a compactação automática não seja acionada prematuramente. Os perfis gerados acima já
> fazem isto para cada modelo.

---

## Bloco de integração no painel

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

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}
```

O URL base é o resolvido pelo cartão (incluindo uma substituição personalizada que tenha introduzido), já
normalizado — sem o sufixo `/v1` nem uma barra final. **A chave nunca é apresentada**: o bloco inclui um
marcador de posição, pelo que uma captura de ecrã ou um fragmento colado não pode divulgá-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 assume 200K para todos os IDs que não reconhece, pelo que,
caso contrário, a compactação automática é acionada no ponto errado (consulte o aviso na secção anterior).
O gerador de fragmentos também aceita esse valor, pelo que 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 por testes unitários), apresentado por `ClaudeGatewayOnboardingBlock`.

---

## Perfis (`CLAUDE_CONFIG_DIR`)

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

`omniroute setup-claude` obtém o catálogo `/v1/models` em tempo real e cria um
perfil por modelo em `~/.claude/profiles/<name>/settings.json`, reutilizando os
**mesmos nomes que `setup-codex`** (`glm52`, `kimi-k27`, `deepseek-pro`, …):

```jsonc
// ~/.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 é guardado no perfil.** Inicie com
> `omniroute launch --profile <name>` (este injeta `ANTHROPIC_AUTH_TOKEN` a partir do
> contexto ativo) ou exporte `ANTHROPIC_AUTH_TOKEN` manualmente e execute
> `CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude`.

**Sincronização automática após a descoberta de modelos (opcional).** O OmniRoute pode regenerar automaticamente estes mesmos
ficheiros `~/.claude/profiles/<name>/settings.json` sempre que uma sincronização dos modelos de um fornecedor
altere o catálogo em tempo real — assim, os modelos novos ou com nomes alterados obtêm perfis sem ser necessário voltar a executar o
comando. Está **desativada por predefinição**: ative-a no **painel de CLI Code** ("Sincronização automática de perfis da CLI" → Claude Code) ou defina `OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true` (também respeita
`CLI_ALLOW_CONFIG_WRITES`, ativada por predefinição). Quando ativada, apenas escreve ficheiros de perfil; nunca
altera a configuração ativa/predefinida do Claude, a autenticação ou o ficheiro `~/.claude/settings.json`.

### Gerar e utilizar perfis

```bash
# OmniRoute local
omniroute setup-claude

# VPS remoto (incorpora o URL do VPS em todos os perfis)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

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

# Também escreve perfis para fornecedores de CLI locais (zcode, auggie, devin-cli-agentic,
# codex-app-server) não detetados neste anfitrião (ignorados por predefinição para um destino local)
omniroute setup-claude --include-local

# Pré-visualizar sem escrever
omniroute setup-claude --dry-run

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

---

## Níveis de modelo (opcional)

O Claude Code encaminha os pedidos para níveis de capacidade. Associe cada nível a um modelo OmniRoute através de variáveis de ambiente /
definições, caso pretenda utilizar fornecedores diferentes por nível:

```bash
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, é utilizado um único `ANTHROPIC_MODEL` (o que os perfis definem) para tudo.

---

## Modo remoto

Depois de executar `omniroute connect <host>` (consulte
[Modo remoto](./REMOTE-MODE.md)), `omniroute launch` e `omniroute setup-claude`
passam automaticamente a utilizar esse servidor remoto e o respetivo token de acesso com âmbito limitado — não são
necessários parâmetros adicionais. Substitua estes valores em cada invocação com `--remote` / `--api-key`.

---

## Resoluçã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 uma única vez durante o arranque). `omniroute launch`
trata disto por si.

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

**`400 Ambiguous model 'claude-…'`** — o Claude Code envia sempre IDs de modelos **sem prefixo**
(por exemplo, `claude-opus-4-8`), pelo que, quando os fornecedores Claude Code (`cc/…`) e
Claude (`claude/…`) estão ambos ligados, o ID sem prefixo corresponde a duas rotas e
o OmniRoute recusa-se a escolher. Corrija o problema de uma destas formas: fixe um ID com prefixo através de
`ANTHROPIC_MODEL=cc/claude-opus-4-8` ou ative **Preferir o Claude Code para
modelos Claude sem prefixo** — a opção na página do fornecedor Claude, ou
`OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true` (desativada por predefinição;
consulte [Ambiente](../reference/ENVIRONMENT.md)) — o que encaminha os IDs `claude-*`
sem prefixo para o Claude Code. Os prefixos explícitos dos fornecedores têm sempre precedência.

**Erros de autenticação** — o perfil não contém qualquer token. Utilize `omniroute launch --profile`
(injeta o token) ou exporte `ANTHROPIC_AUTH_TOKEN`.

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