# Environment Variables Reference (Português (Portugal)) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/ENVIRONMENT.md) · 🇪🇹 [am](../../../am/docs/reference/ENVIRONMENT.md) · 🇸🇦 [ar](../../../ar/docs/reference/ENVIRONMENT.md) · 🇦🇿 [az](../../../az/docs/reference/ENVIRONMENT.md) · 🇧🇬 [bg](../../../bg/docs/reference/ENVIRONMENT.md) · 🇧🇩 [bn](../../../bn/docs/reference/ENVIRONMENT.md) · 🇧🇦 [bs](../../../bs/docs/reference/ENVIRONMENT.md) · 🇨🇿 [cs](../../../cs/docs/reference/ENVIRONMENT.md) · 🇩🇰 [da](../../../da/docs/reference/ENVIRONMENT.md) · 🇩🇪 [de](../../../de/docs/reference/ENVIRONMENT.md) · 🇬🇷 [el](../../../el/docs/reference/ENVIRONMENT.md) · 🇪🇸 [es](../../../es/docs/reference/ENVIRONMENT.md) · 🇪🇪 [et](../../../et/docs/reference/ENVIRONMENT.md) · 🇮🇷 [fa](../../../fa/docs/reference/ENVIRONMENT.md) · 🇫🇮 [fi](../../../fi/docs/reference/ENVIRONMENT.md) · 🇫🇷 [fr](../../../fr/docs/reference/ENVIRONMENT.md) · 🇮🇪 [ga](../../../ga/docs/reference/ENVIRONMENT.md) · 🇮🇳 [gu](../../../gu/docs/reference/ENVIRONMENT.md) · 🇳🇬 [ha](../../../ha/docs/reference/ENVIRONMENT.md) · 🇮🇱 [he](../../../he/docs/reference/ENVIRONMENT.md) · 🇮🇳 [hi](../../../hi/docs/reference/ENVIRONMENT.md) · 🇭🇷 [hr](../../../hr/docs/reference/ENVIRONMENT.md) · 🇭🇺 [hu](../../../hu/docs/reference/ENVIRONMENT.md) · 🇦🇲 [hy](../../../hy/docs/reference/ENVIRONMENT.md) · 🇮🇩 [id](../../../id/docs/reference/ENVIRONMENT.md) · 🇳🇬 [ig](../../../ig/docs/reference/ENVIRONMENT.md) · 🇮🇹 [it](../../../it/docs/reference/ENVIRONMENT.md) · 🇯🇵 [ja](../../../ja/docs/reference/ENVIRONMENT.md) · 🇬🇪 [ka](../../../ka/docs/reference/ENVIRONMENT.md) · 🇰🇭 [km](../../../km/docs/reference/ENVIRONMENT.md) · 🇮🇳 [kn](../../../kn/docs/reference/ENVIRONMENT.md) · 🇰🇷 [ko](../../../ko/docs/reference/ENVIRONMENT.md) · 🇱🇹 [lt](../../../lt/docs/reference/ENVIRONMENT.md) · 🇱🇻 [lv](../../../lv/docs/reference/ENVIRONMENT.md) · 🇮🇳 [ml](../../../ml/docs/reference/ENVIRONMENT.md) · 🇮🇳 [mr](../../../mr/docs/reference/ENVIRONMENT.md) · 🇲🇾 [ms](../../../ms/docs/reference/ENVIRONMENT.md) · 🇲🇹 [mt](../../../mt/docs/reference/ENVIRONMENT.md) · 🇲🇲 [my](../../../my/docs/reference/ENVIRONMENT.md) · 🇳🇵 [ne](../../../ne/docs/reference/ENVIRONMENT.md) · 🇳🇱 [nl](../../../nl/docs/reference/ENVIRONMENT.md) · 🇳🇴 [no](../../../no/docs/reference/ENVIRONMENT.md) · 🇮🇳 [or](../../../or/docs/reference/ENVIRONMENT.md) · 🇮🇳 [pa](../../../pa/docs/reference/ENVIRONMENT.md) · 🇵🇭 [phi](../../../phi/docs/reference/ENVIRONMENT.md) · 🇵🇱 [pl](../../../pl/docs/reference/ENVIRONMENT.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/ENVIRONMENT.md) · 🇷🇴 [ro](../../../ro/docs/reference/ENVIRONMENT.md) · 🇷🇺 [ru](../../../ru/docs/reference/ENVIRONMENT.md) · 🇱🇰 [si](../../../si/docs/reference/ENVIRONMENT.md) · 🇸🇰 [sk](../../../sk/docs/reference/ENVIRONMENT.md) · 🇸🇮 [sl](../../../sl/docs/reference/ENVIRONMENT.md) · 🇷🇸 [sr](../../../sr/docs/reference/ENVIRONMENT.md) · 🇸🇪 [sv](../../../sv/docs/reference/ENVIRONMENT.md) · 🇰🇪 [sw](../../../sw/docs/reference/ENVIRONMENT.md) · 🇮🇳 [ta](../../../ta/docs/reference/ENVIRONMENT.md) · 🇮🇳 [te](../../../te/docs/reference/ENVIRONMENT.md) · 🇹🇭 [th](../../../th/docs/reference/ENVIRONMENT.md) · 🇹🇷 [tr](../../../tr/docs/reference/ENVIRONMENT.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/ENVIRONMENT.md) · 🇵🇰 [ur](../../../ur/docs/reference/ENVIRONMENT.md) · 🇺🇿 [uz](../../../uz/docs/reference/ENVIRONMENT.md) · 🇻🇳 [vi](../../../vi/docs/reference/ENVIRONMENT.md) · 🇳🇬 [yo](../../../yo/docs/reference/ENVIRONMENT.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/ENVIRONMENT.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/ENVIRONMENT.md) --- > Referência completa para cada variável de ambiente reconhecida por OmniRoute. Para obter um modelo de início rápido, consulte [`.env.example`](../../.env.example). > [!IMPORTANT] > Cada variável aqui documentada também deve aparecer em `.env.example` e cada variável em `.env.example` deve aparecer aqui. `npm run check:env-doc-sync` impõe isso no commit e no CI. Para omitir uma variável propositadamente, adicione-a à lista de permissões dentro `scripts/check/check-env-doc-sync.mjs`. --- ## Índice - [1. Segredos necessários](#1-required-secrets) - [2. Armazenamento e base de dados](#2-storage--database) - [3. Rede e portas](#3-network--ports) - [4. Segurança e autenticação](#4-security--authentication) - [5. Higienização de entrada e proteção PII](#5-input-sanitization--pii-protection) - [6. Políticas de ferramentas e encaminhamento](#6-tool--routing-policies) - [7. URLs e sincronização na nuvem](#7-urls--cloud-sync) - [8. Proxy de saída](#8-outbound-proxy) - [9. Integração da ferramenta CLI](#9-cli-tool-integration) - [10. Agente interno e integrações MCP](#10-internal-agent--mcp-integrations) - [11. Credenciais do prestador OAuth](#11-oauth-provider-credentials) - [12. Substituições utilizador-agente do fornecedor](#12-provider-user-agent-overrides) - [13. Compatibilidade de impressão digital CLI](#13-cli-fingerprint-compatibility) - [14. Fornecedores-chave API](#14-api-key-providers) - [15. Configurações de tempo limite](#15-timeout-settings) - [16.º Registo](#16-logging) - [17. Otimização da memória](#17-memory-optimization) - [18. Sincronização de preços](#18-pricing-sync) - [19. Sincronização do modelo (desenvolvimento)](#19-model-sync-dev) - [20. Configurações específicas do prestador](#20-provider-specific-settings) - [21. Proxy de saúde](#21-proxy-health) - [22. Depuração](#22-debugging) - [23. Integração GitHub](#23-github-integration) - [24. Sandbox de habilidades (v3.8.0 +)](#24-skills-sandbox-v380) - [27. Feed de radar (auto-hospedagem)](#27-radar-feed-self-hosting) - [Cenários de implantação](#deployment-scenarios) - [Auditoria: variáveis removidas/mortas](#audit-removed--dead-variables) --- ## 1. Segredos necessários Segredos não definidos marcados** Sim** são gerados automaticamente na primeira execução (`JWT_SECRET`, `API_KEY_SECRET`) e persistidos em `server.env` no directório de dados — define-os explicitamente quando esse directório é efémero. A exceção é `OMNIROUTE_WS_BRIDGE_SECRET`: não é persistido para `server.env` — os pontos de entrada do servidor criarem um valor efémero por inicialização que apenas a ponte em processo pode utilizar, pelo que os clientes da ponte externa necessitam de o definir explicitamente. | Variável | Obrigatório | Predefinição | Arquivo de origem | Descrição | | ---------------------------- | ------------------ | --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `JWT_SECRET` | **Sim** | _(nenhum)_ | `src/lib/auth` | Signs/verifies todos os cookies de sessão do painel (JWT). Gere com `openssl rand -base64 48`. | | `API_KEY_SECRET` | **Sim** | _(nenhum)_ | `src/lib/db/apiKeys.ts` | Chave de encriptação AES para valores de chave API em repouso em SQLite. Gere com `openssl rand -hex 32`. | | `INITIAL_PASSWORD` | Não | _(desativado)_ | `src/lib/auth/managementPassword.ts` | Define a palavra-passe do painel na inicialização enquanto ainda não foi guardada nenhuma; ignorado quando uma palavra-passe é guardada. As instalações npm e source copiam `.env.example` para `.env`, por isso começam com o seu espaço reservado publicamente conhecido `CHANGEME`: substitua-o antes da primeira inicialização ou defina `INITIAL_PASSWORD=` (vazio) nesse `.env` para criar a palavra-passe no assistente de integração na primeira visita, como faz um valor não definido (o padrão da imagem Docker ). Altere uma palavra-passe guardada no Dashboard → Settings → Security ou execute `omniroute reset-password` (`node bin/reset-password.mjs` numa verificação de origem) com `DATA_DIR` definido para o diretório de dados do servidor. | | `OMNIROUTE_WS_BRIDGE_SECRET` | **Sim** (produção) | _(desativado)_ | `src/app/api/internal/codex-responses-ws/route.ts` | Segredo partilhado para a ponte interna Codex Responses WebSocket. Pedidos de ponte autênticos entre o relé Electron/browser WS e OmniRoute. ⚠️**REQUIRED em produção — quando não está definido, todos os pedidos de ponte WS são rejeitados.** Gere com `openssl rand -base64 32`. | | `OMNIROUTE_SW_BUILD_ID` | Não | _(git SHA)_ | `next.config.mjs`, `scripts/build/assembleStandalone.mjs` | ID explícito de bloqueio de cache do trabalhador de serviço para a shell PWA (#11779); primeiro na cadeia de resolução. | | `SOURCE_VERSION` | Não | _(desativado)_ | `next.config.mjs`, `scripts/build/assembleStandalone.mjs` | O segundo na cadeia — definido pelos construtores PaaS (por exemplo, estilo Heroku) como o commit implantado. | | `NEXT_PUBLIC_SW_BUILD_ID` | Não | _(derivado)_ | `src/shared/components/PwaRegister.tsx` | Valor público em tempo de construção que o cliente utiliza para registar `/sw.js?v=…`; derivado dos dois anteriores, então o git SHA. | | `OMNIROUTE_PEER_STAMP_TOKEN` | Não (automático) | _(automático por arranque)_ | `src/server/authz/policies/management.ts` | O segredo por processo que prova que o carimbo de IP de ponto fidedigno veio do próprio servidor HTTP do OmniRoute(`scripts/dev/peer-stamp.mjs`). O middleware authz confia na localidade do pedido (loopback/LAN gating de rotas LOCAL_ONLY ) apenas quando o carimbo carrega este token. Gerado automaticamente cada arranque — não é definido; fixe-o apenas para configurações de vários processos que devem partilhar o carimbo. | | `OMNIROUTE_TRUSTED_PROXIES` | Não | _(desativado)_ | `scripts/dev/peer-stamp.mjs` | Intervalos IPs ou CIDR separados por vírgula de proxies reversos cujo `X-Forwarded-For` / `X-Real-IP` a lista IP allow/deny pode acreditar, para além do loopback, endereços de rede privada e Cloudflare edges , que são sempre fiáveis. Apenas necessário para um proxy em qualquer outro endereço público; caso contrário, o próprio endereço desse proxy é o que o filtro julga. As chaves de aceleração por cliente (`/api/v1/relay/chat/completions`) do relé no mesmo endereço de cliente resolvido, nunca apenas no encaminhamento de cabeçalhos. | ### Comandos de geração ```bash # Generate all four secrets at once: echo "JWT_SECRET=$(openssl rand -base64 48)" echo "API_KEY_SECRET=$(openssl rand -hex 32)" echo "INITIAL_PASSWORD=$(openssl rand -base64 16)" echo "OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -base64 32)" ``` > [!CAUTION] > Nunca envie ficheiros `.env` com segredos reais para controlo de versão. O `.gitignore` já elimina `.env`, mas verifique antes de enviar. --- ## 2. Armazenamento e base de dados OmniRoute usa**SQLite** (via `better-sqlite3`) para todas as persistências. Estas variáveis controlam a localização, a encriptação e o ciclo de vida dos dados. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------ | ----------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATA_DIR` | `~/.omniroute/` | `src/lib/db/core.ts` | Directório raiz para SQLite DB, backups e ficheiros de dados. Substituição de volumes Docker ou caminhos personalizados. | | `OMNIROUTE_ALLOW_DEFAULT_DATA_DIR` | _(desativado)_ | `src/lib/dataPaths.ts` | Escotilha de fuga para o guarda DATA_DIR test/eval #10428). Os testes e sondagens Node eval/print (`-e`/`--eval`/`-p`/`--print`, incluindo formulários `--eval=`/`--print=` ) sem `DATA_DIR` são redirecionados para um diretório temporário descartável para que não possam abrir a base de dados real do operador; defina como `1` para voltar ao diretório real. | | `OMNIROUTE_BUILD_SHA` | _(desativado)_ | `src/lib/monitoring/buildSha.ts` | Git SHA do artefacto em execução. Carimbado por `npm run build:release`; injetável em contentores enviados sem o `dist/BUILD_SHA` sentinela . Apareceu como `system.buildSha` em `/api/monitoring/health`. | | `OMNIROUTE_RELEASE_REF` | `origin/main` | `scripts/build/buildProvenance.ts` | Ref o portão de proveniência do pack-artefacto verifica o build SHA (#10427). | | `OMNIROUTE_ALLOW_CANARY_BUILD` | _(desativado)_ | `scripts/build/buildProvenance.ts` | Defina como `1` para permitir empacotar uma compilação cujo SHA não esteja na linha de lançamento, registando-a como um canário deliberado em vez de falhar no portão (#10427). | | `OMNIROUTE_SMOKE_API_KEY` | _(desativado)_ | `scripts/ops/deploy-canary.mjs` | Chave API para o probe smoke canary-deploy, enviada como `Authorization: Bearer` em `/v1/chat/completions`. Utilizado apenas pelo script de implementação (#10429), nunca pelo servidor. Não relacionado com as variáveis `OMNIROUTE_SMOKE_*` do chicote de fumo CLI opcional (`RUN_CLI_SMOKE=1`, `OMNIROUTE_SMOKE_BASE_URL/MODEL/API_KEY_ENV/TARGETS/TIMEOUT_MS` em `tests/integration/upstream-cli-smoke.int.test.ts`) — ver [CLI Integrações → Varrimento de fumo real](../guides/CLI-INTEGRATIONS.md). | | `OMNIROUTE_BUILDING` | _(desativado)_ | `src/lib/buildPhase.ts` | Sinal de fase de construção (#10060): definido como `1` por `scripts/build/build-next-isolated.mjs` e herdado por cada trabalhador de construção gerado para que a camada DB devolva um stub não operacional em vez de carregar o complemento better-sqlite3 nativo (que aborta o trabalhador na saída). Nunca configure para o servidor em execução. | | `OMNIROUTE_SKIP_NATIVE_DEP_CHECK` | `0` | `scripts/check/check-native-deps.mjs` | Defina como `1` para ignorar a verificação opcional de pré-construção de dependência nativa para árvores exóticas vendidas. Isto não torna uma dependência ausente edificável; utilizar apenas quando as dependências nativas forem fornecidas fora da banda. | | `OMNIROUTE_DATA_DIR` | _(desativado)_ | `open-sse/executors/promptql/threadSticky.ts` | **Alias alternativa** para `DATA_DIR`, verificado apenas quando `DATA_DIR` não está definido. Utilizado para localizar a cache de sessão fixa de thread no disco do executor PromptQL (`/promptql-thread-sessions.json`); se não estiver definida nenhuma var, o cache permanecerá apenas na memória (não persistirá nas reinicializações). | | `OMNIROUTE_PLUGINS_DIR` | _(desativado)_ | `src/lib/plugins/scanner.ts` | Diretório o** scanner de plug-in de tempo de execução** lê — e a raiz que o gestor de plugins instala no — substituindo o padrão derivado de casa (#11827). Aponte-o para a árvore de plug-ins montada no bind no Docker/K8s em vez de mover HOME apenas para realocar o caminho de varrimento (HOME também rege todos os outros comportamentos relativos à casa). Desmarque = `~/.omniroute/plugins` ou `/tmp/.omniroute/plugins` quando o processo não exporta nenhum home — a não descoberta silenciosa que esta variável remove. O diretório resolvido é registado uma vez no arranque como `scanner.dir_resolved` com a entrada que venceu. Apenas no lado do servidor: os plug-ins de comando CLI mantêm o seu próprio `OMNIROUTE_PLUGIN_PATH` (secção 9). | | `STORAGE_ENCRYPTION_KEY` | _( = vazio desativado)_ | `src/lib/db/encryption.ts` | Chave AES para encriptação completa da base de dados SQLite em repouso. Gere com `openssl rand -hex 32`. | | `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/build/bootstrap-env.mjs`, `electron/main.js` | Rótulo da versão da chave de encriptação. Aumente ao executar a rotação de chaves para suportar a desencriptação de cópias de segurança antigas. | | `DISABLE_SQLITE_AUTO_BACKUP` | `false` | `src/lib/db/backup.ts` | Quando `true`, ignora os backups de ficheiros routine/pre-write SQLite (models.dev preços save/clear, gravações de configurações). Os backups manuais e de pré-restauro ainda são executados. Isso acontece** não** desativar o instantâneo de segurança durável obrigatório do executor de migração ou o protetor de migração em massa para um DB persistente existente. Os backups não manuais estão limitados a um máximo de uma vez a cada 60 minutos. Painel** Configurações de armazenamento →** pode desativar o backup automático de rotina de forma independente. | | `OMNIROUTE_SQLITE_SLOW_MS` | _(unset/off)_ | `src/lib/db/adapters/slowDiagnostics.ts` | Milissegundos; valores abaixo de 1 ou não numéricos estão desligados; avisa no máximo uma vez a cada 10s; A linha de registo apenas tem driver, operação e elapsedMs. | | `OMNIROUTE_SQLITE_OPTIMIZE_ENABLED` | `true` | `src/lib/db/sqlitePlannerStats.ts` | Manutenção das estatísticas do planeador em segundo plano, independentemente da limpeza de retenção: a primeira passagem de limpeza ativada (normalmente 30s após o arranque, após as migrações) executa `PRAGMA optimize=0x10002`; passagens subsequentes a cada 6h executam `PRAGMA optimize` (ou `PRAGMA optimize=0x00002` para análise ilimitada). `false` ou `0` desativa toda a manutenção (sem distinção entre maiúsculas e minúsculas, espaços em branco cortados). As bases de dados de memória e os caminhos de cópia de segurança de leitura apenas não são afetados. As avarias são registadas, não lançadas. | | `OMNIROUTE_SQLITE_ANALYSIS_LIMIT` | `400` | `src/lib/db/sqlitePlannerStats.ts` | Define `PRAGMA analysis_limit` antes da otimização. Os números inteiros decimais são fixados em [0, 100000]; Os valores malformed/empty são padronizados como 400. `0` solicita análise exata e ilimitada de tabelas selecionadas pela otimização; a passagem periódica limpa o bit de otimização de amostragem de SQLite para honrar isso. Nenhuma instrução de análise SQL independente é executada. | | `OMNIROUTE_CRYPT_KEY` | _(desativado)_ | `src/lib/db/encryption.ts` | **Alias herdada** para `STORAGE_ENCRYPTION_KEY`. Aceito como substituto quando a variável primária está ausente. | | `OMNIROUTE_API_KEY_BASE64` | _(desativado)_ | `src/lib/db/encryption.ts` | **Alias herdada** (formulário Base64-encoded ) aceite como substituto. Descodificado automaticamente antes da utilização. | | `OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS` | _(desativado)_ | `src/lib/db/core.ts` | Substitua o intervalo periódico de verificação de integridade SQLite (ms). Quando não definidos, os padrões são derivados de `NODE_ENV`. | | `OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS` | _(removido)_ | `src/lib/db/walMaintenance.ts` | **Removido.** Um `wal_checkpoint(TRUNCATE)` periódico ao vivo pode invalidar o mapeamento do índice wal partilhado e bloquear o processo com SIGBUS (#13973), de tal forma que o agendador já não existe. A variável é inerte: um valor positivo regista um aviso de descontinuação único, enquanto `0` ou unset permanece silencioso. O WAL é mantido pelos pontos de verificação PASSIVE (abaixo) e truncado pelo ponto de verificação de encerramento. | | `OMNIROUTE_WAL_PASSIVE_INTERVAL_MS` | `300000` (5m) | `src/lib/db/walMaintenance.ts` | Substitua o intervalo `wal_checkpoint(PASSIVE)` frequente (ms). Mantém os quadros WAL pendentes pequenos para que os pontos de verificação permaneçam rápidos e o ficheiro WAL permaneça limitado entre truncamentos de encerramento. `0` desativa. | | `OMNIROUTE_WAL_GUARD_MAX_MB` | `256` | `src/lib/db/walMaintenance.ts` | Quando um tick PASSIVE encontrar o ficheiro WAL acima deste tamanho, execute `wal_checkpoint(RESTART)` para que o WAL reinicie sem reescrever o índice wal mapeado. Os pontos de verificação do modo truncado ao vivo foram removidos (ver linha `OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS` ). | | `OMNIROUTE_PRESSURE_SELF_RESTART` | `false` | `open-sse/utils/resourcePressure.ts` | Defina como `1`/`true`/`yes`/`on` para sair do processo após a pressão crítica de recursos ser sustentada para `OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS`, permitindo que um supervisor (systemd `Restart=always`, política de reinicialização Docker ) traga de volta um processo limpo em vez de servir 503s indefinidamente. | | `OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS` | `120000` (2m) | `open-sse/utils/resourcePressure.ts` | Quanto tempo deve persistir a pressão crítica antes de a saída de reinicialização automática ser acionada. | | `OMNIROUTE_PRESSURE_PSI_DISABLED` | `false` | `open-sse/utils/resourcePressurePolicy.ts` | Defina como `1`/`true`/`yes`/`on` para ignorar `/proc/pressure/memory` em todo o host (`psi_some` / `psi_full`) quando um vizinho barulhento dispara 503s enquanto este processo está correto (#13124). Os protetores de heap Cgroup e V8 permanecem ativados. PSI também deixa de contar como prova de aceleração do kernel para `cgroup_high`: um total de cgroup acima de `memory.high` torna-se crítico apenas num aumento de `memory.events` `high`/`max`. Sem `memory.events` a proporção bruta é mantida. | | `OMNIROUTE_SQLJS_WASM_PATH` | _(detecção automática)_ | `src/lib/db/adapters/sqljsAdapter.ts` | Caminho explícito (absoluto ou relativo ao cwd) para `sql-wasm.wasm` quando se utiliza o adaptador de substituição `sql.js` WASM. Detetado automaticamente através de dependências de pacotes e layouts candidatos quando não definidos. | | `OMNIROUTE_BATCH_RETENTION_DAYS` | `30` | `src/lib/db/cleanup.ts` | Dias em que um terminal (completed/failed/cancelled/expired) Os pontos de verificação do trabalho API em lote, os ficheiros input/output/error referenciados e a linha são mantidos pela varredura de limpeza automática antes da eliminação. Só entra em vigor quando `BATCH_AND_FILE_AUTO_CLEANUP_ENABLED` está ativado; corresponde à janela de retenção de saída do próprio lote API do OpenAI. Não afeta a rota `DELETE /api/v1/batches/delete-completed` acionada pelo operador, que permanece incondicional (sem filtro de idade) por design. | | `BATCH_AND_FILE_AUTO_CLEANUP_ENABLED` | `false` | `src/lib/db/cleanup.ts` | Quando `true`, deixe que a limpeza automática apague as tarefas do terminal Batch API (e os seus pontos de verificação) após `OMNIROUTE_BATCH_RETENTION_DAYS` e limpe o conteúdo BLOB dos ficheiros carregados para além dos seus próprios `expires_at`. Desativado por predefinição: cada instalação existente mantém estes dados exatamente como antes até que um operador os aceite. Além disso, um sinalizador de recurso editável no painel — consulte `docs/reference/FEATURE_FLAGS.md` → Runtime. | | `OMNIROUTE_SKIP_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts`, `src/lib/db/healthCheck.ts` | Defina como `1` para ignorar totalmente a verificação de integridade DB no arranque. Útil para tarefas de curta duração e testes de integração. | | `OMNIROUTE_FORCE_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts` | Defina como `1` para forçar a ativação do ciclo DB healthcheck, mesmo quando normalmente seria ignorado (por exemplo, tarefas de curta duração). | | `OMNIROUTE_SKIP_POSTINSTALL` | `0` | `scripts/postinstall.mjs` | Defina como `1` para ignorar o aquecimento do tempo de execução nativo durante `npm install`. Útil em instalações CI/headless onde o sqlite já está compilado. | | `OMNIROUTE_MIGRATIONS_DIR` | _(detecção automática)_ | `src/lib/db/migrationRunner.ts` | Substitua o diretório que o executor de migração verifica. Útil ao enviar migrações agrupadas em compilações personalizadas. | | `OMNIROUTE_EXTRA_MIGRATIONS_DIRS` | _(desativado)_ | `src/lib/db/migrationRunner/extraDirs.ts` | Diretórios de migração adicionais como entradas `namespace=dir` separadas pelo delimitador de caminho da plataforma (por exemplo, `ee=/opt/app/enterprise/db/migrations`). Os ficheiros aí encontrados são registados como `-`, pelo que uma distribuição que envia as suas próprias migrações nunca colide com os slots numéricos upstream. Uma entrada malformada, um namespace inválido ou um diretório em falta é lançado no arranque, em vez de ignorar silenciosamente o esquema. | | `OMNIROUTE_MAX_PENDING_MIGRATIONS` | `50` | `src/lib/db/migrationRunner.ts` | Limite de segurança para migrações pendentes em massa (#3416). A inicialização é interrompida se mais do que este número de migrações estiverem pendentes num DB existente (protege contra uma tabela de rastreio apagada). Aumente-o para restaurar um backup mais antigo; defina como `0` para desativar a verificação. | | `OMNIROUTE_INSTALL_UPGRADE_WORKDIR` | _(`/.install-upgrade`)_ | `scripts/check/check-install-upgrade.mjs` | Diretório de trabalho para o release gate `check:install-upgrade`. Necessita de aproximadamente 12 GB (duas árvores de instalação ~ 3 GB mais o tarball), pelo que não deve ser executado num tmpfs pequeno — no executor auto-hospedado `/tmp` é um tmpfs com suporte de RAM de 12 GB e o portão esgotou-o, truncando o pacote. | | `OMNIROUTE_SPEND_FLUSH_INTERVAL_MS` | _(padrão no código)_ | `src/lib/spend/batchWriter.ts` | Intervalo de libertação (ms) para o gravador spend/cost em lote. Valores mais baixos reduzem a coalescência de gravação; valores mais elevados reduzem a contenção DB. | | `OMNIROUTE_SPEND_MAX_BUFFER_SIZE` | _(padrão no código)_ | `src/lib/spend/batchWriter.ts` | Máximo de entradas de despesas armazenadas em buffer antes de uma libertação forçada. Aumente as implementações de alto QPS; menor quando a memória limitada é mais importante. | | `OMNIROUTE_PROXY_FETCH_DEBUG` | _(desativado)_ | `open-sse/utils/proxyFetch.ts` | Defina como `"true"` para emitir registos de depuração `[ProxyFetch]` no caminho de retransmissão Vercel. Desativado por defeito para evitar fugas de dicas de encaminhamento. | | `OMNIROUTE_PROXY_CORE_BINARY_PATH` | _(desativado)_ | `src/lib/proxySubscription/coreConfig/sync.ts` | Caminho absoluto do binário principal do proxy local (um ficheiro denominado `sing-box` / `mihomo`) que verifica uma configuração principal gerada antes de substituir o ficheiro adotado. Unset escreve `.generated` apenas ao lado do ficheiro adoptado. Apenas ambiente host: nunca armazenado na base de dados nem aceite pela gestão API, pois o binário é executado. | | `OMNIROUTE_PROXY_CORE_RELOAD_COMMAND` | _(desativado)_ | `src/lib/proxySubscription/coreConfig/reload.ts` | Como o núcleo do proxy local é recarregado após uma substituição de configuração verificada: uma matriz de argumentos JSON executada sem um shell ou exatamente `external` quando um observador externo aplica o ficheiro. Nunca armazenado na base de dados nem exposto através do API. | | `PROXY_LOG_INCLUDE_IPS` | `false` | `src/lib/proxyLogger.ts` | Configure como `"true"` ou `"1"` para incluir client/egress IPs e o prefixo da conta na linha detalhada do registo do processo `[ProxyEgress]`. Mantido OFF por defeito para que o registo do processo não vaze IPs ou o prefixo da conta. | | `OMNIROUTE_DEBUG` | _(desativado)_ | `bin/cli/commands/quota.mjs` | Defina como `1` para imprimir os diagnósticos de tempo por pedido (`[omniroute] GET completed in Nms`) dos comandos CLI quota para stderr. | | `OMNIROUTE_HEALTHCHECK_PATH` | _(auto)_ | `scripts/dev/healthcheck.mjs` | Caminho explícito investigado pela verificação de integridade do contentor. Não definido, o probe o deriva de `OMNIROUTE_BASE_PATH`; configurá-lo opta novamente pelo endpoint de monitorização profunda. | | `OMNIROUTE_DEBUG_COMPLETION` | _(desativado)_ | `bin/cli/commands/completion.mjs` | Defina como qualquer valor não vazio para emitir diagnósticos `[omniroute completion]` dos caminhos de cache de conclusão da shell CLI (read/refresh/write). Desativado por defeito — estes caches falham silenciosamente para que um cache missing/corrupt nunca interrompa o preenchimento do separador. | | `BATCH_RETRY_DURATION_MS` | `86400000` (24h) | `open-sse/services/batchProcessor.ts` | Janela máxima de novas tentativas para artigos de lote individuais (ms). Os itens que excedam esta duração são marcados como falhados. | | `BATCH_BACKOFF_BASE_MS` | `5000` | `open-sse/services/batchProcessor.ts` | Atraso base (ms) para espera exponencial em novas tentativas de artigos em lote. | | `BATCH_BACKOFF_MAX_MS` | `3600000` (1h) | `open-sse/services/batchProcessor.ts` | Limite (ms) para espera exponencial entre novas tentativas de artigos em lote. | | `BATCH_MAX_CONCURRENT` | `1` | `open-sse/services/batchProcessor.ts` | Número máximo de lotes processados em simultâneo. Aumente para aumentar o rendimento; mantenha-se baixo para evitar tempestades de limite de taxa. | > [!IMPORTANT] > Antes de alterar uma base de dados persistente existente, o executor de migração publica um instantâneo completo com conteúdo endereçado em `DATA_DIR/db_backups/`. A publicação requer um sistema de ficheiros que suporte o mesmo sistema de ficheiros, ligações físicas sem substituição, bem como uma sincronização de ficheiros durável. Os hosts POSIX também requerem sincronização de diretórios; em Windows, o Node pode rejeitar identificadores de diretório, pelo que OmniRoute liberta o ficheiro publicado e trata a sincronização de entrada de diretório como o melhor esforço. Se o `DATA_DIR` montado não conseguir fornecer estas garantias, a inicialização falhará antes de aplicar uma migração. Mover `DATA_DIR` para um volume com estas primitivas; não utilize `DISABLE_SQLITE_AUTO_BACKUP` para ignorar a segurança da migração. ### Cenários | Cenário | Configuração | | ------------------------- | ------------------------------------------------------------------------------------------- | | **Desenvolvimento local** | Deixe todos os padrões. DB vive em `~/.omniroute/omniroute.db`. | | **Docker** | `DATA_DIR=/data` + montar um volume em `/data`. | | **Encriptado em repouso** | Defina `STORAGE_ENCRYPTION_KEY` + para manter os backups da chave! Perdê-lo = perder dados. | | **CI/Testing** | `DATA_DIR=/tmp/omniroute-test` — efémero, sem necessidade de encriptação. | --- ## 3. Rede e portas | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PORT` | `20128` | `src/lib/runtime/ports.ts` | Porta primária para os endpoints UI e API do Dashboard (modo de porta única). | | `OMNIROUTE_BASE_PATH` | _(raiz = vazia)_ | `next.config.mjs`, `scripts/docker/ensure-docker-base-path.mjs` | Subcaminho URL para servir OmniRoute atrás de um proxy reverso (define Next.js `basePath`; os redireccionamentos de autenticação reconhecem basePath). Por exemplo, `/omniroute`. Em Docker o valor é gerado durante `docker build` (`ARG OMNIROUTE_BASE_PATH`); as imagens raiz pré-construídas podem aplicar um valor de tempo de execução diferente uma vez no início do contentor, antes da inicialização Next.js. Defina `NEXT_PUBLIC_BASE_URL` para a origem pública incluindo o mesmo subcaminho. | | `NEXT_PUBLIC_OMNIROUTE_BASE_PATH` | _(raiz = vazia)_ | `src/shared/hooks/useDisplayBaseUrl.ts` | Espelho de `OMNIROUTE_BASE_PATH` visível no browser, incorporado no tempo de construção para que a visualização do endpoint do painel mostre `https://host/omniroute/v1` em vez de `https://host/v1`. Volta a `OMNIROUTE_BASE_PATH` quando não está definido. Reconstruir após a alteração (o próximo `basePath` é o tempo de construção). | | `DASHBOARD_ALLOW_EMBED` | _(não definido = nunca emoldurável)_ | `next.config.mjs`, `scripts/build/dashboardEmbed.mjs` | Incorporação de iframe opcional das páginas HTML. Não definido, todas as rotas são enviadas `frame-ancestors 'none'` + `X-Frame-Options: DENY`. Defina como `vscode` para servir as páginas (painel, login, documentos, landing) com `frame-ancestors 'self' vscode-webview:` e sem `X-Frame-Options`, para que o VS Code Simple Browser possa renderizá-las (modo `dashboardOpen: "editor"` do OmniCopilot). A superfície API (`/api`, `/v1`, `/v1beta`, `/a2a`, `/healthz`, aliases de nível raiz) mantém os cabeçalhos estritos de qualquer forma. Apenas `vscode` é reconhecido — `1`/`true` não o habilita. Tempo de construção: reconstruir após a alteração (`docker build --build-arg DASHBOARD_ALLOW_EMBED=vscode` para imagens; configurá-lo numa instalação pré-construída não tem qualquer efeito). | | `API_PORT` | _(desativado)_ | `src/lib/runtime/ports.ts` | Quando definido, serve o proxy `/v1/*` API (mais `/v1beta/*` nativo do Gemini) nesta porta separada. | | `API_HOST` | `0.0.0.0` | `src/lib/runtime/ports.ts` | Endereço de ligação para a porta API. | | `DASHBOARD_PORT` | _(desativado)_ | `src/lib/runtime/ports.ts` | Quando definido, atende o Dashboard UI nesta porta separada. | | `OMNI_MAX_CONCURRENT_CONNECTIONS` | `0` _(desativado)_ | `src/sse/utils/backpressure.ts` | Limita as ligações de chat simultâneas durante o voo; pedidos acima do limite obtêm `503` com `Retry-After`. Inteiro positivo habilita a guarda; unset/`0` desativa-o. | | `OMNIROUTE_INSTANCE_ID` | _(desativado)_ | `src/shared/resilience/peerRouting.ts` | ID estável e exclusivo para este gateway ao encadear instâncias OmniRoute. Ativa verificações de loop de pares de entrada. Caracteres permitidos: letras, dígitos, `.`, `_`, `:` e `-`; máximo de 64 caracteres. | | `OMNIROUTE_PEER_URLS` | _(desativado)_ | `src/shared/resilience/peerRouting.ts`, `open-sse/executors/base.ts` | URLs OmniRoute por vírgula que pode receber `X-OmniRoute-Peer-Trace`. Apenas URLs upstream explicitamente permitidos recebem metadados de pares; todos os outros fornecedores permanecem intocados. | | `OMNIROUTE_PEER_MAX_HOPS` | `4` | `src/shared/resilience/peerRouting.ts` | Número máximo de instâncias OmniRoute visitadas anteriormente aceites num pedido encadeado (`1`-`32`). Instâncias repetidas ou um orçamento esgotado devolvem HTTP `508 Loop Detected`. | | `PROD_DASHBOARD_PORT` | `20130` | `docker-compose.prod.yml` | Porta publicada no host para o Dashboard no modo de produção Docker. | | `PROD_API_PORT` | `20131` | `docker-compose.prod.yml` | Porta publicada no lado do host para o API no modo de produção Docker. | | `OMNIROUTE_PORT` | _(desativado)_ | `src/lib/runtime/ports.ts` | Tem precedência sobre `PORT` quando se executa dentro Electron ou outros wrappers. | | `LIVE_WS_PORT` | `20129` | `src/server/ws/liveServer.ts` | Porta para o servidor de monitorização WebSocket live em tempo real. | | `LIVE_WS_HOST` | `127.0.0.1` | `src/server/ws/liveServer.ts` | Endereço de ligação para o servidor WebSocket ativo. Defina como `0.0.0.0` para expor no LAN (configure também `LIVE_WS_ALLOWED_ORIGINS`). As ligações são autenticadas com o cookie de sessão do painel ou com uma chave Bearer API que contém um âmbito de gestão (`manage`/`admin`). | | `LIVE_WS_ALLOWED_ORIGINS` | _(desativado)_ | `src/server/ws/liveServer.ts` | Origens extra separadas por vírgula permitiam abrir um WebSocket ativo. As origens do painel de loopback já são permitidas por defeito. | | `LIVE_WS_ALLOWED_HOSTS` | _(desativado)_ | `src/server/ws/liveServerAllowList.ts` | Nomes de host extra separados por vírgula permitidos para origens WebSocket ao vivo. Ao contrário de `LIVE_WS_ALLOWED_ORIGINS` (origem completa URLs), corresponde apenas à parte do host — útil para as configurações LAN/Tailscale. | | `NEXT_PUBLIC_LIVE_WS_PUBLIC_URL` | _(desativado)_ | `src/hooks/useLiveDashboard.ts` | URL público para o painel WebSocket ao vivo (lado do navegador). Definido ao aceder ao servidor WS com um proxy reverso ou túnel Cloudflare (por exemplo, `wss://ws.my-ai.com/live-ws`); o browser liga-se lá em vez de `ws://hostname:20132`. A parte do nome do caminho também é utilizada como caminho de atualização WebSocket (padrão: `/live-ws`). | | `OMNIROUTE_ENABLE_LIVE_WS` | `true` | `src/server/ws/liveServer.ts` e `scripts/start-ws-server.mjs` | Defina como `0` ou `false` para desativar o servidor WebSocket em tempo real (ativado por defeito, ligado a loopback). alternância CI/harness que desativa o script auxiliar WebSocket ao vivo independente. | | `RELAY_IP_PER_MINUTE` | `30` | `src/app/api/v1/relay/chat/completions/route.ts` | Limite da taxa de retransmissão por (token, IP), requests/minute. em memória, por instância. `0` ou negativo desativa a porta de dimensão IP (o limite DB por token ainda se aplica). | | `NODE_ENV` | `production` | núcleo Next.js | Controla o detalhe do registo, o armazenamento em cache, a exposição de detalhes de erros e as otimizações Next.js. | | `OMNIROUTE_USE_TURBOPACK` | _(unset)_ (seleção automática de compilação) | `scripts/build/build-next-isolated.mjs` | Para `npm run build`, unset ou empty selecciona webpack quando o limite de memória efectivo ( RAM físico ou quota cgroup/process inferior) é no máximo** 16 GiB** ou não pode ser determinado com segurança; acima de 16 GiB, Turbopack é seleccionado. `0` explícito força o webpack; `1` explícito e outros valores não vazios diferentes de zero forçam Turbopack. Um valor de ambiente vazio encaminhado pelo Compose não** não** força Turbopack. Este limite provém de uma regressão de memória de compilação de 15,6 GiB (#18184); compilações de host com 24/32 GiB não foram avaliadas. O webpack de produção ignora automaticamente a sua cache persistente por defeito (ver `OMNIROUTE_WEBPACK_BUILD_CACHE` abaixo; #18141) e constrói com RSS de pico substancialmente mais pequeno do que o caminho Turbopack atual. O desenvolvimento mantém o seu comportamento de empacotador existente.** As compilações Docker já estão padronizadas para `0` (webpack)** ; use `--build-arg OMNIROUTE_USE_TURBOPACK=1` para aceitar. Consulte `docs/guides/DOCKER_GUIDE.md`. | | `OMNIROUTE_WEBPACK_BUILD_CACHE` | _(desativado)_ | `next.config.mjs` | As compilações de produção do Webpack (`OMNIROUTE_USE_TURBOPACK=0`) ignoram a cache persistente do sistema de ficheiros do webpack, a menos que seja `1`. Escrever este cache adiciona cerca de 2,5 GB de memória de compilação de pico num limite de heap de 6144 MB, e as compilações limpas nunca o leem de volta. Defina como `1` para manter `.build/next/cache/webpack` para repetições mais rápidas numa máquina com RAM de sobra; As compilações Docker consideram-no `--build-arg OMNIROUTE_WEBPACK_BUILD_CACHE=1` (estágios do construtor `Dockerfile` e `Dockerfile.bun` ). | | `OMNIROUTE_SKIP_DB_HEALTHCHECK` | _(desativado)_ | `src/lib/db/core.ts` / `src/lib/db/healthCheck.ts` | Defina como `1` para ignorar a verificação de integridade da integridade SQLite no arranque. Útil para um arranque mais rápido em grandes bases de dados. | | `NOTIFY_SOCKET` | _(desativado)_ | systemd (protocolo sd_notify) | Definido pelo systemd quando o processo é executado numa unidade de serviço com integração sd_notify; OmniRoute lê (ver `OMNIROUTE_DISABLE_SD_NOTIFY`) para enviar notificações READY/WATCHDOG. Nunca definido pelo utilizador. | | `OMNIROUTE_DISABLE_SD_NOTIFY` | _(desativado)_ | `scripts/dev/systemd-notify.mjs` | Defina como `1` para desativar o systemd sd_notify (digite = notify / WatchdogSec=) mesmo quando está a ser executado numa unidade systemd. O notificador é um sistema externo autónomo, independentemente. | | `CREDENTIAL_HEALTH_CHECK_INTERVAL` | `3600000` | `open-sse/config/constants.ts` / `src/lib/credentialHealth/scheduler.ts` | Intervalo (ms) para o agendador de verificação da integridade das credenciais em segundo plano. Mínimo: 10.000 (10s). | | `CREDENTIAL_HEALTH_CACHE_TTL` | `300000` | `open-sse/config/constants.ts` / `src/lib/credentialHealth/cache.ts` | TTL (ms) para o estado de integridade da credencial armazenada em cache. | | `OMNIROUTE_DISABLE_CREDENTIAL_HEALTH_CHECK` | `false` | `src/lib/credentialHealth/scheduler.ts` | Defina como `1` ou `true` para desativar os testes periódicos em segundo plano das ligações do fornecedor. Os fornecedores de pesquisa (SEARCH_VALIDATOR_CONFIGS em `src/lib/providers/validation/searchProviders.ts`, por exemplo, `tavily-search`) são sempre excluídos da varredura — a sua "validação" é uma consulta upstream faturada real, pelo que a sua integridade nunca é verificada num temporizador (#9970). | | `DEEP_HEALTH_CHECK_ENABLED` | `0` | `src/app/api/monitoring/health/route.ts` | Defina como `1` para permitir que um chamador autenticado solicite `/api/monitoring/health?deep=1`, que amostra a superfície de conclusões uma vez por TTL. Os chamadores anónimos nunca acionam a investigação. | | `OMNIROUTE_EVENT_LOOP_STALL_THRESHOLD_MS` | `5000` | `src/lib/healthzLag.ts` | Limite de paragem (ms) para o gravador de ciclos de eventos de arranque: um congelamento mais longo do que este regista uma linha `event loop stalled` na retoma com memória e contagens em curso e ultrapassa o `eventLoopStall` counter/maximum em `/api/monitoring/health`. Defina como `0` para desativar; um valor ilegível ou negativo volta a `5000`. | | `HOST` | `0.0.0.0` | `scripts/dev/run-next.mjs` | Endereço de ligação para o servidor Next.js dev/start. Substitui o `0.0.0.0` padrão quando definido. | | `HOSTNAME` | `127.0.0.1` | `scripts/dev/run-next-playwright.mjs` | Endereço de ligação utilizado pelo executor Playwright ao iniciar Next.js. O padrão é `127.0.0.1` para testes herméticos.** Não utilizar para `omniroute serve`** — use `OMNIROUTE_SERVER_HOST` em vez disso (POSIX shells definem automaticamente `HOSTNAME` para o nome da máquina; `.env` não pode substituí-lo). | | `OMNIROUTE_SERVER_HOST` | `0.0.0.0` | `bin/cli/commands/serve.mjs` | Endereço de ligação para `omniroute serve`. Evita a colisão com a variável POSIX shell `HOSTNAME` (sempre definida como o nome da máquina por bash/zsh). Volta a `0.0.0.0` quando não está definido. (#6194) | ### Modos de porta ``` ┌─────────────────────────── Single Port (default) ──────────────────────────┐ │ PORT=20128 │ │ → Dashboard: http://localhost:20128 │ │ → API: http://localhost:20128/v1/chat/completions │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────── Split Ports ─────────────────────────────────────┐ │ DASHBOARD_PORT=20128 │ │ API_PORT=20129 │ │ API_HOST=0.0.0.0 │ │ → Dashboard: http://localhost:20128 │ │ → API: http://0.0.0.0:20129/v1/chat/completions │ │ Use case: Expose API to LAN while restricting Dashboard to localhost. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────── Docker Production ──────────────────────────────┐ │ PROD_DASHBOARD_PORT=443 PROD_API_PORT=8443 │ │ → Maps container ports to host ports in docker-compose.prod.yml. │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 4. Segurança e autenticação | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MACHINE_ID_SALT` | `endpoint-proxy-salt` | `src/lib/auth` | Sal combinado com identificadores de hardware para impressão digital de máquinas. Altere por implantação para isolamento. | | `OMNIROUTE_CLI_SALT` | _(desdefinir = sal aleatório por instalação persistido em `/cli-token-salt.json`)_ | `src/lib/machineToken.ts` | HMAC salt para derivar o token de autenticação CLI local. A definição deste valor roda todos os tokens CLI na máquina e tem sempre prioridade sobre o salt persistente. Ver `docs/security/CLI_TOKEN.md`. | | `AUTH_COOKIE_SECURE` | `false` | `src/lib/auth` | Define o sinalizador `Secure` nos cookies de sessão.** Deve ser `true`** ao correr atrás do HTTPS. | | `REQUIRE_API_KEY` | `false` | middleware API | Quando `true`, todos os pedidos de proxy `/v1/*` devem incluir uma chave API válida.** Este sinalizador não bloqueia `GET /v1/models`** , que segue a postura de login do painel (`requireAuthForModels`) em vez de —, pelo que um `401` de `/v1/models` NOT significa que a inferência está protegida. Ver `docs/security/INFERENCE_AUTH_POSTURE.md` (#13695). Aceita `true`, `1` ou `yes`, ignorando maiúsculas e minúsculas e espaços adjacentes; qualquer outro valor (incluindo `on`) está desativado. | | `ALLOW_API_KEY_REVEAL` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | Permite revelar valores completos da chave API no Dashboard UI. Configurável a partir de sinalizadores de recursos do painel; risco de segurança em instâncias partilhadas. | | `NO_LOG_API_KEY_IDS` | _(vazio)_ | `src/lib/compliance/index.ts` | Chave API separada por vírgula IDs que ignora o registo de pedidos (compatibilidade GDPR ). | | `DEFAULT_RATE_LIMIT_PER_DAY` | _(desativar = ilimitado)_ | `src/shared/utils/apiKeyPolicy.ts` | Orçamento de pedido diário substituto aplicado a chaves API cuja coluna `rate_limits` é nula. Não definido ou vazio: sem limite implícito (#2289, #11017). `0` é o mesmo (ilimitado). O número inteiro positivo N permite que N/day, 5N/week, 20N/month. Valores não vazios malformados regressem às janelas herdadas 1000/day, 5000/week, 20000/month. | | `MAX_BODY_SIZE_BYTES` | `10485760` (10 MB) | `src/shared/middleware/bodySizeGuard.ts` | Padrão para a configuração `maxBodySizeMb` visível; uma configuração guardada tem precedência. `/api/v1/chat/completions` e `/api/v1/responses` mantêm um padrão de 50 MB até que um limite seja guardado; um limite guardado substitui-o, para cima ou para baixo, tanto para a proteção do cabeçalho como para a admissão de chat em bytes reais. | | `OMNIROUTE_CHAT_LARGE_BODY_BYTES` | `262144` (256 KB) | `src/shared/middleware/chatBodyAdmission.ts` | Os corpos de pedido reais neste limite ou acima dele aceitam a concessão de admissão pesada local do processo atómico antes da análise JSON ( caminho BYTE, incluindo `POST /v1/responses`). O mesmo escape de espaço saudável [#10437](https://github.com/diegosouzapw/OmniRoute/pull/10437) que a estrutura pesada; ainda limitado por `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` / [#10110](https://github.com/diegosouzapw/OmniRoute/issues/10110) então [#7849](https://github.com/diegosouzapw/OmniRoute/issues/7849) não retorna. | | `OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES` | `52428800` (50 MB) | `src/shared/middleware/chatBodyAdmission.ts` | Limite rígido da rota de chat aplicado contra bytes lidos durante a ingestão limitada, incluindo pedidos com `Content-Length` em falta, inválido ou desonesto; o excesso recebe `413`. Um `maxBodySizeMb` guardado substitui o padrão de 50 MB ; quando esta variável é definida, limita também o valor guardado. | | `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` | _(desdefinir — sem limite de contagem de pedidos)_ | `src/shared/middleware/chatBodyAdmission.ts` | **#503-fanout:** este limite legado de request-COUNT é agora ligado apenas quando definido explicitamente. Se não for definido (o padrão), a admissão de chat pesado é, em vez disso, bloqueada por `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` — um orçamento BYTE derivado automaticamente dimensionado a partir do limite de memória real do processo em** um processo** (uma pilha V8). Dois sobrepostos ~ 750k-token `/v1/responses` abortam ~ 12 Gi heaps (#7849) — a** orçamento de memória** aviso, não é um produto difícil no máximo 2. Um processo saudável (pilha abaixo da taxa de eliminação) MAY admite mais `/v1/responses` longos simultâneos via `OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM`. Dezenas de clientes SSE longos (40–50) são heap + `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` / #10110, e não “max 2”. Aumentar cegamente isto para “usar o host” reintroduz #7849. Multiplicar** montes** com** N `DATA_DIR` s independente** (#11024); nunca `replicas>1` num ficheiro SQLite. | | `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` | _(derivado automaticamente)_ | `src/shared/middleware/admissionBudget.ts` | **#503-fanout:** substituição para o orçamento de bytes de ingestão derivados automaticamente (25% do tecto de memória V8/cgroup mais restrito dividido por amplificação transitória de 8x). Os valores derivados e explícitos são fixados em 8 MiB–2 GiB. Um órgão maior que o orçamento efectivo falha imediatamente com `413 body_exceeds_budget`; a contenção entre órgãos individualmente atendíveis continua a ser passível de nova tentativa `503`. 40–50 clientes SSE longos simultâneos é este heap + de orçamento, não um “máximo 2” rígido. Leia `chatAdmission.maxInflightBytes` / `budgetSource` / `pressureSeverity` em `/api/monitoring/health` antes de ajustar. | | `OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO` | `0.75` | `src/shared/middleware/chatBodyAdmission.ts` | Relação de perda de pressão de pilha (`heapUsed / heap_size_limit`) para admissão de peso pesado BYTE e STRUCTURE (#10183, #10268, #10437). Um pedido pesado simultâneo após `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` só é eliminado com o `503` retentável quando o heap é ALSO igual ou superior a essa relação; numa pilha saudável, é admitido por meio de headroom saudável. | | `OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM` | `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` (padrão `1`) | `src/shared/middleware/chatBodyAdmission.ts` | Capacidade extra limitada para o caminho rápido de heap íntegro (#10437) em** ambos** STRUCTURE e BYTE (`admitChatRequest`, incluindo os corpos ≥ `OMNIROUTE_CHAT_LARGE_BODY_BYTES`). Sem este limite, todos os pedidos de heap ocupado, mas íntegro, ignoraram a admissão sem teto. Depois de estas muitas concessões simultâneas estarem ativas através do caminho de heap íntegro, outros pedidos ocupados passarão para o caminho SAME bounded-wait/shed utilizado sob pressão de heap real. `0` desativa totalmente o bypass. | | `OMNIROUTE_CHAT_HEAVY_MESSAGE_COUNT` | `200` | `src/shared/middleware/chatBodyAdmission.ts` | Contagem de mensagens que classifica um pedido de chat como pesado mesmo quando o seu corpo está abaixo do limite de bytes. | | `OMNIROUTE_CHAT_HEAVY_TOOL_COUNT` | `64` | `src/shared/middleware/chatBodyAdmission.ts` | Contagem de ferramentas que classifica um pedido de chat como pesado mesmo quando o seu corpo está abaixo do limite de bytes. | | `OMNIROUTE_CHAT_HEAVY_ESTIMATED_TOKENS` | `32000` | `src/shared/middleware/chatBodyAdmission.ts` | Estimativa conservadora de token de tamanho de string que classifica um pedido como pesado; este é um proxy de custo de admissão, não uma tokenização de faturação do fornecedor. | | `OMNIROUTE_CHAT_HARD_MAX_MESSAGES` | `0` (desativado) | `src/shared/middleware/chatBodyAdmission.ts` | Limite opcional de histórico de chat opcional. Desativado por defeito: uma contagem de mensagens é uma política de implementação, não uma propriedade universal de um pedido, e o limite aqui rejeita conversas com um terminal `413` antes que o pipeline de compressão possa torná-las utilizáveis. O crescimento do heap é limitado pelo `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` e pela redução da pressão do heap. Defina um valor positivo nas implementações com restrição de memória que necessitam de um limite máximo; o excesso recebe então `413` necessário para a compressão estruturada. | | `OMNIROUTE_MAX_NONSTREAMING_RESPONSE_BYTES` | `67108864` (64 MB) | `open-sse/handlers/chatCore/nonStreamingResponseBody.ts` | Hard cap para uma resposta upstream sem streaming armazenada totalmente na memória. Depois disso, o leitor upstream é cancelado e o pedido falha rapidamente, em vez de aumentar uma sequência ilimitada até que o heap se esgote. | | `OMNIROUTE_FORWARDING_HEADER_BUDGET_BYTES` | `768` | `open-sse/handlers/chatCore/responseHeaders.ts` | Máximo de bytes de ligação encaminhados a partir de cabeçalhos de resposta upstream. Quando o orçamento é excedido, os cabeçalhos de prioridade mais baixa (por exemplo, `x-codex-*` personalizado, `x-oai-request-id`) são descartados para permanecerem dentro dos limites comuns de cabeçalho de proxy inverso. Defina um valor mais elevado para encaminhar mais metadados a montante, com o custo de um tamanho de cabeçalho de resposta maior. | | `OMNIROUTE_QUOTA_RECOVERY_MAX_PER_KEY` | `64` | `src/lib/quota/quotaSessionRecovery.ts` | A maioria dos tickets de recuperação de quotas (pendentes, em execução ou a aguardar confirmação) pode conter uma chave API. Quando uma chave atinge o limite, um novo turno obtém o erro de quota original em vez de um ticket `202` ; tentar novamente uma curva já estacionada ainda irá devolver o seu ticket. Os valores inválidos ou não positivos utilizam o padrão. | | `CORS_ORIGIN` | _(desativado)_ | `src/server/cors/origins.ts` | Lista de permissões CORS legada de origem única. Prefira `CORS_ALLOWED_ORIGINS` para novas implementações. CORS é apenas para clientes API de browser de origem cruzada; as gravações de painel autenticadas utilizam pedidos de mesma origem mais proteção CSRF ligada à sessão. | | `CORS_ALLOWED_ORIGINS` | _(desativado)_ | `src/server/cors/origins.ts` | Lista de permissões CORS separada por vírgulas. Nenhum curinga é enviado, a menos que `CORS_ALLOW_ALL=true` seja configurado explicitamente. | | `CORS_ALLOW_ALL` | `false` | `src/server/cors/origins.ts` | Saída de escape apenas para desenvolvimento para ecoar qualquer navegador `Origin`. Não ative em implementações partilhadas ou de produção. | | `OUTBOUND_SSRF_GUARD_ENABLED` | `true` | `src/shared/network/outboundUrlGuardPolicy.ts` | Alias herdada. A alternância do painel (uma substituição DB ) é lida antes deste valor de ambiente; `false`, `0`, `no` ou `off` desativa as verificações do host da forma que o `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` faz, mesmo quando a alternância do painel do sinalizador está desativada; outros valores deixam a guarda para as duas flags abaixo. | | `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` | `false` | `src/shared/network/outboundUrlGuardPolicy.ts` | Desativa as verificações de host do URL guard de saída, bloco de metadados de nuvem incluído (todos 169.254.0.0/16, metadata.google.internal), nos caminhos do fornecedor que seguem o modo de proteção: validação URL, descoberta de modelo, URLs base do nó do fornecedor (incluindo nós de reclassificação remota) e o teste de fallback de proxy, entre outros caminhos de saída adjacentes ao fornecedor, como a pesquisa remota image/media. Permite também destinos de webhook privados, exceto os endpoints cloud-metadata/link-local, que permanecem bloqueados mesmo com este sinalizador ativado. Os pedidos de chat enviados através do `BaseExecutor.execute()` mantêm a verificação dos metadados da nuvem. Os fornecedores locais trabalham com os padrões: `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` (padrão `true`) já permite o local e LAN URLs nos caminhos de validação, descoberta e nó do fornecedor; o teste de proxy-fallback e os destinos de webhook privados consultam apenas este sinalizador e bloqueiam os hosts local/LAN enquanto está desativado. Substitui `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=false`. Um valor guardado na alternância do painel tem precedência sobre esta variável. | | `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` | `true` | `src/shared/network/outboundUrlGuardPolicy.ts` | Permita o fornecedor URLs em endereços local/private (127.0.0.1, localhost, LAN, intervalos privados) para validação do fornecedor, descoberta de modelos, chat e outros caminhos de saída adjacentes ao fornecedor que o modo de proteção governa.** `true` padrão** (local-first): o guarda bloqueia então os endpoints de metadados da cloud — todos os 169.254.0.0/16 mais os nomes de host de metadados conhecidos (metadata.google.internal, metadata.goog, Alibaba/Azure/Oracle IMDS, fd00:ec2::254). Defina `false` para o modo apenas público, que também bloqueia os hosts privados e de loopback. O guarda verifica o nome do host ou a literal IP tal como está escrita, antes de qualquer pesquisa DNS ; no modo apenas público, o invólucro de pesquisa segura resolve adicionalmente o nome do host e recusa qualquer resposta privada. `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` desativa estas verificações nos caminhos das suas listas de linhas. Os fornecedores locais integrados, como LM Studio, Ollama, vLLM, Llamafile e Triton, ignoram todas as verificações de host para validação de chaves e chat. Um valor guardado na alternância do painel tem precedência sobre esta variável. (#5066) | | `AUDIO_REMOTE_PROVIDER_NODES` | `false` | `src/app/api/v1/_shared/audioProviderNodes.ts` | Deixe as rotas `/v1/audio/*` (transcrições, fala, traduções) utilizarem um nó de fornecedor compatível com OpenAI alojado fora do localhost. Desativado por defeito, o encaminhamento — de áudio para um host remoto altera a identidade de saída e deve ser uma decisão explícita do operador. Os nós Loopback/private (localhost, 127.0.0.1, 172.16-31. x) são sempre permitidos e não são afetados. (#3963) | | `RERANK_REMOTE_PROVIDER_NODES` | `false` | `src/app/api/v1/_shared/rerankProviderNodes.ts` | Deixe `POST /v1/rerank` (e a etapa de reclassificação de loopback do motor de memória) utilize um nó de fornecedor compatível com OpenAI alojado fora do localhost — uma caixa LAN ou Tailscale peer que execute TEI, Infinity, vLLM, etc. Desativado por defeito, o encaminhamento — para um host remoto altera a identidade de saída e deve ser uma decisão explícita do operador. Os nós de loopback (localhost, 127.0.0.1, 172.16-31. x) são sempre permitidos e não são afetados. O URL base de um nó remoto também deve passar pela política URL de saída do fornecedor (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`). | | `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` | _(vazio)_ | `src/shared/network/localNodeHosts.ts` | Nomes de host (separados por vírgula ou espaço em branco) que o encaminhamento do nó do fornecedor trata como — local, normalmente o nome do serviço Docker/Compose de um reclassificador, TEI ou ficheiro secundário de áudio na própria rede Docker do OmniRoute(`http://reranker:8080/v1`), pelo que o nó não necessita de um contentor codificado IP. Os hosts listados são elegíveis para `/v1/rerank`, `/v1/audio/*` e verificação de integridade local sem ativar `RERANK_REMOTE_PROVIDER_NODES` / `AUDIO_REMOTE_PROVIDER_NODES` para cada nó remoto e são chamados diretamente — nunca através `HTTP(S)_PROXY` ou de um proxy fixado de ligação. Enviam ainda a chave API da ligação. Apenas os nomes de rótulo único e os nomes `.internal`/`.local` são aceites; Public FQDNs, literais IP e nomes de metadados de nuvem são ignorados com um aviso. (#14635) | | `OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | `src/app/api/auth/login/route.ts` | Quando OIDC estiver ativado, desative o login com palavra-passe para que os utilizadores se possam autenticar apenas através do logon único OIDC. O alias `OIDC_DISABLE_PASSWORD_LOGIN` também é aceite; o sinalizador de recurso do painel da mesma chave tem precedência. (#10889) | | `OIDC_DISABLE_PASSWORD_LOGIN` | `false` | `src/app/api/auth/login/route.ts` | Alias simples de `OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN` (#10889). | | `OMNIROUTE_DISABLE_MFA` | `false` | `src/server/auth/dashboardMfa.ts` | Recuperação de dispositivo perdido para o painel opcional TOTP login de dois fatores. Quando `true`, o segundo factor é apenas ignorado para uma entrada do próprio host (loopback peer e loopback `Host`); logins remotos e `POST /api/cli/connect` de outras origens ainda requerem o código. Faça login localmente, desative ambos os fatores em Definições → Security (o código pode ser deixado em branco enquanto estiver definido, para que um fator que já não seja verificado possa ser removido; a palavra-passe ainda é necessária) e, em seguida, desmarque-o. TOTP cobre login por palavra-passe e `omniroute connect` apenas — OIDC/SSO login depende do segundo fator do próprio fornecedor de identidade. Veja [AUTHZ_GUIDE](../architecture/AUTHZ_GUIDE.md#optional-totp-two-factor-login-16619). | ### Lista de verificação de endurecimento ```bash # Production security minimum: AUTH_COOKIE_SECURE=true # Requires HTTPS REQUIRE_API_KEY=true # Authenticate all proxy calls ALLOW_API_KEY_REVEAL=false # Never expose keys in UI CORS_ALLOWED_ORIGINS=https://your.domain.com MAX_BODY_SIZE_BYTES=5242880 # 5 MB limit ``` --- ## 5. Higienização de entrada e proteção PII OmniRoute fornece uma defesa de duas camadas: varrimento de injeção no lado do pedido e remoção PII no lado da resposta. > **Limitações ⚠️ :** Estas proteções são deteções heurísticas de _melhor esforço_, não uma firewall completa de injeção de prompt ou sistema PII DLP. Podem produzir falsos positivos (prompts persona/RPG benignos sinalizados) e falsos negativos (leetspeak, espaçamento, padrões que não sejam do inglês). Não são suficientes por si só para a conformidade. Ajuste os modos e teste o seu tráfego antes de confiar neles. ### Lado da solicitação: proteção de injeção imediata | Variável | Predefinição | Arquivo de origem | Descrição | | --------------------------------- | -------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INPUT_SANITIZER_ENABLED` | `true` | `src/middleware/promptInjectionGuard.ts` | Ative a verificação de mensagens recebidas em busca de padrões de injeção de avisos. | | `INPUT_SANITIZER_MODE` | `warn` | `src/middleware/promptInjectionGuard.ts` | Política de injeção: `warn` = apenas log, `block` = rejeita pedido com 400. O `redact` legacy faz** não** texto de injeção de tiras; utilize `PII_REDACTION_ENABLED` para solicitar a reescrita PII. | | `INJECTION_GUARD_MODE` | _(desativado)_ | `src/middleware/promptInjectionGuard.ts` | Alias legado para `INPUT_SANITIZER_MODE` — mesmo comportamento. | | `INPUT_SANITIZER_BLOCK_THRESHOLD` | `high` | `src/shared/utils/injectionSeverity.ts` | Gravidade mínima que `MODE=block` rejeita: `high` (padrão), `medium` ou `low`. Os padrões médios são apenas de observação, a menos que sejam reduzidos. | | `INJECTION_GUARD_BLOCK_THRESHOLD` | _(desativado)_ | `src/shared/utils/injectionSeverity.ts` | Alias legado para `INPUT_SANITIZER_BLOCK_THRESHOLD` — mesmo comportamento. | | `PII_REDACTION_ENABLED` | `false` | `src/lib/guardrails/piiMasker.ts` | Quando `true`, edite PII nos pedidos recebidos (independentemente do modo de injeção). | | `CREDENTIAL_REDACTION_ENABLED` | `false` | `src/lib/guardrails/credentialMasker.ts` | Edite os padrões conhecidos de chave API/token secreto de cargas request/response. Aceitar; espelhos `PII_REDACTION_ENABLED`. | ### Lado da resposta: PII Sanitizer | Variável | Predefinição | Arquivo de origem | Descrição | | -------------------------------- | ------------ | ------------------------- | -------------------------------------------------------------------------------- | | `PII_RESPONSE_SANITIZATION` | `false` | `src/lib/piiSanitizer.ts` | Verifique as respostas LLM em busca de PII vazado antes de regressar ao cliente. | | `PII_RESPONSE_SANITIZATION_MODE` | `redact` | `src/lib/piiSanitizer.ts` | `redact` = máscara PII, `warn` = só log, `block` = elimina a resposta completa. | ### Sanitizador de contexto de rota tokenizada de código VS | Variável | Predefinição | Arquivo de origem | Descrição | | ----------------------------------- | ------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OMNIROUTE_VSCODE_SANITIZE_CONTEXT` | `1` | `src/app/api/v1/vscode/contextSanitizer.ts` | Retira o contexto implícito do editor ativo (`editorContext`, `activeEditor`, `currentFile`, `selection`, `openTabs`…) dos pedidos `/v1/vscode/[token]/*` e edita o conteúdo de ficheiros confidenciais anexados explicitamente. Seguro por defeito; defina como `0` para desativar. | ### Cenários | Cenário | Configuração | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Conformidade empresarial** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=block`, `PII_REDACTION_ENABLED=true`, `PII_RESPONSE_SANITIZATION=true` (blocos de injeção + request/response PII redação; os modos são independentes) | | **Somente monitorização** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=warn` — regista mas nunca bloqueia | | **Uso pessoal** | Deixe todos — desativados com sobrecarga zero | --- ## 6. Políticas de ferramentas e encaminhamento | Variável | Predefinição | Arquivo de origem | Descrição | | ----------------------------------------------------------- | ---------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TOOL_POLICY_MODE` | `disabled` | `src/lib/toolPolicy.ts` | Controla o acesso LLM tool/function-calling. `allowlist` = apenas as ferramentas listadas, `denylist` = todas exceto as listadas, `disabled` = sem restrições. | | `OMNIROUTE_PAYLOAD_RULES_PATH` | `./config/payloadRules.json` | `open-sse/services/payloadRules.ts` | Caminho para o ficheiro JSON das regras de tratamento da carga útil (ajustes a montante per-model/protocol ). | | `OMNIROUTE_PAYLOAD_RULES_RELOAD_MS` | `5000` | `open-sse/services/payloadRules.ts` | Intervalo de recarga (ms) para recarregar a quente o ficheiro de regras de carga útil. `1000` mínimo. | | `OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS` | `false` | `open-sse/services/model.ts` | Aceitação: reencaminhe o modelo `claude-*` simples IDs dos clientes Claude através da conta Claude Code OAuth em vez de exigir um prefixo de fornecedor. Os prefixos de fornecedor explícitos ainda ganham. Também configurável através de um painel de alternância na página do fornecedor Claude. | | `OMNIROUTE_REDACT_THINKING` | `true` | `open-sse/executors/base/redactThinkingBeta.ts` | Defina `false` para impedir que OmniRoute adicione o próprio `redact-thinking-2026-02-12` Anthropic beta (blocos de pensamento vazios apenas com assinatura). Os pedidos com `thinking.display: "summarized"` ignoram independentemente; uma edição beta negociada pelo cliente ou uma opção `requestDefaults.redactThinking` compatível com CC mantém-no. Os pedidos Claude OAuth mantêm o beta (faz parte da impressão digital OAuth do código Claude ), a menos que o sinalizador de recurso `CLAUDE_OAUTH_SUMMARIZED_THINKING_UNREDACTED` desativado por defeito esteja ativado. | | `BARE_MODEL_DEFAULT_OVERRIDE_LEGACY` | `false` | `open-sse/services/model.ts` | Comportamento herdado `resolveBareModelToConnectionDefault` (#4825): substitua qualquer nome de modelo simples pelo `defaultModel` da ligação selecionada. Desativado por defeito, apenas `auto` ou um modelo vazio é substituído; regista um aviso por par quando ativado. | | `COMBO_CONCURRENCY_PER_MODEL` | `3` | `open-sse/services/comboConfig.ts` | Limite de simultaneidade por modelo para combos round-robin (#9100). O semáforo combinado round-robin foi limitado a 3 pedidos simultâneos por modelo, sem substituição, serializando o tráfego de maior simultaneidade por detrás deste limite. Validado para `>= 1`, fixado em `<= 32`. | | `OMNIROUTE_AGENTIC_STALL_FAILOVER` | `false` | `open-sse/services/combo/agenticStallFailover.ts` | Opt-in: definido como `1` (ou `true`) para que um membro do combo que responda a uma curva de resultado de ferramenta com narração `finish: stop` + + zero chamadas de ferramenta faça failover para o próximo alvo (estratégias de loop de prioridade, round-robin e sessões fixadas). Se nenhum alvo tiver um melhor desempenho, a resposta paralisada será devolvida em vez de um erro, e nem o disjuntor do fornecedor nem o bloqueio do modelo serão cobrados. Os turnos transmitidos são retidos ao cliente até que o veredicto seja definido. Os pedidos que utilizam a forma Respostas API `input` não são classificados. Padrão OFF. | | `DISABLE_CONTEXT_WINDOW_CHECKS` | `false` | `open-sse/handlers/chatCore.ts` | Opção perigosa que ignora a verificação da janela de contexto local/token de entrada máxima de OmniRoute para pedidos diretos de modelo único. Os fornecedores upstream ainda impõem os seus limites reais; a compressão imediata e o próprio limite de token de saída do modelo permanecem ativos. A precedência efetiva é Sinalizadores de Recurso DB override variável de ambiente > > default; não é necessária reinicialização. | | `OMNIROUTE_SELF_HOSTED_PROVIDERS` | _(desativado)_ | `open-sse/services/selfHostedEntry.ts` | Documento YAML `providers:` incorporado (RIC-738, D4). Quando definido (com ou sem um bloco `strategy:` ), `/v1/chat/completions` desvia para a entrada compatível com OpenAI unificada auto-hospedada em vez do pipeline de cloud. Não definido (o predefinido): a rota passa diretamente para o pipeline de cloud existente. Veja `docs/routing/SELF_HOSTED_OPENAI_ENTRY.md`. | | `OMNIROUTE_SELF_HOSTED_PROVIDERS_FILE` | _(desativado)_ | `open-sse/services/selfHostedEntry.ts` | Caminho para um ficheiro YAML contendo o mesmo documento `providers:` que `OMNIROUTE_SELF_HOSTED_PROVIDERS`, para implementações que preferem um ficheiro em vez de um ambiente inline var. Qualquer um deles ativa a entrada auto-hospedada. | | `OMNIROUTE_SELF_HOSTED_API_KEY` | _(desativar rota aberta — )_ | `open-sse/services/selfHostedEntry.ts` | Chave API partilhada opcional para a entrada auto-hospedada unificada (andaime D5, reservada para o sistema de cotas por chave). Quando definidos, os pedidos devem incluir `Authorization: Bearer `. Não definido: a rota está aberta, correspondendo ao padrão de fornecedor local auto-hospedado existente (implantação loopback/trusted-network ). | | `OMNIROUTE_SELF_HOSTED_STRATEGY` | _(desativado)_ | `open-sse/services/routingStrategies.ts` | Documento YAML `strategy:` incorporado para o mecanismo de encaminhamento determinístico (M2/RIC-740, D3) — blacklist/whitelist, disjuntor de arrefecimento, prioridade de custo, reconhecimento de latência, cadeia de fallback. Substitui um bloco `strategy:` incorporado aninhado dentro de `OMNIROUTE_SELF_HOSTED_PROVIDERS`, por chave. Ver `docs/routing/DETERMINISTIC_ROUTING.md`. | | `OMNIROUTE_SELF_HOSTED_STRATEGY_FILE` | _(desativado)_ | `open-sse/services/routingStrategies.ts` | Caminho para um ficheiro YAML contendo o mesmo documento `strategy:` que `OMNIROUTE_SELF_HOSTED_STRATEGY`, para implementações que preferem um ficheiro em vez de um ambiente inline var. | | `OMNIROUTE_DISABLE_CONVERSATION_TRACKING` | _(desativado)_ | `open-sse/services/conversationTracker.ts` | Configure `1` para parar de recolher o histórico de conversas. `resolveConversationId()` devolve um resultado não rastreado antes de ler SQLite ou analisar o histórico de mensagens, e a sessão IDs fornecida pelo cliente também é abordada. O tratamento da sessão de encaminhamento permanece inalterado e os registos existentes não são eliminados. Para implementações que não utilizam a vista de conversação do painel e desejam que a mesa giratória pare de crescer. | | `OMNIROUTE_NADIR_API_KEY` | _(desativado)_ | `open-sse/services/autoCombo/nadirStrategy.ts` | Chave API para a estratégia opcional do router de combinação automática `nadir`, utilizada quando o próprio `config.nadir.apiKey` do combo não está definido. Opcional: as chamadas sem chave chegam ao nível anónimo do Nadir, que tem uma taxa limitada por IP e, portanto, não pode ser utilizado atrás de um gateway partilhado. Confidencial; prefira o campo por combo quando os combos utilizam contas diferentes. | | `OMNIROUTE_NADIR_BASE_URL` | `https://api.getnadir.com` | `open-sse/services/autoCombo/nadirStrategy.ts` | Origem base da decisão Nadir API, utilizada quando o próprio `config.nadir.baseUrl` do combo não está definido. Apenas necessário para um Nadir auto-hospedado, que mantém alertas dentro da sua própria rede. Um `/v1` final é tolerado e eliminado. | | `OMNIROUTE_API_KEY_WEEKLY_WINDOW` | `provider` | `src/lib/usage/apiKeyUsageLimits.ts` | Janela semanal para limites de utilização USD por chave API (aplicação de pedido, `GET /api/keys/{id}/usage-limits`, `@@om-usage`). `provider`: a semana termina na primeira reposição semanal entre as ligações a montante que a chave pode alcançar ou dura 7 dias consecutivos quando não é conhecida nenhuma. `calendar`: a semana local de segunda-feira às 00h00 até à próxima segunda-feira às 00h00, idêntica para cada chave. `calendar` é recomendado quando um conjunto de contas upstream é partilhado por muitas chaves orçamentadas individualmente. Os valores inválidos voltam para `provider`. | | `OMNIROUTE_API_KEY_WEEKLY_WINDOW_TIMEZONE` | _(fuso horário do processo)_ | `src/lib/usage/apiKeyUsageLimits.ts` | fuso horário IANA (por exemplo `Asia/Shanghai`) que define segunda-feira 00:00 para a janela semanal `calendar`. Não definido ou inválido: o fuso horário do processo OmniRoute (o `TZ` do host ou contentor, que geralmente não está definido, ou seja, Tempo Universal Coordenado, nas imagens de contentor). Ignorado no modo `provider`. | | `OMNIROUTE_MAX_TOOLS_LIMIT` | `128` | `open-sse/config/constants.ts` | Número máximo padrão de ferramentas permitidas num pedido (OpenAI default). Apenas números inteiros positivos; valores não definidos ou inválidos mantêm `128`. Um fornecedor com limite known/proactive (`grok-cli` 200, `nvidia` 1536) ainda aplica o seu próprio limite — isto apenas move o tecto padrão. Os destinos no formato Claude não têm limite por defeito (o API de Mensagens não tem nenhum); um limite aprendido ainda se aplica. | | `OMNIROUTE_TOOL_OUTPUT_IMAGE_MAX_COUNT` | `16` | `open-sse/translator/request/openai-responses.ts` | Respostas à tradução do Chat: quantas imagens de saída da ferramenta (`function_call_output`, `custom_tool_call_output`, role `tool`) são reenviadas como partes de imagem do utilizador por pedido. Os mais novos são mantidos e cada um dos mais antigos torna-se um espaço reservado para o texto com o seu `tool_call_id`. Apenas números inteiros positivos; valores não definidos ou inválidos mantêm `16`. | | `OMNIROUTE_TOOL_OUTPUT_IMAGE_MAX_BYTES` | `20971520` (20 MB) | `open-sse/translator/request/openai-responses.ts` | Tamanho total da imagem de saída da ferramenta URLs reenviada por pedido na mesma tradução. As imagens que excedam o orçamento serão descartadas primeiro, com um aviso por solicitação. Apenas números inteiros positivos; valores não definidos ou inválidos mantêm `20971520`. | | `OMNIROUTE_RESPONSES_STRICT_TOOL_HISTORY` | `false` | `open-sse/translator/helpers/responsesToolHistory.ts` | Como é tratado o histórico inconsistente da ferramenta Respostas: uma saída sem chamada, uma chamada sem saída, um `call_id` em falta, longo ou inválido ou argumentos históricos malformados. Desligado, OmniRoute repara o histórico e despacha-o (as saídas órfãs são descartadas, as chamadas não atendidas obtêm uma saída vazia, os ids são cunhados ou fixados, os argumentos malformados tornam-se `{}`). Ativado, o pedido recebe um `400` antes do envio; um histórico válido é encaminhado com os seus IDs de chamada e argumentos JSON conforme enviado. Aceita `true` ou `1`; qualquer outro valor mantém o padrão. | | `OMNIROUTE_PROMPT_EMULATE_TOOLS` | _(em)_ | `open-sse/executors/syntxChat.ts` | chamada de ferramenta emulada por prompt SYNTX.ai: unset ou `1`/`true`/`on`/`yes` injecta o catálogo de ferramentas local no prompt; qualquer outro valor (por exemplo, `0`) ignora esta injecção. | --- ## 7. URLs e sincronização na nuvem | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BASE_URL` | `http://localhost:20128` | `src/lib/cloudSync.ts` | URL do lado do servidor para os trabalhos de sincronização interna chamarem `/api/sync/cloud`. Mantenha isto como um loopback/container URL mesmo quando a aplicação está com proxy público. As competências A2A também o utilizam (consulte `OMNIROUTE_BASE_URL`) e falham em vez de enviar uma chave API para um http simples público URL. | | `CLOUD_URL` | _(vazio)_ | `src/lib/cloudSync.ts` | Endpoint de retransmissão na nuvem URL (característica premium). | | `CLOUD_SYNC_TIMEOUT_MS` | `12000` | `src/lib/cloudSync.ts` | Tempo limite HTTP para pedidos de sincronização na nuvem. | | `OMNIROUTE_BUILD_PROFILE` | `full` | Configuração de compilação do Webpack | Perfil em tempo de construção (definido como `minimal` para excluir fisicamente os módulos privilegiados do pacote). | | `OMNIROUTE_STANDALONE_DIR` | _. construir/saída autónoma_ | `scripts/build/colocate-standalone.mjs` | Substituição em tempo de compilação para o diretório de saída independente consumido pela etapa de colocation pós-construção. Não é uma configuração de tempo de execução. | | `OMNIROUTE_DIST_DIR` | `dist/` (raiz do repositório) | `scripts/build/prepublish.ts` | Substituição em tempo de construção para o diretório em que a etapa de publicação (`prepublish.ts`) escreve o pacote CLI, em vez de `dist/` na raiz do repositório. O diretório é apagado antes da construção. Não é uma configuração de tempo de execução. | | `OMNIROUTE_CLOUD_SYNC_SECRET` | _(vazio)_ | `src/lib/cloudSync.ts` | Segredo partilhado utilizado para verificar a assinatura HMAC-SHA256 das respostas do Cloud Sync. | | `OMNIROUTE_CLOUD_SYNC_SECRETS` | `false` | `src/lib/cloudSync.ts` | Defina como `true` para permitir que o endpoint do Cloud Sync substitua as credenciais locais. O predefinido é `false`. | | `OMNIROUTE_CLOUD_SYNC_ENFORCE_SIGNATURE` | `false` | `src/lib/cloudSync.ts` | Defina como `true` para rejeitar uma resposta não assinada do Cloud Sync quando não está configurado nenhum segredo local (#13679). Uma assinatura presente é sempre verificada — e sempre rejeitada quando `OMNIROUTE_CLOUD_SYNC_SECRET` não é definido como — independentemente deste sinalizador. O padrão muda para aplicado na v3.9. | | `OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP` | `false` | `src/app/api/providers/zed/import/route.ts` | Defina como `true` para voltar ao comportamento de "importar tudo" de um passo da v3.8.5 sem confirmação do utilizador. | | `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | OAuth, Painel, sincronização | URL orientado para o público para OAuth redirect_uri, links do painel e URLs público gerado. Defina isto como URL público estável quando os retornos de chamada OAuth ou os links de navegador gerados devem utilizar um host de proxy reverso canónico. | | `NEXT_PUBLIC_CLOUD_URL` | _(vazio)_ | Lado do cliente | Espelho do lado do cliente de `CLOUD_URL`. | | `NEXT_PUBLIC_APP_URL` | _(desativado)_ | `src/shared/services/cloudSyncScheduler.ts` | Fallback legado para `NEXT_PUBLIC_BASE_URL`. | | `NEXT_PUBLIC_PORT` | _(desativar — volta para `PORT`)_ | `src/shared/hooks/useDisplayBaseUrl.ts` | Porta substituta do lado do cliente para a apresentação URLs quando não é conhecida nenhuma origem (SSR/tests); ler antes de `PORT`. | | `OMNIROUTE_PUBLIC_BASE_URL` | _(desativado)_ | Resolvedor de origem pública, imagem URLs | Origem OmniRoute orientada para o navegador de maior prioridade utilizada para a geração pública URL e validação de origem do navegador sem painel. Defina isto quando OpenWebUI ou outro relé atingir OmniRoute por um URL interno, mas o browser do utilizador deve ir buscar os media gerados a um LAN, túnel ou origem pública. Fazer** não** inclui `/v1`. | | `OMNIROUTE_PROVIDER_MANIFEST_URL` | _(desativado)_ | `open-sse/config/providerPluginManifestUrl.ts` | Manifesto do plugin do fornecedor absoluto URL anunciado para clientes secundários. Quando não está definido, OmniRoute deriva `/api/v1/provider-plugin-manifest` da origem do pedido ou HOST/PORT. | | `OMNIROUTE_PUBLIC_PROTOCOL` | `http` | `open-sse/config/providerPluginManifestUrl.ts` | Protocolo utilizado ao derivar o manifesto do plug-in do fornecedor URL a partir do HOST/PORT sem uma origem de pedido. Defina como `https` atrás de um proxy público com terminação TLS quando não estiver definido nenhum `OMNIROUTE_PROVIDER_MANIFEST_URL` explícito. | | `OMNIROUTE_TRUST_PROXY` | _(desativado)_ | `src/server/origin/publicOrigin.ts` | Modo de confiança opcional para cabeçalhos de origem pública encaminhados. Unset = não confia no `Forwarded` / `X-Forwarded-*` para decisões de segurança. `true` / `loopback` confia no host/proto encaminhado apenas a partir de um proxy de loopback com carimbo de token. `private` / `lan` também confia em pares de proxy de LAN privada, permite que a ponte `API_PORT` mantenha o `X-Forwarded-For` de tal par e permite que as rotas LOCAL_ONLY aceitem um cliente de rede privada que tal proxy reporta (nunca um pedido de túnel Cloudflare, uma cadeia apenas de loopback ou o portão de token CLI apenas de loopback). Prefira `NEXT_PUBLIC_BASE_URL` explícito na produção. | | `KIE_CALLBACK_URL` | _(desativado)_ | `open-sse/utils/kieTask.ts` | Retorno de chamada público URL para trabalhos assíncronos kie.ai. Substituição de prioridade mais elevada antes `OMNIROUTE_KIE_CALLBACK_URL` e `OMNIROUTE_PUBLIC_URL`. | | `OMNIROUTE_KIE_CALLBACK_URL` | _(desativado)_ | `open-sse/utils/kieTask.ts` | Grafia alternativa de `KIE_CALLBACK_URL`. Retorna quando a variável primária não está definida. | | `OMNIROUTE_PUBLIC_URL` | _(desativado)_ | `open-sse/utils/kieTask.ts` | Origem pública utilizada para compor o callback assíncrono URLs. Fallback de menor prioridade para chamadas de retorno kie.ai; também utilizado como URL público genérico para outros relés. | | `OMNIROUTE_CROF_USAGE_URL` | `https://crof.ai/usage_api/` | `open-sse/services/usage.ts` | Endpoint de pesquisa de quota CrofAI utilizado pela página Utilização. Substituição para relés/dispositivos de teste. | | `OMNIROUTE_CLINEPASS_USAGE_URL` | `https://api.cline.bot/api/v1/users/me/plan/usage-limits` | `open-sse/services/usage/clinepass.ts` | Endpoint de quota ClinePass de 5 horas/semanal/mensal utilizado pela página Utilização. Substituição para relés/dispositivos de teste. | | `OMNIROUTE_OPENCODE_QUOTA_URL` | `https://opencode.ai/zen/go/v1/usage` | `open-sse/services/opencodeQuotaFetcher.ts` | Endpoint oficial de utilização OpenCode Go autenticado por chave API utilizado pela página Utilização. Substituição para relés/dispositivos de teste. | | `OPENCODE_SYNTHESIZE_CLI_HEADERS` | `true` | `open-sse/executors/opencode.ts` | Sintetizar os cabeçalhos de identidade OpenCode CLI (User-Agent, x-opencode-client/project, request/session UUIDs) nos pedidos upstream opencode-go/zen que o cliente não enviou, pelo que Cloudflare na saída VPS aceita-os (#6210/#5997). Ativado por defeito desde #10571; desativar com `false`/`0`/`no`/`off`. | | `OPENCODE_USER_AGENT` | `opencode/1.18.31` | `open-sse/utils/opencodeHeaders.ts` | User-Agent padrão utilizado quando `OPENCODE_SYNTHESIZE_CLI_HEADERS` está ativado e nenhuma substituição `_USER_AGENT` por fornecedor está definida. Aplicado apenas a executores de código aberto. Num pedido sem chave nas portas upstream, um valor configurado que não carrega `opencode/= 1.17>` é substituído por este padrão em vez de ser recusado. | | `OMNIROUTE_FORWARD_ATTRIBUTION` | `1` (ligado) | `open-sse/utils/opencodeHeaders.ts` | Reencaminhe os cabeçalhos de atribuição de aplicações cliente (`x-session-id`, `x-title`, `http-referer`) para os fornecedores upstream, de modo a que um pedido que comece dentro de um chicote listado mantenha a sua identidade através do router (OpenRouter publisher gates key neles). `0`/`false`/`no`/`off` mantém a identidade registry/operator e elimina os valores fornecidos pelo cliente. Os cabeçalhos personalizados configurados pelo operador superam sempre os valores do cliente. | | `OPENCODE_CLIENT` | `desktop` | `open-sse/executors/opencode.ts` | Valor para o cabeçalho `x-opencode-client` sintetizado quando `OPENCODE_SYNTHESIZE_CLI_HEADERS` está ativado. | | `OPENCODE_PROJECT` | `global` | `open-sse/executors/opencode.ts` | Valor para o cabeçalho `x-opencode-project` sintetizado quando `OPENCODE_SYNTHESIZE_CLI_HEADERS` está ativado. | | `OMNIROUTE_EGRESS_IP_LOCK_PROVIDERS` | _(desativado)_ | `open-sse/config/providerErrorRules.ts` | Conjunto eficaz de fornecedores cujas falhas upstream são agrupadas pela saída IP (um 429 estaciona cada ligação irmã partilhando esse IP). O Unset utiliza o padrão de nível gratuito `opencode,opencode-go,opencode-cli`; `none`/`off`/`false`/`0` desativa totalmente a cascata; uma lista separada por vírgulas substitui o conjunto. Os planos pagos são upstream agrupados em contas e podem desativá-los com segurança (#9611). | | `OMNIROUTE_EGRESS_QUOTA_ROTATION_PROVIDERS` | _(desativado)_ | `open-sse/config/providerErrorRules.ts` | Âmbito de rotação de saída de recusa de quota. Unset separa um membro do pool num 429 apenas para a família com intervalo de IP acima; `all` estende esta gravação a todos os fornecedores, de modo que um limite de taxa recebido através de um membro faz com que a escolha seguinte saia noutro local. Qualquer valor diferente de `all` será ignorado. Necessita de `PROXY_SKIP_RECENTLY_FAILED` (ativado por defeito). A loja é codificada por endereço de saída, e não por (fornecedor, endereço), pelo que são 429 parques alargados para cada fornecedor até que o período decorra (5 min, duplicando para 15). Leia o resultado por resposta, para que seja aplicada uma alteração sem reiniciar. | | `OPENCODE_FREE_TIER_REQUEST_CONTRACT` | _(desativado)_ | `open-sse/executors/opencodeFreeTierContract.ts` | Defina como `off` para parar de ajustar o corpo dos pedidos OpenCode sem chave (sinalizador de streaming e lista de ferramentas). Os cabeçalhos ainda são aplicados. Leia por solicitação, para que uma alteração entre em vigor imediatamente. | | `OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS` | _(desativado)_ | `open-sse/executors/opencodeFreeTierContract.ts` | Nomes de ferramentas separados por vírgula para declarar num pedido OpenCode sem chave que não carrega nenhuma, quando ainda não foi observado nada para esse modelo. O vazio volta para um único espaço reservado que o modelo é instruído a não chamar. No máximo 32 entradas, `[A-Za-z_][A-Za-z0-9_-]{0,63}`; entradas inválidas são ignoradas. | | `OPENCODE_FREE_TIER_CREDENTIAL` | `public` | `open-sse/executors/opencodeFreeTierContract.ts` | Credencial enviada na via de nível livre fechada (`https://opencode.ai/inference/v1`). Desde 21/10/2026, esta pista responde 403 `Model access is disabled` a uma chave API real e, em vez disso, serve o literal anónimo. `key` mantém a chave API do operador, `none`/`off` não envia qualquer cabeçalho de credencial, qualquer outro literal é enviado como token de portador. Leia por solicitação. | | `OPENCODE_FREE_TIER_RELAY_URL` | desarmar | `src/lib/opencodeFreeRelay.ts` | Base URL do relé Bun para pedidos OpenCode de nível livre fechados. Quando definidos, estes pedidos carregam o prompt do sistema OpenCode CLI e o conjunto de ferramentas e são enviados através do relé (`scripts/ops/opencode-free-relay.ts`), porque o upstream responde 429 para clientes não-Bun HTTP. O loopback URLs é iniciado com o servidor quando `bun` está ligado PATH; um caminho no URL é ignorado. `http://` simples só é aceite para hosts de loopback (`localhost`, `127.0.0.0/8`, `::1`); qualquer outro host deve utilizar `https://`, caso contrário, os pedidos falharão com um erro explícito. Apenas conclusões de bate-papo. Leia por solicitação. | | `OPENCODE_FREE_RELAY_BUN` | `bun` em PATH | `src/lib/opencodeFreeRelay.ts` | binário Bun utilizado para iniciar o relé. | | `OPENCODE_FREE_RELAY_SCRIPT` | `scripts/ops/opencode-free-relay.ts` na raiz do pacote | `src/lib/opencodeFreeRelay.ts` | Caminho do script de retransmissão. O padrão é resolvido a partir da raiz do pacote instalado e, em seguida, do diretório de trabalho. | | `OPENCODE_FREE_RELAY_HOST` | `127.0.0.1` | `scripts/ops/opencode-free-relay.ts` | Anfitrião de escuta de retransmissão. | | `OPENCODE_FREE_RELAY_PORT` | `20199` | `scripts/ops/opencode-free-relay.ts` | Porta de escuta de retransmissão. | | `OPENCODE_FREE_RELAY_UPSTREAM` | `https://opencode.ai` | `scripts/ops/opencode-free-relay.ts` | Origem para a qual o relé encaminha. Deve ser `https://` (`http://` apenas para a origem do teste de loopback); o relé recusa-se a arrancar de outra forma. | | `OPENCODE_FREE_RELAY_TOKEN` | desarmar | `scripts/ops/opencode-free-relay.ts`, `open-sse/executors/opencodeRelay.ts` | Segredo partilhado. OmniRoute envia em `x-opencode-relay-auth`; o relé responde 401 sem ele. Obrigatório: um relé com `OPENCODE_FREE_RELAY_HOST` sem loopback recusa-se a arrancar sem ele. | | `OPENCODE_FREE_RELAY_PROXY_ALLOWLIST` | desarmar | `scripts/ops/opencode-free-relay.ts` | Proxies de saída `host` ou `host:port` separados por vírgula que uma retransmissão sem loopback aceita dos chamadores (`x-opencode-relay-proxy`); qualquer outro proxy responde 403. Ignorado numa ligação de loopback. | | `OMNIROUTE_OLLAMA_CLOUD_USAGE_URL` | `https://ollama.com/settings` | `open-sse/services/usage.ts` | Ollama Configurações de nuvem URL utilizadas para extração de quota. Substituição para relés/dispositivos de teste. | | `OMNIROUTE_OLLAMA_CLOUD_BALANCE_URL` | `https://ollama.com/api/balance` | `open-sse/services/ollamaCloudBalance.ts` | Ollama Endpoint de equilíbrio upstream documentado na nuvem (`GET https://ollama.com/api/balance`, `Authorization: Bearer `). Leia uma vez no carregamento do módulo. Utilizado primeiro para a quota Ollama Cloud quando a ligação tem uma chave API ; o raspador de cookies da página de definições permanece como substituto. Substituição para relés/dispositivos de teste. | | `OLLAMA_USAGE_COOKIE` | _(desativado)_ | `open-sse/services/usage.ts` | Cookie Ollama Cloud `__Secure-session` utilizado para extração de quota da página de definições. Confidencial; prefira o campo Painel por ligação quando estão configuradas várias contas. | | `OLLAMA_CLOUD_USAGE_COOKIE` | _(desativado)_ | `open-sse/services/usage.ts` | Alternativo Ollama Cloud `__Secure-session` cookie env var. Confidencial; prefira o campo Painel por ligação quando estão configuradas várias contas. | | `OMNIROUTE_OLLAMA_USAGE_COOKIE` | _(desativado)_ | `open-sse/services/usage.ts` | Alternativa Ollama Cloud `__Secure-session` cookie env var utilizada antes dos aliases mais curtos. Confidencial; prefira o campo Painel por ligação quando estão configuradas várias contas. | | `OMNIROUTE_CODEWHISPERER_BASE_URL` | `https://codewhisperer.us-east-1.amazonaws.com` | `open-sse/services/usage.ts` | CodeWhisperer (AWS Kiro) limite de utilização do endpoint. Substituição para relés/dispositivos de teste. | > [!IMPORTANT] > Ao implementar atrás de um proxy reverso (nginx, Caddy), defina `NEXT_PUBLIC_BASE_URL` como o seu URL público estável (por exemplo, `https://omniroute.example.com`) quando os OAuth callbacks ou os links públicos gerados precisarem de utilizar esse nome de host. Sem isso, os retornos de chamada OAuth podem falhar porque o redirect_uri não corresponderá e os links públicos gerados podem apontar para a origem interna do contentor. > > Mantenha `BASE_URL` como um loopback/container URL interno para trabalhos de servidor para servidor. Não utilize um navegador `Origin` ou um nome de host público para pesquisas internas com credenciais. > > As gravações autenticadas do painel não requerem uma base pública estática URL: o painel envia pedidos inseguros da mesma origem com um token CSRF ligado à sessão. OmniRoute ainda centraliza a validação de origem pública para integrações de navegador sem painel: vars URL env públicos explícitos são confiáveis primeiro; Os cabeçalhos `Forwarded` / `X-Forwarded-*` em bruto são ignorados, a menos que `OMNIROUTE_TRUST_PROXY` esteja ativado e o par proxy imediato seja carimbado como fidedigno. Não utilize as definições CORS para corrigir pedidos de painel de mesma origem; CORS é apenas para clientes de browser de origem cruzada. --- ## 8. Proxy de saída Encaminha as chamadas upstream do fornecedor LLM através de um proxy HTTP ou SOCKS5 para controlo de saída, encaminhamento geográfico ou mascaramento IP. `OMNIROUTE_UPSTREAM_HTTP2_ENABLED` é padronizado como `true`. Defina-o como `false`, `0`, `no` ou `off` para forçar HTTP/1.1 nos despachantes Undici em `open-sse/utils/proxyDispatcher.ts` e `open-sse/utils/proxyFetch.ts`: saída directa, proxies HTTP(S)/SOCKS, relés e as suas novas tentativas de socket. Isto preserva a verificação do certificado TLS, a autenticação de proxy, os limites de ligação e as definições de keep-alive. Reinicie OmniRoute após alterá-lo porque os despachantes são armazenados em cache e os agentes de retransmissão são criados no arranque. O switch não controla as impressões digitais wreq TLS ou os transportes específicos do fornecedor. | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------------------------- | -------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ENABLE_SOCKS5_PROXY` | `true` | `open-sse/executors` | Active o agente proxy SOCKS5 para chamadas upstream. Desative com `false`. | | `OMNIROUTE_GZIP_REQUEST_BODIES` | `true` | `open-sse/executors/base/gzipRequestBody.ts` | Gzip o corpo do pedido enviado para o `api.anthropic.com` oficial (4096 caracteres +, apenas ligações diretas; ignorado atrás de um proxy, representação TLS ou `NODE_EXTRA_CA_CERTS`). Anthropic apenas aceita gzip. Uma codificação recusada (415, um 400/403 não antrópico ou uma análise JSON de origem 400) é reenviada descomprimida uma vez e a origem permanece descomprimida durante uma hora. Desactive com `0`, `false`, `off` ou `no`. | | `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` | `true` | Lado do cliente | Sensibilização do lado do cliente sobre a disponibilidade SOCKS5. | | `PROXY_SKIP_RECENTLY_FAILED` | `true` | `src/shared/utils/featureFlags.ts` | Sinalizador de características ativado por predefinição (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md) ; uma substituição DB do painel ganha). Os pools de proxy e a rotação por conta deixam de servir novamente um membro que acabou de falhar (recusou a sonda TCP ou um 429 através dela) por um período que duplica a cada repetição, até um limite. `false` restaura a seleção simples. | | `SELECTOR_CONTROL_ALLOWLIST` | _(desativado)_ | `src/lib/proxySubscription/selectorGuard.ts` | Lista de permissões para alvos de controlo de selector de núcleo local para além do loopback (comma/space hosts separados ou IPs, `*` abre LAN/private mas nunca metadata/link-local). O loopback sobre http/https é permitido por defeito. Um valor DB do painel vence esta variável quando definido e não vazio. | | `PROXY_QUOTA_429_BASE_MS` | `300000` | `open-sse/utils/proxyRefusalMemory.ts` | Período base (ms) da retirada de 429, duplicado a cada repetição. Leia uma vez no arranque. Limitado a `1000..3600000`; fora do intervalo ou ilegível volta ao padrão com um aviso. | | `PROXY_QUOTA_429_MAX_MS` | `900000` | `open-sse/utils/proxyRefusalMemory.ts` | Limite (ms) da retirada de 429. Ler uma vez no arranque. Limitado a `1000..3600000`; fora do intervalo ou ilegível volta ao padrão com um aviso. Quando o limite está abaixo da base, volta ao padrão. A redução do limite também reduz o esquecimento contínuo: as entradas eliminam `2 x max` após a expiração. | | `PROXY_POOL_SHARED_EGRESS_ORDER` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de recurso de aceitação (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md) ; uma substituição DB do painel ganha). Para prestadores cuja quota é dividida por endereço de saída, classifique um membro da pool que partilhe o endereço de saída observado de um membro recentemente recusado logo abaixo dos membros saudáveis. Apenas pedido, nunca excluído. Necessita de `PROXY_SKIP_RECENTLY_FAILED`, que produz o sinal de recusa que lê. | | `PROXY_WEBHOOK_REBOUND_MS` | `300000` | `src/lib/proxyEvents/proxyTransitionBridge.ts` | Janela de recuperação (ms) limitando alertas repetidos de webhook `proxy.set_aside` por membro da pool para que uma explosão de recusas envie um evento. Leia sobre cada emissão. Limitado a `1000..3600000`; fora do intervalo ou ilegível volta ao padrão silenciosamente. | | `HTTP_PROXY` | _(desativado)_ | padrão Node.js | proxy HTTP para chamadas upstream. | | `HTTPS_PROXY` | _(desativado)_ | padrão Node.js | proxy HTTPS para chamadas upstream. | | `ALL_PROXY` | _(desativado)_ | padrão Node.js | Proxy universal (suporta `socks5://`). | | `OMNIROUTE_PROXY_ECHO_URL` | _(desativado)_ | `src/lib/proxyEchoTarget.ts` | Fixa o destino echo-IP utilizado pelas sondagens de saída do proxy num único URL. Não definido, o probe tenta `api64.ipify.org` e depois `api4.ipify.org` para que os túneis IPv4-only não sejam reportados como mortos (#9694). | | `NO_PROXY` | _(desativado)_ | padrão Node.js | hostnames/IPs separado por vírgula para ignorar o proxy. | | `OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS` | `32` | `open-sse/utils/proxyDispatcher.ts` | Máximo de sockets simultâneos por despachante proxy HTTP/SOCKS em cache. Os fluxos SSE de longa duração, como Codex `/v1/responses` necessitam de mais do que uma ligação quando vários pedidos partilham o mesmo proxy ao nível da conta. Valores acima de `256` são limitados. | | `SOCKS_HANDSHAKE_TIMEOUT_MS` | `10000` | `open-sse/utils/socksConnectorWithFamily.ts` | Tempo limite de handshake (ligação)SOCKS5 em ms. Aumente-o quando um único host de gateway residencial for atingido por uma elevada simultaneidade (por exemplo, 100 pedidos simultâneos). — o handshake real pode exceder 10s num pool saturado, mesmo que o proxy esteja acessível, o que de outra forma aparece como um `[Proxy Fast-Fail] Proxy unreachable` falso. Limitado a `120000`. | | `PROXY_FAIL_OPEN` | `false` | `src/sse/handlers/chatHelpers.ts` | Quando `false` (padrão), um pedido cujo proxy atribuído não consegue resolver é** recusado (fechado com falha)** em vez de recorrer a uma ligação direta, — evita fugas de IP real. Configure `true` para restaurar o substituto herdado DIRECT. | | `ENABLE_TLS_FINGERPRINT` | `false` | `open-sse/executors` | Falsificação de impressões digitais TLS usando wreq-js (imita o Chrome 124). Contraria o bloqueio JA3/JA4. | | `TLS_FINGERPRINT_PROVIDERS` | _(desativado)_ | `open-sse/utils/proxyFetch.ts` | Lista de permissões de fornecedores separados por vírgula para o novo encaminhamento TLS com proxy (`open-sse/utils/proxyFetch.ts`). TLS direto mantém o seu comportamento legado quando não está definido; apenas estes fornecedores passam pela ponte de impressão digital Chrome-124. Groq (`api.groq.com`) é eliminado mesmo quando a lista de permissões não está definida, porque o Chrome JA3 aciona Cloudflare 1010 enquanto o undici nativo atinge o API. | | `OMNIROUTE_TURNSTILE_IGNORE_TLS_ERRORS` | `false` | `open-sse/services/claudeTurnstileSolver.ts` | Permitir que o contexto do browser Claude Turnstile Playwright ignore os erros do certificado HTTPS. | ### Cenários | Cenário | Configuração | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **SOCKS5 através do túnel SSH** | `ALL_PROXY=socks5://127.0.0.1:7890`, `ENABLE_SOCKS5_PROXY=true` | | **Procuração HTTP corporativa** | `HTTP_PROXY=http://proxy.corp.com:3128`, `HTTPS_PROXY=http://proxy.corp.com:3128`, `NO_PROXY=localhost,internal.corp.com` | | **Anti-impressão digital** | `ENABLE_TLS_FINGERPRINT=true` — requer `wreq-js` (incluído) | | **Saída controlada/sem acesso direto** | Deixe `PROXY_FAIL_OPEN=false` (padrão). Os pedidos falham muito quando o proxy está indisponível em vez de vazar via direto. | | **Legacy/dev — permite fallback direto** | `PROXY_FAIL_OPEN=true`. Restaura o comportamento de pré-proteção: ligação direta utilizada quando a resolução do proxy falha. | > **Nota ( ignorar validação NVIDIA — #3226):** O endpoint de validação da chave API do NVIDIA pára quando é encaminhado através da pesquisa global proxy/TLS-patched (undici dispatcher → 504). `src/lib/providers/validation.ts::directHttpsRequest()` ignora intencionalmente o patch de proxy para essa chamada de validação utilizando `safeOutboundFetch({ bypassProxyPatch: true })`. Esta é uma exceção documentada e com âmbito definido — faz** não** afeta a saída chat/usage. O desvio é fixado no âmbito por `tests/unit/proxy-bypass-scope-guard-3226.test.ts`. --- ## 9. Integração da ferramenta CLI Controla a forma como OmniRoute descobre e inicia os sidecars CLI (Claude Code, Codex, etc.). | Variável | Predefinição | Arquivo de origem | Descrição | | --------------------------------- | ------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLI_MODE` | `auto` | `src/shared/services/cliRuntime.ts` | sistema de pesquisa `auto` = PATH; `manual` = utiliza apenas caminhos explícitos. | | `CLI_EXTRA_PATHS` | _(desativado)_ | `src/shared/services/cliRuntime.ts` | Entradas PATH adicionais para a descoberta binária CLI (separadas por dois pontos). | | `CLI_CONFIG_HOME` | _(desativado)_ | `src/shared/services/cliRuntime.ts` | Substitua o directório home para ler as definições CLI (`~/.claude`, `~/.codex`). Deve ser absoluto e dentro do processo home —** ou** , num contentor, um caminho montado em ligação (é assim que funciona `/host-home` ). Qualquer outra coisa volta para o directório home. | | `CLI_ALLOW_CONFIG_WRITES` | `true` | `src/shared/services/cliRuntime.ts` | Permitir OmniRoute escreva ficheiros de configuração CLI (atualização de token, dados de sessão). Defina como `false` para fazer com que cada escrita de configuração CLI falhe com um erro explícito de "escrita desativada". | | `CLI_CLAUDE_BIN` | `claude` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Claude CLI. | | `CLI_CODEX_BIN` | `codex` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Codex CLI. | | `CLI_DROID_BIN` | `droid` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Droid CLI. | | `CLI_OPENCLAW_BIN` | `openclaw` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário OpenClaw CLI. | | `CLI_CURSOR_BIN` | `agent`, então `cursor` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário do agente Cursor. Sem ele, a detecção tenta primeiro `agent` e volta a `cursor`. | | `CLI_CLINE_BIN` | `cline` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Cline CLI. | | `CLI_5DIVE_BIN` | `5dive` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário 5dive CLI. | | `CLI_5DIVE_STATE_DIR` | `/var/lib/5dive` | `src/shared/services/cliRuntime.ts` | Diretório de estado do sistema 5dive (perfis de autenticação de propriedade do root); espelha o próprio padrão STATE_DIR do 5dive. | | `CLI_CONTINUE_BIN` | `cn` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para continuar o binário CLI. | | `CLI_QODER_BIN` | `qodercli` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Qoder CLI. | | `CLI_QWEN_BIN` | `qwen` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Qwen Código CLI. | | `CLI_AIDER_BIN` | `aider` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Aider CLI. | | `CLI_GOOSE_BIN` | `goose` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Goose CLI. | | `CLI_WHYCODES_BIN` | `whycodes` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário WhyCodes CLI. | | `CLI_GEMINI_BIN` | `gemini` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para Google Gemini CLI binário — apenas verificações detection/health do lado do servidor; `omniroute run gemini` resolve o binário `gemini` do sistema PATH. | | `CLI_KILO_BIN` | `kilocode` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Kilo Code CLI. | | `CLI_OPENCODE_BIN` | `opencode` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário OpenCode CLI. | | `CLI_HERMES_BIN` | `hermes` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Hermes. Partilhado por ambas as entradas do catálogo (`hermes` e `hermes-agent`). | | `CLI_FORGE_BIN` | `forge` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário ForgeCode CLI. | | `CLI_JCODE_BIN` | `jcode` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário jcode CLI. | | `CLI_DEEPSEEK_TUI_BIN` | `deepseek-tui` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário DeepSeek TUI. | | `CLI_CODEWHALE_BIN` | `codewhale` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário CodeWhale CLI. | | `CLI_SMELT_BIN` | `smelt` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Smelt CLI. | | `CLI_PI_BIN` | `pi` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Pi (pi-coding-agent). | | `CLI_CRUSH_BIN` | `crush` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Crush CLI. | | `CLI_OMP_BIN` | `omp` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário do agente Oh My Pi (`omp`). | | `CLI_LETTA_BIN` | `letta` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Letta CLI. | | `CLI_PRIME_AGENT_BIN` | `prime-agent` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Prime Agent (Prime Intellect). | | `CLI_WINDSURF_BIN` | _(nenhum)_ | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário Windsurf. navios Windsurf** nenhum comando padrão** A deteção binária — permanece desativada até ser definida. | | `CLI_DEVIN_BIN` | `devin` | `open-sse/executors/devin-cli.ts` | Caminho personalizado para o binário Devin CLI (v3.8.0). Utilizado pelo executor Windsurf/Devin. | | `DEVIN_DESKTOP_VERSION` | `3.6.27` | `open-sse/executors/devin-desktop.ts` | Devin Ambiente de trabalho `ide_version`. As substituições devem utilizar o formato `x.y.z` ; valores inválidos regressam ao padrão verificado. | | `DEVIN_DESKTOP_EXTENSION_VERSION` | `1.48.2` | `open-sse/executors/devin-desktop.ts` | Pacote Codeium/language-server `extension_version`, distinto do Desktop `ide_version`. As substituições devem utilizar `x.y.z`; valores inválidos utilizam o padrão empacotado. | | `CLI_DEVIN_AGENTIC_BIN` | `devin` | `open-sse/executors/devin-cli-agentic.ts` | Substituição Devin CLI apenas de ponte agente. O executor apenas aceita o upstream ACP stdio local. | | `DEVIN_AGENTIC_HOME` | _(obrigatório)_ | `open-sse/executors/devin-cli-agentic.ts` | Início isolado absoluto para o subprocesso agente Devin ; os caminhos de ponte aceites são `/home/bridge` e os caminhos `.sandbox` locais de tarefa (em Windows, `C:\...\.sandbox\...`). | | `DEVIN_AGENTIC_ACP_TIMEOUT_MS` | `120000` | `open-sse/executors/devin-cli-agentic.ts` | Duração máxima de um turno Devin ACP antes da ponte terminar o filho e devolver um tempo limite explícito. | | `DEVIN_BRIDGE_MODEL` | `devin-cli-agentic/swe-1-7` | `docker/devin-bridge/compose.yml` | Alias principal do modelo de código Claude para a ponte isolada. O chicote ativo substitui o exemplo por um modelo devolvido pela conta Devin atual. | | `DEVIN_BRIDGE_SONNET_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias de ponte isolada utilizada quando o código Claude solicita o seu Sonnet padrão. | | `DEVIN_BRIDGE_OPUS_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias de ponte isolada utilizada quando o código Claude solicita o seu padrão Opus. | | `DEVIN_BRIDGE_HAIKU_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias de ponte isolada utilizada quando Claude Code solicita o seu padrão do Haiku. | | `DEVIN_BRIDGE_SUBAGENT_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias de ponte isolada utilizada para subagentes do código Claude. | | `DEVIN_SEAT_API_URL` | `https://server.codeium.com` | `open-sse/services/usage/devinCli.ts` | Substituição opcional para o API de gestão de assentos Codeium utilizado pelo Devin CLI quota (`GetUserStatus`). | | `AUGGIE_BIN` | `auggie` | `open-sse/executors/auggie.ts` | Substituição de caminho absoluto para o binário Augment (Auggie) CLI utilizado pelo fornecedor `auggie` local. Volta a `CLI_AUGGIE_BIN`, em seguida, uma pesquisa PATH. | | `CLI_AUGGIE_BIN` | `auggie` | `open-sse/executors/auggie.ts` | Substituição de alias para o caminho binário Augment (Auggie) CLI (verificado após `AUGGIE_BIN`). | | `ZCODE_BIN` | `zcode` | `open-sse/executors/zcode.ts` | Binário utilizado para o cliente stdio do fornecedor `zcode` local. Volta a `zcode` em PATH. | | `ZCODE_ARGS` | — | `open-sse/executors/zcode.ts` | Matriz JSON (≤ 16 strings) de argumentos extra passados para o binário `zcode` quando iniciado via `cliTools`. | | `ZCODE_CWD` | `process.cwd()` | `open-sse/executors/zcode.ts` | Diretório de trabalho para o subprocesso ZCode app-server. | | `ZCODE_TRANSPORT` | `app-server` | `open-sse/executors/zcode.ts` | `app-server` (padrão) ou `gateway`.** Experimental/sem suporte:** `gateway` envia pedidos diretos do Z.AI Coding Plan HTTP reproduzindo o protocolo do cliente ZCode (assinatura de handshake e cabeçalho de prova de trabalho do cliente 0.16.9) e pode falhar quando ZCode é atualizado. Apenas aceita o perfil Plano de Codificação Individual. | | `ZCODE_PROVIDER_ID` | `account:zai-individual-coding-plan` | `open-sse/executors/zcode.ts` | Perfil de fornecedor nativo exato para seleção de modelo. Quando não está definido, é utilizado o perfil da conta do Plano Individual, voltando a `builtin:zai-coding-plan` (a entrada de configuração que contém a chave do Plano de Codificação Individual). Defina um ID exato como `account:zai-start-plan` para fixar este perfil; um perfil fixado nunca volta. | | `ZCODE_SERVER_RUNTIME_ROOT` | `~/.zcode/server` | `open-sse/executors/zcode.ts` | Raiz do tempo de execução do servidor de aplicações ZCode (onde residem o `node` e `zcode-server.cjs` incluídos). | | `ZCODE_SERVER_NODE` | `/node` | `open-sse/executors/zcode.ts` | Executável a partir do nó utilizado para alojar o servidor de aplicações ZCode. | | `ZCODE_SERVER_ENTRY` | `/zcode-server.cjs` | `open-sse/executors/zcode.ts` | Script de entrada do servidor de aplicações utilizado para alojar o servidor ZCode. | | `ZCODE_STARTUP_TIMEOUT_MS` | `10000` | `open-sse/executors/zcode.ts` | Tempo limite de arranque (ms) antes de o arranque do servidor de aplicações ZCode ser considerado com falha. | | `ZCODE_RPC_TIMEOUT_MS` | `30000` | `open-sse/executors/zcode.ts` | Tempo limite RPC por pedido (ms) para uma chamada ZCode app-server. | | `ZCODE_TURN_TIMEOUT_MS` | `120000` | `open-sse/executors/zcode.ts` | Duração máxima (ms) de um turno ZCode antes de o supervisor expirar. | | `ZCODE_POLL_INTERVAL_MS` | `250` | `open-sse/executors/zcode.ts` | Intervalo de pesquisa (ms) para a conclusão do turno ZCode. | | `MINIMAX_CODE_GATEWAY_URL` | `https://agent.minimax.io/mavis/api/v1/llm/v1/messages` | `open-sse/executors/minimaxCodeGateway.ts` | Endpoint do gateway MiniMax gerido que responde com chamadas de ferramentas nativas. É um endpoint interno da aplicação MiniMax Code, não um API público documentado: pode mudar sem aviso prévio e o pedido falha com um 502 que nomeia o transporte. | | `MINIMAX_CODE_GATEWAY_TIMEOUT_MS` | `60000` | `open-sse/executors/minimax-code.ts` | Duração máxima (ms) de uma tentativa de gateway gerido. A chamada completa (tentativa, espera, uma nova tentativa) dura cerca de dois minutos, pelo que um gateway inacessível não consegue manter um slot de modelo durante muito tempo. | | `MINIMAX_CODE_GATEWAY_RETRIES` | `1` | `open-sse/executors/minimaxCodeGateway.ts` | Novas tentativas de uma chamada de gateway gerida que falha com um erro transitório (429, 5xx, ligação interrompida). | | `MINIMAX_CODE_CONTEXT_WINDOW` | `1000000` | `open-sse/executors/minimaxCodeGateway.ts` | A janela de contexto solicitada pelo gateway MiniMax gerido. O catálogo de modelos do produto Código MiniMax declara 512000 como a janela padrão do MiniMax-M3 e MiniMax-M3. 1-Flash e oferece 1000000 como a segunda; o gateway responde na janela maior (um pedido de 1.024.056 tokens de entrada foi respondido com 200 em 23/10/2026). Defina como 512000 para restringir o pedido — o plano conta menos. Todos os outros valores são ignorados, pelo que um erro de digitação não pode solicitar uma janela que o modelo não possui. | | `MINIMAX_CODE_MAX_INPUT_TOKENS` | `1000000` | `open-sse/executors/minimaxCodeGateway.ts` | Limite máximo (em tokens de entrada) de um pedido enviado para o gateway MiniMax gerido. Um pedido maior é recusado localmente com um 413 em vez de ser encaminhado, porque uma recusa do gateway bloqueia o modelo dos substitutos. O predefinido é a janela de contexto do gateway (1000000); este valor pode diminuir este teto, nunca elevá-lo acima da janela. | | `MINIMAX_CODE_MAX_TOKENS` | `8192` | `open-sse/executors/minimaxCodeGateway.ts` | Número máximo de tokens com os quais o gateway gerido pode responder. | | `MINIMAX_CODE_AUTH_FILE` | `~/.minimax/auth/prod//mcode-public/auth.json` | `open-sse/executors/minimaxCodeGateway.ts` | Caminho do perfil de autenticação do Código MiniMax que contém o token de acesso e de atualização. | | `MINIMAX_CODE_PROFILE_DIR` | `~/.minimax` | `open-sse/executors/minimaxCodeGateway.ts` | Diretório do perfil do Código MiniMax que contém o perfil de autenticação. | | `MINIMAX_CODE_AUTH_RECORD` | _(nova geração)_ | `open-sse/executors/minimaxCodeGateway.ts` | Registo do perfil a utilizar quando tem várias contas. Vazio escolhe a geração mais nova, que é aquela que o próprio CLI atualiza. | | `MINIMAX_CODE_REGION` | `en` | `open-sse/executors/minimaxCodeGateway.ts` | Região da conta MiniMax. Decide o endpoint da conta que atualiza o token e o diretório do perfil a partir do qual a credencial é lida. | | `HERMES_HOME` | `~/.hermes` | `src/lib/cli-helper/config-generator/hermesHome.ts` | Directório inicial do Agente Hermes onde OmniRoute reads/writes a configuração do Hermes CLI. Corresponde ao env var que o instalador do Hermes PowerShell define em Windows (`%LOCALAPPDATA%\hermes`). | | `WHYCODES_HOME` | `~/.whycodes` | `src/lib/cli-helper/config-generator/whycodesHome.ts` | raiz da instância WhyCodes em que OmniRoute reads/writes `config.toml`. O mesmo env var WhyCodes lê; o padrão é `~/.whycodes` (`%USERPROFILE%\.whycodes` em Windows). | ### Sincronização automática do perfil CLI Estes sinalizadores de recursos são ativados e desativados por predefinição. Também podem ser alternados no painel CLI Code. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------- | ------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_AUTO_SYNC_CODEX_PROFILES` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | Após a sincronização do modelo de fornecedor, reescreve automaticamente os ficheiros de perfil `~/.codex/*.config.toml` do catálogo ativo. Requer `CLI_ALLOW_CONFIG_WRITES`; nunca altera a configuração active/default Codex, a autenticação, as definições do Codex-lb ou a escolha do fornecedor. | | `OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | Após a sincronização do modelo de fornecedor, reescreve automaticamente os ficheiros de perfil do código `~/.claude/profiles//settings.json` Claude do catálogo ativo. Requer `CLI_ALLOW_CONFIG_WRITES`; nunca altera a configuração, autenticação ou escolha do fornecedor active/default Claude. | ### Exemplo Docker ```bash # Mount host binaries into the container and tell OmniRoute where they are: CLI_EXTRA_PATHS=/host-cli/bin CLI_CONFIG_HOME=/host-home CLI_ALLOW_CONFIG_WRITES=true CLI_CLAUDE_BIN=/host-cli/bin/claude ``` `CLI_CONFIG_HOME` só entra em vigor quando o caminho é realmente montado por ligação a partir do host — emparelhe-o com montagens como `~/.codex:/host-home/.codex:rw` (consulte o perfil `host` em `docker-compose.yml`). Um caminho que não esteja dentro da casa do utilizador do contentor nem de uma montagem de ligação será ignorado, porque a escrita no mesmo seria descartada quando o contentor fosse recriado. A imagem é executada como `USER node`, pelo que um `/root` desmontado é** não** uma substituição válida. | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------------------------- | ------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_CONTAINER` | _(auto)_ | `src/shared/utils/containerEnv.ts` | Forçar a deteção de contentores ativada (`1`/`true`) ou desativada (`0`/`false`). Apenas necessário em tempos de execução em que a deteção automática falha. | | `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE` | `false` | `src/shared/services/cliRuntime.ts` | Permitir gravações de configuração da ferramenta CLI num caminho de contentor desmontado de qualquer forma. O equivalente CLI é `--allow-container-write`. | | `DOCKER_UPDATE_TRIGGER_FILE` | desarmar | `src/lib/system/autoUpdate.ts` | Apenas imagem Docker : painel** Atualizar agora** escreve um pedido JSON neste ficheiro (deve estar dentro de `DATA_DIR`) para que um observador do lado do host extraia e recrie o contentor. Consulte o [Guia Docker](../guides/DOCKER_GUIDE.md#dashboard-updates-in-docker). | ### Ajudantes binários CLI (`omniroute`) Estas variáveis ajustam o próprio comportamento do binário `omniroute` CLI (não a deteção de sidecar acima). | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------- | --------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_LANG` | _(sistema)_ | `bin/cli/i18n.mjs` | Forçar o idioma de saída CLI. localidade BCP-47 (por exemplo, `en`, `pt-BR`). Substitui vars env de localidade do sistema (LC_ALL, LC_MESSAGES). | | `OMNIROUTE_SHOW_LOG` | _(desativado)_ | `bin/cli/runtime/processSupervisor.mjs` | Defina como `1` para encaminhar o servidor stdout/stderr para o terminal em modo supervisionado. Equivalente ao sinalizador `--log` em `omniroute serve`. | | `OMNIROUTE_CLI_TOKEN` | _(desativado)_ | `bin/cli/api.mjs` | Token de autenticação da máquina injetado como cabeçalho `x-omniroute-cli-token`. Gerado automaticamente na tarefa 8.12. | | `GEMINI_CLI_HOME` | _(desativado)_ | `bin/cli/commands/setup-gemini.mjs` | Raiz inicial Gemini persistente; A corrida única utiliza uma casa isolada temporária. | | `OMNIROUTE_CHILD_SIGNAL_TIMEOUT_MS` | `5000` | `bin/cli/commands/run.mjs` | Período de carência em milissegundos antes de matar à força uma criança CLI sinalizada. | | `OMNIROUTE_CLI_SKIP_DEFAULT_DATA_ENV` | _(desativado)_ | `bin/omniroute.mjs` | Defina como 1 com um DATA_DIR explícito para ignorar o ficheiro de ambiente do diretório de dados do utilizador padrão. | | `OMNIROUTE_SYNC_TOKEN` | _(desativado)_ | `bin/cli/commands/sync.mjs` | Token de sincronização para `omniroute sync bundle` (`GET /api/sync/bundle` apenas aceita um token de sincronização, não uma chave API ). Equivalente a `--token`. | | `OMNIROUTE_HTTP_TIMEOUT_MS` | `30000` | `bin/cli/api.mjs` | Tempo limite HTTP por tentativa (ms) para pedidos do servidor CLI →. | | `OMNIROUTE_READY_TIMEOUT_MS` | `60000` | `bin/cli/utils/pid.mjs` | Tempo máximo (ms) que o CLI aguarda pelo endpoint de integridade do servidor antes de imprimir um aviso de tempo limite. Útil para arranques lentos a frio (por exemplo, Windows). Também configurável via `--ready-timeout`. | | `OMNIROUTE_VERBOSE` | `0` | `bin/cli/api.mjs` | Defina como `1` para imprimir os diagnósticos retry/backoff em stderr durante os comandos CLI. | | `OMNIROUTE_PLUGIN_PATH` | _(desativado)_ | `bin/cli/plugins.mjs` | Diretório personalizado para descoberta de plugins CLI (pacotes `omniroute-cmd-*` ). O predefinido é `~/.omniroute/plugins/` quando não está definido. — apenas CLI nunca chega ao scanner de plug-in do lado do servidor, que é apontado por `OMNIROUTE_PLUGINS_DIR` (secção 2). | | `OMNIROUTE_NO_UPDATE_NOTIFIER` | _(desativado)_ | `bin/omniroute.mjs` | Suprime as verificações de atualização quando definido para qualquer valor não vazio: o aviso CLI na saída do processo e o banner "atualização disponível" do painel (`GET /api/system/version` ignora então as pesquisas de npm, GitHub e notícias). O aviso CLI também permanece desativado em CI, modo silencioso e saída sem texto. | | `OMNIROUTE_DOCTOR_LIVENESS_URL` | _(derivado)_ | `bin/cli/commands/doctor.mjs` | Liveness URL sondado por `omniroute doctor`. Uma opção `livenessUrl` programática tem precedência; caso contrário, esse valor será utilizado literalmente. Não definido, o CLI deriva o endpoint `/api/health/degradation` do painel local. | | `OMNIROUTE_PROVIDER_CATALOG_PATH` | `src/shared/constants/providers/` | `bin/cli/provider-catalog.mjs` | Caminho do catálogo do fornecedor utilizado pelos comandos do fornecedor CLI. Uma opção `catalogPath` programática tem precedência. Os caminhos absolutos são usados como estão; caminhos relativos são resolvidos a partir da raiz do projeto. Não definido, o CLI utiliza o diretório de constantes do fornecedor, com o ficheiro `providers.ts` herdado como substituto. | | `OMNIROUTE_PROVIDER_TEST_MODEL` | _(padrão do fornecedor)_ | `bin/cli/provider-test.mjs` | Modelo de fallback global para testes de ligação do fornecedor CLI. A precedência é o modelo de ligação configurado, a substituição do modelo específico do fornecedor, esse valor e, em seguida, o modelo de teste integrado do fornecedor. | --- ## 10. Agente interno e integrações MCP | Variável | Predefinição | Arquivo de origem | Descrição | | ----------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_BASE_URL` | detecção automática | `open-sse/mcp-server/server.ts` | URL explícito para as ferramentas MCP/A2A atingirem OmniRoute. Substitui a deteção automática de localhost. As competências A2A falham em vez de enviar uma chave API para este URL (ou o `BASE_URL` a que recorre) quando é http simples para um endereço público, um nome de host público pontilhado ou um host de metadados de nuvem, ou contém credenciais: utilize https ou http para loopback, um contentor ou nome de serviço ou um endereço privado. | | `OMNIROUTE_API_KEY` | _(desativado)_ | módulos MCP/A2A | Chave API para chamadas internas da ferramenta MCP. as competências A2A enviam apenas para um chamador sem chave API (sessão de painel); um chamador com uma tecla atua por conta própria. | | `OMNIROUTE_API_KEY_ID` | _(desativado)_ | `open-sse/mcp-server/audit.ts` | Chave ID para atribuição do registo de auditoria MCP. | | `ROUTER_API_KEY` | _(desativado)_ | Legado | Alias legado para `OMNIROUTE_API_KEY`. | | `OMNIROUTE_A2A_HISTORY_RETENTION_DAYS` | `30` | `src/lib/a2a/taskManager.ts` | Dias de histórico de tarefas A2A mantidos na base de dados local antes de a limpeza diária eliminar uma linha. Não definido, não numérico ou `<= 0` retorna a `30`. | | `OMNIROUTE_A2A_MEMORY_HITS` | `1` | `src/lib/a2a/taskExecution.ts` | Kill-switch para o recurso de observabilidade de acessos à memória A2A. Defina como `0` para ignorar totalmente a pesquisa de recuperação de memória para uma tarefa; qualquer outro valor (incluindo não definido) mantém-no ativado. | | `OMNIROUTE_ISSUE_AGENT_ENABLED` | `false` | `src/app/api/issue-agent/runs/route.ts` | Ativa o endpoint de triagem registada offline/local Issue Agent. Deixe desativado, a menos que execute explicitamente fluxos de trabalho de triagem registados locais. | | `OMNIROUTE_ISSUE_AGENT_TIMEOUT_MS` | _(desativado)_ | `src/lib/issueAgent/execution.ts` | Tempo limite (ms) para uma única execução de triagem registada do Agente de Problemas. Fixado ao máximo interno; volta ao padrão integrado quando não definido ou inválido. | | `OMNIROUTE_CONTEXT` | _(contexto ativo)_ | `bin/cli/program.mjs`, `bin/cli/api.mjs` | CLI context/profile de modo remoto para comandos `omniroute` ; substitui o contexto ativo no armazenamento de contextos locais. Equivalente a `--context `. | | `OMNIROUTE_CONTEXT_KEYCHAIN_DISABLED` | `0` | `bin/cli/contexts.mjs` | Desative o backend opcional `keytar` OS-keychain para credenciais de contexto CLI. Quando ativadas, as credenciais permanecem no modo `config.json` `0600` e o CLI emite um aviso de fallback único; destinado à operação deliberada headless/container. | | `OMNIROUTE_MCP_ENFORCE_SCOPES` | `false` | `open-sse/mcp-server/server.ts` | Aplique o controlo de acesso baseado no âmbito nas chamadas de ferramenta MCP. | | `OMNIROUTE_MCP_SCOPES` | _(tudo)_ | `open-sse/mcp-server/server.ts` | Escopos separados por vírgula: `admin`, `combos`, `health`, `models`, `routing`, `budget`, `metrics`, `pricing`, `memory`, `skills`. | | `OMNIROUTE_PPLX_RESEARCH_ENABLED` | `0` | `open-sse/mcp-server/tools/perplexityResearch.ts` | Registe a ferramenta Perplexity Deep Research MCP. Apenas `1` regista; qualquer outra coisa deixa de fora. | | `OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS` | `false` | `open-sse/mcp-server/descriptionCompressor.ts` | Compacte as descrições da ferramenta MCP antes de serializar o manifesto. Active os valores: `1`, `true`, `on`. | | `OMNIROUTE_MCP_DESCRIPTION_COMPRESSION` | `rtk` | `open-sse/mcp-server/descriptionCompressor.ts` | Compressão algorithm/profile. Desactivar valores: `0`, `false`, `off`. | | `OMNIROUTE_MCP_FETCH_TIMEOUT_MS` | `10000` | `open-sse/mcp-server/fetchTimeout.ts` | Abortar orçamento (ms) para leituras de gestão interna do servidor MCP (saúde, resiliência, combos, quota, utilização). | | `OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS` | `60000` | `open-sse/mcp-server/fetchTimeout.ts` | Abortar o orçamento (ms) para saltos MCP que aguardam um fornecedor (`route_request`, `web_search`, `web_fetch`). | | `OMNIROUTE_MCP_SESSION_IDLE_MS` | `300000` | `open-sse/mcp-server/httpTransport.ts` | TTL ocioso (ms) antes de a varredura obter uma sessão de fluxo MCP ocioso. Uma sessão com um fluxo aberto ou um pedido em curso nunca é recolhida. Os valores não definidos, não inteiros ou não positivos voltam ao padrão. | | `OMNIROUTE_CORPUS_CACHE_SIZE` | `5` | `src/lib/localCorpus/configured.ts` | Número máximo de instâncias de índice de corpus local armazenadas em cache na memória (LRU, uma por diretório raiz indexado). Fixo a um mínimo de `1`. | | `MODEL_SYNC_INTERVAL_HOURS` | `6` | `src/shared/services/modelSyncScheduler.ts` | Intervalo de sincronização do catálogo de modelos em horas. | | `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | `src/lib/usage/providerLimits.ts` | Limite de taxa do fornecedor e intervalo de pesquisa de quotas. | | `PROVIDER_LIMITS_SYNC_SPACING_MS` | `1500` | `src/lib/usage/providerLimits.ts` | Intervalo (ms) entre pesquisas consecutivas de cota OAuth numa sincronização em massa; As ligações OAuth são procuradas uma de cada vez para evitar o overflow de um upstream. `0` desativa (simultâneo). | | `OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS` | `250` | `open-sse/services/quotaFetchThrottle.ts` | Intervalo mínimo (ms) entre pesquisas consecutivas de quota upstream no caminho preflight/monitor por pedido; espaça as chamadas de rede simultâneas para que muitas contas num IP não interrompam o upstream. Ligado aos motores de busca de cota Codex (`/wham/usage`), DeepSeek, Bailian (ambos sites de pesquisa), OpenCode e Crof (#6009, #6911). O caminho genérico de despacho `usage.ts::getUsageForProvider` (github/glm/minimax/nanogpt/xai/etc.) ainda não está coberto — rastreado separadamente. O cache não é afetado. `0` desativa; fixado `0..60000`. | | `OMNIROUTE_QUOTA_FETCH_JITTER_MS` | `120` | `open-sse/services/quotaFetchThrottle.ts` | Espaçamento aleatório adicional por pedido (ms), amostrado em cada pesquisa de quota upstream reservada. O predefinido é 120; preso `0..60000`; `0` remove apenas o jitter. Defina `OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS=0` para desativar todo o acelerador. O jitter não garante a prevenção de banimentos upstream. | | `CODEX_QUOTA_FETCH_TIMEOUT_MS` | `8000` | `open-sse/services/codexQuotaFetcher.ts` | Tempo limite (ms) para uma única pesquisa de quota Codex (`chatgpt.com/backend-api/wham/usage`). A simulação aguarda essa procura antes de enviar o pedido. Após um tempo limite ou erro de transporte, o último instantâneo dos últimos 15 minutos é reutilizado, a menos que a sua janela se esgote ou tenha sido reposta; sem nenhuma, a quota é desconhecida, pelo que uma conta de crédito pago é ignorada para este pedido e nenhum arrefecimento persiste. Aceita um número inteiro positivo até `2147483647`; qualquer outro valor volta ao padrão. | | `PROVIDER_LIMITS_POST_USAGE_REFRESH_DELAY_MS` | `5000` | `src/lib/usage/providerLimits.ts` | Atraso (ms) antes de atualizar os limites do fornecedor após um evento de utilização real, dando tempo à quota upstream API para registar o consumo. | | `OMNIROUTE_LOGIN_BROWSER_PATH` | detecção automática | `open-sse/services/adobeFireflyBrowserLogin.ts` | Caminho absoluto para um executável do sistema Chrome ou Edge utilizado para o login interativo do Adobe Firefly e renovação fora do ecrã. | | `ADOBE_FIREFLY_BROWSER_REFRESH` | habilitado | `open-sse/services/adobeFireflySession.ts` | Mantém IMS e o estado de risco do browser atualizados com sessões CDP do Chrome no âmbito da conta. Defina como `0` para desativar a renovação do browser. | | `ADOBE_FIREFLY_SESSION_DISK` | habilitado | `open-sse/services/adobeFireflySession.ts` | Persiste as sessões reparadas da Adobe sob `DATA_DIR` durante as reinicializações do processo. Defina como `0` para manter as sessões apenas em memória. | | `ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS` | `12000` | `open-sse/services/adobeFireflySession.ts` | Espaçamento mínimo em milissegundos entre envios gerados pelo Adobe Firefly; `0` desativa o espaçamento. | | `ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS` | `15000` | `open-sse/services/adobeFireflySession.ts` | Período extra silencioso em milissegundos após cada terceiro envio bem-sucedido da Adobe. | | `ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS` | `8000` | `open-sse/services/adobeFireflyClient.ts` | Retirada básica em milissegundos após respostas transitórias do Adobe 408; combinado com o espaçamento de envio num máximo de cinco ensaios. | | `OMNIROUTE_DISABLE_BACKGROUND_SERVICES` | `false` | `src/instrumentation-node.ts` | Desative todos os serviços em segundo plano: atualização de quota, sincronização de limites de fornecedor, recuperação de ligação, integridade de credenciais, sincronização cloud/model/free-proxy/proxy-health, limpeza de retenção, VACUUM agendado e pesquisa de recarga a quente das definições. Útil para CI/test; numa instalação de longa duração, as ligações não são recuperadas automaticamente e a base de dados continua a crescer. | | `OMNIROUTE_HEADLESS` | _(desativado)_ | `src/lib/system/headless.ts` | Inicialização apenas do motor proxy: ignora os subsistemas opcionais, `/dashboard` → 404. O mesmo que `omniroute serve --headless`. Ver [HEADLESS.md](../guides/HEADLESS.md). | | `OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS` | _(desativado)_ | `src/lib/config/runtimeSettings.ts` | Forçar tarefas em segundo plano sob deteção automatizada de testes. Defina `1` para substituir a heurística de teste. | | `OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS` | `600000` | `src/lib/jobs/budgetResetJob.ts` | Cadência de verificação de redefinição do orçamento (ms). Chão `10000`. | | `OMNIROUTE_CONNECTION_RECOVERY_INTERVAL_MS` | `60000` | `src/lib/quota/connectionRecovery.ts` | Cadência proativa de recuperação de arrefecimento de ligação (ms): revalida as ligações cujo `rate_limited_until` transitório decorreu, fora do caminho ativo do pedido. Piso `5000`. | | `OMNIROUTE_DISABLE_CONNECTION_RECOVERY` | `false` | `src/lib/quota/connectionRecovery.ts` | Desative o agendador proativo de recuperação de arrefecimento da ligação (a recuperação lenta no `getProviderCredentials` ainda se aplica). | | `OMNIROUTE_REASONING_CACHE_CLEANUP_INTERVAL_MS` | `1800000` | `src/lib/jobs/reasoningCacheCleanupJob.ts` | Cadência de limpeza da cache de raciocínio (ms). Chão `60000`. | | `OMNIROUTE_REASONING_MIN_BUDGET` | _desativado_ (desativado) | `open-sse/services/reasoningTokenBuffer.ts` | Piso opcional para orçamentos de produção do modelo de pensamento: o chamador `max_tokens` em `[256, floor)` é elevado ao piso (limitado pelo limite de produção do modelo). Orçamentos de clientes = não definidos nunca ampliados (#9507). | | `OMNIROUTE_REASONING_EFFORT_PROBE_PROVIDERS` | _desativado_ (desativado) | `open-sse/services/learnedReasoningEffortCaps.ts` | IDs de fornecedor separados por vírgula (ou `*`): quando um `reasoning_effort` 400/422 nomeia nenhum conjunto aceite, tente novamente uma vez um nível abaixo (nunca abaixo `low`) e aprenda esse nível apenas se a investigação for respondida (#14895). | | `OMNIROUTE_LOG_EXPORT_CRON` | `0 * * * *` | `src/lib/jobs/logExportJob.ts` | Expressão Cron (UTC) para o trabalho de exportação de registos de chamadas que drena todos os destinos de exportação de registos ativados. Prefira `*/5 * * * *` ao exportar corpos. | | `OMNIROUTE_LOG_EXPORT_RUN_TIMEOUT_MS` | `900000` | `src/lib/logExport/childRunner.ts` | Tempo limite do relógio filho por destino em milissegundos. O tempo limite regista a falha e termina o processo sem avançar o lote não confirmado. Os valores Invalid/non-positive/non-integer utilizam o padrão. | | `OMNIROUTE_LOG_EXPORT_CHILD_MAX_OLD_SPACE_MB` | `1024` | `src/lib/logExport/childRunner.ts` | Limite de espaço antigo filho V8 de exportação de nós em MB (não total RSS). O padrão deixa espaço para 500 linhas de artefactos limitados com corpos; lotes grandes ainda podem esgotar o heap filho. A falha aconselha a diminuir o tamanho do lote ou aumentar esse limite. Os valores Invalid/non-positive/non-integer utilizam o padrão. As exportações Bun recuam no processo sem este limite. | | `OMNIROUTE_CONFIG_HOT_RELOAD_MS` | `5000` | `src/lib/config/hotReload.ts` | Intervalo de pesquisa (ms) para recarregamento a quente de configuração. Menor que `1000` é rejeitado. | | `OMNIROUTE_DISABLE_REDIS_AUTH_CACHE` | _(habilitado)_ | `src/lib/db/apiKeys.ts` | Defina `1` para ignorar a cache de autenticação de chaves API suportada pelo Redis (força leituras DB ). | | `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS` | `0` | `open-sse/services/compression/engines/rtk/filterLoader.ts` | Confie nas regras de filtro do projeto RTK geridas pelo utilizador sem verificações rigorosas de assinatura. | | `OMNIROUTE_LITE_MAX_TOOL_LENGTH` | `2000` | `open-sse/services/compression/lite.ts` | Limite de caracteres para truncamento proativo do resultado da ferramenta Lite quando `lite.maxToolLength` não está definido. Intervalo 256–1000000. A configuração do painel vence este ambiente. | | `OMNI_COMPRESSION_WORKERS` | `2` | `open-sse/services/compression/compressionWorkerPool.ts` | Máximo de trabalhadores RTK/Caveman síncronos simultâneos; excesso de trabalhos espera FIFO. | | `OMNI_COMPRESSION_WORKER_TIMEOUT_MS` | `120000` | `open-sse/services/compression/compressionWorkerPool.ts` | Tempo limite por trabalho em milissegundos. Os trabalhadores expirados são encerrados e o pedido falha ao abrir inalterado. | | `OMNI_COMPRESSION_WORKER_IDLE_MS` | `60000` | `open-sse/services/compression/compressionWorkerPool.ts` | Vida útil ociosa em milissegundos antes de um trabalhador de compressão não utilizado ser encerrado. | | `OMNI_COMPRESSION_WORKER_MAX_OLD_MB` | `1024` | `open-sse/services/compression/compressionWorkerPool.ts` | Limite de heap da geração antiga V8 em MB para cada trabalhador de compressão, todos os modos (floor `128`). Uma tarefa que excede este limite falha ao abrir (descompactar) em vez de aumentar o heap do gateway. | | `COMPRESSION_PIPELINE_BREAKER_ENABLED` | `false` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Chave mestre do disjuntor T02 de tubagem empilhada por motor.** Ativar (padrão desativado)** — quando ativado, um mecanismo que lança repetidamente pedidos é ignorado (falha ao abrir) para um arrefecimento; comportamento herdado de byte idêntico ao =. | | `COMPRESSION_PIPELINE_BREAKER_THRESHOLD` | `3` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Falhas consecutivas de solicitação cruzada antes da abertura do disjuntor do motor. | | `COMPRESSION_PIPELINE_BREAKER_COOLDOWN_MS` | `30000` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Milissegundos que um motor aberto permanece ignorado antes de uma sonda entreaberta. | | `COMPRESSION_CCR_RETRIEVAL_RAMP_FACTOR` | `2` | `open-sse/services/compression/engines/ccr/index.ts` | T08/H8 CCR rampa de recuperação-feedback: cada recuperação anterior de um bloco armazenado aumenta o seu `minChars` efetivo linearmente (o conteúdo recuperado com frequência é comprimido menos; `>=3` recupera = nunca comprimido). `1` desativa a rampa (salto binário apenas no limite). | | `COMPRESSION_CCR_DURABLE_STORE` | `true` | `open-sse/services/compression/engines/ccr/index.ts` | armazenamento em bloco durável CCR (#9061). Faz o backup do armazenamento na memória com o SQLite para que um bloco sobreviva à remoção LRU, ao TTL, a um reinício ou a uma recuperação noutra instância. Defina `false` para manter os blocos apenas em memória. Os blocos acima de 512 KB e os tempos de execução na nuvem permanecem apenas na memória, independentemente. | | `COMPRESSION_PREFIX_FREEZE_ENABLED` | `false` | `open-sse/services/compression/prefixFreeze.ts` | interruptor mestre de congelamento de prefixo observado pelo uso T08/H5.** Ativar (padrão desativado)** — quando ativado, um prompt do sistema observou `>=` o limite é tratado como um prefixo estável em cache e preservado da compressão, mesmo para fornecedores que a heurística do cache estático falha (apenas congelamento _preserva_, nunca sofre mutação). | | `COMPRESSION_PREFIX_FREEZE_THRESHOLD` | `3` | `open-sse/services/compression/prefixFreeze.ts` | Observações de um prompt do sistema antes de ser tratado como um prefixo estável congelado. | | `OMNIROUTE_BOOTSTRAPPED` | `false` | `src/app/(dashboard)/dashboard/page.tsx` | Defina `true` pelo script de arranque após a configuração inicial. Controla a visibilidade do assistente de configuração. | | `OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE` | `0` | `open-sse/executors/antigravity.ts` | Escotilha de escape: permite que o corpo do pedido substitua o campo do projeto Antigravity. | | `ANTIGRAVITY_CREDITS` | `off` | `open-sse/services/antigravityCredits.ts` | Google Uma política de créditos AI : `off` nunca injecta créditos, `retry` injecta uma vez após uma quota elegível 429 e `always` injecta no primeiro pedido. | | `OMNIROUTE_ANTIGRAVITY_TIMING_TELEMETRY` | `false` | `open-sse/executors/antigravity/executeAttempt.ts` | Tempo de ativação higienizado por envio físico: conta inativa, pedidos em curso, tempo para cabeçalhos e primeiro conteúdo SSE significativo. Sem prompt, credencial ou URLs upstream nos logs. | | `ANTIGRAVITY_MAX_429_ATTEMPTS` | `2` | `open-sse/services/antigravity429Guard.ts` | 429 upstream tolerados por pedido Antigravity (`agy`/`antigravity`) em todos os hosts (1–12) antes de o 429 regressar ao chamador. Um corpo que o gastou é respondido localmente no reenvio (2 minutos, dobrando para 30 minutos ou a dica de nova tentativa upstream) e o manipulador de chat não reinicia o pedido após esse 429. | | `ANTIGRAVITY_ALLOW_SIGNATURE_BYPASS` | `0` | `open-sse/translator/request/openai-to-gemini.ts` | Permitir que o tradutor de pedidos Antigravity ignore a sua validação estrita de assinatura de pedido CLI quando o upstream recusa assinaturas reais (modo debug/antiquated-CLI ). Diferente de zero habilita o bypass. | | `AGY_TOKEN_FILE` | `~/.gemini/antigravity-cli/antigravity-oauth-token` | `src/app/api/providers/agy-auth/apply-local/route.ts` | Substitua o caminho do ficheiro de token Antigravity CLI (agy) para a importação de início de sessão local com deteção automática. | ### Ponte OAuth CLI (interior) | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------- | ------------------- | ------------------------------- | ------------------------------------------------------ | | `OMNIROUTE_SERVER` | detecção automática | `src/lib/oauth/config/index.ts` | Servidor URL para ponte de autenticação CLI↔OmniRoute. | | `OMNIROUTE_TOKEN` | _(desativado)_ | `src/lib/oauth/config/index.ts` | Token de autenticação para ponte CLI. | | `OMNIROUTE_USER_ID` | `cli` | `src/lib/oauth/config/index.ts` | Utilizador ID para sessões de ponte CLI. | | `SERVER_URL` | _(desativado)_ | `src/lib/oauth/config/index.ts` | Alias legado para `OMNIROUTE_SERVER`. | | `CLI_TOKEN` | _(desativado)_ | `src/lib/oauth/config/index.ts` | Alias legado para `OMNIROUTE_TOKEN`. | | `CLI_USER_ID` | _(desativado)_ | `src/lib/oauth/config/index.ts` | Alias legado para `OMNIROUTE_USER_ID`. | --- ## 11. Credenciais do prestador OAuth ### Atualização passiva do token Codex `OMNIROUTE_TOKEN_REFRESH_PASSIVE_PROVIDERS` definido como `codex` torna esta instância um consumidor de credenciais Codex sincronizadas, e não um proprietário de rotação de tokens de atualização. O padrão vazio ou não definido preserva o comportamento normal de atualização. Os valores separados por vírgula são cortados e não são sensíveis a maiúsculas e minúsculas; `cx` é um apelido para `codex`. Os fornecedores não suportados falham na validação de arranque. Outros fornecedores permanecem inalterados. Nos pontos de atualização existentes, a instância ignora a cache de leitura de ligação e adota apenas um token de acesso diferente e não expirado. Os tokens rejeitados no upstream durante o pedido não podem voltar a qualificar-se após a reversão da sincronização: as credenciais do pedido contêm um máximo de quatro impressões digitais SHA-256, descartadas com este pedido. Apenas os campos de token são adotados, pelo que os metadados do fornecedor local de pedidos sobrevivem. Nenhuma credencial adotada é persistida. Se não existir nenhuma substituição, `refresh_disabled` não será terminal e não contará para o disjuntor de atualização de token. As respostas reais 401/403 upstream retêm a contabilização normal de falhas, o arrefecimento exponencial e os erros do cliente; os sinais de desativação de conta ainda são bloqueados permanentemente. A atualização manual dashboard/API retorna `409` com o código `refresh_disabled` e uma instrução para atualizar na instância ativa e sincronizar. As atualizações implícitas (chat, utilização, verificações de integridade e validação de importação) não revelam este erro; utilização on-demand 401 tentativas de recuperação uma vez com um token sincronizado adotado. As importações Codex auth armazenam os tokens fornecidos sem uma troca de token de atualização; novos logins OAuth permanecem inalterados. Nenhuma sincronização pré-despacho é adicionada fora do caminho de atualização proativa existente. Mantenha exatamente um proprietário de rotação e organize a sincronização de tokens separadamente, antes que os tokens de acesso expirem (lead proativo padrão: cinco minutos). Esta opção não é um bloqueio distribuído, replicação de base de dados ou implementação SQLite partilhada. Fonte: `open-sse/services/tokenRefresh/passiveCodex.ts`. Credenciais integradas para** desenvolvimento localhost** . Para implementações remotas, registe-se na consola do desenvolvedor de cada fornecedor. | Variável | Provedor | Notas | | ------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLAUDE_OAUTH_CLIENT_ID` | Código Claude (Anthropic) | Cliente público — nenhum segredo necessário. | | `CLAUDE_CODE_REDIRECT_URI` | Código Claude | Substituir o redireccionamento URI. Padrão: `https://platform.claude.com/oauth/code/callback` | | `CODEX_OAUTH_CLIENT_ID` | Codex / OpenAI | Cliente público. | | `GEMINI_OAUTH_CLIENT_ID` | Gemini (Google) | Requer correspondência `_SECRET`. | | `GEMINI_OAUTH_CLIENT_SECRET` | Gemini (Google) | — | | `KIMI_CODING_OAUTH_CLIENT_ID` | Codificação Kimi (Moonshot) | Cliente público. | | `MUSE_CODE_OAUTH_CLIENT_ID` | Código da Musa (Meta) | Substituição opcional para o ID público do cliente de fluxo de dispositivo do Muse CLI. Deixe indefinido para utilizar o cliente público integrado. | | `ANTIGRAVITY_OAUTH_CLIENT_ID` | Antigravity (Google) | Requer correspondência `_SECRET`. | | `ANTIGRAVITY_OAUTH_CLIENT_SECRET` | Antigravity (Google) | — | | `GITHUB_OAUTH_CLIENT_ID` | GitHub Copilot | Cliente público. | | `GHE_COPILOT_OAUTH_CLIENT_ID` | GHE Copilot | Substituição opcional do ID do cliente OAuth do GitHub Enterprise Copilot. Volta ao padrão público de `GITHUB_OAUTH_CLIENT_ID` quando não está definido. | | `COPILOT_INTEGRATION_ID` | GitHub Copilot | Substituição opcional para a integração do cliente GitHub Copilot ID enviada nos cabeçalhos `Copilot-Integration-Id` e `Editor-Plugin-Version`. O predefinido é `copilot-developer-cli`. | | `WINDSURF_API_KEY` | Windsurf / Devin (v3.8) | Fallback de chave API utilizado por `open-sse/executors/devin-cli.ts` quando não está disponível nenhuma credencial por ligação. Opcional. | | `CLI_DEVIN_BIN` | Devin CLI (v3.8) | Caminho personalizado para o binário CLI Devin (`devin`). Resolvido por `open-sse/executors/devin-cli.ts`. | | `GITLAB_DUO_OAUTH_CLIENT_ID` | GitLab Duo (v3.8) | Cliente OAuth ID para GitLab Duo. Registe uma aplicação no `https://gitlab.com/-/profile/applications` com redireccionamento URI `/callback` e escopos `api, read_user, openid, profile, email`. Volta para `GITLAB_OAUTH_CLIENT_ID`. | | `GITLAB_DUO_OAUTH_CLIENT_SECRET` | GitLab Duo (v3.8) | Segredo do cliente OAuth para GitLab Duo. O fluxo — PKCE opcional não requer segredo. Volta para `GITLAB_OAUTH_CLIENT_SECRET`. | | `GITLAB_DUO_BASE_URL` | GitLab Duo (v3.8) | Substitua GitLab base URL ( GitLab auto-hospedado). O predefinido é `https://gitlab.com`. Volta para `GITLAB_BASE_URL`. | | `GITLAB_BASE_URL` | GitLab Duo (v3.8) | Fallback legado para `GITLAB_DUO_BASE_URL`. Utilizado quando a variante `_DUO_` não está definida. | | `GITLAB_OAUTH_CLIENT_ID` | GitLab Duo (v3.8) | Fallback legado para `GITLAB_DUO_OAUTH_CLIENT_ID` consumido por `src/lib/oauth/constants/oauth.ts`. | | `GITLAB_OAUTH_CLIENT_SECRET` | GitLab Duo (v3.8) | Fallback legado para `GITLAB_DUO_OAUTH_CLIENT_SECRET` consumido por `src/lib/oauth/constants/oauth.ts`. | | `QODER_OAUTH_CLIENT_SECRET` | Qoder | — | | `QODER_OAUTH_AUTHORIZE_URL` | Qoder | Defina para ativar Qoder OAuth. | | `QODER_OAUTH_TOKEN_URL` | Qoder | — | | `QODER_OAUTH_USERINFO_URL` | Qoder | — | | `QODER_OAUTH_CLIENT_ID` | Qoder | — | | `QODER_PERSONAL_ACCESS_TOKEN` | Qoder | Fallback direto da chave API (ignora OAuth). | | `QODER_CLI_WORKSPACE` | Qoder | Espaço de trabalho ID para Qoder CLI. | | `OMNIROUTE_QODER_WORKSPACE` | Qoder | Alias para `QODER_CLI_WORKSPACE`. | | `QODER_CLI_CONFIG_DIR` | Qoder | Substitua o diretório de configuração Qoder CLI (sessão PAT isolada, evita perturbar o login do browser). | | `QODER_CLI_MAX_CONCURRENCY` | Qoder | Máximo de execuções simultâneas de qodercli (impressão spawns ou prompts ACP ); fila de pedidos extra FIFO. Não está definido (padrão) = sem limite. | | `QODER_CLI_QUEUE_TIMEOUT_MS` | Qoder | Quanto tempo um pedido Qoder aguarda um slot qodercli (apenas com um limite definido) antes de falhar com 429 `qodercli_busy` + `Retry-After`. Padrão `120000`. | | `QODER_CLI_TRANSPORT` | Qoder | `print` (padrão) gera `qodercli --print` por pedido; `acp` mantém um processo `qodercli --acp` persistente por PAT. | | `QODER_CLI_ACP_IDLE_TIMEOUT_MS` | Qoder | Transporte ACP : eliminar o processo qodercli persistente após tanto tempo de inatividade. Padrão `600000`. | | `QODER_CLI_ACP_STARTUP_TIMEOUT_MS` | Qoder | transporte ACP : prazo para qodercli responder ao ACP `initialize`. `60000` padrão. | | `QODER_CLI_ACP_MAX_SESSIONS_PER_PROCESS` | Qoder | Transporte ACP : recicle o processo qodercli persistente após tantas sessões. Padrão `500`. | | `BLACKBOX_WEB_VALIDATED_TOKEN` | Web caixa preta | Token `tk` front-end para enviar como `validated` em `/api/chat`. Obrigatório quando o Blackbox impõe a correspondência de tokens; caso contrário, OmniRoute volta a um UUID aleatório. Veja o problema #2252. | | `VISION_BRIDGE_BASE_URL` | Guarda-corpo da Ponte Vision | Base URL compatível com OpenAI para chamadas de ponte de visão não antrópicas. O padrão é o OpenAI URL env legacy ou api.openai.com. Aponte para o auto-loop `/v1` do OmniRoute ou para qualquer endpoint compatível com OpenAI (Gemini OpenAI-compat, OpenRouter). Emitir #2232. Quando o URL é o próprio `/v1` de OmniRoute, a subsolicitação de descrição envia `x-omniroute-admission-bypass: internal` e autentica com a credencial de auto-loop resolvida (`sk_omniroute` sentinela no modo local ou `OMNIROUTE_API_KEY` / `ROUTER_API_KEY` — #1350) para que as implementações `REQUIRE_API_KEY=true` funcionem. | | `VISION_BRIDGE_API_KEY` | Guarda-corpo da Ponte Vision | Chave API para o URL acima. Substitui vars OpenAI / Google env por fornecedor para chamadas de ponte de visão não antropogénicas. Os modelos Anthropic mantêm o seu caminho de chave Anthropic dedicado. Emitir #2232. | | `OMNIROUTE_VISION_BRIDGE_NEGATIVE_CACHE_MS` | Guarda-corpo da Ponte Vision | Durante quanto tempo um resultado de encaminhamento "nenhum candidato utilizável" é armazenado em cache, em ms (padrão `30000`). Valores inválidos ou negativos regressam ao padrão; `0` desativa a cache negativa. Fonte: `src/lib/guardrails/visionBridgeRouter.ts`. | | `OMNIROUTE_IMAGE_NORMALIZATION` | Normalização de imagem de visão | Aceitar (desativar =, alteração de comportamento zero; `1`/`true`/`on` ativado). Normaliza cada imagem incorporada (dados base64 URI / Claude `source.data`) nos corpos do pedido de chat antes do envio: orientação EXIF aplicada, RGB (alfa achatado em branco), borda longa `<= 4096` px, total de pixéis `<= ~4M`; imagens que necessitam de alteração são recodificadas como linha de base JPEG (alpha-free PNGs permanece sem perdas PNG), RGB JPEG/PNG já compatível passa intacto. Os orçamentos são fixos. Tem como alvo pipelines de visão Qwen2-VL-style que rejeitam imagens oversized/exotic com 400 erros de análise ou falhas de saída zero. URLs http(s) remotos não são descarregados; um binário `sharp` em falta ou uma imagem não descodificável passa intacta (falha ao abrir). Redimensionar uma imagem grande adiciona latência de pedido. Fonte: `open-sse/utils/visionImageNormalization.ts`. | > [!WARNING] > > 1. Vá para [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials) 2. Crie um cliente OAuth 2.0 ID (digite: "web application") 3. Adicione o seu servidor URL como Redireccionamento autorizado URI 4. Substitua os valores das credenciais em `.env`. --- ## 12. Substituições utilizador-agente do fornecedor Substitua o cabeçalho `User-Agent` enviado para cada fornecedor upstream. Este é resolvido dinamicamente em tempo de execução pela classe base do executor: ``` process.env[`${PROVIDER_ID}_USER_AGENT`] ``` > **Fonte:** `open-sse/executors/base.ts` → `buildHeaders()` | Variável | Valor padrão | Quando atualizar | | -------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CLAUDE_USER_AGENT` | `claude-cli/2.1.280 (external, cli)` | Quando Anthropic lança uma nova versão CLI | | `CLAUDE_DISABLE_TOOL_NAME_CLOAK` | `false` | `executors/base.ts` + `executors/cliproxyapi.ts` | Defina como `1`/`true` para encaminhar nomes de ferramentas de aproveitamento de terceiros literalmente para Anthropic em ambos os caminhos com ligação antrópica ( OAuth e CLIProxyAPI nativos). Por defeito, o executor cria apelidos determinísticos para nomes de ferramentas que não são do Código Claude (mapeamento canónico do código Claude onde existe, caso contrário PascalCase) e reverte-os na resposta via `_toolNameMap`, para que os aproveitamentos com ferramentas snake_case não sejam recusados como clientes de terceiros com impressão digital. Apenas depuração. | | `CODEX_USER_AGENT` | `codex-cli/0.155.0 (Windows 10.0.26200; x64)` | Quando OpenAI atualiza o Codex CLI | | `CODEX_CLIENT_VERSION` | `0.155.0` | Substituir a versão do cliente Codex independentemente da string UA completa | | `GROK_CLI_CLIENT_VERSION` | `1.0.41` | Substitua `x-grok-client-version` para inferência, sincronização de modelos e código de dispositivo OAuth, além do Grok CLI User-Agent padrão para inferência e sincronização de modelos. Aceita SemVer com metadados prerelease/build opcionais, até 128 caracteres após o corte dos espaços em branco circundantes. Os valores não definidos, vazios, inválidos ou que contenham quebra de linha utilizam o PIN enviado. A substituição de agente de utilizador de inferência completa existente mantém a precedência. | | `CLAUDE_CODE_CLIENT_VERSION` | `2.1.280` | Substitua a versão anunciada do código Claude independentemente de `CLAUDE_USER_AGENT`. Anthropic bloqueia alguns modelos neste valor (#12417). | | `CLAUDE_CODE_CLIENT_BUILD_REVISION` | `1e2` | Substitua o sufixo de três caracteres OmniRoute acrescenta a `cc_version=` no bloco de cobrança Claude. Bata ao lado de `CLAUDE_CODE_CLIENT_VERSION` — fixando apenas a versão que anuncia um par `version.revision` sem emissões binárias reais. | | `GITHUB_COPILOT_CLI_VERSION` | `1.0.91` | Substituir a versão anunciada Copilot CLI independentemente do `GITHUB_USER_AGENT` | | `GITHUB_USER_AGENT` | `GitHubCopilotChat/0.54.0` | Quando GitHub Copilot Chat é atualizado | | `ANTIGRAVITY_CLI_CL` | _(desativado)_ | Substitua a lista de alterações do Piper Antigravity CLI `agy`) reportada como `cl=` no CLI User-Agent. Não derivável da versão nem exposta pelos manifestos públicos; propagado por versão de uma captura em directo (1.4.4 → `1003595037`). Unset numa versão desconhecida omite `cl=` em vez de anunciar a lista de alterações de outra compilação. | | `KIRO_USER_AGENT` | `AWS-SDK-JS/3.0.0 kiro-ide/1.0.0` | Quando Kiro IDE é atualizado | | `KIRO_OAUTH_CLIENT_ID` | `kiro-cli` | Substitua o código do dispositivo social Kiro `clientId` (id público) | | `KIRO_VERIFY_FULL_CRC` | `false` | Aceitação: validação CRC de mensagem completa por frame no fluxo de eventos Kiro (depuração de fluxos corrompidos) | | `KIRO_CREDIT_PRICE_USD` | `0.02` | USD por crédito Kiro ; converte os créditos `meteringEvent` no custo exato por pedido | | `KIRO_REQUIRE_CREDITS` | `false` | Falha numa resposta Kiro que não informa nenhuma medição de crédito em vez de a registar como não faturada | | `QODER_USER_AGENT` | `Qoder-Cli` | Quando Qoder CLI é atualizado | | `CURSOR_USER_AGENT` | `Cursor/3.3` | Quando Cursor atualiza | > [!TIP] > Pode adicionar substituições de User-Agent para** qualquer** fornecedor usando o padrão `{PROVIDER_ID}_USER_AGENT`. O executor constrói dinamicamente o nome da variável env. --- ## 13. Compatibilidade de impressão digital CLI Quando ativado, OmniRoute reordena os cabeçalhos HTTP e os campos do corpo JSON para corresponder à assinatura exata das ferramentas CLI oficiais. Isto reduz o risco de sinalização de conta, preservando o seu proxy IP. **Fonte:** `open-sse/config/cliFingerprints.ts`, `open-sse/executors/base.ts` ### Por fornecedor | Variável | Ativação | Efeito | | ------------------------ | -------- | ------------------------------------------------ | | `CLI_COMPAT_CODEX` | `=1` | Imita a assinatura do pedido Codex CLI | | `CLI_COMPAT_CLAUDE` | `=1` | Imita assinatura de pedido de código Claude | | `CLI_COMPAT_GITHUB` | `=1` | Imita a assinatura do pedido GitHub Copilot | | `CLI_COMPAT_ANTIGRAVITY` | `=1` | Imita assinatura de pedido Antigravity | | `CLI_COMPAT_CURSOR` | `=1` | Imita assinatura de pedido Cursor | | `CLI_COMPAT_KIMI_CODING` | `=1` | Imita a assinatura do pedido de codificação Kimi | | `CLI_COMPAT_KILOCODE` | `=1` | Imita assinatura de pedido de Kilo Code | | `CLI_COMPAT_CLINE` | `=1` | Imita assinatura de pedido Cline | ### Global | Variável | Ativação | Efeito | | ---------------- | -------- | --------------------------------------------------------------------------------------- | | `CLI_COMPAT_ALL` | `=1` | Ativar a compatibilidade de impressão digital para** tudo** fornecedores de uma só vez. | ### Kimi Codificação substituições de identidade CLI | Variável | Predefinição | Arquivo de origem | Descrição | | ----------------------- | -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------ | | `KIMI_CLI_VERSION` | `1.36.0` | `src/lib/oauth/providers/kimi-coding.ts` | Substitua a versão Kimi CLI enviada durante as chamadas OAuth/API. | | `KIMI_CODING_DEVICE_ID` | _(padrão capturado)_ | `src/lib/oauth/providers/kimi-coding.ts` | Substitua o dispositivo Kimi capturado ID utilizado nos cabeçalhos do cliente. | > [!NOTE] > Esta funcionalidade funciona em conjunto com as substituições do User-Agent (§12). O sistema de impressão digital trata da ordenação do cabeçalho e dos campos do corpo, enquanto as substituições do User-Agent tratam da string UA específica. Ambos podem ser ativados de forma independente. --- ## 14. Fornecedores-chave API Chaves API para fornecedores que utilizam autenticação direta.** Configuração preferencial:** Fornecedores → do painel → Adicionar chave API. A configuração através de variáveis de ambiente é uma alternativa para as implementações Docker ou headless. Padrão reconhecido: `{PROVIDER_ID}_API_KEY` | Variável | Provedor | | ------------------ | ------------------------------------------------------ | | `DEEPSEEK_API_KEY` | DeepSeek | | `NVIDIA_API_KEY` | NVIDIA NIM | | `JINA_AI_API_KEY` | Jina AI (substituição do leitor da Fundação API + ) | | `JINA_API_KEY` | Jina AI (alcunha de `JINA_AI_API_KEY`) | | `GEMINI_API_KEY` | Gemini (Google AI Studio) embeddings + chat substituto | | `GOOGLE_API_KEY` | Gemini (alias para `GEMINI_API_KEY`) | > [!NOTE] > As entradas `${PROVIDER}_API_KEY` estáticas para Groq, xAI, Mistral, Perplexity, Together AI, Fireworks, Cerebras, Cohere, Nebius e Qianfan foram removidas na v3.8.0 porque o tempo de execução já não as lê — estes fornecedores dependem exclusivamente do Dashboard/ `data/provider-credentials.json` /o DB encriptado. Consulte a secção _Auditoria: variáveis removidas/mortas_ na parte inferior deste documento para obter o caminho de migração. > [!TIP] > As chaves definidas através do Dashboard são armazenadas encriptadas em SQLite e têm precedência sobre as variáveis de ambiente. > > **Jina:** embeddings `jina-ai/…`, reclassificar, classificar, segmentar e `jina-search` fazer** não** faturar uma chave env de cluster quando existe uma ligação `jina-ai` do painel (ou `jina-reader` partilhada) — `getProviderCredentials` é preenchido em primeiro lugar. `JINA_AI_API_KEY` / `JINA_API_KEY` são utilizados apenas quando não existe nenhuma chave de painel utilizável. Os registos de chamadas atribuem o substituto env como `connection_id=env:JINA_AI_API_KEY`. O cartão Leitor (`jina-reader`, `r.jina.ai`) nunca atende `/v1/embeddings` ou `/v1/rerank`. > > **Gemini:** `gemini/gemini-embedding-2` (também conhecido como `google/gemini-embedding-2`) utiliza primeiro a ligação `gemini` do painel. `GEMINI_API_KEY` / `GOOGLE_API_KEY` são utilizados apenas quando não existe nenhuma chave de painel utilizável. Os registos de chamadas atribuem o substituto do env como `connection_id=env:GEMINI_API_KEY`. O tráfego multimodal nativo utiliza `x-goog-api-key` contra `:embedContent` / `:batchEmbedContents` — N OpenAI `input` os itens tornam-se N vetores. --- ## 15. Configurações de tempo limite Todos os valores estão em** milissegundos** . Resolução centralizada em `src/shared/utils/runtimeTimeouts.ts`. ### Hierarquia de tempo limite ``` REQUEST_TIMEOUT_MS (global override) ├─→ FETCH_TIMEOUT_MS (upstream provider calls, default: 600000) │ ├─→ FETCH_HEADERS_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS) │ ├─→ FETCH_BODY_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS) │ ├─→ TLS_CLIENT_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS) │ │ └── TLS_FIRST_BYTE_WATCHDOG_MS (independent, default: 10000) │ ├── RESPONSES_FIRST_BYTE_TIMEOUT_MS (independent, default: 15000) │ ├── OPENCODE_RESPONSES_HEADERS_WAIT_MS (independent, default: 0 = off, suggested: 30000) │ ├── OPENCODE_RESPONSES_HEADERS_WAIT_MAX_ROTATIONS (independent, default: 2) │ ├── FETCH_CONNECT_TIMEOUT_MS (independent, default: 30000) │ └── FETCH_KEEPALIVE_TIMEOUT_MS (independent, default: 4000) ├─→ STREAM_IDLE_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 600000) ├─→ STREAM_ACTIVE_TIMEOUT_MS (independent; unset: 1260000, raised by declared budgets; set: hard cap; 0 disables) ├─→ STREAM_READINESS_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 80000) ├─→ STREAM_READINESS_MAX_TIMEOUT_MS (caps adaptive readiness extensions, default: 180000) └─→ API_BRIDGE_PROXY_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 30000) ├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS (derived, default: 300000) ├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS (default: 60000) ├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS (default: 5000) └── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (default: 0 = disabled) ``` | Variável | Predefinição | Descrição | | ------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REQUEST_TIMEOUT_MS` | _(desativado)_ | O atalho global — substitui os padrões `FETCH_TIMEOUT_MS` e `STREAM_IDLE_TIMEOUT_MS`. | | `FETCH_TIMEOUT_MS` | `600000` | Tempo limite total de pedido HTTP para chamadas de fornecedor upstream. | | `STREAM_IDLE_TIMEOUT_MS` | `600000` | Silêncio máximo entre bytes upstream em bruto antes de abortar. Os modelos de pensamento alargado raramente pausam > anos 90. | | `STREAM_ACTIVE_TIMEOUT_MS` | `1260000` | Vida útil total máxima do caudal SSE ativo; nunca é reposto em bytes upstream e é independente de `REQUEST_TIMEOUT_MS`. Quando não está definido, o padrão é o maior `timeoutMs` por modelo no registo (1200000, Codex) mais uma margem de 60.000, e uma meta que declara um orçamento mais longo (ligação `timeoutMs`, depois por modelo, depois ao nível do fornecedor, por exemplo, 3000000 de GLM) obtém esse orçamento mais 60.000. Um valor positivo é um limite máximo para cada meta que os orçamentos declarados não podem aumentar. Defina como `0` para desativar para cada alvo. | | `OMNIROUTE_SSE_COMMENTS` | _(desativado)_ | Se OmniRoute pode emitir linhas de comentários SSE `:` (por exemplo, os trailers `: keepalive` heartbeat e `x-omniroute-*` metadata). Desativado por defeito (#10524), pois os clientes estritamente compatíveis com OpenAI JSON. parse cada linha SSE e bloqueia nos comentários `:` ; os batimentos cardíacos `data:` não são afetados. Defina `on`/`true`/`1`/`yes` para voltar a ativar. Utilizado por `open-sse/utils/sseHeartbeat.ts`. | | `SSE_COALESCE_MS` | `0` (desligado) | Aceitação: mescla eventos Claude `content_block_delta` consecutivos (mesmo índice de bloco e tipo delta) enviados para os clientes Claude, libertando pelo menos a cada N ms. Sem perdas; Os eventos `signature_delta` e border nunca são fundidos. Aplica-se a todos os tipos delta, a menos que seja definida uma variável por tipo abaixo. Utilizado por `open-sse/utils/sseDeltaCoalesce.ts`. | | `SSE_COALESCE_THINKING_MS` | `0` (desligado) | Substituição por tipo de `SSE_COALESCE_MS` para `thinking_delta`. | | `SSE_COALESCE_TEXT_MS` | `0` (desligado) | Substituição por tipo de `SSE_COALESCE_MS` para `text_delta`. | | `SSE_COALESCE_INPUT_JSON_MS` | `0` (desligado) | Substituição por tipo de `SSE_COALESCE_MS` para `input_json_delta`. | | `SSE_FRAME_COALESCE_MS` | `0` (desligado) | Opt-in: tramas SSE em lote encaminhadas em N ms numa escrita para o cliente. O primeiro quadro e os quadros terminais (`[DONE]`, `message_stop`, `error`, `response.completed`/`failed`/`incomplete`) nunca são atrasados; com lote ativado, ITL mede os intervalos entre lotes. Usado por `open-sse/utils/sseOutputSink.ts`. | | `SSE_STALL_WATCHDOG` | `timer` | Implementação de byte-stall watchdog para respostas transmitidas. `timer` rearma um temporizador por bloco upstream (dispara exatamente no stall bud); `interval` mantém uma verificação por fluxo com período `clamp(budget/4, 1s, 5s)`, pelo que é despoletada uma paragem dentro do período + do orçamento. Utilizado por `open-sse/utils/streamStallWatchdog.ts`. | | `STREAM_READINESS_TIMEOUT_MS` | `80000` | Está na hora de receber o primeiro evento SSE sem ping. Herda `REQUEST_TIMEOUT_MS` quando definido. | | `STREAM_READINESS_MAX_TIMEOUT_MS` | `180000` | Janela máxima adaptável de prontidão do primeiro evento para pedidos de streaming grandes, com muitas ferramentas ou com alto raciocínio. | | `OMNIROUTE_AGENT_GOAL_POLICY_ENABLED` | `true` | Kill-switch para a heurística `/goal`. Defina `false`/`0`/`off` para desativar totalmente a deteção. Os tempos limite de prontidão — e a recuperação de fluxo nunca são elevados pelo pedido body/headers, mitigando a amplificação de tempo limite controlada pelo cliente. | | `OMNIROUTE_AGENT_GOAL_READINESS_MAX_TIMEOUT_MS` | `600000` | Janela máxima de preparação para o primeiro evento para execuções ou pedidos forçados do agente `/goal` detetados com `x-omniroute-agent-goal`. | | `OMNIROUTE_AGENT_GOAL_STREAM_RECOVERY` | `true` | Ative a recuperação antecipada de fluxo automaticamente para execuções detetadas do agente `/goal`. Defina `false`/`0`/`off` para desativar a aceitação específica da meta. Este só pode recuperar ADD para além do — padrão do operador, nunca substitui uma desativação explícita das definições `STREAM_RECOVERY_ENABLED`/DB. | | `OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS` | `true` | Remova os eventos `codex.*` SSE não padrão (por exemplo, `codex.rate_limits`) que quebram o `responses.stream()` do OpenAI SDK com um 502. ON padrão (#11014). Defina `0`/`false`/`no`/`off` para os encaminhar. | | `OMNIROUTE_CODEX_APPSERVER_WS` | _(desativado)_ | Transporte de servidor de aplicações Codex opcional. Endpoint WebSocket (`ws://`/`wss://`) de um sidecar `codex app-server` local. Quando definidos juntamente com um token, os pedidos Codex são encaminhados por JSON-RPC para o ficheiro secundário em vez das respostas HTTP API. Também configurável por ligação via `providerSpecificData.codexAppServerUrl`. Utilizado por `open-sse/executors/codex/appServerConfig.ts`. | | `OMNIROUTE_CODEX_APPSERVER_WS_TOKEN` | _(desativado)_ | Token capability/bearer incorporado apresentado ao servidor de aplicações. Substituição por ligação: `providerSpecificData.codexAppServerToken`. | | `OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE` | _(desativado)_ | Caminho para um ficheiro que contém o token de capacidade do servidor de aplicações (de `codex app-server --ws-token-file`). Utilizado quando `OMNIROUTE_CODEX_APPSERVER_WS_TOKEN` não está definido. Substituição por ligação: `providerSpecificData.codexAppServerTokenFile`. | | `OMNIROUTE_CODEX_APPSERVER_CWD` | `/tmp` | Diretório de trabalho no qual o servidor de aplicações é executado. Substituição por ligação: `providerSpecificData.codexAppServerCwd`. | | `OMNIROUTE_CODEX_APPSERVER_APPROVAL` | _(desativado)_ | Política de aprovação passada para o turno do servidor de aplicações (por exemplo, `never`, `on-request`). Substituição por ligação: `providerSpecificData.codexAppServerApprovalPolicy`. | | `OMNIROUTE_CODEX_APPSERVER_SANDBOX` | _(desativado)_ | Política de sandbox passada para o turno do servidor de aplicações (por exemplo, `read-only`, `workspace-write`, `danger-full-access`). Quando não está definido, o executor assume por defeito `workspace-write` (endurecido; anteriormente `danger-full-access`). Substituição por ligação: `providerSpecificData.codexAppServerSandbox`. | | `OMNIROUTE_CODEX_APPSERVER_AUTO_APPROVE` | `false` | Aprovar automaticamente os próprios avisos de aprovação do servidor de aplicações (execução command/file/permission no host). Desativado por defeito, os prompts — são automaticamente negados; as chamadas da ferramenta de chicote não são afetadas (percorrem a passagem `item/tool/call` separada). Aceita `true`/`1`/`yes`. Substituição por ligação: `providerSpecificData.codexAppServerAutoApprove`. | | `FETCH_HEADERS_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Hora de receber os cabeçalhos de resposta. | | `OMNIROUTE_FETCH_START_TIMEOUT_CAP_MS` | `110000` | Espera máxima por cabeçalhos de resposta em pedidos de streaming (ms). `0` desativa esse limite; um fornecedor explícito `fetchStartTimeoutCapMs` tem precedência. | | `OMNIROUTE_CODEX_IMAGE_RESPONSE_START_TIMEOUT_MS` | `600000` (10 min) | Prazo de início da primeira resposta (ms) para Codex image-generation/edit POSTs pago, tanto direto como através de um proxy HTTP(S)/SOCKS. Estes pedidos nunca são reproduzidos após um tempo limite ambíguo ou falha de rede. Os relés de bordo (`vercel`/`deno`/`cloudflare`) também fazem uma tentativa, mas mantêm o seu próprio prazo `OMNIROUTE_RELAY_FETCH_TIMEOUT_MS`. | | `OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS` | `30000` (30 anos) | Espera máxima de início de resposta (ms) para cada tentativa direta sem proxy. Um tempo limite é repetido uma vez num socket novo; configure `0` para desativar o limite e manter o comportamento anterior. | | `OMNIROUTE_LOCAL_DIRECT_HEADERS_TIMEOUT_MS` | `300000` (5 min) | Piso de início de resposta (ms) para tentativas diretas sem proxy cujo host de destino é private/LAN/loopback (por exemplo `localhost`, `host.docker.internal`, `192.168.x.x`), pelo que um arranque a frio Ollama nativo não é interrompido pelo padrão 30s acima. Atua como piso: a espera efetiva é maior entre este valor e `OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS`; `0` ou um valor inválido remove o piso local. Os hosts remotos não são afetados. | | `OMNIROUTE_DIRECT_HEADERS_VOLUME_ADAPTIVE` | `1` | Aumentar a janela de início de resposta direta por nível de carga útil de pedido: os corpos acima de 512 KB recebem × 2, acima de 2 MB × 3, limitado a 180 s e nunca baixando um piso já superior (a substituição do operador ou o piso local/LAN acima). Os contextos grandes são pré-preenchidos proporcionalmente ao tamanho da entrada, sem seletor de raciocínio para o limite de raciocínio ser ativado, de modo a que a janela plana corte os fluxos de pré-preenchimento lento e saudável exatamente no chão. Defina `0`/`false`/`off` para fixar o comportamento plano. | | `OMNIROUTE_DIRECT_RESPONSE_RETRY_TIMEOUT_MS` | `600000` (10 min) | Teto (ms) para a tentativa RETRY novo socket após um tempo limite de início de resposta de tentativa em pool acima (#13703). Aplica-se apenas quando o chamador já tiver anexado o seu próprio sinal de prazo (a ligação/modelo/fornecedor/cascata `FETCH_TIMEOUT_MS` resolvida); este sinal é o limite real e dispara primeiro no caminho pretendido, portanto, este é um backstop generoso em vez de um — de tampa plana sem ele, a nova tentativa reutilizou a janela `OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS` curta idêntica à tentativa agrupada e 504 modelos de raciocínio TTFB lentos e saudáveis. Nunca permitido abaixo do piso plano acima; quando o chamador não fornece qualquer sinal de prazo, a nova tentativa mantém o piso plano inalterado. | | `FETCH_BODY_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Está na hora de receber o corpo da resposta completo. | | `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Tempo limite de estabelecimento da ligação TCP. | | `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Tempo limite de inatividade do socket keep-alive. | | `TLS_CLIENT_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Tempo limite do proxy de impressão digital TLS (wreq-js). | | `TLS_FIRST_BYTE_WATCHDOG_MS` | `10000` | Limita o tempo até ao primeiro byte especificamente no corpo do transporte de impressões digitais TLS wreq-js; `TLS_CLIENT_TIMEOUT_MS` por si só não consegue capturar um corpo paralisado, pois é resolvido assim que os cabeçalhos chegam (#12656). Um tempo limite cancela o leitor wreq e retorna ao despachante direct/proxy ; `0` desativa o watchdog. | | `RESPONSES_FIRST_BYTE_TIMEOUT_MS` | `15000` | Apenas executor OpenCode e apenas enquanto o sinalizador de recurso `OPENCODE_RESPONSES_STALL_ROTATION` estiver ativado (padrão desativado): limita a espera pelo primeiro byte do corpo de uma resposta de Respostas transmitida após os seus cabeçalhos (#13484). Um fluxo de respostas é aberto com `response.created`, pelo que o silêncio após esta janela é uma paragem: a conta é arrefecida e o pedido passa para a conta seguinte uma vez; uma segunda paragem falha rapidamente. `0` desativa a proteção mesmo com o sinalizador ativado. | | `OPENCODE_RESPONSES_HEADERS_WAIT_MS` | `0` (= desligado) | Apenas executor OpenCode : limita a espera por cabeçalhos de resposta a montante numa chamada de Respostas transmitida quando outra conta ainda está disponível — um pedido na fila deixa de esperar e segue em frente em vez de manter a janela de cabeçalhos completa. Apenas as chamadas de Respostas transmitidas são afetadas (o fluxo de Respostas abre com `response.created`, pelo que existe uma fila de silêncio, e não uma geração); as conclusões do chat e as chamadas não transmitidas permanecem intactas, e a janela apenas reduz o limite efetivo de início de pesquisa, nunca o estende. Valor sugerido ao ativar: `30000`. `0` desativa. | | `OPENCODE_RESPONSES_HEADERS_WAIT_MAX_ROTATIONS` | `2` | Apenas executor OpenCode : quantas vezes por pedido o limite de espera de cabeçalho acima pode ser movido para a conta seguinte. A última conta restante mantém sempre a janela completa dos cabeçalhos. | | `OPENCODE_PARK_AND_RESUME` | `false` | Apenas executor OpenCode : estacione o pedido com uma pulsação após repetidos 429s transitórios (ou um novo marcador de tensão de pool) e, em seguida, reproduza uma perna limitada de até 3 contas sequenciais em vez de espalhar toda a frota (#13924). Desativado por defeito: cada 429 rotações para a conta seguinte exatamente como antes. | | `OPENCODE_PARK_REPLAY_SERVE_SETASIDE` | `false` | Apenas executor OpenCode : quando todas as contas prontas para arrefecimento na perna de repetição estacionar e retomar forem reservadas pela memória de recusa de proxy, sirva-as de qualquer maneira, em vez de reproduzir nada (#14851, acompanhamento de #14750). Desativado por predefinição: o trecho de reprodução está vazio neste caso, como anteriormente #14750. | | `STREAM_READINESS_STALL_RETRY` | `false` | Apenas chat de streaming: quando o primeiro corpo upstream pára antes de produzir um evento utilizável, emita uma segunda tentativa limitada através do mesmo caminho de encaminhamento com o mesmo orçamento de prontidão e sem penalização de conta. Desativado por predefinição: um primeiro corpo parado falha o pedido sem tentar novamente. | | `OPENCODE_POOL_RESELECT` | `false` | Apenas executor OpenCode : após um 429 de um fornecedor com bucket de saída numa conta sem proxy num contexto de pool de ambiente, solicite ao pool de ligações outro membro para a próxima tentativa, em vez de tentar novamente o mesmo endereço de saída. Ordena, nunca elimina: um pool esgotado mantém o comportamento atual. Desativado por defeito: cada 429 rotações para a conta seguinte exatamente como antes. | | `OPENCODE_POOL_STRAIN_MARKER_PATH` | _(desativado)_ | Apenas executor OpenCode : substitui o caminho do marcador de tensão do pool lido antes de estacionar (`{since, reason, ttl_s}`, padrão `/tmp/opencode-pool-strain.json`, #13924). Um novo marcador estaciona sem recontar; em falta ou obsoleto volta para o contador de burst. | | `API_BRIDGE_PROXY_TIMEOUT_MS` | `30000` | Tempo limite de salto do proxy para pedidos de ponte `/v1`. | | `FIRECRAWL_BASE_URL` | `https://api.firecrawl.dev` | Aponte o executor de pesquisa web do Firecrawl para uma instância auto-hospedada ( chave API opcional fora da nuvem). | | `FIRECRAWL_TIMEOUT_MS` | `30000` | Tempo limite por pedido para o executor de pesquisa na Web do Firecrawl. | | `TAVILY_BASE_URL` | _(desativado)_ | Base URL para o motor de busca de quotas Tavily `/usage` (Limites do Prestador); ignorado quando aponta para `api.tavily.com`. Unset retorna à base da ligação URL. | | `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `300000` | Tempo limite geral de pedido do servidor para a ponte. | | `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Está na hora de enviar cabeçalhos de resposta pela ponte. | | `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Tempo limite de inatividade do keep-alive da ponte. | | `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Tempo limite do socket em bruto (0 = desativado). | | `SHUTDOWN_TIMEOUT_MS` | `30000` | Período de carência em SIGTERM/SIGINT antes da saída forçada. | | `OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS` | `120000` | Fallback utilizado por `src/shared/utils/fetchTimeout.ts` quando `FETCH_TIMEOUT_MS` não está definido. | | `OMNIROUTE_PROVIDER_PROBE_TIMEOUT_MS` | `8000` | Tempo limite (ms) para as predefinições `validationRead` e `modelsProbe` em `src/shared/network/safeOutboundFetch.ts`. Aumente para endpoints lentos (Cerebras, Cloudflare AI, Groq) para evitar oscilações entre active/error no painel. Volta aos 8.000 ms para valores inválidos (< 1.000) ou não numéricos. | | `OMNIROUTE_RELAY_FETCH_TIMEOUT_MS` | `25000` | Tempo limite de procura específico do relé em `open-sse/utils/proxyFetch.ts` (#9158). Um relé interrompido deve falhar antes do tempo limite client/agent (~ 30s) para que os chamadores vejam uma falha específica do relé em vez de um tempo limite upstream genérico. Limitado em `29000` para que dispare sempre primeiro. | | `OMNIROUTE_RETRY_BACKOFF_MS` | `10` | Espera de repetição partilhada para os caminhos de repetição única direct/relay/proxy em `open-sse/utils/proxyFetch.ts` (#9158). `0` = tente novamente imediatamente. | | `OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS` | `60000` | Tempo limite de pedido wreq-js nativo (`claudeTlsClient.ts`). | | `OMNIROUTE_CLAUDE_TLS_GRACE_MS` | `10000` | Graça absoluta de prazo máximo JS adicionada ao tempo limite nativo. | | `OMNIROUTE_PPLX_TLS_TIMEOUT_MS` | `30000` | Tempo limite de pedido wreq-js nativo (`perplexityTlsClient.ts`). | | `OMNIROUTE_PPLX_TLS_GRACE_MS` | `10000` | Graça absoluta de prazo máximo JS adicionada ao tempo limite nativo. | | `OMNIROUTE_PPLX_SEARCH_HINT` | `0` (desligado) | Acrescenta "Tem pesquisa na web integrada. Responda às perguntas diretamente utilizando os resultados da pesquisa." à mensagem do sistema do chamador (`perplexity-web/protocol.ts`). Desativado por defeito, — Perplexity pesquisa de qualquer forma, e a frase vaza nas respostas como meta-comentário para clientes de codificação. Defina `1`/`true`/`yes`/`on` para restaurar. | | `OMNIROUTE_GROK_TLS_TIMEOUT_MS` | `60000` | Tempo limite de pedido wreq-js nativo (`grokTlsClient.ts`). | | `OMNIROUTE_GROK_TLS_GRACE_MS` | `10000` | Graça absoluta de prazo máximo JS adicionada ao tempo limite nativo. | | `OMNIROUTE_NOTION_TLS_TIMEOUT_MS` | `30000` | Tempo limite de pedido wreq-js nativo (`notionTlsClient.ts`); `notion-web` aumenta por pedido para `180000` durante longas gerações. | | `OMNIROUTE_NOTION_TLS_GRACE_MS` | `10000` | Graça absoluta de prazo máximo JS adicionada ao tempo limite nativo. | | `OMNIROUTE_BROWSER_POOL` | `on` | Pool de navegadores Playwright partilhado para chat com cookies da web suportados pelo navegador (`browserPool.ts`); defina `off` para desativar. | | `OBSCURA_BIN` | `auto-detect` | Caminho para o binário `obscura` utilizado como motor principal pelo pool de browsers e pelo executor Cloudflare Playground (`open-sse/services/obscura.ts`); detectado automaticamente no sistema PATH quando não está definido. | | `OBSCURA_CDP_ENDPOINT` | _(desativado)_ | Aponte para um Obscura (`http://host:port`) já em execução em vez de gerar um; o módulo não possui este processo (`open-sse/services/obscura.ts`). | | `OBSCURA_PORT` | `random free port` | Porta explícita para o `obscura serve` gerado; uma porta livre é escolhida automaticamente quando não está definida (`open-sse/services/obscura.ts`). | | `WEB_COOKIE_USE_BROWSER` | `0` | Opte por um pedido de chat de cookies da Web no caminho do navegador (`browserBackedChat.ts`); `1` para ativar. | | `KIMI_WEB_BASE_URL` | `https://www.kimi.ai` | Base URL para o executor Kimi Web (internacional kimi.ai Connect-RPC) (`kimi-web.ts`); substituir apenas para os terminais mirror/proxy. | | `KIMI_WEB_CHAT_URL` | `/apiv2/kimi.gateway.chat.v1.ChatService/Chat` | Endpoint de chat completo para o executor Web Kimi (`kimi-web.ts`). | | `OMNIROUTE_LOGIN_BROWSER_PATH` | _(detetado automaticamente)_ | Caminho para um executável Chrome/Edge do sistema para o login do browser interativo Adobe Firefly (`adobeFireflyBrowserLogin.ts`); substitui a deteção automática por sistema operativo. | | `OMNIROUTE_STANDALONE_DIR` | _. construir/saída autónoma_ | Substituição em tempo de construção para o diretório de saída independente consumido pela etapa de colocation pós-construção (`scripts/build/colocate-standalone.mjs`); ferramentas de construção, e não de tempo de execução. | As tentativas de destino combinado herdam o tempo limite de pedido upstream resolvido (`FETCH_TIMEOUT_MS` ou `REQUEST_TIMEOUT_MS` quando fornece o padrão de pesquisa). Defina `targetTimeoutMs` num combo, padrões de combo ou substituição de fornecedor apenas para tornar o fallback do combo mais rápido; valores acima do tempo limite de upstream atual estão limitados ao tempo limite de upstream. `comboTimeoutMs` é um orçamento combinado completo separado para alvos de failover. Deixe-o não definido ou `0` para manter a iteração ilimitada (uma paragem codificada de 10 minutos em `comboPredicates.ts` ainda se aplica). Um valor positivo substitui a rede de segurança do combinado. Mantenha `comboTimeoutMs` durante mais tempo do que `targetTimeoutMs` para que o failover ainda tenha tempo após um primeiro destino lento. ### Limites do disjuntor Ajuste do disjuntor ao nível do fornecedor. Os padrões refletem os valores escalonados utilizados desde a v3.6 para ligações de 500 +. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------------------------- | ------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD` | `8` | `open-sse/config/constants.ts` | Limite de falha consecutiva para os fornecedores OAuth antes do disparo do disjuntor. | | `OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS` | `60000` | `open-sse/config/constants.ts` | Janela de reposição (ms) para o disjuntor do fornecedor OAuth. | | `OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD` | `12` | `open-sse/config/constants.ts` | Limite de falha consecutiva para fornecedores de chaves API. | | `OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS` | `30000` | `open-sse/config/constants.ts` | Janela de reposição (ms) para o disjuntor do fornecedor de chaves API. | | `OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD` | `2` | `open-sse/config/constants.ts` | Limite de falha consecutiva para fornecedores locais (Ollama, LM Studio, ...). | | `OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS` | `15000` | `open-sse/config/constants.ts` | Janela de rearme (ms) para disjuntor do fornecedor local. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_THRESHOLD` | `10` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: falhas na janela antes de todo o fornecedor OAuth entrar em arrefecimento. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_WINDOW_MS` | `900000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: janela contínua de contagem de falhas (ms) para fornecedores OAuth. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_COOLDOWN_MS` | `300000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: arrefecimento (ms) quando o limite do fornecedor OAuth é atingido. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_DEGRADATION_THRESHOLD` | `5` | `open-sse/config/constants.ts` | O fornecedor OAuth entra DEGRADED com tantas falhas. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_MAX_BACKOFF_MULTIPLIER` | `8` | `open-sse/config/constants.ts` | multiplicador de escalonamento máximo resetTimeout do fornecedor OAuth. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_BACKOFF_ESCALATION_COUNT` | `2` | `open-sse/config/constants.ts` | O fornecedor OAuth aumenta após tantos ciclos abertos. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_THRESHOLD` | `15` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: falhas na janela antes de todo o fornecedor de chaves API entrar em arrefecimento. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_WINDOW_MS` | `1800000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: janela contínua de contagem de falhas (ms) para fornecedores de chaves API. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_COOLDOWN_MS` | `600000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: arrefecimento (ms) quando o limite do fornecedor da chave API é atingido. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_DEGRADATION_THRESHOLD` | `7` | `open-sse/config/constants.ts` | O fornecedor de chaves API entra no DEGRADED com tantas falhas. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_MAX_BACKOFF_MULTIPLIER` | `4` | `open-sse/config/constants.ts` | Multiplicador de escalação max resetTimeout do fornecedor de chaves API. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_BACKOFF_ESCALATION_COUNT` | `3` | `open-sse/config/constants.ts` | O fornecedor de chaves API aumenta após tantos ciclos abertos. | | `OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_THRESHOLD` | `2` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: falhas antes de todo o fornecedor local entrar em arrefecimento. | | `OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_WINDOW_MS` | `300000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: janela contínua de contagem de falhas (ms) para fornecedores locais. | | `OMNIROUTE_PROVIDER_BREAKER_LOCAL_COOLDOWN_MS` | `60000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: arrefecimento (ms) quando o limite do fornecedor local é atingido. | | `OMNIROUTE_API_KEY_COOLDOWN_MS` | `60000` | `open-sse/services/apiKeyRotator.ts` | Arrefecimento por chave (ms) aplicado pela rotação de chave API multichave quando um upstream 429 não carrega `Retry-After` (#14573). Os valores não positivos ou não numéricos voltam ao padrão. | | `OMNIROUTE_AVALANCHE_PROTECTION_ENABLED` | `false` | `open-sse/services/accountFallback/antiAvalanche.ts` | Proteção anti-avalanche opcional: apenas um `true` explícito a ativa. Quando ativado, um 429 que nomeia um limite de tokens por minuto (e um overflow de contexto 400) interrompe o failover em cascata nas restantes chaves do fornecedor. Um 429 com quota esgotada continua a fazer failover, por maior que seja o prompt, e HTTP 413 não é afetado (mantém o comportamento de nova tentativa #13350 noutra conta). | | `OMNIROUTE_AVALANCHE_BURST_COOLDOWN_MS` | `60000` | `open-sse/services/accountFallback/antiAvalanche.ts` | Recarga de bloqueio de modelo (ms) aplicada quando o guarda dispara, em vez do bloqueio crescente. Uma reposição upstream mais longa ganha sempre. Os valores não positivos ou não numéricos voltam ao padrão. | | `PIN_DROP_BACKOFF_LEVEL` | `2` | `open-sse/services/combo.ts` | Profundidade de backoff na qual o fornecedor de um pino de cache de contexto é considerado permanentemente insalubre e o pino é descartado para failover. | | `PIN_DROP_GRACE_MS` | `20000` | `open-sse/services/combo.ts` | Janela anti-flap (ms) que tolera breves arrefecimentos transitórios antes de descartar um pino de cache de contexto. | ### Cenários | Cenário | Configuração | | -------------------------------------- | ----------------------------------------------------- | | **Geração de código de longa duração** | `REQUEST_TIMEOUT_MS=900000` (15 min) | | **Duração total do stream ligado** | `STREAM_ACTIVE_TIMEOUT_MS=1260000` (21 min) | | **Falha rápida para produção API** | `API_BRIDGE_PROXY_TIMEOUT_MS=10000` | | **Modelos de pensamento alargado** | `STREAM_IDLE_TIMEOUT_MS=300000` (5 min entre pedaços) | --- ## 16.º Registo O sistema de registo escreve em ficheiros de registo stdout e girados. Toda a configuração é lida por `src/lib/logEnv.ts`. | Variável | Predefinição | Descrição | | ----------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `APP_LOG_LEVEL` | `info` | Nível mínimo de registo: `debug`, `info`, `warn`, `error`. | | `APP_LOG_FORMAT` | `text` | Formato de saída: `text` (legível por humanos) ou `json` (estruturado). | | `APP_LOG_TO_FILE` | `true` | Grave os logs em ficheiro juntamente com o stdout. | | `APP_LOG_FILE_PATH` | `logs/application/app.log` | Caminho do ficheiro de registo (relativo à raiz do projeto ou `DATA_DIR`). | | `APP_LOG_MAX_FILE_SIZE` | `50M` | Tamanho máximo do ficheiro antes da rotação. Aceita: `50M`, `1G`, `512K` ou bytes simples. | | `APP_LOG_RETENTION_DAYS` | `7` | Dias para manter os ficheiros de registo da aplicação alternados. | | `APP_LOG_MAX_FILES` | `20` | Máximo de backups de ficheiros de registo rodados. | | `CALL_LOG_RETENTION_DAYS` | `7` | Dias para manter as entradas de registo request/call na base de dados. | | `CALL_LOG_MAX_ENTRIES` | `10000` | Máximo de entradas de registo de chamadas no buffer de memória. | | `CALL_LOGS_TABLE_MAX_ROWS` | `100000` | Máximo de linhas na tabela `call_logs` SQLite antes da remoção. | | `ENABLE_REQUEST_LOGS` | _(desativado)_ | Forçar a ativação ou desativação do logon de pedido detalhado, substituindo a configuração do painel. | | `MAX_PENDING_REQUEST_AGE_MS` | `3600000` (1 hora) | Idade máxima para entradas de registo de pedidos ativos órfãos antes da limpeza na memória. | | `MAX_PENDING_DETAILS` | `5000` | Máximo de detalhes pendentes (número inteiro positivo); limite de contagem: varrimento; tampas byte/map : inserir. | | `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS` | `false` | Armazene pedaços de fluxo em artefactos de pipeline quando `call_log_pipeline_enabled=true`. Active (`true`) — desativado por defeito para guardar o disco. | | `CALL_LOG_PIPELINE_MAX_SIZE_KB` | `512` | Tamanho máximo do artefacto do registo de chamadas do pipeline em KB quando `call_log_pipeline_enabled=true`. | | `PROXY_LOGS_TABLE_MAX_ROWS` | `100000` | Máximo de linhas na tabela `proxy_logs` SQLite antes da remoção. | | `PROXY_LOG_INCLUDE_IPS` | `false` | Inclua client/egress IPs e prefixos de conta nos registos da consola `[ProxyEgress]`. Os registos de proxy-log dashboard/database retêm os detalhes completos. | | `PROXY_LOG_FIRST_CHUNK_TIMING` | `false` | Defina como `"true"` ou `"1"` para registar `first_chunk_ms` (enviar início para o primeiro byte útil do corpo) nas linhas de registo do proxy. Envolve cada corpo a montante num fluxo de passagem lento e corrige a linha assim que o byte chega; desativado por defeito para que as respostas passem intactas. | | `APP_LOG_ROTATION_CHECK_INTERVAL_MS` | `60000` (1 min) | Com que frequência `src/lib/logRotation.ts` verifica novamente o tamanho do ficheiro de registo ativo. | | `CHAT_LOG_TEXT_LIMIT` | `65536` | Comprimento máximo da string retido nos artefactos de registo de chat (padrão 64 KB). | | `CHAT_LOG_ARRAY_TAIL_ITEMS` | `128` | Número de itens da matriz retidos da parte final ao truncar cargas de registo de chat. | | `CHAT_LOG_MAX_DEPTH` | `6` | Profundidade máxima de aninhamento antes que as cargas do registo de chat sejam truncadas. | | `CHAT_LOG_MAX_OBJECT_KEYS` | `80` | Máximo de chaves de objeto retidas em cargas úteis de registo de chat (0 = ilimitado). | | `CHAT_LOG_MAX_BODY_KB` | `1024` | Tamanho inteiro do corpo request/response (KB) antes de ser substituído por um resumo simples em vez do clone completo. Aumente isto se as longas conversas de agente mostrarem um espaço reservado em vez das mensagens reais no painel. | | `CHAT_DEBUG_FILE` | `false` | Quando verdadeiro, `serializeArtifactForStorage` ignora o truncamento baseado no tamanho. Apenas depuração. | --- ## 17. Otimização da memória | Variável | Predefinição | Descrição | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_HEAP_DIAGNOSTICS_ENABLED` | `0` (desligado) | Configure `1` para registar as métricas de pressão de heap V8 do `src/lib/healthzLag.ts`. Tamanhos de registo e contagem em curso, nunca solicite conteúdo, rastreios ou instantâneos de heap. É executado dentro do gravador de ciclos de eventos, pelo que `OMNIROUTE_EVENT_LOOP_STALL_THRESHOLD_MS=0` também o desativa. | | `OMNIROUTE_HEAP_DIAGNOSTICS_THRESHOLD_MB` | `900` | Limite positivo para heapUsed (MiB) que desencadeia um registo de diagnóstico opcional. Valores inválidos usam 900 MiB; mensagens de heap elevado estão limitadas a uma vez a cada 60 segundos. | | `OMNIROUTE_MEMORY_MB` | _auto_ (metal puro);**`1024` na imagem Docker** | **Recomendado** limite de heap Docker/standalone V8 (MB). Quando não definido, calibrado dinamicamente (~ 35% do sistema RAM, fixado em `[512, 4096]`); `512` é apenas o piso quando a memória total não pode ser lida. Em `run-standalone.mjs` (Docker CMD), um** explícito** o valor é anexado como `--max-old-space-size` e** vence** sobre um sinalizador de heap NODE_OPTIONS conflituante (último sinalizador V8). `omniroute serve` prefere ainda um heap NODE_OPTIONS existente (#5238). Não defina ambos com números diferentes — o processo regista um aviso a nomear os valores e o vencedor.** A imagem oficial Docker define sempre `1024`, pelo que a calibração nunca é executada aí.** O agente de codificação `/v1/responses` necessita `8192`–`12288` plus cgroup headroom — consulte [Docker Guide — runtime RAM](../guides/DOCKER_GUIDE.md#runtime-ram-for-coding-agents). | | `OMNIROUTE_RSS_PRESSURE_MB` | _auto_ (`max(3072, 2 × OMNIROUTE_MEMORY_MB)`; desativado quando `OMNIROUTE_MEMORY_MB` não está definido) | `open-sse/utils/resourcePressure.ts` | Fusível RSS de processo absoluto (MB) para memória native/external que o V8 `heapUsed` não consegue ver; acima dele, os novos pedidos recebem 503 `resource_pressure`. RSS raramente cai após um pico, por isso combine-o com `OMNIROUTE_PRESSURE_SELF_RESTART`. | | `PROMPT_CACHE_MAX_SIZE` | `50` | Máximo de entradas de prompt do sistema em cache. | | `PROMPT_CACHE_MAX_BYTES` | `2097152` (2 MB) | Tamanho total máximo da cache de prompt. | | `PROMPT_CACHE_TTL_MS` | `300000` (5 min) | Solicita a entrada de cache TTL. | | `SEMANTIC_CACHE_MAX_SIZE` | `100` | Temperatura máxima em cache = 0 respostas. | | `SEMANTIC_CACHE_MAX_BYTES` | `4194304` (4 MB) | Tamanho máximo total da cache semântica. | | `SEMANTIC_CACHE_TTL_MS` | `1800000` (30 min) | Entrada de cache semântica TTL. | | `OMNIROUTE_SEMANTIC_CACHE_PRUNE_INTERVAL_MS` | `1800000` (30 min) | intervalo de poda SQLite. `0` desativa a inicialização e as execuções periódicas; outros valores abaixo de `60000` voltam ao padrão. Valores acima de `2147483647` ms limitam o atraso máximo do temporizador do Node, evitando overflow para polling de 1ms. Primeira corrida após 1s; os temporizadores não são controlados e as execuções nunca se sobrepõem. | | `OMNIROUTE_SEMANTIC_CACHE_PRUNE_BATCH_SIZE` | `2000` | Linhas por SQLite podam DELETE, fixadas em `[100, 50000]`; produz o ciclo de eventos entre lotes. | | `OMNIROUTE_SEMANTIC_CACHE_PRUNE_MAX_BATCHES` | `50` | Orçamento em lote DELETE partilhado por execução durante a expiração e passes de limite de linha opcionais, fixados em `[1, 10000]`. Os backlogs continuam em execuções posteriores. | | `OMNIROUTE_SEMANTIC_CACHE_MAX_ROWS` | `0` | Limite de linha SQLite opcional (`0` = none). Depois de eliminar `expires_at <=` o carimbo de data/hora ISO de início de execução, remova `created_at` mais antigo e, em seguida, `rowid`, incluindo linhas ativas, sujeito ao orçamento de lote partilhado. As contagens são truncadas para números inteiros (até ao limite de números inteiros seguros). Os valores vazios, não numéricos, não finitos ou negativos para todas as quatro variáveis de remoção regressam aos seus padrões; frações arredondadas para baixo. A remoção não altera o comportamento da TTL, da memória LRU ou da cache vectorial. | | `OMNIROUTE_CORPUS_CACHE_SIZE` | `5` | Raízes de corpus local que mantêm um índice activo na memória de uma só vez (`src/lib/localCorpus/configured.ts`). LRU: no limite, o índice da raiz menos recentemente utilizado é removido e reconstruído na sua próxima consulta. Fixo a um mínimo de `1`; um valor não numérico regressa ao padrão. | | `STREAM_HISTORY_MAX` | `50` | Máximo de eventos de transmissão recentes no buffer de visualização em direto do Dashboard. | | `CONTEXT_LENGTH_DEFAULT` | _(desativado)_ | Substituição global do comprimento do contexto (tokens) para cada fornecedor que não tenha variável `CONTEXT_LENGTH_`. Quando definido,** substitui** o catálogo, a substituição do painel e os valores de registo desses fornecedores; quando não está definido, OmniRoute utiliza a sua cadeia integrada, cujo último recurso é `128000`. Consulte [Comprimento do contexto por fornecedor](#per-provider-context-length-context_length_provider). | | `USAGE_TOKEN_BUFFER` | `100` | Espaço extra de token reservado ao rastrear quotas de utilização. | ### Comprimento do contexto por fornecedor (`CONTEXT_LENGTH_`) `open-sse/services/contextManager.ts` (`getEnvOverride()` / `resolveTokenLimit()`) também lê um** por fornecedor** formulário cujo nome é construído a partir do fornecedor ID em tempo de execução, pelo que não pode ser listado linha a linha na tabela acima ou em `.env.example`. **Nome.** `CONTEXT_LENGTH_`, onde `` é o fornecedor ID maiúsculo, com todos os caracteres fora de `A-Z` / `0-9` substituídos por `_`. O fornecedor ID é o canónico após a resolução do alias (a parte `provider` de uma string `provider/model` depois de um alias curto ter sido resolvido). Os nós personalizados compatíveis com OpenAI ou Anthropic utilizam o seu nó gerado ID, pelo que UUID faz parte do nome da variável. O valor é um número inteiro positivo de tokens; qualquer outra coisa (vazia, `0`, negativa, não numérica) é ignorada e a resolução passa para o passo seguinte. | Fornecedor ID | Nome da variável | | ----------------------------------------------------------- | -------------------------------------------------------------------------- | | agente router | CONTEXT_LENGTH_AGENTROUTER | | router aberto | CONTEXT_LENGTH_OPENROUTER | | openai-compatible-chat-0f8e2c1a-5b7d-4e3f-9a6c-2d1b8e4f7a90 | CONTEXT_LENGTH_OPENAI_COMPATIBLE_CHAT_0F8E2C1A_5B7D_4E3F_9A6C_2D1B8E4F7A90 | **Precedência.** Para um par `provider/model`, o primeiro passo que produz um valor ganha: 1. `CONTEXT_LENGTH_` para esse fornecedor. 2. `CONTEXT_LENGTH_DEFAULT` (substituição do ambiente global). 3. A janela por modelo: uma substituição de contexto persistente (definida no painel ou fixada automaticamente pelo reconciliador de descoberta, ver `CONTEXT_WINDOW_RECONCILE_INTERVAL`), caso contrário, o valor sincronizado catalog/models.dev. 4. O registo do fornecedor `defaultContextLength`. 5. Heurística do nome do modelo (`claude` 200000, `gemini` 1000000, `gpt` / `o1` / `o3` / `o4` / `codex` 400000). 6. Padrões integrados por fornecedor e, em seguida, `128000`. Ambas as etapas ambientais se aplicam ao** provedor inteiro** : cada modelo desse fornecedor obtém o mesmo limite e ganha as substituições de painel por modelo. Quando apenas um modelo de um fornecedor necessita de uma janela diferente, utilize uma substituição por modelo no painel. **Âmbito.** Esta cadeia impulsiona a verificação da janela de contexto no momento do pedido (a rejeição `context_length_exceeded` / "A entrada excede a janela de contexto" em `open-sse/handlers/chatCore.ts`), orçamentos de compressão imediata e limites de contexto combinados. O `context_length` anunciado pelo `GET /v1/models` pode ainda vir de metadados de catálogo ou de registo e não há garantia de que reflita a substituição do ambiente. **Exemplo.** Um fornecedor cujo modelo aceita uma janela de 1.050.000 tokens enquanto o catálogo informa 128.000: ```dotenv CONTEXT_LENGTH_AGENTROUTER=1050000 ``` Reinicie o servidor após a sua alteração: o valor é lido no ambiente de processo do servidor. No** aplicação de desktop** o servidor é executado como um processo filho e não vê uma variável de sistema definida após o lançamento da aplicação; coloque a linha no ficheiro `.env` que a aplicação carrega (ordem de pesquisa em [Electron Guide: Environment file lookup](../guides/ELECTRON_GUIDE.md#environment-file-lookup) ), feche completamente e reinicie a aplicação. ### Compressão | Variável | Predefinição | Descrição | | ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS` | desarmar | Confie no projeto `.rtk/filters.json` sem um hash `.rtk/trust.json`. Utilizar apenas em desenvolvimento local controlado. | ### Mecanismo de Memória (plano 21) ### Custo do loop de eventos de memória, habilidades e atualização de tokens (#10349) OmniRoute é um** processo de nó único** . A memória extraction/retrieval, a injeção de habilidades e a atualização do token do fornecedor são executadas neste** mesmo loop de eventos** como `GET /healthz` e o painel. Não são um thread de trabalho. | Trabalho | Código | Predefinição | Controlo do operador | | ------------------------------- | ---------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Extração/recuperação de memória | `src/lib/memory/` | Painel**memoryEnabled** (padrão ativado) | Desligar** Configurações → Memória** . Não existe nenhum interruptor de eliminação de ambiente separado para além de desativar o recurso nas definições. | | Injeção de competências | `src/lib/skills/injection.ts` | Painel**skillsEnabled** (padrão ativado) | Desligar** Configurações → Memory/Skills** (`skillsEnabled`). Os botões sandbox abaixo apenas da execução ligada após a injeção já estar ativada. | | Atualização de token | `src/sse/services/tokenRefresh.ts` | Ativado para fornecedores OAuth/web conectados | Desligue o fornecedor ou deixe os tokens permanecerem válidos; não há ambiente `TOKEN_REFRESH=0` hoje. | Se `/healthz` estiver lento numa caixa silenciosa, desative primeiro as capacidades de memória + e, em seguida, verifique a carga catalog/compression (#10303, #9685). Estes recursos rendem pontos `await`, mas ainda assim competem por um thread. Incorporação de camadas, armazenamento de vetores e botões de reclassificação para o subsistema de memória persistente (`src/lib/memory/`). | Variável | Predefinição | Descrição | | ------------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MEMORY_EMBEDDING_CACHE_TTL_MS` | `300000` (5 min) | TTL para a cache de incorporação na memória (por assinatura source/model/dim ). | | `MEMORY_EMBEDDING_CACHE_MAX` | `1000` | Máximo de entradas LRU mantidas na cache de incorporação. | | `MEMORY_TRANSFORMERS_MODEL` | `Xenova/all-MiniLM-L6-v2` | ID do repositório HF para o pipeline MiniLM local `@huggingface/transformers` opcional (~ 23 MB int8, ~ 400 MB RAM). | | `MEMORY_STATIC_MODEL` | `minishlab/potion-base-8M` | ID do repositório HF para o incorporador da tabela de pesquisa potion/Model2Vec estática. Descarregado lentamente no diretório de cache. | | `MEMORY_STATIC_CACHE_DIR` | `/embeddings` | Diretório utilizado para armazenar em cache os ficheiros do modelo de poção estática. O predefinido é `DATA_DIR` quando não está definido. | | `HF_HUB_ENDPOINT` | `https://huggingface.co` | Substituir URL base do Hugging Face Hub utilizado pelo `staticPotion.ts` (por exemplo, ponto final do espelho para configurações com espaço aéreo). | | `MEMORY_VEC_TOP_K` | `20` | Top-K padrão utilizado pela pesquisa de vetor de força bruta `sqlite-vec` dentro de `src/lib/memory/vectorStore.ts`. | | `MEMORY_RRF_K` | `60` | Constante de fusão de classificação recíproca `k` para recuperação de vetor híbrido FTS5 + (receita sqlite-vec). | | `VECTOR_STORE_DISABLE_VEC` | `false` | costura Test/diagnostic em `getVectorStore()` (`src/lib/memory/vectorStore.ts`): quando `true`, força o armazenamento de vetores para `null` (simula um ambiente cloud/WASM sem `sqlite-vec`), degradando a recuperação de memória para a pesquisa de palavras-chave FTS5. Deixe sem definição na produção. | | `NOTION_API_KEY` | _(desativado)_ | Chave API para back-end Notion (utilizada pela predefinição de back-end conhecida `genericBackend.ts` ). | | `NOTION_API_URL` | `https://api.notion.com/v1` | Base URL para Notion API (pode substituir as alternativas Notion auto-hospedadas). | | `OBSIDIAN_API_KEY` | _(desativado)_ | Chave API para o back-end Obsidian Vault (utilizada pela predefinição de back-end conhecida `genericBackend.ts` ). | | `OBSIDIAN_API_URL` | `http://localhost:27123` | Base URL para Obsidian Vault API (pode substituir para vault remoto). | | `MEMORY_TYPED_DECAY_ENABLED` | `false` | Chave mestre de decaimento de memória digitada TV6.** Ativar (padrão desativado)** — a varredura** exclui** memórias deterioradas. Com ele desligado, `access_count`/`last_accessed_at` são pura telemetria e nada é excluído. | | `MEMORY_TYPED_DECAY_EPISODIC_DAYS` | `30` | TTL (dias) após o qual uma memória `episodic` não utilizada decai. `0` também torna imune episódico. Os tipos duráveis (`factual`/`procedural`/`semantic`) são sempre imunes. O relógio de decaimento baseia-se novamente em `last_accessed_at`. | | `MEMORY_TYPED_DECAY_ACCESS_IMMUNITY` | `3` | Uma memória `>=` injetada torna-se muitas vezes imune à deterioração, independentemente do tipo. `0` desativa a imunidade de acesso. | | `MEMORY_TYPED_DECAY_SWEEP_INTERVAL` | `0` (desativado) | Intervalo (segundos) para a varredura periódica de decaimento opcional em `src/lib/memory/typedDecay.ts`. `0`/unset = sem varrimento periódico. Aceitação dupla: também requer `MEMORY_TYPED_DECAY_ENABLED=true`. | | `OMNIROUTE_STRICT_SYSTEM_PROVIDERS` | _(desativado)_ | IDs de fornecedores separados por vírgula (sem distinção entre maiúsculas e minúsculas) que aceitam uma mensagem `system`** apenas no índice 0** (`src/lib/memory/injection.ts`). Para estes, a emenda de memória intermédia segura em cache não é segura em conversas multivoltas, pelo que a memória é merged/prepended como a mensagem principal do sistema. O padrão é apenas `xiaomi-mimo`/`mimo`; estender para endpoints auto-hospedados compatíveis com OpenAI (por exemplo, Qwen3.5 +/3.6) cujo modelo de chat impõe a mesma restrição de mensagem de sistema líder único. | ### Exemplo Docker com pouca RAM `128` is dashboard-only. Coding agents on this heap `FATAL ERROR` during long `/v1/responses`. Do not use this example as a Claude/Codex/Grok gateway. ```bash OMNIROUTE_MEMORY_MB=128 PROMPT_CACHE_MAX_SIZE=20 PROMPT_CACHE_MAX_BYTES=524288 # 512 KB SEMANTIC_CACHE_MAX_SIZE=25 SEMANTIC_CACHE_MAX_BYTES=1048576 # 1 MB STREAM_HISTORY_MAX=10 ``` --- ## 18. Sincronização de preços Sincronização automática de dados de preços de modelos de fontes externas. | Variável | Predefinição | Arquivo de origem | Descrição | | ----------------------- | ------------- | ------------------------ | ------------------------------------------ | | `PRICING_SYNC_ENABLED` | `false` | `src/lib/pricingSync.ts` | Ative a sincronização periódica de preços. | | `PRICING_SYNC_INTERVAL` | `86400` (24h) | `src/lib/pricingSync.ts` | Intervalo de sincronização em segundos. | | `PRICING_SYNC_SOURCES` | `litellm` | `src/lib/pricingSync.ts` | Fontes de dados separadas por vírgula. | --- ## Arena ELO Sincronização | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ARENA_ELO_SYNC_ENABLED` | `true` | `src/shared/constants/featureFlagDefinitions.ts` | Sincronização periódica ELO do placar de líderes do Arena AI, configurável nos sinalizadores de recurso do painel ou com `false` para cancelar. | | `MODELS_CATALOG_PREFIX_MODE` | `dual` | `src/shared/constants/featureFlagDefinitions.ts`, `src/app/api/v1/models/catalog.ts` | Formulário de prefixo utilizado para IDs de modelo em `GET /v1/models`. `dual` anuncia o prefixo de alias curto e o prefixo de fornecedor canónico para cada modelo (a compatibilidade com versões anteriores — praticamente duplica o catálogo); `alias` emite um ID por modelo; `canonical` emite apenas o prefixo completo do ID do fornecedor (os fornecedores cujo alias já é o ID canónico mantêm a sua entrada única). Os clientes podem substituir por pedido com `?prefix=alias`. Ver [API_REFERENCE](API_REFERENCE.md#model-id-prefixes-prefix). | | `ARENA_ELO_SYNC_INTERVAL` | `86400` (24h) | `src/lib/arenaEloSync.ts` | Intervalo de sincronização em segundos. | --- ## Fornecedor de recreio PromptQL (Unofficial/Experimental) Ponte de sessão GraphQL com engenharia inversa para prompt.ql.app (`src/shared/constants/providers/web-cookie.ts`). Todos os padrões opcionais — apontam para os endpoints do playground público; substituir apenas para uma implementação self-hosted/alternate PromptQL. | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `PROMPTQL_GRAPHQL_ENDPOINT` | `https://data.prompt.ql.app/promptql/playground-v2-hge/v1/graphql` | `open-sse/executors/promptql.ts` | Endpoint GraphQL utilizado para operações chat/session. | | `PROMPTQL_CREDITS_ENDPOINT` | `https://data.pro.ql.app/v1/graphql` | `open-sse/executors/promptql.ts`, `open-sse/services/usage/promptql.ts` | Endpoint GraphQL utilizado para consultar crédito balance/usage. | | `PROMPTQL_TOKEN_REFRESH_URL` | `https://auth.pro.ql.app/ddn/project/token` | `open-sse/executors/promptql.ts` | Endpoint utilizado para a atualização de token de melhor esforço. | | `PROMPTQL_POLL_TIMEOUT_MS` | `180000` | `open-sse/executors/promptql.ts` | Tempo máximo (ms) para pesquisar `thread_events` antes do tempo limite. | --- ## Fornecedor Web HyperAgent (Unofficial/Experimental) Ponte de sessão com engenharia inversa para hyperagent.com (`src/shared/constants/providers/web-cookie.ts`). Opcional — os pontos padrão no terminal billing/usage público; substituir apenas para uma implementação self-hosted/alternate HyperAgent. | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------- | --------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------ | | `HYPERAGENT_USAGE_URL` | `https://hyperagent.com/api/settings/billing/usage` | `open-sse/services/usage/hyperagent.ts` | Endpoint utilizado para pesquisar blocos de crédito billing/usage. | --- ## Política de orçamento de utilização sem preço | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `UNPRICED_USAGE_BUDGET_POLICY` | _(desativado; falha no fecho, a menos que a desativação booleana esteja ativada)_ | `src/shared/utils/featureFlags.ts` | Limites daily/weekly USD por chave: `fail_closed` bloqueia utilização genuinamente sem preço; `count_as_zero` conta como $0 enquanto impõe gastos com o preço. Um enum explícito (DB antes de env) substitui a desativação booleana. Valores inválidos e falhas na pesquisa de preços falham no fecho. | | `USAGE_LIMIT_IGNORE_UNPRICED` | `false` | `src/shared/utils/featureFlags.ts` | Desativação de compatibilidade booleana upstream: conta a utilização genuinamente sem preço como 0 dólares apenas quando não está configurada nenhuma política de enumeração explícita. Os gastos precificados e as pesquisas com falhas permanecem aplicados. | ## Quotas de utilização de código Kilo Saldo USD pessoal e pesquisa de utilização do Kilo Pass para o fornecedor Kilo Code. Opcional — o padrão aponta para o Kilo API público; substituir apenas por um acessório relay/test. A autenticação utiliza o token de acesso OAuth existente da ligação. | Variável | Predefinição | Arquivo de origem | Descrição | | -------------- | --------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- | | `KILO_API_URL` | `https://api.kilo.ai` | `open-sse/services/usage/kilocode.ts` | Base URL utilizada para pesquisar o saldo pessoal do Kilo Code e utilização do Kilo Pass. | --- ## Adobe Firefly Web Provider (Unofficial/Experimental) Atualização de sessão orientada pelo browser para o fornecedor Web Adobe Firefly (`open-sse/services/adobeFireflyBrowserLogin.ts`, `open-sse/services/adobeFireflySession.ts`, `open-sse/services/adobeFireflyClient.ts`). Opcional — todos os padrões são ajustados para uma instalação normal em desktop. > **Removido em #9255.** O antigo tempo de execução do Chrome anexado ao CDP (adobeFireflyChromeRuntime.ts) foi substituído por um serviço de login do navegador Playwright e os seus botões já não existem. As variáveis ADOBE_FIREFLY_CHROME_ CDP_PORT / VISIBLE / HEADED / PING / FORCE_RESTART, mais ADOBE_FIREFLY_LOGIN_WAIT_MS e ADOBE_FIREFLY_FORTER_WAIT_MS, não são lidas em lado nenhum da base de código — a sua definição não tem qualquer efeito. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------ | -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `ADOBE_FIREFLY_CHROME_HEADLESS` | `0` | `open-sse/services/adobeFireflyBrowserLogin.ts` | Defina como `1` para Chrome sem cabeça verdadeiro (quebrado para geração; apenas depuração). | | `ADOBE_FIREFLY_BROWSER_REFRESH` | `1` | `open-sse/services/adobeFireflySession.ts` | Aquecimento proativo do navegador opt-in/out. `0` desativa o aquecimento proativo (a recuperação 408 a meio do lote ainda se aplica). | | `ADOBE_FIREFLY_SESSION_DISK` | `1` | `open-sse/services/adobeFireflySession.ts` | Defina como `0` para desativar a persistência da sessão do Adobe Firefly no disco. | | `ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS` | _(desativado)_ | `open-sse/services/adobeFireflySession.ts` | Intervalo mínimo (ms) aplicado entre envios sucessivos, substituindo o padrão integrado. | | `ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS` | _(desativado)_ | `open-sse/services/adobeFireflySession.ts` | Lacuna extra (ms) adicionada após um lote bem-sucedido, substituindo o padrão integrado. | | `ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS` | _(desativado)_ | `open-sse/services/adobeFireflyClient.ts` | Atraso base (ms) antes de enviar um pedido de geração, substituindo o padrão integrado. | --- ## 19. Sincronização do modelo (desenvolvimento) | Variável | Predefinição | Arquivo de origem | Descrição | | ----------------------------------- | -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `MODELS_DEV_SYNC_ENABLED` | _(desativado)_ | `src/lib/modelsDevSync.ts` | Substituição forçada para sincronização de preços models.dev. Desdefinir = honor Definições > AI (`modelsDevSyncEnabled`). `0`/`false`/`off`/`no`** vence o DB** e ignora a sincronização periódica e as varreduras `getModelsDevPricing()` SQL/JSON (recuperação quando o painel está preso no mesmo ciclo de eventos). `1`/`true`/`on`/`yes` força a sincronização. O preço save/clear ainda chama `backupDbFile("pre-write")`, que não funciona sob o acelerador de 60 minutos ou `DISABLE_SQLITE_AUTO_BACKUP`. | | `MODELS_DEV_SYNC_INTERVAL` | `86400` (24h) | `src/lib/modelsDevSync.ts` | Intervalo de sincronização do catálogo do modelo em tempo de desenvolvimento em segundos. | | `CONTEXT_WINDOW_RECONCILE_INTERVAL` | `86400` (24h) | `src/lib/contextWindowResolver.ts` | Intervalo (segundos) para o reconciliador de janela de contexto auto-corretivo (5004): fixa as janelas declaradas pelo fornecedor da descoberta `/models` como substituições `auto:discovery` quando divergem do catálogo. Defina como `0` para desativar. Reutiliza dados já sincronizados (sem nova pesquisa); nunca substitui as substituições `manual`. | --- ## 20. Configurações específicas do prestador | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OPENROUTER_CATALOG_TTL_MS` | `86400000` (24h) | `src/lib/catalog/openrouterCatalog.ts` | cache de catálogo de modelos OpenRouter TTL. | | `MODEL_CATALOG_INCLUDE_NAMES` | `true` | `src/shared/constants/featureFlagDefinitions.ts` | Inclua campos `name` de fácil apresentação nas respostas `/v1/models`. Desative para clientes que apenas esperam IDs. | | `OMNIROUTE_GEMINI_WEB_ARGON_ENABLED` | `0` (desligado) | `open-sse/config/providers/registry/gemini/web/index.ts` | Aceitar (#16573). Configure `1` (ou `true`/`yes`) para anunciar `gweb/gemini-4-argon` no fornecedor Web Gemini e deixe o seu executor selecionar esse modo. Desativado por defeito porque os seletores de menu do modo Argon não foram verificados numa conta Web Gemini ativa; enquanto desativado, o modelo não é listado e um pedido é rejeitado como um modelo desconhecido, como anteriormente. Leia no arranque, portanto, uma alteração precisa de ser reiniciada. | | `CATALOG_BUILD_TIMEOUT_MS` | `8000` (8s) | `src/app/api/v1/models/catalogCache.ts` | Limite de espera de caminho frio para uma reconstrução de catálogo `GET /v1/models` unido (#12627). No tempo limite, é servido um último 200 válido quando existe. | | `OMNIROUTE_SYNCED_CATALOG_STALE_AFTER_MS` | `2592000000` (30 dias) | `src/lib/db/models/activeSyncedCatalog.ts` | Período após o qual a lista de modelos sincronizados de uma ligação deixa de ser autoritativa para encaminhamento e falha na abertura do registo (#12849). As linhas sem carimbo de data e hora contam como obsoletas. | | `OMNIROUTE_ANALYTICS_CACHE_TTL_MS` | `60000` (anos 60) | `src/lib/usage/analyticsResponseCache.ts` | Durante quanto tempo é reutilizada uma resposta `GET /api/usage/analytics` lenta para a mesma string de consulta (#15629). `0` desativa a cache. | | `OMNIROUTE_ANALYTICS_CACHE_MIN_COMPUTE_MS` | `1000` (1s) | `src/lib/usage/analyticsResponseCache.ts` | Apenas as respostas analíticas que demoraram pelo menos esse tempo a serem criadas são armazenadas em cache, pelo que as pequenas instâncias veem sempre dados atualizados. | | `OMNIROUTE_CACHE_METRICS_MIN_COMPUTE_MS` | desarmar (desligar) | `src/app/api/cache/route.ts` via `src/lib/usage/analyticsResponseCache.ts` | Aceitar (#16361). Quando definido como um número inteiro não negativo N, a parte do histórico de utilização de `GET /api/cache` (tendência + dos totais da cache de prompt) é servida a partir da cache de resposta analítica partilhada quando demorou pelo menos N ms a construir, por janela `trendHours` fixada, para `OMNIROUTE_ANALYTICS_CACHE_TTL_MS` (o histórico pode atrasar até esse TTL; `DELETE /api/cache` invalida-o). Histórico = não definido ou inválido lido ao vivo em cada pedido. | | `NANOBANANA_POLL_TIMEOUT_MS` | `120000` | `open-sse/handlers/imageGeneration.ts` | Máximo de espera pelos trabalhos de geração de imagem NanoBanana. | | `NANOBANANA_POLL_INTERVAL_MS` | `2500` | `open-sse/handlers/imageGeneration.ts` | frequência de pesquisa de trabalho NanoBanana. | | `ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS` | `8000` | `open-sse/services/adobeFireflyUpscale.ts` | Atraso base para a espera exponencial de envio e nova tentativa de upscale do Adobe Firefly. | | `AWS_REGION` | _(desativado)_ | `src/lib/providers/validation.ts`, `open-sse/handlers/audioSpeech.ts` | Região utilizada para construir endpoints AWS Bedrock (Kiro, audio). | | `AWS_DEFAULT_REGION` | _(desativado)_ | `src/lib/providers/validation.ts`, `open-sse/handlers/audioSpeech.ts` | Fallback quando `AWS_REGION` não está definido. | | `CLOUDFLARE_ACCOUNT_ID` | _(desativado)_ | `open-sse/executors/cloudflare-ai.ts` | Conta ID para Cloudflare Trabalhadores AI. | | `CLOUDFLARE_PLAYGROUND_CHROME_PATH` | _(desativado)_ | `open-sse/executors/cloudflare-playground.ts` | Caminho binário completo do Chrome para desktop para o executor Cloudflare AI Playground, utilizado quando a verificação de impressões digitais sem cabeça bloqueia o Chromium incluído no Playwright. | | `CODEBUDDY_SYSTEM_PROMPT_MAX_LEN` | ∅ (∞) — _unset = sem comprimento cap_ | `open-sse/executors/codebuddy/shared.ts` | Limite de comprimento opcional para os avisos do sistema chamador enviados para CodeBuddy (CN e internacional). Por defeito, apenas um prompt que contém um marcador de identidade do agente de codificação é substituído por um neutro (o filtro de conteúdo do Tencent rejeita-os); prompts longos são mantidos. Um número inteiro > 0 também substitui qualquer indicação do sistema com mais de tantos caracteres; unset, `0` ou um valor não inteiro desativa o limite. Cada substituição regista qual a regra que foi acionada (marcador de identidade ou comprimento). | | `CLOUDFLARE_API_BASE` | `https://api.cloudflare.com/client/v4` | `src/app/api/settings/proxy/cloudflare-deploy/route.ts` | Substitua a base Cloudflare REST API utilizada pelo implementador de retransmissão do proxy-pool Workers (#4640 / 9router#1360). | | `NEXT_PUBLIC_CLOUDFLARE_RELAY_DEFAULT_PROJECT` | `omniroute-relay` | `src/app/(dashboard)/dashboard/settings/components/proxy/CloudflareRelayModal.tsx` | Nome do projeto de trabalho padrão sugerido no modal "Deploy Relay" da pool de proxy. | | `NEXT_PUBLIC_CLOUDFLARE_RELAY_ENABLED` | `true` | `src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx` | Defina como `false` para ocultar a opção de retransmissão de trabalhadores Cloudflare no separador Pool de proxy. | | `CLOUDFLARED_BIN` | detecção automática | `src/lib/cloudflaredTunnel.ts` | Caminho personalizado para o binário `cloudflared`. | | `CLOUDFLARED_PROTOCOL` | `http2` | `src/lib/cloudflaredTunnel.ts` | Protocolo de transporte de túnel: `http2` (padrão), `quic` ou `auto`. | | `CLOUDFLARED_CONFIG` | _(desativado)_ | `src/lib/cloudflaredTunnel.ts` | Caminho para um `config.yml` cloudflared gerido localmente (com `tunnel:`, `credentials-file:`, `ingress:`). Quando definido, OmniRoute executa `tunnel --config run` (túnel denominado) em vez de um túnel rápido efémero. | | `CLOUDFLARED_HOSTNAME` | _(da entrada de configuração)_ | `src/lib/cloudflaredTunnel.ts` | Substituição do nome de host público do túnel nomeado (por exemplo, `ai.example.com`), reportado como `publicUrl`/`apiUrl`. Quando não está definido, é lido no primeiro nome de host `ingress` da configuração. | | `DENO_DEPLOY_API_BASE` | `https://api.deno.com/v2` | `src/app/api/settings/proxy/deno-deploy/route.ts` | Substitua a base Deno Deploy REST API utilizada pelo implantador de retransmissão do pool de proxy (#4643 / 9router#1437). | | `NEXT_PUBLIC_DENO_RELAY_DEFAULT_PROJECT` | `omniroute-deno-relay` | `src/app/(dashboard)/dashboard/settings/components/proxy/DenoRelayModal.tsx` | Nome padrão da aplicação Deno Deploy sugerido no modal "Deploy Relay" do proxy pool. | | `NEXT_PUBLIC_DENO_RELAY_ENABLED` | `true` | `src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx` | Defina como `false` para ocultar a opção de retransmissão Deno Deploy do separador Proxy Pool. | | `SEARCH_CACHE_TTL_MS` | `300000` (5 min) | `open-sse/services/searchCache.ts` | TTL para a cache de resposta de pesquisa API (Perplexity, Brave, etc.). | | `ENABLE_CC_COMPATIBLE_PROVIDER` | `false` | `src/shared/utils/featureFlags.ts` | Revele o fornecedor experimental UI compatível com CC para relés apenas de código Claude. | | `NINEROUTER_HOST` | `127.0.0.1` | `open-sse/executors/ninerouter.ts` | Substitua o host onde a instância integrada do 9router escuta. | | `NINEROUTER_PORT` | `20130` | `open-sse/executors/ninerouter.ts` | Substitua a porta onde a instância integrada do 9router escuta. | | `EMBED_WS_PROXY_HOST` | `127.0.0.1` | `src/lib/services/embedWsProxy.ts` | Ligue o host para o proxy WebSocket de serviço integrado (loopback apenas por defeito). | | `EMBED_WS_PROXY_PORT` | `20131` | `src/lib/services/embedWsProxy.ts` | Porta para o servidor proxy WebSocket de serviço integrado. | | `CLIPROXYAPI_HOST` | `127.0.0.1` | `open-sse/executors/cliproxyapi.ts` | host ponte CLIProxyAPI (integração legada). | | `CLIPROXYAPI_PORT` | `5544` | `open-sse/executors/cliproxyapi.ts` | porta da ponte CLIProxyAPI. | | `CLIPROXYAPI_API_KEY` | _(vazio)_ | `open-sse/handlers/chatCore/cliproxyapiCredentials.ts` | Fallback da chave do plano de dados quando a configuração `cliproxyapi_api_key` está em falta. | | `CLIPROXYAPI_MANAGEMENT_KEY` | _(vazio)_ | `src/lib/services/cliproxyAccountHealth.ts` | Chave de gestão para leituras de integridade da conta de uma instância CLIProxyAPI gerida externamente. | | `CLIPROXYAPI_CONFIG_DIR` | `~/.cli-proxy-api` | `src/lib/versionManager/processManager.ts` | diretório de configuração CLIProxyAPI. | | `CLIPROXY_BIND_HOST` | `127.0.0.1` | `docker-compose.yml` | A interface do host docker-compose publica o sidecar `cliproxyapi` em (#12578). O seu volume de dados contém as credenciais do fornecedor OAuth/API e a imagem fixada não tem qualquer substituição `api-keys` do plano de dados baseado em env (apenas um `config.yaml` montado), pelo que `0.0.0.0` expõe um serviço com credencial para todo o LAN. | | `MUX_SERVICE_PORT` | `8322` | `src/lib/services/bootstrap.ts` | Substitua a porta onde o daemon de orquestração do agente Mux (coder/mux) integrado serve (sempre 127.0.0.1). | | `OPENWA_SERVICE_PORT` | `8323` | `src/lib/services/bootstrap.ts` | Substitua a porta onde o daemon open-wa integrado (WhatsApp Web Automation) escuta (sempre 127.0.0.1). | | `DARIO_HOST` | `127.0.0.1` | `open-sse/executors/dario.ts` | Host bind/connect de serviço integrado Dario (loopback apenas por defeito). | | `DARIO_PORT` | `3456` | `open-sse/executors/dario.ts` | Porta de serviço integrado Dario. | | `DARIO_HOST` | `127.0.0.1` | `open-sse/executors/dario.ts` | Host bind/connect de serviço integrado Dario (loopback apenas por defeito). | | `DARIO_PORT` | `3456` | `open-sse/executors/dario.ts` | Porta de serviço integrado Dario. | | `LOCAL_HOSTNAMES` | _(vazio)_ | `open-sse/config/providerRegistry.ts` | Nomes de host adicionais separados por vírgula tratados como "locais" (nomes de serviço Docker, etc.). | `ENABLE_CC_COMPATIBLE_PROVIDER` é apenas para retransmissões de terceiros que aceitam exclusivamente clientes Claude Code. OmniRoute reescreve os pedidos para que esses relés os aceitem. Se quiser utilizar apenas o código Claude CLI ou não tiver a certeza de quais são estes relés, mantenha-o desativado e adicione um fornecedor regular compatível com o Anthropic. --- ## 21. Proxy de saúde | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000` | `src/lib/proxyHealth.ts` | Tempo limite de verificação rápida da integridade da falha. | | `PROXY_LATENCY_WINDOW_HOURS` | `3` | `src/lib/db/proxies.ts` | Janela temporal (horas) para calcular a latência média dos proxies candidatos na estratégia de pool com otimização de latência. | | `PROXY_HEALTH_CACHE_TTL_MS` | `30000` | `src/lib/proxyHealth.ts` | Cache de resultados da verificação de integridade TTL. | | `NONE_HONORED_WINDOW_HOURS` | `24` | `src/lib/db/reasoningEffortCompliance.ts` | Janela final em horas para o leitor de conformidade reasoning_effort = none em GET /v1/models/health. | | `NONE_HONORED_CACHE_TTL_MS` | `20000` | `src/lib/db/reasoningEffortCompliance.ts` | Armazene TTL em cache em ms para o instantâneo de não conformidade (15-30s). | | `NONE_HONORED_MIN_SAMPLE` | `3` | `src/lib/db/reasoningEffortCompliance.ts` | Mínimo de nenhuma solicitação antes de um modelo ser honrado ou não honrado; abaixo deste, o modelo indica desconhecido. | | `PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS` | `2000` | `src/lib/proxyHealth.ts` | Cache TTL para sondagens de integridade do proxy com falha. Mantenha isto mais curto do que `PROXY_HEALTH_CACHE_TTL_MS` para que os tempos limite de proxy transitórios sob alta simultaneidade tentem novamente rapidamente, sem desativar a falha rápida para proxies realmente inativos. | | `PROXY_HEALTH_ENABLED` | `true` | `src/lib/proxyHealth/scheduler.ts` | Configure `false` para desativar o agendador de integridade do proxy de segundo plano que sonda periodicamente os proxies registados. | | `PROXY_HEALTH_INTERVAL_MS` | `600000` | `src/lib/proxyHealth/scheduler.ts` | Intervalo de varrimento do agendador de integridade em segundo plano em ms (mínimo `60000`). | | `PROXY_HEALTH_RELAY_INTERVAL_MS` | `21600000` | `src/lib/proxyHealth/relayCadence.ts` | Intervalo de sondagem em ms para proxies de retransmissão de bordo (`deno`/`vercel`/`cloudflare`), cujas sondagens activam um isolado sem servidor cobrado (mínimo `60000`). | | `PROXY_HEALTH_RECOVERY_INTERVAL_MS` | `600000` | `src/lib/proxyHealth/scheduler.ts` | Intervalo de passagem de recuperação em segundo plano em ms: com que frequência os proxies anteriormente não íntegros são testados novamente para que um proxy recuperado regresse à rotação sem reinicialização. Valores abaixo de `60000` voltam ao padrão. | | `PROXY_HEALTH_TEST_URL` | `https://httpbin.org/ip` | `src/lib/proxyHealth/probeTarget.ts` | Destino da sonda de acessibilidade utilizado pelo planeador e pelo endpoint `/api/settings/proxies/auto-test`. Aponte para um internal/self-hosted URL para evitar o padrão público. | | `PROXY_HEALTH_TEST_CONCURRENCY` | `10` | `src/lib/proxyHealth/probeTarget.ts` | As análises são iniciadas uma vez por batch, partilhadas pelo agendador e pelo endpoint `/api/settings/proxies/auto-test`. Piso em 1 e limite em 50. | | `PROXY_HEALTH_TEST_STAGGER_MS` | `100` | `src/lib/proxyHealth/probeTarget.ts` | Atraso em ms entre duas partidas de sonda dentro de um lote. Sem ele, todo o lote sai no mesmo momento e uma saída partilhada IP pode disparar um alvo com uma taxa limitada. Defina como `0` para desativar o espaçamento; limitado a 5.000. | | `PROXY_HEALTH_USE_PROVIDER_TARGET` | `true` | `src/lib/proxyHealth/providerProbeTarget.ts` | Defina "false" para parar de sondar o host real do fornecedor atribuído a um proxy (`GET /models`, sem chave API ) e utilize sempre `PROXY_HEALTH_TEST_URL`. | | `PROXY_HEALTH_AUTO_DEACTIVATE` | `false` | `src/lib/proxyHealth/statusPolicy.ts` | Quando `false` (padrão), os testes automatizados de acessibilidade (o agendador + o botão `/api/settings/proxies/auto-test` "Testar tudo") são** somente leitura** e nunca escreve o estado de um proxy — apenas o operador define active/inactive, pelo que uma sonda instável não pode prender um proxy atribuído (#6246). Defina `true` para restaurar o comportamento de teste e configuração legado. | | `FLUSH_EMPTY_RETRY_ENABLED` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de recurso de aceitação (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md) ; uma substituição DB do painel ganha). `true` (ou `1`, `yes`) tenta novamente o streaming traduzido vazio através do caminho de credencial normal (até `STREAM_RECOVERY.EMPTY_TURN_RETRY_MAX` novas tentativas) em vez de expor um 200 vazio ou um 502 de conteúdo vazio. | | `EMPTY_STREAM_SIBLING_RECOVERY_ENABLED` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de recurso de aceitação (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md) ; uma substituição DB do painel ganha). `true` (ou `1`, `yes`) arma a sonda de conteúdo de fluxo vazio Claude/Codex e gasta a nova tentativa limitada existente noutra ligação elegível após um turno `empty_content`, sem arrefecimento ou bloqueio de modelo. | | `STREAM_LATE_OUTPUT_PROBE_ENABLED` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de recurso de aceitação (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md) ; uma substituição DB do painel ganha). `true` (ou `1`, `yes`) continua a amostrar um pedaço encaminhado em 16 após os primeiros 64, de modo que a saída visível tardia ainda marca o fluxo como tendo emitido saída (um único 5xx pós-saída permanece no âmbito do pedido em vez de um bloqueio apenas de modelo). | | `PROXY_POOL_EGRESS_OBSERVATION` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de recurso de aceitação (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md) ; uma substituição DB do painel ganha). `true` (ou `1`, `yes`) mostra a observação de saída do pool de leitura apenas num pool de proxy no painel (saída distinta IPs, ligações e o mais visto atrás de um IP nas últimas 24 horas, do registo do proxy). Nunca utilizado para encaminhamento. | | `PROXY_OPERATOR_EGRESS_ENABLED` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de recurso de aceitação (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md) ; uma substituição DB do painel ganha). `true` (ou `1`, `yes`) aceita endereços observados datados enviados pelo operador por membro do pool e funde-os com o diário lido para apresentação e ordem do pool. | | `PROXY_OPERATOR_EGRESS_WINDOW_HOURS` | `24` | `src/lib/db/proxyOperatorEgress.ts` | Janela de observação em horas para as linhas de saída enviadas pelo operador (leitura em cada leitura; não é necessário reiniciar). Limitado a 1..168; fora do intervalo, não numérico ou vazio volta a 24 com um único aviso em todo o processo, nunca um lançamento. | | `PROXY_AUTO_REMOVE` | `false` | `src/lib/proxyHealth/scheduler.ts` | Defina `true` para permitir que o agendador remova automaticamente os proxies após repetidas falhas consecutivas. | | `PROXY_AUTO_REMOVE_AFTER` | `3` | `src/lib/proxyHealth/scheduler.ts` | Falhas consecutivas antes de o agendador remover automaticamente um proxy (quando `PROXY_AUTO_REMOVE=true`). | | `PROXY_AUTO_DISABLE` | `false` | `src/lib/proxyHealth/scheduler.ts` | Defina `true` para permitir que o agendador desative suavemente (estado `dead`, nunca eliminado) um proxy após repetidas falhas consecutivas, em vez de o remover. Alternativa não destrutiva ao `PROXY_AUTO_REMOVE`: o proxy sai da resolução pool/rotation imediatamente (o filtro de estado ativo utilizado pela resolução do conjunto de âmbito já o elimina) e é automaticamente reativado assim que começa a passar novamente pelos testes. Partilha o limite `PROXY_AUTO_REMOVE_AFTER`. Se ambos os sinalizadores forem `true`, `PROXY_AUTO_REMOVE` ganha. | | `PROXY_HEALTH_PASSIVE_SKIP` | `false` | `src/lib/proxyHealth/scheduler.ts` | Opt-in skip passivo: quando `true`, o agendador ignora a investigação ao vivo para um endpoint cujo tráfego de produção recente já o comprova (pelo menos um sucesso e nenhuma falha de proxy atribuída na janela, exatamente um fornecedor observado). Desativado por defeito: todo o proxy é investigado. | | `PROXY_PASSIVE_WINDOW_MS` | `300000` | `src/lib/proxyHealth/passiveVerdict.ts` | Janela em ms de tráfego de produção que o salto passivo analisa (limitado `60000..599999`). Inferior ao intervalo de varrimento de 10 minutos, pelo que uma falha recente domina em vez de ser diluída. | | `OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | Permita que os fluxos de validação OAuth e do fornecedor ignorem um proxy fixado e se liguem diretamente quando as pré-verificações de acessibilidade do proxy falham. A precedência efetiva é Feature Flags DB override > env var > default. | | `RATE_LIMIT_MAX_WAIT_MS` | `30000` (30 anos) | `src/lib/resilience/settings.ts` | Predefinição** fila-espera** orçamento: quanto tempo um pedido pode esperar por um slot do fornecedor e ficar na fila antes de ser rejeitado, nunca chegando ao upstream. O temporizador é limpo quando o trabalho começa a ser executado — execução é limitada separadamente por `RATE_LIMIT_EXECUTION_MAX_WAIT_MS`. O Env define apenas o padrão: um `resilienceSettings.requestQueue.maxWaitMs` persistente e, em seguida, um `rateLimitOverrides.maxWaitMs` por ligação, cada um vencendo-o. | | `RATE_LIMIT_EXECUTION_MAX_WAIT_MS` | `600000` (10 min) | `open-sse/services/rateLimitManager.ts` | Limite de quanto tempo um pedido admitido pode permanecer em execução antes que a sua reserva de limite de taxa expire — desacoplada do orçamento de espera de fila para que o início lento da pesquisa em gateways não incrementais não expire (#12027). | | `RATE_LIMIT_MAX_QUEUE_DEPTH` | `0` (desativado) | `open-sse/services/rateLimitManager.ts` | Limite de admissão na fila: rejeitar com 429 `queue_full` quando este número de pedidos já se encontra na fila. `0` = ilimitado (padrão). | | `RATE_LIMIT_AUTO_ENABLE` | _(desativado)_ | `open-sse/services/rateLimitManager.ts` | Força a rede de segurança de limite de taxa de ativação automática on/off independentemente da configuração persistente do Dashboard (`resilienceSettings.requestQueue.autoEnableApiKeyProviders`). Aceita `true`/`1`/`on` para forçar, `false`/`0`/`off` para forçar o encerramento. Quando ativas (padrão), as ligações de chave API ativas são automaticamente protegidas pelo limite de taxa. A definição de `rateLimitProtection: false` por ligação desativa a proteção explícita, mas não exclui esta rede de segurança; definir este env var como `false` é o mecanismo global para executar ligações de chaves API sem filas de limite de taxa. | | `PROVIDER_COOLDOWN_ENABLED` | _(desativar → )_ | `open-sse/services/providerCooldownTracker.ts` | Acompanhamento de arrefecimento provider/connection de solicitação cruzada global opcional. OFF por defeito (sobrepõe o arrefecimento da ligação/disjuntor do fornecedor). Aceita `true`/`1`/`on` para habilitar. | | `PROVIDER_COOLDOWN_MIN_MS` | `5000` | `open-sse/services/providerCooldownTracker.ts` | Tempo de espera mínimo (ms) antes de um provider/connection com falha ser tentado novamente. Dimensionado exponencialmente com falhas consecutivas. Utilizado apenas quando `PROVIDER_COOLDOWN_ENABLED`. | | `PROVIDER_COOLDOWN_MAX_MS` | `300000` (5 min) | `open-sse/services/providerCooldownTracker.ts` | Limite máximo de arrefecimento (ms) antes de um provider/connection com falha ser repetido independentemente. Utilizado apenas quando `PROVIDER_COOLDOWN_ENABLED`. | | `STREAM_RECOVERY_ENABLED` | _(desativar → )_ | `src/lib/resilience/settings.ts` (semente) → `open-sse/services/streamRecovery.ts` (lógica) | **O quê:** recuperação transparente de fluxos upstream truncados (porta de código de claude livre). Mantém a janela SSE de abertura até `STREAM_RECOVERY.HOLDBACK_MS` (750 ms) para que um corte — _pré-commit_ que ocorre antes de qualquer byte atingir o cliente — seja reaberto e tentado novamente de forma invisível.** Quando ativar:** flaky/upstreams que frequentemente trunca 0 byte no início do fluxo; deixe OFF se não puder pagar até 750 ms de tempo adicional para o primeiro token em cada fluxo. Aceita `true`/`1`/`on`. Semeia a configuração de resiliência persistente; a configuração do painel vence depois de definida. | | `STREAM_RECOVERY_MIDSTREAM_ENABLED` | _(desativar → )_ | `src/lib/resilience/settings.ts` (semente) → `open-sse/services/streamRecovery.ts` (lógica) | **O quê:** continuação do mid-stream (Fase 4.4) — após um truncamento _pós-commit_ (bytes já chegaram ao cliente), solicite novamente com o texto parcial como pré-preenchimento do assistente e costure o sufixo em falta. Apenas fluxos de texto simples compatíveis com OpenAI; nunca dispara com uma chamada de ferramenta em voo.** Quando ativar:** longas gerações que são cortadas a meio da resposta e aceita que a cauda recuperada chegue como uma explosão, em vez de ficha a ficha. Independentemente do `STREAM_RECOVERY_ENABLED` (perfil de risco diferente). Aceita `true`/`1`/`on`. | | `STREAM_THROUGHPUT_WATCHDOG_ENABLED` | _(desativar → )_ | `src/lib/resilience/settings.ts` → `open-sse/services/throughputWatchdog.ts` | Watchdog de saída útil de fluxo ativo opcional. Deteta fluxos que continuam a enviar pedaços, mas permanecem abaixo da taxa de saída do assistente configurada; pulsações, eventos de utilização, deltas vazios e fases tool/reasoning não se disfarçam de progresso. Separado dos tempos limite de inatividade e dos prazos rígidos. Propaga apenas o padrão: um booleano guardado em `resilienceSettings` (Dashboard → Settings → Resilience) tem precedência. | | `STREAM_THROUGHPUT_WATCHDOG_WARMUP_MS` | `30000` | `src/lib/resilience/settings/normalize.ts` | Período de carência antes da avaliação do rendimento, limitado a 0–600.000 ms. | | `STREAM_THROUGHPUT_WATCHDOG_WINDOW_MS` | `30000` | `src/lib/resilience/settings/normalize.ts` | Janela contínua de saída útil, limitada a 1.000–600.000 ms; é necessária uma janela completa antes de abortar. | | `STREAM_THROUGHPUT_WATCHDOG_MIN_BYTES_PER_SECOND` | `4` | `src/lib/resilience/settings/normalize.ts` | Taxa mínima de bytes de saída do assistente UTF-8 (proxy de token conservador), limitada a 1–1000000. | | `STREAM_THROUGHPUT_WATCHDOG_MIN_USEFUL_BYTES` | `1` | `src/lib/resilience/settings/normalize.ts` | Amostra mínima de saída útil diferente de zero considerada mensurável, limitada a 1–1.000.000 bytes. | | `HEALTHCHECK_STAGGER_MS` | `3000` | `src/lib/tokenHealthCheck.ts` | Intervalo escalonado (ms) entre verificações de integridade do token do fornecedor na inicialização. | | `HEALTHCHECK_JITTER_MIN_MS` | `500` | `src/lib/tokenHealthCheck.ts` | Jitter aleatório mínimo (ms) adicionado ao `HEALTHCHECK_STAGGER_MS` entre as verificações de integridade do token do fornecedor, para evitar overflows (problema nº 1220). | | `HEALTHCHECK_JITTER_MAX_MS` | `5000` | `src/lib/tokenHealthCheck.ts` | Tremulação aleatória máxima (ms) adicionada sobre `HEALTHCHECK_STAGGER_MS` entre verificações de integridade do token do fornecedor, para evitar intermitências (problema nº 1220). | | `HEALTHCHECK_BATCH_SIZE` | `20` | `src/lib/tokenHealthCheck.ts` | Tamanho do lote de verificação simultânea para a varredura de verificação de integridade do token de inicialização; valores mais elevados verificam mais ligações em paralelo, valores mais baixos reduzem a carga intermitente (Problema nº 7875, regressão de nº 7719). | | `REQUEST_RETRY` | `2` | `src/sse/services/cooldownAwareRetry.ts` | Número de novas tentativas automáticas em respostas de arrefecimento no âmbito do modelo antes de devolver o erro ao cliente. | | `MAX_RETRY_INTERVAL_SEC` | `30` | `src/sse/services/cooldownAwareRetry.ts` | Intervalo máximo de espera (segundos) entre novas tentativas de arrefecimento. Limitada por este valor, independentemente do `Retry-After` upstream. | | `HEADROOM_URL` | `http://localhost:8787` | `src/lib/headroom/detect.ts` | Proxy de proteção de token de headroom URL. O ciclo de vida do painel (`api/headroom/*`) gera um `headroom-ai` CLI local em loopback por defeito; substitua apenas para apontar para um proxy secundário Docker externo. | ### Constantes de ajuste de recuperação de caudal O comportamento de retenção de recuperação é ajustado por constantes codificadas em `open-sse/config/constants.ts` (`STREAM_RECOVERY`), mostradas aqui para referência — alterá-las requer uma edição de código, não uma var env: - `STREAM_RECOVERY.HOLDBACK_MS = 750` — quanto tempo é mantida a janela SSE de abertura para que um truncamento antecipado possa ser repetido antes de qualquer byte ser confirmado no cliente. - tampa rígida `STREAM_RECOVERY.BUFFER_MAX_BYTES = 65536` — na janela retida; commit (libertar passagem + ) assim que se acumularem tantos bytes, independentemente do temporizador. - `STREAM_RECOVERY.EARLY_RETRY_MAX = 4` — max reabre transparente do fluxo upstream enquanto o holdback ainda não foi confirmado. > **Limite de taxa de janela deslizante por fornecedor (sem env var):** o _fallback_ de limite de taxa de janela deslizante por fornecedor portado pela FCC existe no código (`open-sse/services/providerDefaultRateLimit.ts`, ligado através `open-sse/services/rateLimitManager.ts`), mas é fornecido com um** mapa padrão vazio** e tem** nenhum operador env var** hoje — ele é habilitado apenas através de um gancho de teste/edição de código. Não está intencionalmente listado na tabela acima. O limitador de relé `(token, IP)` que _tem_ um botão é `RELAY_IP_PER_MINUTE` (§3 Rede e Portas). --- ## 22. Depuração > [!CAUTION] > Estas variáveis produzem** saída detalhada** e pode divulgar dados confidenciais.** Nunca habilite na produção.** | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CURSOR_DEBUG` | _(desativado)_ | `open-sse/executors/cursor.ts` | Defina `1` para ativar os registos detalhados do executor Cursor (pedaços SSE descodificados, etc.). | | `CURSOR_STREAM_DEBUG` | _(desativado)_ | `open-sse/executors/cursor.ts` | Alias compatível com versões anteriores de `CURSOR_DEBUG`. | | `CURSOR_DUMP_FILE` | _(desativado)_ | `open-sse/executors/cursor.ts` | Caminho de ficheiro opcional que recebe pedaços Cursor descodificados em bruto quando `CURSOR_DEBUG=1`. | | `CURSOR_STREAM_TIMEOUT_MS` | `300000` | `open-sse/executors/cursor.ts` | Tempo limite de inatividade do fluxo (ms) para o executor Cursor. | | `CURSOR_KV_GRACE_MS` | `2000` | `open-sse/executors/cursor.ts` | Janela de tolerância (ms) após um terminador suave do compositor kv_after_text quando os bytes permanecem em buffer — fornece um tempo de chamada da ferramenta exec_mcp final para completar o seu quadro. | | `CURSOR_TOOL_DIRECTIVE` | habilitado (`!== "0"`) | `open-sse/executors/cursor.ts` | Diretiva de confirmação de ferramentas que faz com que composer-2. 5 emita chamadas de ferramentas de forma fiável. Defina `0` para desativar. | | `OMNIROUTE_SYSTEM_INSTRUCTION_APPEND` | _(desativado)_ | `open-sse/translator/request/claude-to-openai.ts`, `open-sse/translator/response/openai-to-claude.ts` | Texto de prompt do sistema definido pelo operador anexado à mensagem do sistema tradução AFTER (injeção pós-tradução), alcançando os caminhos codex/Responses e `/v1/messages`. Também utilizado como prefixo de diretiva retirado dos blocos de preâmbulo do sistema ecoados. Deixe sem definir para desativar. | | `OMNIROUTE_STRIP_SYSTEM_PREAMBLE` | `0` (desligado) | `open-sse/translator/response/openai-to-claude.ts`, `open-sse/utils/directivePreambleStripper.ts` | Defina como `1` para remover os blocos de preâmbulo do prompt do sistema ecoados desde o início de um fluxo openai → claude. Desativada por defeito — a heurística tem o formato da prosa inglesa e altera a carga útil da resposta, pelo que uma resposta que abre legitimamente com tal secção a perderia. | | `CURSOR_IMAGE_FETCH_TIMEOUT_MS` | `15000` | `open-sse/utils/cursorImages.ts` | Tempo limite de pesquisa por imagem (ms) para entrada remota `image_url` vision. | | `CURSOR_STATE_DB_PATH` | _(sondado)_ | `open-sse/utils/cursorVersionDetector.ts` | Substitua a pesquisa Cursor IDE state DB utilizada para a deteção da versão IDE. | | `CURSOR_AGENT_CLI_VERSION` | _(detectar/fixar)_ | `open-sse/utils/cursorAgentCliVersion.ts` | ID de compilação do agente CLI (`YYYY.MM.DD-`) para `x-cursor-client-version: cli-…` no Agent Run. | | `CURSOR_AGENT_BIN` | _(desativado)_ | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Caminho para o binário do agente Cursor utilizado para a geração de imagem. Não definido, o manipulador utiliza `providerSpecificData.agentBin` e depois PATH. | | `CURSOR_IMG_TIMEOUT_MS` | `210000` | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Relógio de parede por imagem (ms) para trabalhos de imagem Cursor Agent. | | `CURSOR_IMG_MAX_CONCURRENT` | `2` | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Porta de simultaneidade de assento partilhado para trabalhos de imagem Cursor. | | `CURSOR_IMG_MODEL` | pedido / `auto` | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Substitua Cursor CLI `--model` para trabalhos de imagem. | | `UC_IMAGE_POLL_INTERVAL_MS` | `2000` | `open-sse/handlers/imageGeneration/providers/ucImage.ts` | UC (uncensored.com) cadência de pesquisa de resultados de geração de imagens (ms). | | `UC_IMAGE_POLL_TIMEOUT_MS` | `60000` | `open-sse/handlers/imageGeneration/providers/ucImage.ts` | relógio de parede de pesquisa de resultados de geração de imagem UC (ms). | | `UC_VIDEO_POLL_INTERVAL_MS` | `3000` | `open-sse/handlers/videoGeneration/providers/ucVideo.ts` | UC (uncensored.com) cadência de pesquisa de resultados de geração de vídeo (ms). | | `UC_VIDEO_POLL_TIMEOUT_MS` | `300000` | `open-sse/handlers/videoGeneration/providers/ucVideo.ts` | relógio de parede UC video-gen result-poll (ms). | | `CURSOR_DATA_DIR` | _(sondado)_ | `open-sse/utils/cursorAgentCliVersion.ts` | Substituir o diretório de dados CLI do agente Cursor (`…/versions/`); mesma var que o agente oficial utiliza. | | `CURSOR_TOKEN` | _(desativado)_ | `scripts/ad-hoc/cursor-tap.cjs` | Token de portador Cursor direto utilizado pelas ferramentas do programador. | | `OMNIROUTE_LOG_REQUEST_SHAPE` | desativado (aceitar via `"1"`) | `src/app/api/v1/chat/completions/route.ts` | Registe marcadores content-type/length para grandes cargas de chat quando `"1"` estiver definido. Desativado por predefinição para reduzir o ruído do registo. | | `DEBUG_RESPONSES_SSE_TO_JSON` | _(desativado)_ | `open-sse/handlers/responseTranslator.ts` | Configure `true` para registar respostas API SSE→JSON detalhes de tradução. | | `DEBUG_CLAUDE_NONSTREAM` | _(desativado)_ | `open-sse/handlers/responseTranslator.ts` | Configure `true` para apresentar pedaços textContent vazios no caminho de tradução da resposta Claude (apenas depuração). | | `NEXT_PUBLIC_OMNIROUTE_E2E_MODE` | _(desativado)_ | equipamento de teste E2E | Defina `true` para ativar o modo de teste E2E (autenticação relaxada, ganchos de teste). | --- ## 23. Integração GitHub Permita que os utilizadores comuniquem problemas diretamente no Painel. | Variável | Predefinição | Arquivo de origem | Descrição | | --------------------- | -------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GITHUB_ISSUES_REPO` | _(desativado)_ | `src/app/api/v1/issues/report/route.ts` | Repositório em formato `owner/repo`. | | `GITHUB_ISSUES_TOKEN` | _(desativado)_ | `src/app/api/v1/issues/report/route.ts` | Token de acesso pessoal GitHub com âmbito `issues:write`. | | `GITHUB_TOKEN` | _(desativado)_ | auxiliares de triagem de problemas/agentes de cloud | Token de acesso GitHub genérico utilizado como substituto do `GITHUB_ISSUES_TOKEN` e consumido pelos auxiliares de agente de cloud em `src/lib/cloudAgent/*`. | --- ## Renderizar Keep-Alive de nível gratuito O Render desativa um serviço Web gratuito após cerca de 15 minutos sem tráfego de entrada. O iniciador independente (`scripts/dev/run-standalone.mjs`, que a imagem Docker executa) pode executar ping no URL público do próprio serviço para evitar isto. Não faz nada, a menos que um URL público esteja disponível e regista apenas quando o estado muda. | Variável | Predefinição | Descrição | | ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `SELF_PING_ENABLED` | ativado quando um URL é definido | `0`, `false`, `off` ou `no` desliga o pinger. Utilize-o em planos de renderização pagos, onde nada falha. | | `SELF_PING_URL` | `RENDER_EXTERNAL_URL` | Base URL para fazer ping. A renderização define o próprio `RENDER_EXTERNAL_URL` em todos os planos, pelo que o pinger está lá por defeito. | | `SELF_PING_PATH` | `/api/monitoring/health` | Caminho nesse URL. Deve começar por `/`; qualquer outra coisa desativa o pinger com um aviso. | | `SELF_PING_INTERVAL_SECONDS` | `180` | Segundos entre pings, após um primeiro ping 60 segundos depois. Valores abaixo `30` voltam a `180`. | Um serviço mantido ativo durante um mês inteiro utiliza cerca de 744 horas de instância, por isso compare-o com o limite atual de nível gratuito do Render. ## Cenários de implantação Para orientação de backend de retransmissão SRE (comportamento ts/bifrost/auto, posicionamento 9router vs CLIProxyAPI e estratégia de fallback de alto rendimento), consulte [Estratégia de backend de retransmissão](/docs/reference/RELAY_BACKEND_STRATEGY.md). ### Desenvolvimento Local Mínimo ```bash JWT_SECRET=$(openssl rand -base64 48) API_KEY_SECRET=$(openssl rand -hex 32) INITIAL_PASSWORD=dev123 PORT=20128 NODE_ENV=development ``` ### Produção Docker ```bash JWT_SECRET= API_KEY_SECRET= INITIAL_PASSWORD= STORAGE_ENCRYPTION_KEY= DATA_DIR=/data PORT=20128 API_PORT=20129 NODE_ENV=production AUTH_COOKIE_SECURE=true REQUIRE_API_KEY=true NEXT_PUBLIC_BASE_URL=https://omniroute.example.com BASE_URL=http://localhost:20128 OMNIROUTE_MEMORY_MB=8192 CORS_ORIGIN=https://your-frontend.example.com ``` ### Air Gapped/ CI ```bash JWT_SECRET=test-jwt-secret-for-ci API_KEY_SECRET=test-api-key-secret-for-ci INITIAL_PASSWORD=testpass NODE_ENV=production OMNIROUTE_DISABLE_BACKGROUND_SERVICES=true APP_LOG_TO_FILE=false ``` ### VPS com proxy reverso (nginx + Cloudflare) ```bash JWT_SECRET= API_KEY_SECRET= STORAGE_ENCRYPTION_KEY= PORT=20128 AUTH_COOKIE_SECURE=true REQUIRE_API_KEY=true NEXT_PUBLIC_BASE_URL=https://omniroute.example.com BASE_URL=http://127.0.0.1:20128 CORS_ORIGIN=https://omniroute.example.com ENABLE_TLS_FINGERPRINT=true CLI_COMPAT_ALL=1 ``` --- ## 24. Sandbox de habilidades (v3.8.0 +) Limites e botões de segurança aplicados quando a estrutura Skills (`src/lib/skills/`) executa automatizações definidas pelo utilizador num ambiente de área restrita. | Variável | Predefinição | Arquivo de origem | Descrição | | -------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SKILLS_SANDBOX_TIMEOUT_MS` | `10000` (10 s) | `src/lib/skills/builtins.ts` | Tempo limite do relógio de parede por execução para o código de habilidade em área restrita. Tampa rígida; qualquer coisa a mais é morta. | | `SKILLS_EXECUTION_TIMEOUT_MS` | _(volta para `SKILLS_SANDBOX_TIMEOUT_MS`)_ | `src/lib/skills/` | Tempo limite de orquestração de competências de alto nível. Defina um valor superior a `SKILLS_SANDBOX_TIMEOUT_MS` para permitir fluxos de trabalho de várias etapas. | | `SKILLS_MAX_FILE_BYTES` | `1048576` (1 MB) | `src/lib/skills/builtins.ts` | Máximo de bytes que uma habilidade pode ler de qualquer ficheiro numa área restrita. | | `SKILLS_MAX_HTTP_RESPONSE_BYTES` | `256000` (250 KB) | `src/lib/skills/builtins.ts` | Máximo de bytes capturados de qualquer resposta HTTP única dentro de uma habilidade. | | `SKILLS_MAX_SANDBOX_OUTPUT_CHARS` | `100000` | `src/lib/skills/builtins.ts` | Limite máximo para caracteres stdout/stderr devolvidos de uma invocação de sandbox. | | `SKILLS_SANDBOX_NETWORK_ENABLED` | `false` | `src/lib/skills/builtins.ts` | Defina `1`/`true` para permitir a rede de saída a partir do interior da sandbox. O padrão é** isolado** para segurança. Ignorado pelo tempo de execução `agent-sandbox` : isolamento de rede, o sistema de ficheiros raiz de leitura apenas e os limites CPU/memory provêm do `SandboxTemplate` do operador. | | `SKILLS_ALLOWED_SANDBOX_IMAGES` | _(vazio)_ | `src/lib/skills/builtins.ts` | Lista de permissões separadas por vírgulas de imagens de contentores permitidas para execução de sandbox. Vazio significa apenas padrão integrado. | | `SKILLS_SANDBOX_DOCKER_IMAGE` | _(padrão integrado)_ | `src/lib/skills/` | Imagem de contentor utilizada ao gerar uma sandbox baseada em Docker. Substitua para fixar uma imagem de base reforçada personalizada. | | `SKILLS_SANDBOX_RUNTIME` | `auto` | `src/lib/skills/sandbox.ts`, `src/lib/skills/containerProvider.ts` | Tempo de execução do contentor para sandbox de habilidades: `auto` \| `docker` \| `apple` \| `wsl` \| `orbstack` \| `podman` \| `agent-sandbox`. `auto` escolhe o melhor tempo de execução instalado por host OS (Apple Container/OrbStack em macOS, WSL Container em Windows, Podman em Linux), voltando a Docker. `agent-sandbox` (pools quentes remotos do Kubernetes) é apenas opcional e nunca é detectado automaticamente. | | `SKILLS_AGENT_SANDBOX_POOLS` | _(vazio)_ | `src/lib/skills/agentSandboxProvider.ts` | Pares `image=pool`, separados por vírgula: que `SandboxWarmPool` transmitem cada imagem de sandbox quando `SKILLS_SANDBOX_RUNTIME=agent-sandbox`. | | `SKILLS_AGENT_SANDBOX_POOL` | _(vazio)_ | `src/lib/skills/agentSandboxProvider.ts` | Pool quente substituto para imagens não listadas em `SKILLS_AGENT_SANDBOX_POOLS`. Uma execução falha (sem fallback para contentores locais) quando nenhuma delas é resolvida. | | `SKILLS_AGENT_SANDBOX_NAMESPACE` | `default` | `src/lib/skills/agentSandboxProvider.ts` | Namespace que contém os pools quentes; um `SandboxClaim` por execução é criado e eliminado aqui. | | `SKILLS_AGENT_SANDBOX_KUBECONFIG` | _(kubectl padrão)_ | `src/lib/skills/agentSandboxProvider.ts` | Kubeconfig para o tempo de execução do agente-sandbox. Necessita apenas de sandboxclaims create/get/list/watch/delete, pods get, pods/exec create no namespace. | | `SKILLS_AGENT_SANDBOX_KUBECTL` | `kubectl` | `src/lib/skills/agentSandboxProvider.ts` | Binário kubectl utilizado pelo tempo de execução do agente-sandbox. | | `SKILLS_AGENT_SANDBOX_CONTAINER` | `main` | `src/lib/skills/agentSandboxProvider.ts` | Nome do contentor dentro do pod sandbox em que os comandos são executados. | | `SKILLS_AGENT_SANDBOX_CLAIM_TIMEOUT_S` | `60` | `src/lib/skills/agentSandboxProvider.ts` | Segundos de espera para que uma reclamação fique pronta (máximo de 600). A reclamação será eliminada se isso nunca acontecer. | > [!CAUTION] > A ativação `SKILLS_SANDBOX_NETWORK_ENABLED=true` abre um caminho de saída do código de habilidade arbitrário. Combine com `OUTBOUND_SSRF_GUARD_ENABLED=true` e uma política estrita `CORS_ORIGIN`/proxy em implementações partilhadas. --- ## 25. Quotas dos Provedores, Túneis, Cópias de Segurança e Diversos Aspetos do Runtime Invalidação alternativa da afinidade de sessão no Redis (apenas opcional; o comportamento predefinido do SQLite permanece inalterado): Cada armazenamento de afinidade do Redis admite, no máximo, 8 operações pendentes; quando a capacidade é atingida, as chamadas utilizam imediatamente o SQLite, e os slots permanecem ocupados até a operação subjacente do Redis terminar, mesmo depois do prazo de 100 ms definido para o chamador. - R1. Qualquer resposta do Redis entregue atempadamente para uma operação de sessão é autoritativa: mutações aceites, operações CAS rejeitadas/perdidas, chaves em falta, eliminações de chaves inexistentes e acertos ou falhas de expulsão limpam de forma síncrona a linha de fallback local dessa sessão, sem qualquer `await` entre a resposta e a limpeza. A limpeza é segura (no pior caso, ocorre uma nova seleção durante uma falha posterior); uma linha obsoleta não é. - R2. Uma operação que exceda o tempo limite ou gere um erro e escreva um fallback local regista exatamente o que escreveu como bytes serializados. Se o comando do Redis for concluído tardiamente, uma operação síncrona de comparação e eliminação no SQLite limpa apenas essa linha idêntica em bytes, nunca com base numa correspondência de conta ou ligação. Uma escrita mais recente durante a falha é preservada. - R3. A expulsão remove sempre o pin local da conta que falhou, incluindo durante uma falha; o processamento da respetiva resposta segue depois R1/R2. Um Redis saudável nunca escreve pins locais: não existe qualquer espelho ou registo de ordenação, e as instâncias podem divergir durante uma falha. Endpoints de quotas dos provedores, túneis de rede (Tailscale, Ngrok, proxy de depuração MITM), o conjunto de egress do 1Proxy, cópias de segurança da base de dados e pequenas substituições por funcionalidade referenciadas pela camada de execução ou pelos scripts. | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_SESSION_AFFINITY_STORE` | `sqlite` | `src/lib/db/sessionAffinity/storeFactory.ts` | Backend de afinidade entre sessão e conta. Apenas `redis` juntamente com `REDIS_URL` configurado permite a partilha; valores não definidos/desconhecidos ou a configuração Redis em falta utilizam SQLite. Requer `sessionAffinityTtlMs` positivo. O encaminhamento Redis armazena a identidade com hash da conta de utilização, juntamente com o ID da ligação; o encaminhamento SQLite predefinido mantém a forma JSON legada de quatro campos. Faz corresponder a identidade dentro do conjunto local elegível antes do ID. Utiliza o `REDIS_KEY_PREFIX` do cliente partilhado, valores JSON e TTL `PX`; as mutações comparam o valor observado exato. As respostas Redis saudáveis invalidam o fallback local de indisponibilidade, e uma resposta tardia pode limpar apenas a linha de fallback serializada exata escrita por essa operação cujo tempo limite foi excedido. As associações pré-obtidas são revalidadas no momento da utilização. Os erros Redis, os timeouts ou a saturação da admissão recorrem ao SQLite com avisos limitados (limite de 100 ms por chamada ao armazenamento); os resultados sem correspondência bem-sucedidos do Redis não leem o shadow. Não partilha a persistência de combinações, as associações de turnos nativas do Codex, a concorrência de contas, os bloqueios nem os limites de gastos. | | `REDIS_URL` | `redis://localhost:6379` | `src/shared/utils/rateLimiter.ts` | String de ligação Redis para o backend do limitador de taxa. | | `ALIBABA_CODING_PLAN_HOST` | _(anfitrião de produção)_ | `open-sse/services/bailianQuotaFetcher.ts` | Substituição do anfitrião utilizado para obter as quotas do plano de programação Alibaba Bailian. | | `ALIBABA_CODING_PLAN_QUOTA_URL` | derivado do anfitrião | `open-sse/services/bailianQuotaFetcher.ts` | Substituição do URL completo das quotas do Alibaba Bailian. | | `QWEN_CLOUD_COOKIE` | _(não definido)_ | `open-sse/services/qwenTokenPlanQuotaFetcher.ts` | Cookie de sessão da consola para o gateway de quotas do Token Plan pessoal do Qwen Cloud / Model Studio (a chave API de inferência não consegue lê-lo). Copie o cabeçalho de pedido `Cookie` completo — contém `login_qwencloud_ticket` — de qualquer chamada `api.json` para `cs-data.qwencloud.com` em home.qwencloud.com › Faturação › Subscrição (F12 › Rede). Sensível e associado à sessão; prefira o campo `qwenCloudCookie` por ligação no Dashboard. | | `QWEN_CLOUD_SEC_TOKEN` | _(não definido)_ | `open-sse/services/qwenTokenPlanQuotaFetcher.ts` | Substituição manual de `sec_token` para o gateway da consola do Token Plan. Sensível; quando não definido, o fetcher resolve-o a partir do HTML do dashboard utilizando o cookie. | | `QWEN_TOKEN_PLAN_HOST` | `https://cs-data.qwencloud.com` | `open-sse/services/qwenTokenPlanQuotaFetcher.ts` | Substituição do anfitrião do gateway para o obtentor de quota do Token Plan pessoal (por exemplo, `bailian-singapore-cs.alibabacloud.com` para a consola do Model Studio). | | `QWEN_TOKEN_PLAN_DASHBOARD_URL` | `https://home.qwencloud.com/` | `open-sse/services/qwenTokenPlanQuotaFetcher.ts` | URL do painel utilizada para obter `sec_token` a partir do HTML da sessão iniciada. | | `XIAOMI_MIMO_CONSOLE_COOKIE` | _(unset)_ | `open-sse/services/usage/xiaomi-mimo.ts` | Cookie da sessão da consola para a API de quota do Token Plan do Xiaomi MiMo (`platform.xiaomimimo.com/api/v1/tokenPlan/usage` + `tokenPlan/detail` — a chave da API de inferência não o consegue ler). Copie o cabeçalho de pedido `Cookie` completo — contém `api-platform_serviceToken` e `userId` — de qualquer pedido para `platform.xiaomimimo.com` na página do Token Plan (F12 › Rede). Sensível e associado à sessão; prefira o campo Dashboard `xiaomiMimoConsoleCookie` por ligação. | | `XIAOMI_MIMO_MONTHLY_TOKEN_LIMIT` | `4100000000` | `open-sse/services/usage/xiaomi-mimo.ts` | Orçamento mensal (Créditos) para o fallback do Xiaomi MiMo monitorizado pelo OmniRoute, utilizado quando não está configurado nenhum cookie da consola. O valor predefinido é o do escalão Lite, 4,1B; defina-o como os Créditos do plano (Standard 11B / Pro 38B / Max 82B). Uma substituição `providerSpecificData.monthlyTokenLimit` por ligação tem precedência sobre esta variável de ambiente. | | `ALIBABA_FREE_TIER_VISION_FE_PATH` | `/costing-balance/free-quota-image-video` | `open-sse/services/alibabaFreeTierQuotaFetcher.ts` | Substituição do caminho do front-end da consola para obter a quota gratuita de visão multimédia do Alibaba Model Studio. | | `ALIBABA_FREE_TIER_MULTIMODAL_FE_PATH` | `/costing-balance/free-quota-multimodal` | `open-sse/services/alibabaFreeTierQuotaFetcher.ts` | Substituição do caminho do front-end da consola para obter a quota multimodal gratuita do Alibaba Model Studio. | | `ALIBABA_FREE_TIER_AUDIO_FE_PATH` | `/costing-balance/free-quota-audio` | `open-sse/services/alibabaFreeTierQuotaFetcher.ts` | Substituição do caminho do front-end da consola para obter a quota de áudio gratuita do Alibaba Model Studio. | | `ALIBABA_FREE_TIER_ALLOWLIST_PATH` | _(unset)_ | `open-sse/services/alibabaFreeTierAllowlist.ts` | Caminho opcional para uma substituição JSON local da lista de permissões incorporada de modelos de texto do escalão gratuito da Alibaba. Recorre a `$DATA_DIR/alibaba-free-tier-allowlist.json` e, em seguida, a `config/alibaba-free-tier-allowlist.json`. | | `CONTEXT_RESERVE_TOKENS` | `1024` | `open-sse/services/contextManager.ts` | Tokens reservados para o resultado da conclusão ao calcular os orçamentos do prompt. | | `CONTEXT_KEEP_LATEST_IMAGES` | `2` | `open-sse/services/contextManager.ts` | Número de imagens inline mais recentes a manter ao remover imagens mais antigas para ajustar à janela de contexto (#8560). | | `MODEL_ALIAS_COMPAT_ENABLED` | enabled | `open-sse/services/model.ts` | Ativa ou desativa a camada de compatibilidade com aliases de modelos legados utilizada por clientes mais antigos. | | `OMNIROUTE_EMERGENCY_FALLBACK` | enabled | `open-sse/services/emergencyFallback.ts` | Defina como `false` (ou `0`) para desativar o fallback de emergência por esgotamento do orçamento, que redireciona os pedidos falhados para o modelo gratuito `nvidia`/`nvidia/nemotron-3.5-super-vl-120b-a12b`. A precedência efetiva é substituição na base de dados de Feature Flags > variável de ambiente > predefinição; se não estiver disponível, o serviço recorre ao valor bruto da variável de ambiente. | | `COMMAND_CODE_CALLBACK_PORT` | _(unset)_ | `src/app/api/providers/command-code/auth/shared.ts` | Porta local utilizada para callbacks ao estilo OAuth pelo auxiliar CLI do Command Code. | | `COMMAND_CODE_VERSION` | `0.33.2` | `open-sse/executors/commandCode.ts` | Valor enviado no cabeçalho `x-command-code-version` para o upstream do Command Code. Substitua-o para atualizar a versão da CLI. | | `COMMANDCODE_API_URL` | `https://api.commandcode.ai` | `open-sse/services/usage/command-code.ts` | URL base do upstream de utilização/cota do Command Code utilizado pela telemetria do leitor de quotas do smartphone. Substitua-a por uma API do Command Code alojada localmente ou alternativa. | | `MITM_LOCAL_PORT` | `443` | `src/mitm/server.cjs` | Porta de ligação local do proxy de depuração MITM. | | `MITM_DISABLE_TLS_VERIFY` | `0` | `src/mitm/server.cjs` | Defina `1` para desativar a verificação TLS a montante (apenas para desenvolvimento). | | `MITM_IDLE_TIMEOUT_MS` | `60000` | `src/mitm/socketTimeouts.ts`, `src/mitm/server.cjs` | Tempo limite de inatividade do socket (ms) para ligações através do proxy; os sockets inativos que ultrapassem este valor são terminados para evitar fugas de túneis parcialmente abertos. | | `BRIDGE_PORT` | `20129` | `bin/antigravity-bridge.mjs` | Porta em que a ponte MITM do Antigravity aguarda ligações. | | `ROUTER_URL` | `http://127.0.0.1:20128/v1/antigravity` | `bin/antigravity-bridge.mjs` | Endpoint do router para o qual a ponte reencaminha o tráfego do Antigravity. | | `CERT_DIR` | `/mitm` | `bin/antigravity-bridge.mjs` | Substitui o diretório a partir do qual a ponte lê o respetivo material TLS. O modelo de certificados é selecionado tal como no servidor AgentBridge: `server.crt`/`server.key` para uma instalação legada com certificado leaf; caso contrário, `ca.crt`/`ca.key` (CA raiz, um certificado leaf por anfitrião intercetado; forçado por `MITM_ROOT_CA_ENABLED=true`). A ponte termina no arranque se os ficheiros correspondentes ao modelo ativo estiverem em falta. | | `MITM_VERBOSE` | `1` | `src/mitm/server.cjs`, `src/mitm/_internal/bypass.cjs` | Verbosidade dos registos das decisões de encaminhamento: `0` silencia os registos; valores superiores registam mais decisões de bypass/encaminhamento. | | `MITM_ROOT_CA_ENABLED` | `false` | `src/mitm/manager.ts` | Defina `true` para ativar o modelo de CA raiz + certificados leaf por anfitrião (#6684). As instalações novas obtêm-no automaticamente; as instalações com um certificado leaf legado previamente considerado fidedigno mantêm o certificado legado com SAN fixo, a menos que optem por este modelo. | | `MITM_CERT_MODE` | `legacy` | `src/mitm/manager.ts`, `src/mitm/server.cjs` | Definido PELO gestor MITM para o processo de proxy iniciado (`root-ca` \| `legacy`) — reflete a decisão de migração de certificados; não se destina a ser definido manualmente. | | `OMNIROUTE_NO_SUDO` | `0` | `src/mitm/systemCommands.ts` | Defina como `1` (truthy) para remover o `sudo` inicial dos comandos de confiança de certificados MITM — para implementações sem root / com espaços de nomes de utilizador, nas quais o operador confia manualmente na CA (por exemplo, através do mecanismo de certificados CA adicionais do Node). | | `SKIP_ANTIGRAVITY_DNS` | _(não definido)_ | `src/mitm/dns/provision.ts` | Defina como `true` para ignorar totalmente o aprovisionamento das entradas DNS de `/etc/hosts` para os nomes de anfitrião do proxy Antigravity — para contentores sem acesso a sudo/root. | | `OMNIROUTE_SKIP_DNS_WRITE` | _(não definido)_ | `src/mitm/dns/dnsConfig.ts` | Defina como `1` para ignorar a escrita no ficheiro hosts ao adicionar/remover entradas DNS — para ambientes de teste isolados ou só de leitura. | | `OMNIROUTE_SKIP_SYSTEM_TRUST` | `0` | `src/mitm/cert/install.ts`, `src/mitm/tproxy/caTrust.ts` | Proteção exclusiva para testes/CI: defina como `1` para tornar a instalação/desinstalação da confiança de certificados uma operação nula, para que o conjunto de testes nunca altere o arquivo de confiança do sistema operativo. Definida automaticamente pela configuração dos testes e pelos fluxos de trabalho de CI. | | `CHANGELOG_BASE_REF` | _(automático)_ | `scripts/check/check-changelog-integrity.mjs` | Referência base explícita para a verificação anti-remoção do CHANGELOG (por predefinição, utiliza a branch base do PR em CI ou a versão `release/v*` mais elevada). | | `FREE_PROXY_AUTO_SYNC_ENABLED` | `false` | `src/lib/freeProxyProviders/scheduler.ts` | Defina como `true` para ativar o agendador de sincronização automática em segundo plano do conjunto de proxies gratuitos. Opt-in, desativado por predefinição. | | `FREE_PROXY_AUTO_SYNC_INTERVAL_MS` | `1800000` | `src/lib/freeProxyProviders/scheduler.ts` | Intervalo de sincronização automática em milissegundos (predefinição: 30 min). | | `FREE_PROXY_1PROXY_ENABLED` | `true` | `src/lib/freeProxyProviders/oneproxy.ts` | Ativa a fonte de proxies gratuitos 1proxy. Defina como `false` para desativar. | | `FREE_PROXY_1PROXY_API_URL` | _(ver oneproxy.ts)_ | `src/lib/freeProxyProviders/oneproxy.ts` | Substituição do URL da API do 1proxy. | | `FREE_PROXY_1PROXY_MAX` | `500` | `src/lib/freeProxyProviders/oneproxy.ts` | Número máximo de proxies obtidos por sincronização do 1proxy. | | `FREE_PROXY_1PROXY_MIN_QUALITY` | `50` | `src/lib/freeProxyProviders/oneproxy.ts` | Limiar mínimo da pontuação de qualidade para importações do 1proxy. | | `FREE_PROXY_PROXIFLY_ENABLED` | `true` | `src/lib/freeProxyProviders/proxifly.ts` | Ativar a fonte de proxies gratuitos Proxifly. Defina como `false` para desativar. | | `FREE_PROXY_PROXIFLY_QUANTITY` | `100` | `src/lib/freeProxyProviders/proxifly.ts` | Número de proxies a obter por sincronização do Proxifly. | | `FREE_PROXY_PROXIFLY_ANONYMITY` | `elite` | `src/lib/freeProxyProviders/proxifly.ts` | Filtro do nível de anonimato do Proxifly (`elite`, `anonymous`, `transparent`). | | `FREE_PROXY_IPLOCATE_ENABLED` | `false` | `src/lib/freeProxyProviders/iplocate.ts` | Ativar a fonte de proxies gratuitos IPLocate. Apenas mediante ativação explícita. | | `FREE_PROXY_IPLOCATE_BASE_URL` | `https://raw.githubusercontent.com/iplocate/free-proxy-list/main/protocols` | `src/lib/freeProxyProviders/iplocate.ts` | Substituição do URL base da lista de proxies do IPLocate. | | `FREE_PROXY_WEBSHARE_ENABLED` | `true` | `src/lib/freeProxyProviders/webshare.ts` | Ativar a origem do conjunto de proxies Webshare. Defina como `false` para desativar; também requer que `FREE_PROXY_WEBSHARE_API_KEY` esteja definida. | | `FREE_PROXY_WEBSHARE_API_KEY` | _(nenhum)_ | `src/lib/freeProxyProviders/webshare.ts` | Token de API da conta Webshare (`Authorization: Token `). Obrigatório — o fornecedor permanece desativado sem ele. | | `FREE_PROXY_WEBSHARE_API_URL` | `https://proxy.webshare.io/api/v2/proxy/list/` | `src/lib/freeProxyProviders/webshare.ts` | Substituição do URL da API da lista de proxies Webshare. | | `FREE_PROXY_WEBSHARE_MAX` | `500` | `src/lib/freeProxyProviders/webshare.ts` | Número máximo de proxies importados por sincronização do Webshare. | | `NEXT_PUBLIC_VERCEL_RELAY_ENABLED` | `true` | `src/app/(dashboard)/…/ProxyPoolTab.tsx` | Mostrar/ocultar o botão Deploy Vercel Relay no separador Proxy Pool. | | `VERCEL_API_BASE` | `https://api.vercel.com` | `src/app/api/settings/proxy/vercel-deploy/route.ts` | Substituição do URL base da API da Vercel (para testes). | | `NEXT_PUBLIC_VERCEL_RELAY_DEFAULT_PROJECT` | `omniroute-relay` | `src/app/(dashboard)/…/VercelRelayModal.tsx` | Nome do projeto predefinido preenchido previamente no modal de implementação do Vercel Relay. | | `TAILSCALE_BIN` | _(deteção automática)_ | `src/lib/tailscaleTunnel.ts` | Caminho explícito para o binário `tailscale`. | | `TAILSCALED_BIN` | _(auto-detect)_ | `src/lib/tailscaleTunnel.ts` | Caminho explícito para o binário do daemon `tailscaled`. | | `TAILSCALE_AUTHKEY` | _(unset)_ | `src/lib/tailscaleTunnel.ts` | Chave de autenticação Tailscale pré-partilhada para `tailscale up` não interativo / sem interface (passada através de `--auth-key=`). Quando não definida, o início de sessão recorre ao URL de autenticação interativo no navegador. | | `NGROK_AUTHTOKEN` | _(unset)_ | `src/lib/ngrokTunnel.ts` | Autentica túneis ngrok de saída. | | `DB_BACKUP_MAX_FILES` | `20` | `src/lib/db/backup.ts` | Número máximo de ficheiros de cópia de segurança SQLite mantidos pela limpeza manual/agendada de cópias de segurança. Os instantâneos de migração são endereçados pelo conteúdo e reutilizados para um estado idêntico da base de dados; não são eliminados dentro da janela de migração concorrente. Substitui o valor guardado em Definições → Retenção de cópias de segurança da base de dados. | | `DB_BACKUP_RETENTION_DAYS` | `0` | `src/lib/db/backup.ts` | Idade máxima (em dias) mantida pela limpeza manual/agendada de cópias de segurança. `0` desativa a eliminação baseada na idade. Os instantâneos de migração não são eliminados dentro da janela de migração concorrente. Substitui o valor guardado em Definições → Retenção de cópias de segurança da base de dados. | | `OMNIROUTE_BACKUP_SCHEDULE_JOB_INTERVAL_MS` | `30000` | `src/lib/jobs/backupScheduleJob.ts` | Intervalo de execução (ms) do trabalho do lado do servidor que executa `backup-schedule.json`. Deve permanecer bem abaixo da granularidade de 1 minuto do cron; valores inferiores a `5000` ou impossíveis de analisar revertem para `30000`. | | `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | Indicação do runtime de contentores para a verificação de permissões do ponto de entrada. Defina como `podman` para qualquer topologia Podman. Como o contentor não consegue determinar se o motor é local ou é acedido através do Podman Machine, o aviso mantém-se neutro relativamente à topologia e aponta para `contrib/podman/README.md`. | | `QUOTA_STORE_DRIVER` | `sqlite` | `src/lib/quota/storeFactory.ts` | Backend do armazenamento do consumo de quota partilhada: `sqlite` (predefinido) ou `redis`. | | `QUOTA_STORE_REDIS_URL` | _(unset)_ | `src/lib/quota/storeFactory.ts` | Cadeia de ligação ao Redis utilizada quando `QUOTA_STORE_DRIVER=redis` (por exemplo, `redis://localhost:6379`). | | `QUOTA_SATURATION_THRESHOLD` | `0.5` | `src/lib/quota/enforce.ts` | Rácio de saturação do pool (0..1); quando é igual ou superior a este valor, o pool entra no modo estrito (sem empréstimos). | | `QUOTA_SOFT_DEPRIORITIZE_FACTOR` | `0.7` | `open-sse/services/combo.ts` | Multiplicador de pontuação (0..1) aplicado a um destino quando a política de quota flexível lhe reduz a prioridade. | | `STATUS_SOFT_DEPRIORITIZE_FACTOR` | `0.5` | `open-sse/services/combo/autoStrategy.ts` | Multiplicador de pontuação (0..1) aplicado a um fornecedor esgotado (`credits_exhausted`/`rate_limited`) na pontuação de combinação automática quando o corte de quota da verificação prévia está DESATIVADO (#4540). | | `QUOTA_CONSUMPTION_RETENTION_DAYS` | `14` | `src/lib/db/quotaConsumption.ts` | Período de retenção (dias) dos blocos de `quota_consumption` antes da recolha de lixo (`gcQuotaConsumption`). | | `QUOTA_PREFLIGHT_CUTOFF_ENABLED` | `false` | `src/lib/resilience/settings.ts` | Opt-in (predefinição DESATIVADO): ativa o corte rígido de quota do encaminhamento automático, que remove os candidatos com pouca quota antes da pontuação. Apenas define a predefinição: um valor booleano guardado em `resilienceSettings` (Painel → Definições → Resiliência) tem precedência. | | `OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL` | `false` | `open-sse/services/autoCombo/virtualFactory.ts` | Opt-in (predefinição DESATIVADO): quando um filtro `auto/:` não encontra candidatos ligados, restaura o comportamento legado de recuar para o pool completo (não filtrado), em vez de devolver um pool vazio. A predefinição DESATIVADO faz com que `:free` signifique "apenas o nível gratuito". | | `OMNIROUTE_CHAOS_MAX_PANEL` | `5` | `open-sse/services/autoCombo/virtualFactory.ts` | Limite do tamanho do painel (limitado a 1–10) para a variante de transmissão `auto/*:chaos` — um pedido é distribuído por, no máximo, este número de modelos de fornecedores distintos. | | `OMNIROUTE_CHAOS_MIN_PANEL` | `_(engine default)_` | `open-sse/services/autoCombo/virtualFactory.ts` | Afinação do tamanho mínimo do painel encaminhada para o processador de difusão do chaos; não definido mantém o valor predefinido do motor. | | `OMNIROUTE_CHAOS_PANEL_TIMEOUT_MS` | `_(engine default)_` | `open-sse/services/autoCombo/virtualFactory.ts` | Tempo limite rígido (ms) para toda a distribuição do painel de chaos; não definido mantém o valor predefinido do motor. | | `GROK_AUTH_PATH` | `~/.grok/auth.json` | `open-sse/services/grokQuotaFetcher.ts` | Caminho para o `auth.json` da CLI do Grok usado para obter a quota semanal do grok-web; substitua-o para testes ou para uma instalação não padrão da CLI. | | `AGENTBRIDGE_UPSTREAM_CA_CERT` | `_(unset)_` | `src/mitm/manager.ts` | Certificado de CA adicional (PEM) considerado fidedigno para ligações TLS upstream do AgentBridge. | | `INSPECTOR_BUFFER_SIZE` | `1000` | `src/mitm/inspector/buffer.ts` | Número máximo de pedidos capturados mantidos no buffer circular do Traffic Inspector. | | `INSPECTOR_MAX_BODY_KB` | `1024` | `src/mitm/inspector/buffer.ts` | Tamanho máximo (KB) do corpo do pedido/resposta capturado antes do truncamento. | | `INSPECTOR_HTTP_PROXY_PORT` | `8080` | `src/mitm/inspector/httpProxyServer.ts` | Porta local para o proxy HTTP do Traffic Inspector. | | `INSPECTOR_HTTP_PROXY_AUTOSTART` | `false` | `src/mitm/inspector/httpProxyServer.ts` | Inicia automaticamente o proxy HTTP do inspector durante o arranque. | | `INSPECTOR_LLM_HOSTS_EXTRA` | _(unset)_ | `src/lib/inspector/captureState.ts` | Nomes de anfitrião adicionais (separados por vírgulas) tratados como endpoints LLM para a captura. | | `INSPECTOR_MASK_SECRETS` | `true` | `src/mitm/inspector/buffer.ts` | Oculta segredos (cabeçalhos de autenticação / chaves de API) no tráfego capturado. | | `INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES` | `30` | `src/app/api/tools/traffic-inspector/capture-modes/system-proxy/route.ts` | Minutos até que a proteção do proxy do sistema reverta automaticamente as definições de proxy do sistema operativo. | | `INSPECTOR_INTERNAL_INGEST_TOKEN` | _(auto)_ | `src/app/api/tools/traffic-inspector/internal/ingest/route.ts` | Token que autentica a ingestão interna de capturas no inspetor. | | `PLAYGROUND_COMPARE_MAX_COLUMNS` | `4` | `src/app/(dashboard)/dashboard/playground/` | Número máximo de colunas lado a lado no modo de comparação do Playground. | | `PLAYGROUND_IMPROVE_PROMPT_DEFAULT_MODEL` | _(unset)_ | `src/app/(dashboard)/dashboard/playground/` | Modelo predefinido para a ação «melhorar prompt» do Playground (recorre ao modelo ativo quando não definido). | | `BIFROST_ENABLED` | `1` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Interruptor geral para desativar o proxy sidecar do Bifrost. Quando definido como `0`, a rota devolve 503 com o cabeçalho `X-Bifrost-Killswitch` e o operador é redirecionado para o caminho TS. Utilize-o para desativar o sidecar sem efetuar uma nova implementação (incidente do router de nível 1, rotação de chaves). | | `BIFROST_BASE_URL` | _(unset)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Quando definido, a rota do proxy sidecar Bifrost encaminha o tráfego de `/v1/chat/completions` para este gateway Go, em vez do processador de relay TS. Não definido → 503 com fallback. A barra final é removida. | | `BIFROST_PORT` | `8080` | `src/lib/services/bootstrap.ts` | Porta à qual o serviço Bifrost incorporado supervisionado se associa (`127.0.0.1:`) quando o OmniRoute gere o ciclo de vida do sidecar Bifrost. O valor predefinido é `8080`. | | `SINGBOX_PORT` | `20140` | `src/lib/services/bootstrap.ts` | Porta à qual o serviço sing-box incorporado supervisionado se associa (`127.0.0.1:`) quando o OmniRoute gere o ciclo de vida do sidecar sing-box. O valor predefinido é `20140`. | | `LLMLINGUA_PORT` | `20135` | `src/lib/services/bootstrap.ts` | Porta à qual o serviço de compressão LLMLingua supervisionado se associa (`127.0.0.1:`). O valor predefinido é `20135`. | | `LLMLINGUA_BASE_URL` | `http://127.0.0.1:20135` | `open-sse/services/compression/engines/llmlingua/index.ts` | URL base do daemon do microsserviço HTTP local de compressão LLMLingua. O valor predefinido é `http://127.0.0.1:20135`. | | `LLMLINGUA_MODEL` | `atjsh/llmlingua-2-js-tinybert-meetingbank` | `src/lib/services/installers/llmlingua.ts` | ID do modelo do Hugging Face carregado pelo sidecar LLMLingua supervisionado (transmitido para o ambiente do processo filho). | | `BIFROST_API_KEY` | _(unset)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Chave API para o gateway Bifrost (enviada como `Authorization: Bearer ...`). Se não estiver definida, a rota espera que o pedido contenha uma chave API OmniRoute válida; esta chave destina-se apenas à autenticação do lado do gateway. | | `BIFROST_STREAMING_ENABLED` | `true` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Quando definida como true, a rota do sidecar Bifrost transmite as respostas através de SSE pelo gateway, em vez de utilizar o executor de streaming TS. Defina-a como `0` para forçar respostas JSON sem streaming através do gateway. | | `BIFROST_TIMEOUT_MS` | `30000` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Tempo limite por pedido ao fazer proxy para o gateway Bifrost (ms). Quando o tempo limite é atingido, a rota devolve o caminho de relay TS através do cabeçalho `X-Bifrost-Fallback`. | | `OMNIROUTE_BIFROST_KEY` | _(não definido)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Alias para `BIFROST_API_KEY` (utilizado por scripts que leem o ambiente através de `OMNIROUTE_*`). `BIFROST_API_KEY` tem precedência quando ambos estão definidos. | | `OMNIROUTE_RELAY_BACKEND` | `ts` / `auto` | `src/app/api/v1/relay/chat/completions/routingBackend.ts` | Backend de relay para `/api/v1/relay/chat/completions`: `ts \| bifrost \| auto`. `ts` = relay TypeScript (predefinido quando o Bifrost não está configurado); `auto` seleciona o Bifrost quando `BIFROST_BASE_URL` está definido e `BIFROST_ENABLED` ≠ `0`, com fallback automático para TS se o sidecar estiver inacessível; `bifrost` força o Bifrost (estrito, sem fallback). A autenticação, o limite de taxa, a proteção contra injeção e a lista de permissões são sempre aplicados primeiro na rota Next. As respostas incluem `X-Routing-Backend` / `X-Routing-Fallback` / `X-Routing-Fallback-Reason`. | | `RELAY_ROUTING_BACKEND` | _(não definido)_ | `src/app/api/v1/relay/chat/completions/routingBackend.ts` | Alias aceite para `OMNIROUTE_RELAY_BACKEND` (os mesmos valores `ts \| bifrost \| auto`). `OMNIROUTE_RELAY_BACKEND` tem precedência quando ambos estão definidos. | | `OMNIROUTE_BIFROST_FAILURE_COOLDOWN_MS` | `5000` | `src/app/api/v1/relay/chat/completions/bifrostCooldown.ts` | Período de espera (ms) após uma falha numa passagem pelo sidecar Bifrost no modo `auto`, antes de o relay voltar a tentar utilizar o sidecar; durante o período de espera, encaminha diretamente para o percurso TS e, em seguida, volta a testar. `0` desativa. Aplica-se apenas quando `OMNIROUTE_RELAY_BACKEND=auto`. | | `OMNIROUTE_TLS_CERT` | _(não definido)_ | `bin/cli/commands/serve.mjs` | Caminho para um certificado TLS PEM para disponibilizar `omniroute serve` através de HTTPS (equivalente a `--tls-cert`). Tem de ser utilizado em conjunto com `OMNIROUTE_TLS_KEY`; o servidor autónomo termina então o TLS no mesmo listener (`wss://` funciona sem alterações). Não definido → HTTP simples. Se for fornecido apenas um dos elementos cert/key, ou se o caminho não puder ser lido, é registado um aviso e permanece em HTTP. | | `OMNIROUTE_TLS_KEY` | _(não definido)_ | `bin/cli/commands/serve.mjs` | Caminho para a chave privada TLS PEM para o HTTPS de `omniroute serve` (equivalente a `--tls-key`). Tem de ser utilizada em conjunto com `OMNIROUTE_TLS_CERT`. Consulte `OMNIROUTE_TLS_CERT`. | | `OMNIROUTE_LOCAL_ENDPOINTS_ENABLED` | `0` | `src/lib/security/localEndpoints.ts` | Interruptor principal para as rotas `/api/local/*`. Quando não definida ou com o valor `0`, todas as rotas `/api/local/*` devolvem 503 em produção. Tem de ser `1` em implementações que não utilizem loopback para ativar o iniciador do Redis e outros iniciadores de serviços locais com um clique. Em conjunto com a classificação de proteção de rotas `isLocalOnlyPath()` (`LOCAL_ONLY_API_PREFIXES` em `src/server/authz/routeGuard.ts`). | | `OMNIROUTE_LOCAL_ENDPOINTS_TOKEN` | _(não definido)_ | `src/lib/security/localEndpoints.ts` | Token Bearer para clientes de `/api/local/*` que não estejam em loopback (por exemplo, a aplicação de ambiente de trabalho). Quando definido, os pedidos provenientes de endereços IP que não sejam de loopback têm de incluir `Authorization: Bearer `. Obrigatório quando `OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=1` em implementações que não utilizem loopback. | | `OMNIROUTE_REDIS_CONTAINER_NAME` | `omniroute-redis` | `bin/cli/commands/redis.mjs` | Nome do contentor para o iniciador Redis de 1 clique (`omniroute redis up`). Utilizado tanto pela CLI como pela interface gráfica `RedisLauncherPanel`. | | `OMNIROUTE_REDIS_HOST_PORT` | `6379` | `bin/cli/commands/redis.mjs` | Porta do anfitrião para o iniciador Redis de 1 clique. Aumente-a se o anfitrião já utilizar a porta 6379. A porta interna do contentor permanece 6379. | | `OMNIROUTE_REDIS_BIND_HOST` | `127.0.0.1` | `bin/cli/commands/redis.mjs` | Interface do anfitrião na qual o iniciador Redis de 1 clique publica. O iniciador inicia o Redis SEM palavra-passe, pelo que associar a `0.0.0.0` disponibiliza a todos os anfitriões da sua LAN um Redis sem autenticação — só alargue esta associação se também definir pessoalmente uma palavra-passe na instância. | | `REDIS_BIND_HOST` | `127.0.0.1` | `docker-compose.yml` | Interface do anfitrião na qual o docker-compose publica o sidecar Redis (#9286). O Redis do compose é executado sem `requirepass`; os contentores da aplicação acedem-lhe através da rede do compose (`redis:6379`) — a porta publicada existe apenas para ferramentas no anfitrião. `0.0.0.0` expõe um Redis sem autenticação a toda a LAN. | | `REDIS_PORT` | `6379` | `docker-compose.yml` | Porta do anfitrião para o sidecar Redis do compose. | | `APP_BIND_HOST` | `127.0.0.1` | `docker-compose.yml`, `docker-compose.prod.yml` | Interface do anfitrião na qual o docker-compose publica as próprias portas do painel/API/WS em tempo real da aplicação (#12568). Com `REQUIRE_API_KEY=false` definido como predefinição no `.env.example`, `0.0.0.0` expõe o proxy LLM anónimo `/v1` a toda a LAN/WAN — só alargue a associação depois de definir `REQUIRE_API_KEY=true` ou de um proxy inverso à frente impor a sua própria autenticação. | | `QDRANT_BIND_HOST` | `127.0.0.1` | `docker-compose.yml` | Interface do anfitrião na qual o docker-compose publica o sidecar de memória Qdrant (#12578). Aplica-se o mesmo raciocínio de exposição à LAN que a `REDIS_BIND_HOST`. | | `BIFROST_BIND_HOST` | `127.0.0.1` | `docker-compose.yml` | Interface do anfitrião na qual o docker-compose publica o sidecar do encaminhador Bifrost (#12578). Aplica-se o mesmo raciocínio de exposição à LAN que a `REDIS_BIND_HOST`. | | `REDIS_KEY_PREFIX` | `omniroute:` | `src/shared/utils/rateLimiter.ts` | Prefixo de namespace aplicado a todas as chaves Redis do OmniRoute (limitador de taxa, cache de autenticação, armazenamento de quotas, disjuntor de circuito de aquecimento). Evita colisões de chaves quando a instância Redis é partilhada com outras aplicações (#11042). | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN` | _(unset — mechanism disabled)_ | `src/lib/api/internalServiceAuth.ts` | Segredo partilhado para saltos REST internos que preservam a identidade (#9260): os componentes do OmniRoute que chamam outras rotas locais do OmniRoute enviam-no como `x-omniroute-internal-service-token`, para que a identidade do autor da chamada original seja preservada. Comparado com `timingSafeEqual`. | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE` | _(unset)_ | `src/lib/api/internalServiceAuth.ts` | Variante baseada num ficheiro do token de serviço interno: caminho para um ficheiro cujo conteúdo, após remover os espaços em branco nas extremidades, corresponde ao token. Só é consultada quando a variável inline não está definida. | | `OPENROUTER_PROVIDER_STATS_ENABLED` | `true` | `src/lib/catalog/openrouterProviderStats.ts` | Enriquece a lista de fornecedores do painel com estatísticas semanais de classificação do OpenRouter (#9324). Ativada por predefinição; defina como `false` para ignorar completamente a obtenção em segundo plano (não bloqueante e nunca fatal). | | `OPENROUTER_PROVIDER_STATS_TTL_MS` | `86400000` (24h) | `src/lib/catalog/openrouterProviderStats.ts` | TTL da cache para o instantâneo de estatísticas dos fornecedores do OpenRouter, em milissegundos. | | `OMNIROUTE_REDIS_IMAGE` | `redis:7-alpine` | `bin/cli/commands/redis.mjs` | Imagem Redis utilizada pelo iniciador Redis com um clique. Substitua por `redis:8-alpine` ou por um espelho de um registo privado, conforme necessário. | | `QDRANT_HOST` | `qdrant` | _(opt-in cluster profile)_ | Nome de anfitrião do sidecar Qdrant quando `--profile memory` está ativo. Por predefinição, aponta para o nome do serviço qdrant na rede; substitua-o por uma implementação externa, se necessário. Só é consumido quando `qdrantEnabled` é `true` no código (`src/lib/memory/vectorStore.ts:108`). | | `QDRANT_PORT` | `6333` | _(opt-in cluster profile)_ | Porta REST do sidecar Qdrant. | | `QDRANT_GRPC_PORT` | `6334` | _(perfil de cluster opcional)_ | Porta gRPC do sidecar do Qdrant. Utilizada por bibliotecas cliente que preferem gRPC a REST para operações de transmissão. | | `QDRANT_API_KEY` | _(unset)_ | _(perfil de cluster opcional)_ | Chave API opcional para o Qdrant Cloud ou uma instância local autenticada. Vazia → não é enviado nenhum cabeçalho `api-key`. | | `QDRANT_COLLECTION` | `omniroute-memory` | _(perfil de cluster opcional)_ | Nome da coleção para os embeddings da memória de conversas do OmniRoute. Criada na primeira execução com dimensões `QDRANT_VECTOR_SIZE`. | | `QDRANT_EMBEDDING_MODEL` | `text-embedding-3-small` | _(perfil de cluster opcional)_ | Nome predefinido do modelo de embeddings registado nos metadados da coleção do Qdrant. Os embeddings efetivos são gerados pelo fornecedor para o qual aponta o campo `embeddingModel` nas definições do OmniRoute. | | `QDRANT_VECTOR_SIZE` | `1536` | _(perfil de cluster opcional)_ | Dimensão do vetor de embeddings. Tem de corresponder ao modelo utilizado para gerar os embeddings (text-embedding-3-small → 1536; ada-002 → 1536; nomic-embed-text → 768). | | `QDRANT_HNSW_EF_CONSTRUCT` | `128` | _(perfil de cluster opcional)_ | Precisão da construção do índice HNSW. Um valor mais elevado = compilação mais lenta, pesquisa mais rápida. | | `OMNIROUTE_ROTATION_ENABLED` | `true` | `open-sse/services/rotationConfig.ts` | Interruptor principal para a rotação de contas configurável pelo operador. Quando `false`, nenhuma das classes `OMNIROUTE_ROTATE_*` abaixo aciona o fallback de conta (o estado de desativação principal também bloqueia as classes 429/500/502 ativadas por predefinição). Permite que um front-end supervisor (por ex., a aplicação de ambiente de trabalho VibeProxy) replique as suas próprias regras de rotação no motor de fallback de contas do back-end. | | `OMNIROUTE_ROTATION_RATE_LIMIT_RESET_SECONDS` | `0` | `open-sse/services/rotationConfig.ts` | Período de espera (em segundos) aplicado a uma conta limitada pela taxa quando o upstream não fornece uma indicação explícita de reposição. `0` = utilizar o período de espera predefinido do motor em vez de uma substituição fixa. | | `OMNIROUTE_ROTATION_DISABLE_TAG_WITHOUT_RESET` | `true` | `open-sse/services/rotationConfig.ts` | Espelho da preferência do front-end «não etiquetar como limitado pela taxa sem um tempo de reposição». | | `OMNIROUTE_ROTATE_ON_429` | `true` | `open-sse/services/rotationConfig.ts` | Ativação de fallback por estado para erros `429`. Quando `false` (e `OMNIROUTE_ROTATION_ENABLED=true`), um `429` deixa de desencadear a rotação da conta e é devolvido ao cliente. | | `OMNIROUTE_ROTATE_429_THRESHOLD` | `1` | `open-sse/services/rotationConfig.ts` | Número de erros `429` dentro de `OMNIROUTE_ROTATE_429_WINDOW_SECONDS` necessário antes de a conta ser rodada. `1` (predefinição) roda imediatamente, preservando o comportamento histórico. | | `OMNIROUTE_ROTATE_429_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (em segundos) durante a qual os erros `429` são contabilizados para `OMNIROUTE_ROTATE_429_THRESHOLD`. | | `OMNIROUTE_ROTATE_ON_500` | `true` | `open-sse/services/rotationConfig.ts` | Ativação de fallback por estado para erros de servidor `5xx` (excluindo `502`, que tem a sua própria classe). Quando `false`, estes erros deixam de desencadear a rotação da conta. | | `OMNIROUTE_ROTATE_500_THRESHOLD` | `1` | `open-sse/services/rotationConfig.ts` | Número de erros `5xx` dentro de `OMNIROUTE_ROTATE_500_WINDOW_SECONDS` necessário antes de a conta ser rodada. `1` (predefinição) roda imediatamente. | | `OMNIROUTE_ROTATE_500_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (em segundos) durante a qual os erros `5xx` são contabilizados para `OMNIROUTE_ROTATE_500_THRESHOLD`. | | `OMNIROUTE_ROTATE_ON_502` | `true` | `open-sse/services/rotationConfig.ts` | Ativação de fallback por estado para erros `502` (gateway inválido). Quando `false`, os erros `502` deixam de desencadear a rotação da conta. | | `OMNIROUTE_ROTATE_502_THRESHOLD` | `1` | `open-sse/services/rotationConfig.ts` | Número de erros `502` dentro de `OMNIROUTE_ROTATE_502_WINDOW_SECONDS` necessário antes de a conta ser rodada. `1` (predefinição) provoca a rotação imediatamente. | | `OMNIROUTE_ROTATE_502_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (em segundos) durante a qual os erros `502` são contabilizados para `OMNIROUTE_ROTATE_502_THRESHOLD`. | | `OMNIROUTE_ROTATE_ON_400` | `false` | `open-sse/services/rotationConfig.ts` | Ativação opcional (desativada por predefinição): quando `true`, um `400` simples (pedido inválido) também desencadeia a rotação da conta. Isto é apenas aditivo — nunca bloqueia o comportamento existente do motor, no qual um `400` que contenha texto de limite de velocidade/quota continua a provocar fallback, independentemente desta opção. | | `OMNIROUTE_ROTATE_400_THRESHOLD` | `1` | `open-sse/services/rotationConfig.ts` | Número de erros `400` dentro de `OMNIROUTE_ROTATE_400_WINDOW_SECONDS` necessário antes de a conta ser rodada (consultado apenas quando `OMNIROUTE_ROTATE_ON_400=true`). | | `OMNIROUTE_ROTATE_400_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (em segundos) durante a qual os erros `400` são contabilizados para `OMNIROUTE_ROTATE_400_THRESHOLD`. | ### Agendador de Warmup do Claude Warmup acionado por cron para ligações OAuth da Anthropic selecionadas, para que a janela de limite de velocidade de 5 horas seja aberta por um pedido agendado trivial, em vez de pelo primeiro pedido real (#8848). O agendador está desativado, exceto quando `OMNIROUTE_WARMUP_ENABLED` tem um valor verdadeiro **e** a ligação está assinalada em `settings.claudeWarmup.connections`; uma lista de ligações vazia significa que nada é aquecido, mesmo quando a variável de ambiente está ativada. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------ | --------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_WARMUP_ENABLED` | _(unset → off)_ | `src/lib/warmupScheduler.ts` | Interruptor principal do agendador de warmup. Aceita `1`/`true`/`yes`/`on` (sem distinção entre maiúsculas e minúsculas, com espaços iniciais e finais removidos). Qualquer outro valor, ou a ausência de valor, mantém o agendador desativado. | | `OMNIROUTE_WARMUP_CRON` | `0 7 * * *` | `src/lib/warmupScheduler.ts` | Expressão cron de cinco campos para o ciclo de warmup, avaliada em `America/Los_Angeles` (o fuso horário de reposição da Anthropic), independentemente do relógio do anfitrião. | | `OMNIROUTE_WARMUP_CONCURRENCY` | `3` | `src/lib/warmupScheduler.ts` | Número de ligações aquecidas em paralelo por ciclo. Limitado ao intervalo `1`-`10`; um valor não numérico reverte para `3`. | | `OMNIROUTE_WARMUP_MODEL` | `claude-3-5-haiku-20241022` | `src/lib/warmupScheduler.ts` | Modelo utilizado para o pedido de warmup. Substitua-o apenas se a predefinição não estiver disponível no seu plano; escolha o modelo mais barato que ainda abra a janela. | ### Sessões VNC de início de sessão no browser e alias do diretório de dados Chromium+VNC em contentor utilizado para a captura interativa de credenciais de início de sessão no browser (`/api/vnc-session`), além de um alias legado `DATA_DIR`. Tudo opcional — as predefinições do VNC destinam-se à imagem incluída `omniroute-vnc-chromium:local` e só são substituídas para utilizar uma imagem de contentor personalizada, portas personalizadas ou ajustar o ciclo de vida. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_VNC_IMAGE` | `omniroute-vnc-chromium:local` | `src/lib/vncSession/manifest.ts` | Etiqueta da imagem Docker para o contentor de início de sessão Chromium+VNC. Compile `docker/vnc-browser/chromium` ou aponte esta variável para uma imagem personalizada. | | `OMNIROUTE_DOCKER_BIN` | `docker` | `src/lib/vncSession/manifest.ts` | Binário do runtime de contentores utilizado para iniciar o contentor VNC (por exemplo, defina-o como `podman`). | | `OMNIROUTE_VNC_CONTAINER_VNC_PORT` | `3000` | `src/lib/vncSession/manifest.ts` | Porta VNC/noVNC exposta dentro do contentor. | | `OMNIROUTE_VNC_CONTAINER_CDP_PORT` | `9223` | `src/lib/vncSession/manifest.ts` | Porta do Chrome DevTools Protocol dentro do contentor. | | `OMNIROUTE_VNC_CONTAINER_PROFILE_DIR` | `/config` | `src/lib/vncSession/manifest.ts` | Caminho do diretório de perfil do Chromium dentro do contentor. | | `OMNIROUTE_VNC_PROFILE_DIR` | `$HOME/.omniroute/browser-login-profiles` | `src/lib/vncSession/manifest.ts` | Diretório do anfitrião que contém os perfis de início de sessão do navegador persistidos. | | `OMNIROUTE_VNC_IDLE_MS` | `600000` (10 min) | `src/lib/vncSession/manifest.ts` | Tempo-limite de inatividade (ms) antes de uma sessão VNC inativa ser eliminada. | | `OMNIROUTE_VNC_MAX_MS` | `1800000` (30 min) | `src/lib/vncSession/manifest.ts` | Limite máximo (ms) da duração de uma única sessão VNC. | | `OMNIROUTE_VNC_MAX_SESSIONS` | `4` | `src/lib/vncSession/manifest.ts` | Número máximo de sessões VNC simultâneas. | | `OMNIROUTE_VNC_READY_MS` | `45000` | `src/lib/vncSession/manifest.ts` | Tempo-limite (ms) para aguardar que o navegador em contentor fique pronto para CDP. | | `OMNIROUTE_VNC_HARVEST_MS` | `20000` | `src/lib/vncSession/manifest.ts` | Tempo-limite (ms) para recolher a sessão/cookies capturados após a conclusão do início de sessão. | | `OMNIROUTE_VNC_CHROMIUM_ARGS` | `--remote-debugging-port=9222 --no-first-run --no-default-browser-check` | `src/lib/vncSession/manifest.ts` | Sinalizadores adicionais da linha de comandos transmitidos ao Chromium em contentor. | | `OMNIROUTE_VNC_NETWORK` | `omniroute-vnc-browser-login` | `src/lib/vncSession/manifest.ts` | Rede Docker dedicada à qual o contentor de início de sessão VNC se liga (#12571), em vez da bridge predefinida, para que os contentores vizinhos não consigam aceder à respetiva porta bridge de CDP. | | `VIBEPROXY_DATA_DIR` | _(não definido)_ | `open-sse/services/notionThreadSessions.ts` | **Alias legado** de `DATA_DIR`, verificado apenas depois de `DATA_DIR` e `OMNIROUTE_DATA_DIR` não estarem definidos. Localiza a cache de sessões de threads Web do Notion (`/notion-web-thread-sessions.json`). | --- ## 26. Teste e cablagem E2E Utilizado por `scripts/dev/run-next-playwright.mjs`, `scripts/dev/smoke-electron-packaged.mjs`, `scripts/dev/run-ecosystem-tests.mjs` e `scripts/build/uninstall.mjs`. Deixe todos os valores abaixo não definidos nas implementações de produção. | Variável | Predefinição | Arquivo de origem | Descrição | | -------------------------------------- | ------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_E2E_BOOTSTRAP_MODE` | `auth` | `scripts/dev/run-next-playwright.mjs` | modo de inicialização E2E (`auth`, `fresh`, `reuse`) para o executor Playwright. | | `OMNIROUTE_E2E_PASSWORD` | voltar para `INITIAL_PASSWORD` | `scripts/dev/run-next-playwright.mjs` | Password de administrador injetada no ambiente Playwright. | | `OMNIROUTE_DISABLE_LOCAL_HEALTHCHECK` | `true` | `scripts/dev/run-next-playwright.mjs` | Desative a pesquisa de verificação de integridade local durante as execuções Playwright. | | `OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK` | `true` | `scripts/dev/run-next-playwright.mjs` | Desative o loop de verificação de integridade do token OAuth durante os testes. | | `OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS` | _(desativado)_ | `src/lib/tokenHealthCheck.ts` | Fornecedores separados por vírgula excluídos da varredura proativa de atualização de tokens (por exemplo, `codex,openai`). Alternativa direcionada para desativar totalmente os prestadores de verificação de saúde — short-TTL continuam a atualizar enquanto os prestadores em cascata permanecem apenas reativos. | | `OMNIROUTE_HIDE_HEALTHCHECK_LOGS` | `true` | `scripts/dev/run-next-playwright.mjs` | Silencie o ruído da verificação de integridade no Playwright stdout. | | `OMNIROUTE_PLAYWRIGHT_SKIP_BUILD` | `0` | `scripts/dev/run-next-playwright.mjs` | Ignore a construção de produção Next.js antes do início Playwright (otimização CI ). | | `OMNIROUTE_SKIP_UNINSTALL_HOOK` | `0` | `scripts/build/uninstall.mjs` | Ignore o gancho de desinstalação OmniRoute (utilizado pelo CI para manter `node_modules` intacto). | | `ECOSYSTEM_SERVER_WAIT_MS` | `180000` | `scripts/dev/run-ecosystem-tests.mjs` | Tempo de espera (ms) para que o servidor fique íntegro antes de executar testes ecosystem/protocol. | | `ELECTRON_SMOKE_URL` | `http://127.0.0.1:20128/login` | `scripts/dev/smoke-electron-packaged.mjs` | URL o equipamento de fumo Electron espera que a aplicação empacotada seja veiculada. | | `ELECTRON_SMOKE_TIMEOUT_MS` | `45000` | `scripts/dev/smoke-electron-packaged.mjs` | Tempo limite total (ms) antes de o chicote de fumo ceder. | | `ELECTRON_SMOKE_SETTLE_MS` | `2000` | `scripts/dev/smoke-electron-packaged.mjs` | Janela de liquidação (ms) após o carregamento da página. | | `ELECTRON_SMOKE_APP_EXECUTABLE` | _(auto)_ | `scripts/dev/smoke-electron-packaged.mjs` | Caminho explícito para o executável Electron empacotado. | | `ELECTRON_SMOKE_DATA_DIR` | _(tmpdir)_ | `scripts/dev/smoke-electron-packaged.mjs` | Diretório de dados para a execução do Electron smoke. | | `ELECTRON_SMOKE_KEEP_DATA` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | Defina `1` para preservar o diretório de dados do smoke após a execução. | | `ELECTRON_SMOKE_STREAM_LOGS` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | Configure `1` para transmitir os registos Electron para o stdout durante a execução. | | `ELECTRON_SMOKE_COLD_RESTART` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | #7592: reiniciar no mesmo diretório de dados e afirmar que a segunda inicialização seleciona o controlador SQLite nativo. | | `CLI_DEVIN_BIN` | _(pesquisa PATH )_ | `open-sse/executors/devin-cli.ts` | Substitua o caminho binário Devin CLI. | ### Pipeline de tradução de documentos Utilizado por `scripts/i18n/run-translation.mjs` (o comando `npm run i18n:run` ). Todas as seis variáveis não estão definidas por defeito. — configure-as em `.env` apenas nas máquinas que devem ser capazes de executar o tradutor de documentos. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------ | -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OMNIROUTE_TRANSLATION_API_URL` | _(desativado)_ | `scripts/i18n/run-translation.mjs` | Base URL compatível com OpenAI para o back-end de tradução. | | `OMNIROUTE_TRANSLATION_API_KEY` | _(desativado)_ | `scripts/i18n/run-translation.mjs` | Token de portador para o back-end de tradução (nunca registado). | | `OMNIROUTE_TRANSLATION_MODEL` | _(desativado)_ | `scripts/i18n/run-translation.mjs` | ID do modelo, por exemplo, `gpt-4o-mini` ou `cx/gpt-5.4-mini`. | | `OMNIROUTE_TRANSLATION_FALLBACK_MODELS` | _(desativado)_ | `scripts/i18n/lib/translate-backend.mjs` | Cadeia de modelos separada por vírgulas opcional tentada por ordem quando o modelo primário falha (cota 429, 401/402, 5xx, tempo limite, rede); uma solicitação malformada (400/413/422) não é repetida noutro local. | | `OMNIROUTE_TRANSLATION_TIMEOUT_MS` | `60000` | `scripts/i18n/run-translation.mjs` | Tempo limite por pedido em milissegundos. | | `OMNIROUTE_TRANSLATION_REASONING_EFFORT` | _(desativado)_ | `scripts/i18n/lib/translate-backend.mjs` | Controlo de raciocínio opcional, enviado tal como está para o back-end quando definido. | | `OMNIROUTE_TRANSLATION_CONCURRENCY` | `4` | `scripts/i18n/run-translation.mjs` | Pedidos de tradução paralela ao executar vários ficheiros/localidades. | | `OMNIROUTE_TRANSLATION_ENGINE` | `llm` | `scripts/i18n/run-translation.mjs` | `llm` usa o backend acima; `google` é traduzido através do mecanismo Google com estrutura segura e não necessita de nenhuma das variáveis LLM. | | `OMNIROUTE_TRANSLATION_GOOGLE_FALLBACK` | `1` | `scripts/i18n/run-translation.mjs` | Com o mecanismo `llm`, um pedaço que o modelo não conseguiu produzir (a proteção de saída falhou em todas as tentativas ou um erro do modelo) é traduzido por Google em vez de falhar no código do idioma. `0` o desativa. | | `OMNIROUTE_TRANSLATION_GOOGLE_API_KEY` | _(desativado)_ | `scripts/i18n/lib/google-translate.mjs` | Chave opcional do Cloud Translation v2. O Unset utiliza o endpoint web sem chave (taxa limitada, adequado para ondas ocasionais). | | `OMNIROUTE_TRANSLATION_GOOGLE_CONCURRENCY` | `6` | `scripts/i18n/lib/google-translate.mjs` | Pedidos Google paralelos partilhados por cada localidade de uma execução. | | `OMNIROUTE_TRANSLATION_GOOGLE_TIMEOUT_MS` | `30000` | `scripts/i18n/lib/google-translate.mjs` | Tempo limite por pedido para o motor Google, em milissegundos. | | `UI_KIT_READ_TOKEN` | _(desativado)_ | `scripts/check/check-ui-kit-upstream.mjs` | Token de leitura apenas para o repositório upstream privado UI kit, utilizado pelo `npm run check:ui-kit-upstream` e pelo workflow semanal "UI Kit upstream watch". Localmente, a verificação utiliza as suas credenciais git. | --- ## 27. Feed de radar (auto-hospedagem) Complemento opcional controlado pelo sinalizador de recurso RADAR_ENABLED (o predefinido é — um sinalizador de recurso alternado através de Settings/DB, e não de um env var; ver [docs/frameworks/RADAR.md](../frameworks/RADAR.md#flag-radar_enabled-default-off) ). As primeiras quatro variáveis abaixo são substituições opcionais para um feed auto-hospedado ou bifurcado e fluxos de chave de suporte. O quinto, `RADAR_ADMIN_URL`, é uma ligação separada e livre de normas para o painel de operações privado do proprietário. Consulte [docs/frameworks/RADAR.md](../frameworks/RADAR.md) para obter o documento completo do módulo e a sua [ativação ponta a ponta e sequência de configuração guiada](../frameworks/RADAR.md#end-to-end-activation-and-guided-setup). O leitor de anúncios Home/Changelog genérico não é configurado por uma variável de ambiente e não depende do sinalizador de recurso RADAR_ENABLED. Lê o repositório público `news.json` URL declarado em `src/shared/utils/releaseNotes.ts` apenas pelo GET ; dispensa IDs permanece no armazenamento local do browser. | Variável | Predefinição | Arquivo de origem | Descrição | | ----------------------------- | -------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RADAR_FEED_URL` | `https://radar.omniroute.online` | `src/lib/radar/{sync,referralsSync,offersSync,intelSync}.ts` | Base URL partilhada pelo catálogo assinado separadamente, referências, ofertas de apoiantes e feeds da Intel. Substitua para apontar para um serviço auto-hospedado ou bifurcado. | | `RADAR_FEED_PUBKEY` | _(chave padrão fixada)_ | `src/lib/radar/pinnedKeys.ts` | Chave pública Ed25519 (base64-DER SPKI ou PEM) utilizada para verificar as subscrições de feeds de um feed personalizado. | | `RADAR_CONTRIBUTOR_CLAIM_URL` | `https://radar.omniroute.online/auth/github` | `src/lib/radar/links.ts` | URL o botão do painel "Sou um contribuidor" é aberto (GitHub OAuth fluxo de reivindicação da chave de suporte). | | `RADAR_SUPPORTER_PLANS_URL` | `https://radar.omniroute.online/planos` | `src/lib/radar/links.ts` | URL o botão do painel "Apoiar o projeto" é aberto (página payment/plans ). | | `RADAR_ADMIN_URL` | _(desativado)_ | `src/lib/radar/links.ts` | Link do painel de operações privado exclusivo do proprietário. HTTPS é necessário, exceto para um loopback HTTP SSH forward; valores não definidos ou inválidos não criam qualquer item de navegação. | --- ## Auditoria: variáveis removidas/mortas As seguintes variáveis apareceram em versões anteriores do `.env.example`, mas foram** sem referências de tempo de execução** na base de código atual. Foram removidos: | Variável | Razão | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STORAGE_DRIVER=sqlite` | Nunca leia nenhum ficheiro de origem. SQLite é o único driver suportado. — não é necessária qualquer seleção. | | `INSTANCE_NAME=omniroute` | Presente nos modelos docs/env antigos, mas não utilizado em tempo de execução. Pode retornar num futuro recurso de múltiplas instâncias. | | `SQLITE_MAX_SIZE_MB=2048` | Não referenciado no código-fonte. O tamanho da base de dados não é limitado artificialmente. | | `SQLITE_CLEAN_LEGACY_FILES=true` | Não referenciado no código-fonte. A limpeza legada foi provavelmente removida. | | `CLI_ROO_BIN` | Não registado em `src/shared/services/cliRuntime.ts`. | | `CLI_KIMI_CODING_BIN` | Não registado em `src/shared/services/cliRuntime.ts` (a codificação Kimi utiliza OAuth, e não um binário CLI ). | | `IFLOW_OAUTH_CLIENT_ID` / `IFLOW_OAUTH_CLIENT_SECRET` | Não referenciado em lado nenhum do código-fonte. | | `CEREBRAS_API_KEY` / `COHERE_API_KEY` / `FIREWORKS_API_KEY` / `GROQ_API_KEY` / `MISTRAL_API_KEY` / `NEBIUS_API_KEY` / `PERPLEXITY_API_KEY` / `TOGETHER_API_KEY` / `XAI_API_KEY` | Removido na v3.8.0. O tempo de execução já não lê estas credenciais env vars — provenientes do Dashboard / `data/provider-credentials.json` /crypto DB. | | `CURSOR_PROTOBUF_DEBUG` | Removido na v3.8.0. O executor Cursor utiliza `CURSOR_DEBUG` / `CURSOR_STREAM_DEBUG` (ver §22). | | `CLI_COMPAT_KIRO` | Removido na v3.8.0. Kiro está em `CLI_COMPAT_OMITTED_PROVIDER_IDS` — a sua alternância não tem qualquer efeito. | | `QIANFAN_API_KEY` | Removido juntamente com outros stubs de chave API do fornecedor não utilizados na v3.8.0. | ### Correções de valor padrão | Variável | Valor `.env.example` antigo | Padrão de código real | Fixado | | ------------------------- | --------------------------- | --------------------- | -------------------------------------------------------- | | `APP_LOG_RETENTION_DAYS` | `90` | `7` | ✅ Removido valor enganador; `7` documentado como padrão | | `CALL_LOG_RETENTION_DAYS` | `90` | `7` | ✅ Removido valor enganador; `7` documentado como padrão | ### regeneração de configuração OpenCode (ferramentas ad-hoc) Utilizado pelo `scripts/ad-hoc/regen-opencode-config.ts` para regenerar um `opencode.json` com valores `limit.context` e `limit.output` precisos extraídos da instância OmniRoute em execução. Nenhum deles é necessário para o funcionamento normal — o script é apenas uma ferramenta de programador. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------ | ------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_URL` | `http://localhost:20128` | `scripts/ad-hoc/regen-opencode-config.ts` | Base URL da instância OmniRoute para consultar `/v1/models`. | | `OMNIROUTE_KEY` | _(desativado)_ | `scripts/ad-hoc/regen-opencode-config.ts` | Chave API para autenticação no endpoint OmniRoute `/v1/models`. Volta a `OPENCODE_API_KEY` quando não está definido. | | `OPENCODE_API_KEY` | _(desativado)_ | `scripts/ad-hoc/regen-opencode-config.ts` | Chave API estilo OpenCode (`sk-...`) escrita no `opencode.json` regenerado. Volta a `OMNIROUTE_KEY` quando não está definido. | ### Chicote de avaliação offline de compressão (ferramentas ad-hoc) Utilizado por `scripts/compression-eval/index.ts`, a avaliação de compressão offline CLI. Não é apenas necessário para o funcionamento normal, apenas para as ferramentas de programador —. | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------------- | ------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_EVAL_CREDENTIALS` | `{}` (vazio) | `scripts/compression-eval/index.ts` | Credenciais JSON fornecidas pelo operador para o fornecedor exercido pelo CLI de avaliação de compressão offline (analisado com `JSON.parse`). Deixe desativado para uma simulação. | ### Sessões do navegador VNC Utilizado pela `src/lib/vncSession/manifest.ts` para configurar sessões headless do Chromium baseadas em Docker para fornecedores de automatização de browsers. Todos os padrões — opcionais indicados abaixo. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------- | ------------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------- | | `OMNIROUTE_DOCKER_BIN` | `docker` | `src/lib/vncSession/manifest.ts` | Caminho para o binário Docker utilizado para gerar contentores VNC. | | `OMNIROUTE_VNC_IMAGE` | `omniroute-vnc-chromium:local` | `src/lib/vncSession/manifest.ts` | Imagem Docker para o contentor VNC Chromium. | | `OMNIROUTE_VNC_CHROMIUM_ARGS` | _(sinalizadores integrados)_ | `src/lib/vncSession/manifest.ts` | Argumentos extra do Chromium CLI passados para o browser dentro do contentor. | | `OMNIROUTE_VNC_CONTAINER_VNC_PORT` | `3000` | `src/lib/vncSession/manifest.ts` | porta VNC dentro do contentor. | | `OMNIROUTE_VNC_CONTAINER_CDP_PORT` | `9223` | `src/lib/vncSession/manifest.ts` | Porta do protocolo Chrome DevTools dentro do contentor. | | `OMNIROUTE_VNC_CONTAINER_PROFILE_DIR` | `/config` | `src/lib/vncSession/manifest.ts` | Diretório de perfil dentro do contentor. | | `OMNIROUTE_VNC_PROFILE_DIR` | _(desativado)_ | `src/lib/vncSession/manifest.ts` | Diretório do lado do host para perfis de navegador persistentes. | | `OMNIROUTE_VNC_IDLE_MS` | `600000` | `src/lib/vncSession/manifest.ts` | Tempo limite de inatividade (ms) antes de uma sessão VNC ser recolhida. | | `OMNIROUTE_VNC_MAX_MS` | `1800000` | `src/lib/vncSession/manifest.ts` | Duração máxima da sessão (ms). | | `OMNIROUTE_VNC_MAX_SESSIONS` | `4` | `src/lib/vncSession/manifest.ts` | Máximo de sessões VNC simultâneas. | | `OMNIROUTE_VNC_READY_MS` | `45000` | `src/lib/vncSession/manifest.ts` | Tempo limite de prontidão do navegador (ms). | | `OMNIROUTE_VNC_HARVEST_MS` | `20000` | `src/lib/vncSession/manifest.ts` | tempo limite Harvest/cleanup (ms). | | `OMNIROUTE_VNC_NETWORK` | `omniroute-vnc-browser-login` | `src/lib/vncSession/manifest.ts` | Rede Docker dedicada à qual o contentor se junta (#12571), fora da ponte padrão. | | `VIBEPROXY_DATA_DIR` | _(desativado)_ | `open-sse/services/notionThreadSessions.ts` | Directório para persistência de sessão de thread Notion. | ### Autenticação de serviço interno | Variável | Predefinição | Descrição | | --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN` | – | Token incorporado para autenticação de serviço a serviço no plano de gestão. | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE` | – | Caminho para um ficheiro que contém o token de serviço interno (preferencial em contentores; substitui a variável incorporada). | ### estatísticas do fornecedor OpenRouter | Variável | Predefinição | Descrição | | ----------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `OPENROUTER_PROVIDER_STATS_ENABLED` | `true` | Defina como `false` para ignorar a pesquisa de estatísticas OpenRouter por fornecedor para enriquecimento de catálogo. | | `OPENROUTER_PROVIDER_STATS_TTL_MS` | `3600000` | Cache TTL (ms) para as estatísticas do fornecedor OpenRouter pesquisadas. | ### Ligação Redis incorporada | Variável | Predefinição | Descrição | | --------------------------- | ------------ | ------------------------------------------------------------------------------- | | `REDIS_BIND_HOST` | `127.0.0.1` | Endereço de ligação para o serviço Redis integrado. | | `REDIS_PORT` | `6379` | Porta para o serviço Redis integrado. | | `OMNIROUTE_REDIS_BIND_HOST` | – | Substituição no âmbito do OmniRoute para o endereço de ligação Redis integrado. | --- ## 24. Lançamento de adições v3.8.50 Estas definições foram introduzidas após o instantâneo anterior do contrato ambiental. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_CHAT_ADMISSION_QUEUE_MS` | `2000` | `src/shared/middleware/chatBodyAdmission.ts` | Espera máxima por um slot de admissão de chat pesado antes de uma nova tentativa `503`; uma espera curta e limitada serializa rajadas de agente em vez de um `503` instantâneo. `0` restabelece a rejeição imediata. | | `OMNIROUTE_CHAT_ADMISSION_MAX_QUEUED_BYTES` | `4194304` (4 MB) | `src/shared/middleware/chatBodyAdmission.ts` | Orçamento de bytes em fila para a espera de admissão: limita o total de bytes do corpo em buffer estacionados em todo o processo para que a espera não possa amplificar o heap (#4380). As esperas acima do orçamento recebem um `503` repetível imediatamente. | | `OMNIROUTE_CHAT_VIRTUAL_TTL_MS` | `60000` (60s) | `src/shared/middleware/chatBodyAdmission.ts` | Modo autónomo obsoleto desde #10110: as faixas de admissão por sessão foram removidas em favor de um orçamento para todo o processo. Aceite para compatibilidade de configuração; ignorado. | | `OMNIROUTE_CHAT_VIRTUAL_MAX_SESSIONS` | `64` | `src/shared/middleware/chatBodyAdmission.ts` | Modo autónomo obsoleto desde #10110: as faixas de admissão por sessão foram removidas em favor de um orçamento para todo o processo. Aceite para compatibilidade de configuração; ignorado. | | `OMNIROUTE_CHAT_VIRTUAL_LANES` | `0` (desligado) | `open-sse/services/admission/runtime.ts` | Gamas de admissão virtual de tempo de execução adaptativo (#9654): switch mestre para o gate adaptativo por tenant (sistema 2). Distinto dos vars obsoletos de pista por ligação acima (TTL_MS / MAX_SESSIONS, sem operação desde #10110). Sinalizador de recurso do painel com o mesmo nome; o env var ganha a substituição do painel; requer reinicialização. | | `OMNIROUTE_RUNNOW_TIMEOUT_MS` | `30000` | `src/app/api/jobs/[id]/run-now/route.ts` | Limita o tempo que uma chamada run-now aguarda por um trabalho em curso antes de iniciar a execução na fila. | | `ADOBE_FIREFLY_BROWSER_REFRESH` | habilitado | `open-sse/services/adobeFireflySession.ts` | Mantém o estado IMS e de risco do browser atualizado através de sessões CDP do Chrome no âmbito da conta; defina `0` para desativar. | | `ADOBE_FIREFLY_SESSION_DISK` | habilitado | `open-sse/services/adobeFireflySession.ts` | Persiste as sessões reparadas da Adobe em `DATA_DIR`; defina `0` para estado apenas de memória. | | `ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS` | `12000` | `open-sse/services/adobeFireflySession.ts` | Espaçamento mínimo entre envios gerados pelo Adobe Firefly. | | `ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS` | `15000` | `open-sse/services/adobeFireflySession.ts` | Período extra silencioso após cada terceiro envio bem-sucedido da Adobe. | | `ADOBE_FIREFLY_CHROME_HEADLESS` | `0` | `open-sse/services/adobeFireflyBrowserLogin.ts` | Modo true-headless apenas de depuração; O Adobe Colligo rejeita normalmente a sessão de risco resultante. | | `CHROME_PATH` | detecção automática | `open-sse/executors/cloudflare-playground.ts`, `open-sse/executors/chatgpt-web-codex.ts` | Executável absoluto opcional do Chrome utilizado pelos executores acionados pelo navegador quando a deteção automática da plataforma é insuficiente. | | `TELEGRAM_BOT_TOKEN` | _(desativado)_ | `src/lib/telegram/config.ts` | Token BotFather que ativa o webhook de entrada e subscreve a Mini App `initData`. | | `TELEGRAM_WEBHOOK_SECRET` | _(desativado)_ | `src/lib/telegram/config.ts` | Segredo partilhado registado via `setWebhook` e verificado no cabeçalho `X-Telegram-Bot-Api-Secret-Token` em cada entrega de webhook. Obrigatório para o caminho do webhook; unset significa que as entregas do webhook foram recusadas com o 503. | | `TELEGRAM_DEFAULT_MODEL` | `auto/chat` | `src/lib/telegram/chatProxy.ts` | Modelo utilizado para respostas de chat Telegram. | | `TELEGRAM_BOT_API_BASE` | `https://api.telegram.org` | `src/lib/telegram/config.ts` | Substituição do Bot API base URL para proxies ou servidores Bot API auto-hospedados. | | `TELEGRAM_WEBHOOK_TIMEOUT_MS` | `60000` | `src/lib/telegram/config.ts` | Tempo limite em milissegundos para chamadas de saída Bot API. | | `TELEGRAM_USER_ALLOWLIST_ENABLED` | `false` | `src/lib/telegram/config.ts` | Defina como `true` para servir apenas os utilizadores Telegram listados em `TELEGRAM_ALLOWED_USER_IDS` (outros: Mini App 403, mensagem webhook descartada). Desativado por defeito: cada utilizador Telegram é atendido e recebe uma chave API cunhada que gasta a quota upstream. | | `TELEGRAM_ALLOWED_USER_IDS` | _(desativado)_ | `src/lib/telegram/config.ts` | IDs de utilizador Telegram numéricos separados por vírgula apresentados quando `TELEGRAM_USER_ALLOWLIST_ENABLED=true`. As entradas que não sejam números inteiros positivos simples são ignoradas com um aviso único. Ignorado enquanto a lista de permissões está desativada; vazio com a lista de permissões ativada não serve ninguém. | | `OMNIROUTE_OPTIONAL_PACK_TAR` | `1` (habilitado) | `scripts/build/optionalPackStaging.mjs` | Configure `0` para ignorar a emissão de tarballs `.tar.gz` enquanto prepara pacotes ML/browser opcionais para a árvore autónoma Electron (os diretórios de pacotes e `optional-packs.index.json` ainda são produzidos). Utilizado pelo fluxo de trabalho de versão para desktop para reduzir o tamanho do carregamento do artefacto. | | `GROK_SUBSCRIPTION_IMAGES_ENABLED` | `false` | `open-sse/config/imageRegistry.ts` | Permite o registo das rotas de imagem de assinatura xAI ; desativado por defeito para que o caminho da imagem da chave API permaneça inalterado. | | `OMNIROUTE_API_KEY_COOLDOWN_MS` | `60000` | `open-sse/services/apiKeyRotator.ts` | Tempo de espera por chave em milissegundos quando uma resposta `429` não tem nenhuma dica `Retry-After` utilizável. | | `OMNIROUTE_ESTIMATOR_CALIBRATION` | habilitado | `open-sse/services/estimatorCalibration.ts` | Defina como `off`, `0` ou `false` para desativar a gravação e aplicação de calibração do estimador na memória. | | `NEXT_MANUAL_SIG_HANDLE` | _(interno)_ | `scripts/dev/standalone-server-ws.mjs` | Substituição interna do manipulador de sinal do servidor independente; normalmente definido e limpo pelo lançador em vez de configurado pelos operadores. | | `CHATGPT_WEB_TURN_TIMEOUT_MS` | `180000` | `open-sse/utils/chatgptWebExecutorAdapter.ts` | Teto por turno para um turno de texto ChatGPT Web (Sala Limpa); valores abaixo de `1000` são ignorados. | | `CHATGPT_WEB_TOOL_TURN_TIMEOUT_MS` | `180000` | `open-sse/utils/chatgptWebExecutorAdapter.ts` | Teto por turno para um turno ChatGPT Web (Sala Limpa) que carrega ferramentas de cliente (envelope `` emulado); baixe-o para devolver o controlo ao cliente mais cedo. Os valores abaixo de `1000` são ignorados. | | `CHATGPT_WEB_HEADLESS` | `1` (sem cabeça) | `open-sse/utils/chatgptWebExecutorAdapter.ts` | Execute o navegador ChatGPT Web (Sala Limpa) sem cabeça. Defina `0` apenas para contas cujo desafio primário rejeita o modo headless (o padrão mudou de headless para headless em #14948). | | `CHATGPT_WEB_BROWSER_ACQUIRE_TIMEOUT_MS` | `45000` | `open-sse/utils/chatgptWebExecutorAdapter.ts` | Limite máximo para iniciar o navegador ChatGPT Web (Sala Limpa) e aquecer o chatgpt.com, para que um navegador ou sessão inoperacional não possa consumir o prazo da fila de pedidos. | | `UI_KIT_CLONE` | `_references/cheaper-inference-ui-kit` | `scripts/check/check-ui-kit-snapshot.mjs` | Caminho do kit CI UI privado para clonar o portão de instantâneo do fornecedor comparando `packages/ui-kit/src` com (KEA-7886); o portão salta com um aviso quando o clone está ausente. | ### ChatGPT Web (Codex) Padrões globais para o navegador headless e o túnel de ferramentas expandido. Im Dashboard gesetzte Connection-Werte haben Vorrang. | Variável | Predefinição | Arquivo de origem | Descrição | | --------------------------------------- | ------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CHATGPT_WEB_CODEX_CHROME_PATH` | _(detecção automática)_ | `open-sse/executors/chatgpt-web-codex.ts` | Explique Chrome-/Chromium-Pfad para npm-, systemd- e PM2-Betrieb. | | `CHROME_PATH` | _(detecção automática)_ | `open-sse/executors/chatgpt-web-codex.ts` | Gemeinsamer Fallback para um Chrome-/Chromium-Pfad. explícito | | `CHATGPT_WEB_CODEX_CDP_URL` | _(desativado)_ | `open-sse/executors/chatgpt-web-codex.ts` | Interno CDP-Endpunkt; Docker usa o Sidecar no Porto `9223`. | | `CHATGPT_WEB_CODEX_USE_CDP_PROFILE` | _(desativar — )_ | `open-sse/vendor/codex-chatgpt-web/persistent-cdp-context.ts` | Defina como `1` (com um endpoint CDP configurado) para reutilizar a página ChatGPT existente do perfil do browser ligado e gerido externamente em vez de um contexto isolado por turno; também limita as guias ChatGPT simultâneas em 1. Desativado por defeito. Consulte [perfil CDP persistente](../guides/CHATGPT-WEB-PERSISTENT-CDP.md). | | `CDP_PROXY_TOKEN` | _(desativado)_ | `docker/chatgpt-web-codex-browser/cdp-proxy.mjs` | Se for obtido, deve fazer a transferência e o CDP-Proxy-Sidecar neste local no cabeçalho `X-Omni-Cdp-Token` mitschicken (#13679). Ohne Wert deut der Proxy unauthentifiziert weiter — dann schützt nur die Netzisolierung des Compose-Netzes `chatgpt-web-codex-net`. Erzeugen com `openssl rand -hex 32`. | | `CHATGPT_WEB_CODEX_TUNNEL_ID` | _(desativado)_ | `open-sse/executors/chatgpt-web-codex.ts` | ID de túnel OpenAI global para execução de ferramenta Codex local. | | `CHATGPT_WEB_CODEX_RUNTIME_KEY` | _(desativado)_ | `open-sse/executors/chatgpt-web-codex.ts` | Chave de tempo de execução do túnel Globaler; niemals em Logs ausgeben. | | `CHATGPT_WEB_CODEX_CONNECTOR_NAME` | `OmniRoute Codex v2` | `open-sse/executors/chatgpt-web-codex.ts` | Nome exato dos novos conectores ChatGPT personalizados para a porta MCP. | | `CODEX_CHATGPT_WEB_HOME` | `/chatgpt-web-codex` | `open-sse/vendor/codex-chatgpt-web/config.ts` | Dediziertes Verzeichnis für Browser, Broker e Tunnelzustand. | | `CODEX_CHATGPT_WEB_BROWSER_DIAGNOSTICS` | `0` | `open-sse/vendor/codex-chatgpt-web/adapters/chatgpt-web/browser-worker.ts` | Bei `1` werden Browser-Diagnosebilder e jedem Checkpoint erfasst. | | `CODEX_CHATGPT_WEB_LAUNCHER` | _(desativado)_ | `open-sse/vendor/codex-chatgpt-web/config.ts` | Opcionalmente absoluto Pfad zu einem dauerhaften Launcher-Binary. | | `CODEX_CHATGPT_WEB_BUN` | _(detecção automática)_ | `open-sse/vendor/codex-chatgpt-web/config.ts` | Opcionalmente absoluto Pfad zum Bun-Runtime-Binary. | | `CODEX_WEB_GPT_BUN` | _(desativado)_ | `open-sse/vendor/codex-chatgpt-web/config.ts` | Legacy-Fallback para `CODEX_CHATGPT_WEB_BUN`; As novas configurações usam o nome canónico. | --- ## Ponte OmniConductor Consumidor SSE de longa duração que espelha as tarefas do hub OmniConductor no TaskManager A2A (`src/lib/conductor/`). Opte por — a ponte só arranca quando `CONDUCTOR_HUB_URL` está definido. Apenas no lado do servidor: o token do hub nunca deve chegar ao browser. | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------ | ----------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `CONDUCTOR_HUB_URL` | _(vazio)_ | `src/lib/conductor/boot.ts` | Base URL do hub OmniConductor (por exemplo, `http://127.0.0.1:7910`). Desativar ponte = desativada. | | `CONDUCTOR_HUB_TOKEN` | _(vazio)_ | `src/lib/conductor/boot.ts` | A credencial do hub para o SSE — feed emite um peer `spokesperson` -kind no hub (`POST /v1/peers`, admin). | | `CONDUCTOR_ORCHESTRATOR_TOKEN` | _(vazio)_ | `src/lib/conductor/hubProxy.ts` | Credencial para delegação de tarefas do hub A2A→ de entrada (`POST /v1/tasks`); volta a `CONDUCTOR_HUB_TOKEN` quando não está definido. | | `CONDUCTOR_SPOKESPERSON_URL` | `http://127.0.0.1:7920` | `src/lib/conductor/faroProxy.ts` | Base URL do serviço porta-voz (Faro) por detrás do proxy de chat do dashboard (`/api/conductor/ask`). | ### Agendamento com reconhecimento de quota Utilizado por `open-sse/services/combo.ts` e `src/lib/quota/quotaScheduler.ts` para verificações de orçamento de tokens pré-solicitação. O comportamento de encaminhamento padrão — opt-in permanece inalterado quando não está definido. | Variável | Predefinição | Arquivo de origem | Descrição | | ---------------------------------- | ------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OMNIROUTE_QUOTA_AWARE_ROUTING` | `0` | `open-sse/services/combo.ts` | Quando `1`, ignore as ligações cujo orçamento de token por janela (`rateLimitOverrides.tpm`, tabela `provider_quota_state`) não possa suportar o custo estimado do pedido antes do envio. Fail-open quando não há orçamento configurado. | | `OMNIROUTE_ESTIMATOR_CALIBRATION` | _(em)_ | `open-sse/services/estimatorCalibration.ts` | Calibração de feedback do estimador de token de proteção de contexto (#14931): por (fornecedor, modelo, ferramentas presentes) EMA de `usage.prompt_tokens` /estimativa, fixado em 0,15–2,0, apenas na memória. `off`, `0` ou `false` desativa a gravação e a aplicação. | | `GROK_SUBSCRIPTION_IMAGES_ENABLED` | `false` | `open-sse/config/imageRegistry.ts` | Regista as rotas de imagem `xai-oauth` (`xao`) e `grok-cli`. Sinalizador de recurso do painel com o mesmo nome; uma substituição DB vence esse valor. | ## Diagnóstico de sincronização de modelos | Variável | Predefinição | Arquivo de origem | Descrição | | ------------------------------ | ------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_MODEL_SYNC_TIMINGS` | `0` | `src/lib/providerModels/modelSyncTimings.ts` | Defina como `1` para registar o tempo de fase, um pedido ID gerado e os resultados de fase success/error durante a sincronização do modelo. Desativado para todos os outros valores. Os registos omitem as cargas úteis de pedido, conta, catálogo e erro. | ## Ferramenta local de análise de multimédia do OpenCode Utilizada por `scripts/cli/omniroute-media-mcp.mjs`. Defina estas variáveis no ambiente do processo da ferramenta local. | Variável | Predefinição | Descrição | | -------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_MEDIA_CONFIG` | `$XDG_CONFIG_HOME/opencode/opencode.json` (ou `~/.config/opencode/opencode.json`) | Configuração do OpenCode lida pela ferramenta de multimédia e pelo instalador. | | `OMNIROUTE_MEDIA_PROVIDER` | `omniroute` | Entrada do fornecedor lida pela ferramenta de multimédia a partir da configuração do OpenCode. | | `OMNIROUTE_MEDIA_MODEL` | `auto` | Modelo submetido pela ferramenta de multimédia. O respetivo fornecedor tem de suportar os tipos de multimédia solicitados. | | `OMNIROUTE_MEDIA_API_KEY` | Chave de API do fornecedor configurado ou a respetiva referência de ambiente | Substituição opcional da credencial. Mantenha-a no ambiente do processo local; nunca a submeta para o repositório. |