# CLI Tools — OmniRoute (Português (Brasil)) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/CLI-TOOLS.md) · 🇪🇹 [am](../../../am/docs/reference/CLI-TOOLS.md) · 🇸🇦 [ar](../../../ar/docs/reference/CLI-TOOLS.md) · 🇦🇿 [az](../../../az/docs/reference/CLI-TOOLS.md) · 🇧🇬 [bg](../../../bg/docs/reference/CLI-TOOLS.md) · 🇧🇩 [bn](../../../bn/docs/reference/CLI-TOOLS.md) · 🇧🇦 [bs](../../../bs/docs/reference/CLI-TOOLS.md) · 🇨🇿 [cs](../../../cs/docs/reference/CLI-TOOLS.md) · 🇩🇰 [da](../../../da/docs/reference/CLI-TOOLS.md) · 🇩🇪 [de](../../../de/docs/reference/CLI-TOOLS.md) · 🇬🇷 [el](../../../el/docs/reference/CLI-TOOLS.md) · 🇪🇸 [es](../../../es/docs/reference/CLI-TOOLS.md) · 🇪🇪 [et](../../../et/docs/reference/CLI-TOOLS.md) · 🇮🇷 [fa](../../../fa/docs/reference/CLI-TOOLS.md) · 🇫🇮 [fi](../../../fi/docs/reference/CLI-TOOLS.md) · 🇫🇷 [fr](../../../fr/docs/reference/CLI-TOOLS.md) · 🇮🇪 [ga](../../../ga/docs/reference/CLI-TOOLS.md) · 🇮🇳 [gu](../../../gu/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ha](../../../ha/docs/reference/CLI-TOOLS.md) · 🇮🇱 [he](../../../he/docs/reference/CLI-TOOLS.md) · 🇮🇳 [hi](../../../hi/docs/reference/CLI-TOOLS.md) · 🇭🇷 [hr](../../../hr/docs/reference/CLI-TOOLS.md) · 🇭🇺 [hu](../../../hu/docs/reference/CLI-TOOLS.md) · 🇦🇲 [hy](../../../hy/docs/reference/CLI-TOOLS.md) · 🇮🇩 [id](../../../id/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ig](../../../ig/docs/reference/CLI-TOOLS.md) · 🇮🇹 [it](../../../it/docs/reference/CLI-TOOLS.md) · 🇯🇵 [ja](../../../ja/docs/reference/CLI-TOOLS.md) · 🇬🇪 [ka](../../../ka/docs/reference/CLI-TOOLS.md) · 🇰🇭 [km](../../../km/docs/reference/CLI-TOOLS.md) · 🇮🇳 [kn](../../../kn/docs/reference/CLI-TOOLS.md) · 🇰🇷 [ko](../../../ko/docs/reference/CLI-TOOLS.md) · 🇱🇹 [lt](../../../lt/docs/reference/CLI-TOOLS.md) · 🇱🇻 [lv](../../../lv/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ml](../../../ml/docs/reference/CLI-TOOLS.md) · 🇮🇳 [mr](../../../mr/docs/reference/CLI-TOOLS.md) · 🇲🇾 [ms](../../../ms/docs/reference/CLI-TOOLS.md) · 🇲🇹 [mt](../../../mt/docs/reference/CLI-TOOLS.md) · 🇲🇲 [my](../../../my/docs/reference/CLI-TOOLS.md) · 🇳🇵 [ne](../../../ne/docs/reference/CLI-TOOLS.md) · 🇳🇱 [nl](../../../nl/docs/reference/CLI-TOOLS.md) · 🇳🇴 [no](../../../no/docs/reference/CLI-TOOLS.md) · 🇮🇳 [or](../../../or/docs/reference/CLI-TOOLS.md) · 🇮🇳 [pa](../../../pa/docs/reference/CLI-TOOLS.md) · 🇵🇭 [phi](../../../phi/docs/reference/CLI-TOOLS.md) · 🇵🇱 [pl](../../../pl/docs/reference/CLI-TOOLS.md) · 🇵🇹 [pt](../../../pt/docs/reference/CLI-TOOLS.md) · 🇷🇴 [ro](../../../ro/docs/reference/CLI-TOOLS.md) · 🇷🇺 [ru](../../../ru/docs/reference/CLI-TOOLS.md) · 🇱🇰 [si](../../../si/docs/reference/CLI-TOOLS.md) · 🇸🇰 [sk](../../../sk/docs/reference/CLI-TOOLS.md) · 🇸🇮 [sl](../../../sl/docs/reference/CLI-TOOLS.md) · 🇷🇸 [sr](../../../sr/docs/reference/CLI-TOOLS.md) · 🇸🇪 [sv](../../../sv/docs/reference/CLI-TOOLS.md) · 🇰🇪 [sw](../../../sw/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ta](../../../ta/docs/reference/CLI-TOOLS.md) · 🇮🇳 [te](../../../te/docs/reference/CLI-TOOLS.md) · 🇹🇭 [th](../../../th/docs/reference/CLI-TOOLS.md) · 🇹🇷 [tr](../../../tr/docs/reference/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/CLI-TOOLS.md) · 🇵🇰 [ur](../../../ur/docs/reference/CLI-TOOLS.md) · 🇺🇿 [uz](../../../uz/docs/reference/CLI-TOOLS.md) · 🇻🇳 [vi](../../../vi/docs/reference/CLI-TOOLS.md) · 🇳🇬 [yo](../../../yo/docs/reference/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/CLI-TOOLS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/CLI-TOOLS.md) --- Última atualização: 2026-08-23 O OmniRoute integra-se a três categorias de ferramentas CLI distribuídas em três páginas dedicadas do dashboard: | Página | Rota | Conceito | Quantidade | | -------------- | ----------------------- | ------------------------------------------------------------------------------------------- | ------------------- | | **CLI Code's** | `/dashboard/cli-code` | Ferramentas de programação direcionadas ao OmniRoute (Cliente → CLI → OmniRoute → Provedor) | 26 | | **CLI Agents** | `/dashboard/cli-agents` | Agentes autônomos direcionados ao OmniRoute (mesmo fluxo, escopo mais amplo) | 10 | | **ACP Agents** | `/dashboard/acp-agents` | CLIs que o OmniRoute inicia como backend via stdio/ACP (fluxo inverso) | consulte o registro | As rotas legadas redirecionam via 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`. --- ## Como funciona ``` CLI Code's / CLI Agents (fluxo de consumo): Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ... │ ▼ (todos apontam para o OmniRoute) http://YOUR_SERVER:20128/v1 │ ▼ (o OmniRoute encaminha para o provedor correto) Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... ACP Agents (fluxo inverso de inicialização): Solicitação do cliente → OmniRoute → inicia a CLI via stdio/ACP → resposta ``` **Benefícios:** - Uma única chave de API para gerenciar todas as ferramentas - Acompanhamento de custos de todas as CLIs no dashboard - Troca de modelos sem precisar reconfigurar cada ferramenta - Funciona localmente e em servidores remotos (VPS, Docker, Akamai, Cloudflare Tunnel) --- ## Configuração automática com `setup-*` Você não precisa criar manualmente a configuração de cada ferramenta. O OmniRoute inclui um comando `setup-*` para cada CLI compatível, que lê o catálogo de modelos **ativo** de uma instância do OmniRoute em execução (local ou remota) e grava a configuração da própria ferramenta em sua máquina: ```bash omniroute setup-codex omniroute setup-claude omniroute setup-opencode omniroute setup-cline omniroute setup-kilo omniroute setup-continue omniroute setup-cursor omniroute setup-roo omniroute setup-crush omniroute setup-goose omniroute setup-qwen omniroute setup-aider omniroute setup-5dive ``` Cada comando aceita `--remote --api-key ` (para configurar uma ferramenta local com uma instância remota do OmniRoute), `--dry-run` (para visualizar sem gravar) e `--port`. Ferramentas sem descoberta automática de modelos (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive) aceitam `--model ` (e `--yes` para execuções não interativas). `setup-5dive` é a única receita que não grava em `$HOME`: ela configura uma frota de agentes 5dive gravando um perfil de autenticação pertencente ao root no host da frota; portanto, executa novamente por meio de `sudo` e não possui um modo remoto próprio. Para iniciar uma CLI com as variáveis de ambiente corretas injetadas, sem gravar nenhuma configuração, use o inicializador genérico `omniroute run ` (claude, codex, aider, goose, opencode, qwen, gemini — os destinos e aliases vêm de `bin/cli/cli-manifest.mjs`); os inicializadores legados específicos de cada ferramenta, `omniroute launch` (Claude Code) e `omniroute launch-codex` (Codex), continuam disponíveis. A Gemini CLI pode apenas ser iniciada: ela é um destino de `omniroute run`, mas não possui receita `setup-*`/`configure`. > **Referência completa:** a tabela principal — o que cada comando grava, todas as flags, > execução local ou remota e quais ferramentas exigem o sufixo `/v1` — está em > **[Integrações de CLI](../guides/CLI-INTEGRATIONS.md)**. ### Execução desses comandos dentro de um contêiner Um comando `setup-*` executado dentro do contêiner do OmniRoute grava no diretório home do próprio contêiner, que não é lido por nenhuma CLI do host e desaparece junto com o contêiner. O OmniRoute detecta essa situação e encerra com o código `2`, fornecendo instruções em vez de gravar. Há duas alternativas compatíveis: instalar a CLI no host e usar `omniroute connect` para conectá-la ao contêiner, ou montar os diretórios de configuração via bind mount e definir `CLI_CONFIG_HOME` (o perfil `host` do Compose). Todos os comandos `setup-*`, além de `omniroute configure` e `omniroute config set`, aceitam `--allow-container-write` quando a intenção é realmente configurar as CLIs do próprio contêiner; `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` faz o mesmo para o servidor. Consulte [Guia do Docker → Configuração de ferramentas CLI do host](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker). O **endpoint de aplicação** do dashboard (`POST /api/cli-tools/apply`) aplica a mesma proteção: em um contêiner, uma gravação cujo destino não esteja montado a partir do host via bind mount responde com **`422`**, incluindo `containerEphemeralTarget: true`, o texto seguro do erro e — para as ferramentas que possuem uma receita para o host (claude, codex, opencode, cline, kilo, continue) — um `hostSetupCommand` (por exemplo, `omniroute setup-opencode`) para ser executado no host; nada é gravado. `dryRun: true` continua funcionando no modo de contêiner e retorna uma visualização prévia com dados sensíveis ocultados + o caminho de destino sem alterar o disco. O conteúdo da visualização prévia não é uma configuração com credenciais que deva ser copiada ou importada. Aplique usando os dados originais da ferramenta, URL base, chave de API e modelo no host, ou use o comando de configuração no host indicado. Consulte [Segurança da configuração de CLI](../security/CLI-CONFIGURATION.md) para obter informações sobre o cabeçalho da visualização prévia e o contrato da solicitação. Esse comportamento é intencional e protegido contra regressões por `tests/unit/api/cli-tools/apply-container-guard.test.ts` — nunca "corrija" um erro 422 removendo a proteção. --- ## Fonte da verdade O catálogo unificado está localizado em `src/shared/constants/cliTools.ts` como `CLI_TOOLS: Record`. Cada entrada possui estes campos (definidos em `src/shared/schemas/cliCatalog.ts`): | Campo | Tipo | Descrição | | ----------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- | | `category` | `"code" \| "agent"` | Em qual página a ferramenta aparece | | `vendor` | `string` | Origem da ferramenta ("Anthropic", "OSS (P. Gauthier)") | | `acpSpawnable` | `boolean` | Também utilizável como um Agente ACP (badge exibido) | | `baseUrlSupport` | `"full" \| "partial" \| "none"` | Nível de suporte a endpoint personalizado. `"none"` = backlog de MITM | | `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | Mecanismo de configuração | | `id`, `name`, `color`, `description`, `docsUrl` | padrão | Campos principais de exibição | As entradas com `baseUrlSupport: "none"` **não são exibidas** nas páginas do dashboard — elas são registradas no backlog de MITM para o plano 11 (consulte `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`). ### Níveis de capacidade (catalogável × detectável × configurável × executável) Nem toda ferramenta catalogada é detectável, configurável ou executável. Cada nível possui uma única fonte de declaração, e um teste de divergência os mantém alinhados: | Nível | Significado | Declarado em | | ---------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | **Catalogável** | Aparece no catálogo do dashboard (nome, fornecedor, documentação, tipo de configuração) | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`) | | **Detectável** | Detecção de binário/configuração, verificações de integridade, caminhos de configuração | `src/shared/services/cliRuntime.ts` (catálogo de runtime `CLI_TOOLS`) | | **Configurável** | Compatível com `omniroute configure ` (existe uma receita de configuração) | `bin/cli/cli-manifest.mjs` (`configure: true`) | | **Executável** | Compatível com `omniroute run ` (injeção de ambiente/argumentos definida) | `bin/cli/cli-manifest.mjs` (`run: true`) | `bin/cli/cli-manifest.mjs` é o manifesto executável canônico para as superfícies de comando da CLI: `run`, `configure` e os geradores de autocompletar do shell derivam dele suas listas de destinos, resolução de aliases (por exemplo, `kilocode`/`kilo-code`/`kilo_cli` → `kilo`) e a configuração da flag `--model`. A proteção contra divergências `tests/unit/cli/cli-manifest-drift.test.ts` garante que o manifesto, o catálogo de runtime, o catálogo da interface e cada superfície consumidora permaneçam sincronizados — um destino adicionado a uma superfície sem as demais faz a suíte falhar, em vez de permitir uma divergência silenciosa. --- ## 1. Catálogo do CLI Code (26 ferramentas) Todas as ferramentas exibidas em `/dashboard/cli-code`. Aquelas com `baseUrlSupport: none` são integradas por meio de MITM ou de um guia manual, em vez de uma URL base personalizada: | id | nome | fornecedor | baseUrlSupport | configType | acpSpawnable | | ------------ | ----------------------- | ------------------- | -------------- | -------------- | ------------ | | claude | Claude Code | Anthropic | full | env | true | | codex | OpenAI Codex CLI | OpenAI | full | custom | true | | zcode | ZCode (GLM Coding Plan) | Z.ai | none | custom | false | | cline | Cline | OSS (ex-Claude Dev) | full | custom | true | | kilo | Kilo Code | Kilo-Org | full | custom | false | | roo | Roo Code | Roo (OSS) | full | guide | false | | continue | Continue | continue.dev | full | guide | false | | aider | Aider | OSS (P. Gauthier) | full | guide | true | | forge | ForgeCode | Antinomy HQ | full | custom | true | | jcode | jcode | 1jehuang (OSS) | full | custom | false | | deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false | | codewhale | CodeWhale | Hmbown (OSS) | full | custom | false | | opencode | OpenCode | Anomaly (ex-SST) | full | guide | true | | droid | Factory Droid | Factory AI | partial | guide | false | | copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false | | cursor-cli | Cursor CLI | Anysphere | partial | guide | true | | smelt | Smelt | leonardcser (OSS) | full | custom | false | | pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false | | grok-build | Grok Build | xAI | full | custom | false | | crush | Crush | OSS (Charm) | full | custom | false | | qwen | Qwen Code | Alibaba | full | guide | true | | cursor | Cursor | Anysphere | none | guide | false | | antigravity | Antigravity | Google | none | mitm | false | | hermes | Hermes | Nous Research | none | guide | false | | kiro | Kiro AI | Amazon | none | mitm | false | | custom | Custom CLI | — | full | custom-builder | false | As ferramentas com `baseUrlSupport: "partial"` exibem um selo "⚠ Base URL parcial" no cartão do dashboard. --- ## 2. Catálogo de Agentes de CLI (10 ferramentas) Agentes autônomos exibidos em `/dashboard/cli-agents`: | id | name | vendor | baseUrlSupport | acpSpawnable | | ------------ | ---------------- | ------------------------ | -------------- | ------------ | | hermes-agent | Hermes Agent | Nous Research | full | false | | openclaw | OpenClaw | OSS (P. Steinberger) | full | true | | goose | Goose | Block / Linux Foundation | full | true | | interpreter | Open Interpreter | OSS | full | true | | warp | Warp AI | Warp Inc. | partial | true | | agent-deck | Agent Deck | asheshgoplani (OSS) | full | false | | omp | Oh My Pi | OSS | full | true | | letta | Letta CLI | Letta | full | false | | prime-agent | Prime Agent | Prime Intellect (OSS) | full | false | | 5dive | 5dive | OSS (5dive-ai) | full | false | --- ## 3. Agentes ACP (/dashboard/acp-agents) Esta página (renomeada de `/dashboard/agents`) exibe CLIs que o OmniRoute pode **iniciar** como mecanismos de execução de backend por meio do protocolo stdio/ACP. O catálogo é mantido separadamente em `src/lib/acp/registry.ts` e **não** é o mesmo que `CLI_TOOLS`. --- ## 4. Backlog de MITM (não exibido no painel) As CLIs a seguir não oferecem suporte nativo a uma URL base personalizada e **não estão listadas** nas páginas CLI Code ou CLI Agents. Elas são candidatas à interceptação MITM no plano 11: | CLI | Motivo | | ------------------- | ------------------------------------------------------------------- | | windsurf | BYOK limitado a modelos Claude selecionados + URL/token corporativo | | amp | Ecossistema fechado (Sourcegraph) | | amazon-q / kiro-cli | Autenticação por AWS SSO, sem URL personalizada | | cowork | Anthropic Desktop, sem endpoint configurável | Consulte `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md` para obter a referência cruzada completa. --- ## 5. API de Detecção em Lote Toda a detecção de ferramentas é agregada por meio de um único endpoint: **`GET /api/cli-tools/all-statuses`** - Autenticação: `requireCliToolsAuth(request)` (a mesma das outras rotas `/api/cli-tools/`) - Retorna: `Record` (tipo: `src/shared/types/cliBatchStatus.ts`) - Estratégia: `Promise.all` para todas as ferramentas, com timeout de 5 s por ferramenta - Cache: LRU em memória indexado pelo `mtime` do arquivo de configuração. O cache é invalidado quando o mtime é alterado. É redefinido quando o servidor é reiniciado. Formato da resposta por ferramenta: ```ts interface ToolBatchStatus { detection: { installed: boolean; runnable: boolean; version?: string; command?: string; commandPath?: string; reason?: string; }; config: { status: "configured" | "not_configured" | "not_installed" | "unknown" | "other"; endpoint?: string | null; lastConfiguredAt?: string | null; }; error?: string; // sanitizado, sem rastreamentos de pilha } ``` --- ## 6. Manipuladores de configurações para novas ferramentas Novas ferramentas com `configType: "custom"` têm rotas dedicadas na API de configurações: | Rota | Ferramenta | | ------------------------------------------- | ------------------------------------------------------------------------------- | | `POST /api/cli-tools/forge-settings` | ForgeCode (.forge.toml) | | `POST /api/cli-tools/jcode-settings` | jcode (flag --base-url) | | `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL, legado) | | `POST /api/cli-tools/codewhale-settings` | CodeWhale (OPENAI_BASE_URL, principal + sincronização legada com `~/.deepseek`) | | `POST /api/cli-tools/smelt-settings` | Smelt | | `POST /api/cli-tools/pi-settings` | Agente de programação Pi | | `POST /api/cli-tools/grok-build-settings` | Grok Build (~/.grok/config.toml, `[model.omniroute]`) | | `POST /api/cli-tools/qwen-settings` | Qwen Code (`~/.qwen/settings.json` + chave dedicada no `.env`) | Todas as rotas usam `sanitizeErrorMessage()` para respostas de erro (Regra Rígida nº 12). --- ## 7. Arquitetura das páginas do dashboard ### Códigos CLI (`/dashboard/cli-code`) - `src/app/(dashboard)/dashboard/cli-code/page.tsx` — componente de servidor - `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — grade do cliente - `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — página de detalhes da ferramenta - `src/app/(dashboard)/dashboard/cli-code/components/` — 12 cartões especializados de ferramentas + `ToolDetailClient.tsx` ### Agentes CLI (`/dashboard/cli-agents`) - `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — componente de servidor - `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — grade do cliente - `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — reutiliza `ToolDetailClient` ### Agentes ACP (`/dashboard/acp-agents`) - `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — componente de servidor (movido de `agents/`) ### Componentes de UI compartilhados (`src/shared/components/cli/`) | Arquivo | Finalidade | | ----------------------- | ----------------------------------------------------------------- | | `CliToolCard.tsx` | Cartão inteligente de status (detecção + configuração + endpoint) | | `CliConceptCard.tsx` | Cartão de explicação de conceitos por página | | `CliComparisonCard.tsx` | Comparação em três colunas entre tipos de CLI | | `BaseUrlSelect.tsx` | Lista suspensa de endpoints (local/nuvem/personalizado) | | `ApiKeySelect.tsx` | Seletor de chave de API | | `ManualConfigModal.tsx` | Modal com trecho de configuração copiável | ### Hook compartilhado (`src/shared/hooks/cli/`) | Arquivo | Finalidade | | ------------------------- | ----------------------------------------------------------------------------------- | | `useToolBatchStatuses.ts` | Busca `/api/cli-tools/all-statuses` e gerencia o estado de carregamento/atualização | --- ## 8. i18n Novos namespaces adicionados no plano 14 F9: | Namespace | Finalidade | | ----------- | ------------------------------------------------------------------------------------------------------------ | | `cliCommon` | Strings compartilhadas (rótulos de cartões, textos de conceitos/comparações, rótulos de páginas de detalhes) | | `cliCode` | Strings da página do CLI Code | | `cliAgents` | Strings da página do CLI Agents | | `acpAgents` | Strings da página do ACP Agents | São fornecidas traduções completas para PT-BR e EN. Os outros 39 locales usam EN automaticamente como fallback por meio da mesclagem no nível de namespace em `src/i18n/request.ts`. --- ## 9. Início Rápido ### Etapa 1 — Obtenha uma chave de API do OmniRoute 1. Abra `/dashboard/api-manager` → **Criar chave de API** 2. Dê um nome a ela (por exemplo, `cli-tools`) e selecione todas as permissões 3. Copie a chave — você precisará dela para cada CLI abaixo > Sua chave se parece com: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` --- ### Etapa 2 — Instale as ferramentas de CLI Todas as ferramentas baseadas em npm exigem Node.js 22.22.2+ ou 24.x: ```bash # Claude Code (Anthropic) npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex # OpenCode npm install -g opencode-ai # Cline npm install -g cline # KiloCode npm install -g kilocode # Qwen Code npm install -g @qwen-code/qwen-code # Google Gemini CLI (pode ser iniciado via `omniroute run gemini` → superfície /v1beta) npm install -g @google/gemini-cli # Aider pip install aider-chat # Smelt cargo install smelt # Baseado em Rust # Agente de programação Pi # consulte https://github.com/zechnerj/pi-coding-agent para saber como instalar # jcode # consulte https://github.com/1jehuang/jcode para saber como instalar ``` --- ### Etapa 3 — Configure pelo painel 1. Acesse `http://localhost:20128/dashboard/cli-code` 2. Encontre sua ferramenta na grade 3. Clique no cartão para abrir a página de detalhes da ferramenta 4. Selecione sua chave de API e URL base 5. Clique em **Aplicar configuração** ou copie o trecho de configuração manual --- ### Etapa 4 — Defina as variáveis de ambiente globais ```bash # Endpoint universal do OmniRoute export OPENAI_BASE_URL="http://localhost:20128/v1" export OPENAI_API_KEY="sk-your-omniroute-key" export ANTHROPIC_BASE_URL="http://localhost:20128" export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key" # O Gemini CLI lê GOOGLE_GEMINI_BASE_URL na RAIZ (seu SDK acrescenta /v1beta/... por conta própria) export GOOGLE_GEMINI_BASE_URL="http://localhost:20128" export GEMINI_API_KEY="sk-your-omniroute-key" ``` > Para um **servidor remoto**, substitua `localhost:20128` pelo IP ou domínio do servidor, > por exemplo, `http://:20128`. --- ### Etapa 4 — Configure cada ferramenta #### Claude Code ```bash # Crie ~/.claude/settings.json: mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF { "env": { "ANTHROPIC_BASE_URL": "http://localhost:20128", "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key" } } EOF ``` Use a raiz unificada do gateway Anthropic para o Claude Code. Não acrescente `/v1` aqui. **Teste:** `claude "say hello"` --- #### OpenAI Codex O Codex moderno (v0.137+) lê apenas `~/.codex/config.toml` — o antigo `config.yaml` pertence à CLI npm legada e é silenciosamente ignorado. A chave de API permanece na variável de ambiente `OMNIROUTE_API_KEY` (`env_key`), nunca dentro do arquivo: ```bash mkdir -p ~/.codex && cat > ~/.codex/config.toml << EOF model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute" base_url = "http://localhost:20128/v1" env_key = "OMNIROUTE_API_KEY" requires_openai_auth = false EOF export OMNIROUTE_API_KEY="sk-your-omniroute-key" ``` Referência completa (perfis, `wire_api`, janelas de contexto): [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md). **Teste:** `codex "what is 2+2?"` --- #### OpenCode ```bash mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF { "\$schema": "https://opencode.ai/config.json", "provider": { "omniroute": { "npm": "@ai-sdk/openai-compatible", "name": "OmniRoute", "options": { "baseURL": "http://localhost:20128/v1", "apiKey": "sk-your-omniroute-key" }, "models": { "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" }, "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" }, "gemini-3-flash": { "name": "gemini-3-flash" } } } } } EOF ``` **Teste:** `opencode` > Use `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high` > para enviar variantes com raciocínio. --- #### Cline (CLI ou VS Code) **Modo CLI:** ```bash mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF { "apiProvider": "openai", "openAiBaseUrl": "http://localhost:20128/v1", "openAiApiKey": "sk-your-omniroute-key" } EOF ``` **Modo VS Code:** Configurações da extensão Cline → Provedor de API: `OpenAI Compatible` → URL base: `http://localhost:20128/v1` Ou use o painel do OmniRoute → **Ferramentas de CLI → Cline → Aplicar configuração**. --- #### KiloCode (CLI ou VS Code) **Modo CLI:** ```bash kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key ``` **Configurações do VS Code:** ```json { "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", "kilo-code.apiKey": "sk-your-omniroute-key" } ``` Ou use o painel do OmniRoute → **Ferramentas de CLI → KiloCode → Aplicar configuração**. --- #### Continue (extensão do VS Code) Edite `~/.continue/config.yaml`: ```yaml models: - name: OmniRoute provider: openai model: auto apiBase: http://localhost:20128/v1 apiKey: sk-your-omniroute-key default: true ``` Reinicie o VS Code após a edição. --- #### VS Code Insiders (`chatLanguageModels.json`) Use esta opção quando o VS Code Insiders estiver configurado para modelos com endpoints personalizados e você quiser que o OmniRoute funcione sem um campo de cabeçalho personalizado. **Local recomendado:** - Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json` - Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json` **Exemplo usando o alias tokenizado do OmniRoute:** ```json [ { "vendor": "customendpoint", "id": "auto", "name": "OmniRoute Auto", "family": "gpt-4", "version": "1.0.0", "url": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/chat/completions", "modelsUrl": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/models", "requestFormat": "openai-chat-completions", "contextWindow": 256000, "maxOutputTokens": 32768, "auth": { "type": "none" } } ] ``` **Observações:** - Substitua `sk-your-omniroute-key` por uma chave de API criada no OmniRoute. - O campo `url` deve apontar para `/api/v1/vscode/{token}/chat/completions`. - O campo `modelsUrl` deve apontar para `/api/v1/vscode/{token}/models`. - Prefira o fluxo normal com `/v1` + cabeçalho Bearer quando o cliente oferecer suporte a cabeçalhos personalizados. - Tokens incorporados à URL são uma alternativa de compatibilidade e podem aparecer nos logs do editor ou no histórico do proxy. --- #### Kiro CLI (Amazon) ```bash # Faça login na sua conta AWS/Kiro: kiro-cli login # A CLI usa autenticação própria — o OmniRoute não é necessário como backend para a própria Kiro CLI. # Use a kiro-cli junto com o OmniRoute para outras ferramentas. kiro-cli status ``` Para o aplicativo desktop **Kiro IDE**, use o endpoint MITM disponibilizado pelo OmniRoute em `/dashboard/cli-tools → Kiro`. --- ## 10. CLI interna do OmniRoute O binário `omniroute` fornece comandos para o ciclo de vida do servidor, configuração, diagnósticos e gerenciamento de provedores. Ponto de entrada: `bin/omniroute.mjs`. ```bash omniroute # Iniciar o servidor (porta padrão 20128) omniroute setup # Assistente de configuração interativo omniroute doctor # Verificar configuração, banco de dados, portas e ambiente de execução omniroute providers list # Conexões de provedores configuradas omniroute providers test-all # Testar todas as conexões ativas omniroute reset-password # Redefinir a senha do administrador omniroute logs # Transmitir logs de requisições omniroute health # Integridade detalhada (disjuntores, cache, memória) omniroute --version # Exibir a versão omniroute --help # Mostrar todos os comandos ``` ### Configuração e inicialização ```bash omniroute setup # Assistente de configuração interativo omniroute setup --non-interactive # Modo de CI/automação (lê variáveis de ambiente + opções) omniroute setup --password '' # Definir diretamente a senha do administrador omniroute setup --add-provider \ --provider openai \ --api-key '' \ --test-provider # Adicionar e testar um provedor de uma só vez ``` Variáveis de ambiente reconhecidas para configuração não interativa: | Variável | Finalidade | | ------------------- | ---------------------------------------------------------------------------- | | `OMNIROUTE_API_KEY` | Chave de API do provedor (vinculada a `--api-key` via `.env()` do Commander) | | `DATA_DIR` | Sobrescrever o diretório de dados do OmniRoute | Todas as outras entradas não interativas são passadas como opções, não como variáveis de ambiente: `--password`, `--provider`, `--provider-name`, `--provider-base-url`, `--default-model` (consulte as opções de `omniroute setup` acima). ### Diagnósticos ```bash omniroute doctor # Verificar configuração, banco de dados, portas, ambiente de execução, memória e atividade omniroute doctor --json # JSON legível por máquina omniroute doctor --no-liveness # Ignorar a sondagem de integridade HTTP omniroute doctor --host 0.0.0.0 # Sobrescrever o host da sondagem de atividade omniroute doctor --liveness-url # Sobrescrever a URL completa do endpoint de integridade ``` O doctor executa estas verificações: `Config`, `Database`, `Storage/encryption`, `Port availability`, `Node runtime`, `Native binary` (better-sqlite3), `Memory` e `Server liveness`. Ele encerra com um código diferente de zero se alguma verificação resultar em `fail`. ### Gerenciamento de provedores ```bash omniroute providers available # Catálogo de provedores do OmniRoute omniroute providers available --search openai # Filtrar o catálogo por ID/nome/alias/categoria omniroute providers available --category api-key # Filtrar por categoria (api-key, oauth, free, ...) omniroute providers available --json # JSON legível por máquina omniroute providers list # Conexões de provedores configuradas omniroute providers list --json omniroute providers test # Testar uma conexão configurada omniroute providers test-all # Testar todas as conexões ativas omniroute providers validate # Validação estrutural somente local omniroute providers add --credential-env PROVIDER_KEY omniroute providers import ./providers.json --dry-run --json omniroute providers auth # Fluxo OAuth existente omniroute providers edit --default-model omniroute providers remove --yes ``` `providers add/import/auth/edit/remove` priorizam a API e, portanto, funcionam no contexto local ou remoto ativo. A entrada de credenciais deve usar `--credential-stdin` ou `--credential-env`; `--dry-run --json` informa apenas a presença/estrutura com dados confidenciais ocultados. `providers available` lê o catálogo do OmniRoute; `providers list/test/test-all/validate` mantêm seu comportamento local com SQLite e não exigem que o servidor esteja em execução. Para um nó personalizado compatível com OpenAI ou Anthropic, associe as credenciais ao ID do nó retornado por `omniroute nodes add`, usando `omniroute keys add "$NODE_ID" --stdin`. Isso exige um servidor em execução e autenticação de gerenciamento para o contexto ativo. A CLI usa `POST /api/providers`, que valida o nó e copia as configurações de endpoint dele para a conexão. Um nó ausente, uma falha de autorização ou um servidor indisponível retorna um erro sem criar uma credencial de fallback local. `nodes add --base-url` define o endpoint do nó; ele é diferente do endereço do servidor em `OMNIROUTE_BASE_URL`. Para arquivos OpenAPI, use `omniroute openapi dump --format json --out ./openapi.json`; a opção global `--output` seleciona a formatação de exibição da CLI, não o nome de um arquivo de destino. ### Recuperação e redefinição ```bash omniroute reset-password # Redefinir a senha do administrador (também: omniroute-reset-password) omniroute reset-encrypted-columns # Mostrar aviso + simulação da redefinição de credenciais criptografadas omniroute reset-encrypted-columns --force # Realmente definir como nulas as credenciais criptografadas no SQLite ``` ### Exportação de credenciais (⚠ manuseie com cuidado) ```bash omniroute auth export # Mostrar aviso + etapa de confirmação — sem acesso ao banco de dados omniroute auth export --force # Exportar as credenciais DESCRIPTOGRAFADAS de TODAS as conexões para stdout como JSON omniroute auth export --force --id # Exportar somente a conexão correspondente omniroute auth export --force --format env # Emitir linhas OMNIROUTE__= omniroute auth export --force --out creds.json # Gravar em um arquivo (criado com permissões 0600) ``` `auth export` é **somente local** (leitura direta do SQLite, sem rota HTTP) e intencionalmente exibe/grava valores **em texto simples** de `apiKey`/`accessToken`/`refreshToken`/`idToken` — isso é um recurso, não um bug. Nada é lido do banco de dados e nada é descriptografado sem `--force`. Um banner de aviso no stderr sempre é exibido antes que qualquer texto simples seja emitido. Requer que `STORAGE_ENCRYPTION_KEY` esteja definida. Um campo cuja descriptografia falhar (chave antiga, texto cifrado corrompido) será informado como `DecryptFailed: true`, em vez de interromper toda a exportação ou expor o erro subjacente. ### Outros subcomandos Estes pressupõem que um servidor OmniRoute esteja em execução, salvo indicação em contrário: ```bash omniroute status # Status abrangente do ambiente de execução omniroute logs # Transmite logs de requisições (--json, --search, --follow) omniroute config list # Exibe as ferramentas de CLI configuradas omniroute provider list # Lista os provedores disponíveis (alias de providers list) omniroute provider add # Registra o OmniRoute como provedor em uma ferramenta omniroute keys add | list | remove # Gerencia chaves de API omniroute models [provider] # Lista modelos (--json, --search) omniroute combo list | switch | create | delete omniroute backup # Cria um snapshot da configuração + banco de dados omniroute restore # Restaura a partir de um snapshot anterior omniroute health # Integridade detalhada (disjuntores, cache, memória) omniroute quota # Uso da cota do provedor omniroute cache # Status do cache omniroute cache clear # Limpa os caches semântico + de assinaturas omniroute mcp status | restart # Status / reinicialização do servidor MCP omniroute a2a status | card # Status do servidor A2A / cartão do agente omniroute tunnel list | create | stop # Gerencia túneis (cloudflare/tailscale/ngrok) omniroute env show | get | set # Inspeciona / define variáveis de ambiente (temporárias) omniroute test # Teste rápido de conectividade do provedor omniroute update # Verifica se há atualizações omniroute completion # Gera o preenchimento automático do shell ``` ### Flags comuns | Flag | Descrição | | ------------------- | ----------------------------------------------------------- | | `--no-open` | Não abre automaticamente o navegador ao iniciar | | `--port ` | Substitui a porta da API (padrão: 20128) | | `--mcp` | Executa como servidor MCP via stdio (para IDEs) | | `--non-interactive` | Modo de CI (sem prompts; lê a partir do ambiente/das flags) | | `--json` | Saída JSON legível por máquina (doctor, providers etc.) | | `--help`, `-h` | Exibe a ajuda específica do comando | | `--version`, `-v` | Exibe a versão instalada | --- ## Endpoints de API disponíveis | Endpoint | Descrição | Usar para | | -------------------------- | --------------------------------- | -------------------------------------- | | `/v1/chat/completions` | Chat padrão (todos os provedores) | Todas as ferramentas modernas | | `/v1/responses` | API Responses (formato OpenAI) | Codex, fluxos de trabalho agênticos | | `/v1/completions` | Conclusões de texto legadas | Ferramentas antigas que usam `prompt:` | | `/v1/embeddings` | Embeddings de texto | RAG, busca | | `/v1/images/generations` | Geração de imagens | GPT-Image, Flux etc. | | `/v1/audio/speech` | Conversão de texto em fala | ElevenLabs, OpenAI TTS | | `/v1/audio/transcriptions` | Conversão de fala em texto | Deepgram, AssemblyAI | Exemplos prontos para colar com uma URL tokenizada do OmniRoute: ```txt Exemplo de token: sk-a3ab3c080beaee3a-69f4a4-070d71af Base padrão da OpenAI: http://localhost:20128/v1 Modelos do VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models Chat do VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions Responses do VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses Tags do Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags Chat do Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat ``` --- ## Solução de problemas | Erro | Causa | Correção | | ------------------------------------------------ | -------------------------------------- | ---------------------------------------------------------------- | | `Connection refused` | O OmniRoute não está em execução | `omniroute serve` | | `401 Unauthorized` | Chave de API incorreta | Verifique em `/dashboard/api-manager` | | `No combo configured` | Nenhuma combinação de roteamento ativa | Configure em `/dashboard/combos` | | A CLI mostra "not installed" | O binário não está no PATH | Verifique com `which ` | | O painel mostra "not detected" após a instalação | Cache desatualizado | Clique em "⟳ Refresh detection" no painel | | Link antigo `/dashboard/cli-tools` | Favorito anterior à v3.8.6 | Redirecionado automaticamente para `/dashboard/cli-code` (308) | | Link antigo `/dashboard/agents` | Favorito anterior à v3.8.6 | Redirecionado automaticamente para `/dashboard/acp-agents` (308) | ## Gerenciar a política de chaves de inferência com a CLI do OmniRoute Use um contexto de gerenciamento autenticado (consulte [Modo remoto](../guides/REMOTE-MODE.md)) para inspecionar ou atualizar uma chave de inferência existente por meio de seu ID: ```bash omniroute --output json keys policy show KEY_ID omniroute keys policy set KEY_ID --unrestricted omniroute --output json keys policy show KEY_ID ``` `--unrestricted` é um alias para `--model-access-mode all`. A atualização limpa a lista de modelos permitidos. Ela preserva escopos, regras de conexão, modelos bloqueados, limites de requisições e limites de custo; portanto, esses outros controles ainda podem negar uma requisição. Um `--allowed-models ""` explícito também seleciona `all`; combine-o com `--model-access-mode restricted` para manter uma chave restrita sem modelos permitidos. Uma lista não vazia separada por vírgulas seleciona `restricted`, a menos que isso seja especificado explicitamente. A combinação contraditória de `all` com uma lista de permissões não vazia é rejeitada antes do envio de uma requisição. `--rate-limit 30` define as requisições por minuto e preserva as regras de outras janelas de tempo. `--max-cost 5` habilita o limite diário em USD sem alterar o limite semanal; `--max-cost 0` remove o limite diário e preserva a configuração existente do limite de uso e o limite semanal. Os campos de política omitidos permanecem inalterados. Alterações de limite de requisições leem primeiro a política atual; evite edições simultâneas no array de limites de requisições da mesma chave. Os comandos de política usam `GET`/`PATCH /api/keys/{id}` autenticados e respeitam o contexto ativo e a opção global `--api-key`. A saída JSON contém apenas os campos da política, sem a chave armazenada nem sua representação mascarada. Uma credencial exclusiva para inferência não pode autorizar alterações de gerenciamento. Uma resposta 401/403 exige a verificação da credencial e do contexto de gerenciamento; ela não comprova uma falha no token local da CLI nem no salt. Consulte [Token da CLI](../security/CLI_TOKEN.md) para conhecer o contrato separado de autenticação local.