# 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 de todas as variáveis de ambiente reconhecidas pelo OmniRoute. > Para obter um modelo de início rápido, consulte [`.env.example`](../../.env.example). > [!IMPORTANT] > Todas as variáveis documentadas aqui também têm de constar em `.env.example`, e > todas as variáveis em `.env.example` têm de constar aqui. `npm run check:env-doc-sync` > valida esta correspondência em cada commit e na CI. Para omitir intencionalmente uma variável, adicione-a à > lista de permissões em `scripts/check/check-env-doc-sync.mjs`. --- ## Índice - [1. Segredos obrigatórios](#1-segredos-obrigatórios) - [2. Armazenamento e base de dados](#2-armazenamento-e-base-de-dados) - [3. Rede e portas](#3-rede-e-portas) - [4. Segurança e autenticação](#4-segurança-e-autenticação) - [5. Sanitização de entradas e proteção de PII](#5-sanitização-de-entradas-e-proteção-de-pii) - [6. Políticas de ferramentas e encaminhamento](#6-políticas-de-ferramentas-e-encaminhamento) - [7. URLs e sincronização com a nuvem](#7-urls-e-sincronização-com-a-nuvem) - [8. Proxy de saída](#8-proxy-de-saída) - [9. Integração de ferramentas de CLI](#9-integração-de-ferramentas-de-cli) - [10. Integrações internas de agentes e MCP](#10-integrações-internas-de-agentes-e-mcp) - [11. Credenciais de fornecedores OAuth](#11-credenciais-de-fornecedores-oauth) - [12. Substituições de User-Agent dos fornecedores](#12-substituições-de-user-agent-dos-fornecedores) - [13. Compatibilidade de impressão digital da CLI](#13-compatibilidade-de-impressão-digital-da-cli) - [14. Fornecedores de chaves de API](#14-fornecedores-de-chaves-de-api) - [15. Definições de tempo limite](#15-definições-de-tempo-limite) - [16. Registo](#16-registo) - [17. Otimização da memória](#17-otimização-da-memória) - [18. Sincronização de preços](#18-sincronização-de-preços) - [19. Sincronização de modelos (desenvolvimento)](#19-sincronização-de-modelos-desenvolvimento) - [20. Definições específicas dos fornecedores](#20-definições-específicas-dos-fornecedores) - [21. Estado do proxy](#21-estado-do-proxy) - [22. Depuração](#22-depuração) - [23. Integração com o GitHub](#23-integração-com-o-github) - [24. Sandbox de competências (v3.8.0+)](#24-sandbox-de-competências-v380) - [27. Feed do Radar (alojamento próprio)](#27-feed-do-radar-alojamento-próprio) - [Cenários de implementação](#cenários-de-implementação) - [Auditoria: variáveis removidas/inativas](#auditoria-variáveis-removidas--inativas) --- ## 1. Segredos Obrigatórios Os segredos não definidos marcados como **Sim** são gerados automaticamente na primeira execução (`JWT_SECRET`, `API_KEY_SECRET`) e guardados em `server.env` no diretório de dados — defina-os explicitamente quando esse diretório for efémero. A exceção é `OMNIROUTE_WS_BRIDGE_SECRET`: não é guardado em `server.env` — os pontos de entrada do servidor cunham um valor efémero por arranque que apenas a ponte no próprio processo pode utilizar, pelo que os clientes externos da ponte precisam de o definir explicitamente. | Variável | Obrigatório | Predefinição | Ficheiro de Origem | Descrição | | ---------------------------- | ------------------ | ------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `JWT_SECRET` | **Sim** | _(nenhuma)_ | `src/lib/auth` | Assina/verifica todos os cookies de sessão do painel (JWT). Gere com `openssl rand -base64 48`. | | `API_KEY_SECRET` | **Sim** | _(nenhuma)_ | `src/lib/db/apiKeys.ts` | Chave de encriptação AES para os valores das chaves de API armazenados no SQLite. Gere com `openssl rand -hex 32`. | | `INITIAL_PASSWORD` | Não | _(não definido)_ | `src/lib/auth/managementPassword.ts` | Define a palavra-passe do painel no arranque enquanto nenhuma estiver guardada; é ignorado assim que exista uma palavra-passe guardada. As instalações npm e a partir do código-fonte copiam `.env.example` para `.env`, pelo que arrancam com o seu marcador de posição publicamente conhecido `CHANGEME`: substitua-o antes do primeiro arranque, ou defina `INITIAL_PASSWORD=` (vazio) nesse `.env` para criar a palavra-passe no assistente de configuração inicial na primeira visita, tal como faz um valor não definido (a predefinição da imagem Docker). Altere uma palavra-passe guardada em Painel → Definições → Segurança, ou execute `omniroute reset-password` (`node bin/reset-password.mjs` num checkout do código-fonte) com `DATA_DIR` definido para o diretório de dados do servidor. | | `OMNIROUTE_WS_BRIDGE_SECRET` | **Sim** (produção) | _(não definido)_ | `src/app/api/internal/codex-responses-ws/route.ts` | Segredo partilhado para a ponte WebSocket interna de Respostas Codex. Autentica os pedidos da ponte entre o retransmissor WS do Electron/navegador e o OmniRoute. ⚠️ **OBRIGATÓRIO em produção — quando não está definido, todos os pedidos à ponte WS são rejeitados.** Gere com `openssl rand -base64 32`. | | `OMNIROUTE_SW_BUILD_ID` | Não | _(SHA do git)_ | `next.config.mjs`, `scripts/build/assembleStandalone.mjs` | ID explícito para invalidação da cache do service worker da shell da PWA (#11779); primeiro na cadeia de resolução. | | `SOURCE_VERSION` | Não | _(não definido)_ | `next.config.mjs`, `scripts/build/assembleStandalone.mjs` | Segundo na cadeia — definido pelos sistemas de compilação PaaS (por exemplo, ao estilo do Heroku) como o commit implementado. | | `NEXT_PUBLIC_SW_BUILD_ID` | Não | _(derivado)_ | `src/shared/components/PwaRegister.tsx` | Valor público definido durante a compilação que o cliente utiliza para registar `/sw.js?v=…`; derivado dos dois anteriores e, em seguida, do SHA do git. | | `OMNIROUTE_PEER_STAMP_TOKEN` | Não (automático) | _(automático em cada arranque)_ | `src/server/authz/policies/management.ts` | Segredo por processo que comprova que a marca do IP do par fidedigno provém do próprio servidor HTTP do OmniRoute (`scripts/dev/peer-stamp.mjs`). O middleware de autorização só confia na localidade do pedido (restrição a loopback/LAN das rotas LOCAL_ONLY) quando a marca contém este token. Gerado automaticamente em cada arranque — deixe-o por definir; fixe-o apenas em configurações com vários processos que tenham de partilhar a marca. | | `OMNIROUTE_TRUSTED_PROXIES` | Não | _(não definido)_ | `scripts/dev/peer-stamp.mjs` | IPs ou intervalos CIDR, separados por vírgulas, de proxies inversos cujos cabeçalhos `X-Forwarded-For` / `X-Real-IP` podem ser considerados fidedignos pela lista de permissões/bloqueios de IP, além dos endereços de loopback, dos endereços de redes privadas e dos nós periféricos da Cloudflare, que são sempre considerados fidedignos. Necessário apenas para um proxy em qualquer outro endereço público; caso contrário, o filtro avalia o endereço do próprio proxy. | ### Comandos de Geração ```bash # Gerar os quatro segredos de uma só vez: 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 submeta ficheiros `.env` com segredos reais ao controlo de versões. O `.gitignore` já exclui `.env`, mas confirme antes de efetuar o push. --- ## 2. Armazenamento e Base de Dados O OmniRoute utiliza **SQLite** (através de `better-sqlite3`) para toda a persistência. Estas variáveis controlam a localização, encriptação e ciclo de vida dos dados. | Variável | Predefinição | Ficheiro de Origem | Descrição | | ------------------------------------------ | ----------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATA_DIR` | `~/.omniroute/` | `src/lib/db/core.ts` | Diretório raiz para a base de dados SQLite, cópias de segurança e ficheiros de dados. Substitua-o para volumes Docker ou caminhos personalizados. | | `OMNIROUTE_ALLOW_DEFAULT_DATA_DIR` | _(não definida)_ | `src/lib/dataPaths.ts` | Mecanismo de escape para a proteção de DATA_DIR em testes/avaliações (#10428). Os testes e as sondas de avaliação/impressão do Node (`-e`/`--eval`/`-p`/`--print`, incluindo as formas `--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 a utilizar o diretório real. | | `OMNIROUTE_BUILD_SHA` | _(não definida)_ | `src/lib/monitoring/buildSha.ts` | SHA Git do artefacto em execução. Registado por `npm run build:release`; pode ser injetado em contentores distribuídos sem o sentinela `dist/BUILD_SHA`. Exposto como `system.buildSha` em `/api/monitoring/health`. | | `OMNIROUTE_RELEASE_REF` | `origin/main` | `scripts/build/buildProvenance.ts` | Referência relativamente à qual o controlo de proveniência do artefacto empacotado verifica o SHA da compilação (#10427). | | `OMNIROUTE_ALLOW_CANARY_BUILD` | _(não definida)_ | `scripts/build/buildProvenance.ts` | Defina como `1` para permitir o empacotamento de uma compilação cujo SHA não se encontra na linha de lançamento, registando-a como uma versão canário deliberada em vez de fazer falhar o controlo (#10427). | | `OMNIROUTE_SMOKE_API_KEY` | _(não definida)_ | `scripts/ops/deploy-canary.mjs` | Chave de API para a sonda de verificação rápida da implementação canário, enviada como `Authorization: Bearer` para `/v1/chat/completions`. Utilizada apenas pelo script de implementação (#10429), nunca pelo servidor. Não está relacionada com as variáveis `OMNIROUTE_SMOKE_*` do mecanismo de verificação rápida da CLI que requer ativação explícita (`RUN_CLI_SMOKE=1`, `OMNIROUTE_SMOKE_BASE_URL/MODEL/API_KEY_ENV/TARGETS/TIMEOUT_MS` em `tests/integration/upstream-cli-smoke.int.test.ts`) — consulte [Integrações da CLI → Verificação rápida real](../guides/CLI-INTEGRATIONS.md). | | `OMNIROUTE_BUILDING` | _(não definida)_ | `src/lib/buildPhase.ts` | Sinal da fase de compilação (#10060): definido como `1` por `scripts/build/build-next-isolated.mjs` e herdado por todos os processos de trabalho de compilação iniciados, para que a camada da base de dados devolva um substituto sem operações em vez de carregar o módulo nativo better-sqlite3 (que termina abruptamente o processo de trabalho ao sair). Nunca é definido 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é-compilação das dependências nativas em árvores de dependências integradas pouco comuns. Isto não torna compilável uma dependência em falta; utilize apenas quando as dependências nativas forem fornecidas externamente. | | `OMNIROUTE_DATA_DIR` | _(não definida)_ | `open-sse/executors/promptql/threadSticky.ts` | **Alias de recurso** para `DATA_DIR`, verificado apenas quando `DATA_DIR` não está definida. Utilizado para localizar a cache em disco das sessões persistentes por conversa do executor PromptQL (`/promptql-thread-sessions.json`); se nenhuma das variáveis estiver definida, a cache permanece apenas na memória (não é mantida entre reinícios). | | `OMNIROUTE_PLUGINS_DIR` | _(não definida)_ | `src/lib/plugins/scanner.ts` | Diretório lido pelo **analisador de plugins em tempo de execução** — e diretório raiz no qual o gestor de plugins efetua a instalação — substituindo a predefinição derivada do diretório pessoal (#11827). Aponte-o para a árvore de plugins montada por associação no Docker/K8s, em vez de alterar HOME apenas para mudar o caminho de análise (HOME também controla todos os outros comportamentos relativos ao diretório pessoal). Não definida = `~/.omniroute/plugins`, ou `/tmp/.omniroute/plugins` quando o processo não exporta qualquer diretório pessoal — evitando assim a ausência silenciosa de deteção que esta variável resolve. O diretório resolvido é registado uma vez no arranque como `scanner.dir_resolved`, juntamente com o valor de entrada utilizado. Apenas no lado do servidor: os plugins de comandos da 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 integral da base de dados SQLite em repouso. Gere-a com `openssl rand -hex 32`. | | `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/build/bootstrap-env.mjs`, `electron/main.js` | Etiqueta de versão da chave de encriptação. Incremente-a ao efetuar a rotação da chave para permitir a desencriptação de cópias de segurança antigas. | | `DISABLE_SQLITE_AUTO_BACKUP` | `false` | `src/lib/db/backup.ts` | Quando definido como `true`, ignora as cópias de segurança de rotina/anteriores à escrita do ficheiro SQLite (guardar/limpar preços de models.dev, escritas de definições). As cópias de segurança manuais e anteriores ao restauro continuam a ser executadas. **Não** desativa o instantâneo de segurança durável obrigatório do executor de migrações nem a proteção contra migrações em massa para uma BD persistente existente. As cópias de segurança não manuais são limitadas a, no máximo, uma a cada 60 minutos. A opção **Definições → Armazenamento** do painel pode desativar de forma independente a cópia de segurança automática de rotina. | | `OMNIROUTE_CRYPT_KEY` | _(não definida)_ | `src/lib/db/encryption.ts` | **Alias legado** de `STORAGE_ENCRYPTION_KEY`. Aceite como alternativa quando a variável principal não está presente. | | `OMNIROUTE_API_KEY_BASE64` | _(não definida)_ | `src/lib/db/encryption.ts` | **Alias legado** (formato codificado em Base64) aceite como alternativa. É descodificado automaticamente antes da utilização. | | `OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS` | _(não definida)_ | `src/lib/db/core.ts` | Substitui o intervalo da verificação periódica do estado do SQLite (ms). Quando não está definido, os valores predefinidos são derivados de `NODE_ENV`. | | `OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS` | _(removida)_ | `src/lib/db/walMaintenance.ts` | **Removida.** Uma execução periódica de `wal_checkpoint(TRUNCATE)` em atividade pode invalidar o mapeamento wal-index partilhado e provocar a falha do processo com SIGBUS (#13973), pelo que o agendador deixou de existir. A variável está inerte: um valor positivo regista uma única vez um aviso de descontinuação, enquanto `0` ou a ausência de um valor não produz qualquer aviso. O WAL é mantido por checkpoints PASSIVE (abaixo) e truncado pelo checkpoint de encerramento. | | `OMNIROUTE_WAL_PASSIVE_INTERVAL_MS` | `300000` (5 min.) | `src/lib/db/walMaintenance.ts` | Substitui o intervalo frequente de `wal_checkpoint(PASSIVE)` (ms). Mantém reduzido o número de frames WAL pendentes, para que os checkpoints permaneçam rápidos e o tamanho do ficheiro WAL se mantenha limitado entre truncamentos de encerramento. `0` desativa esta funcionalidade. | | `OMNIROUTE_WAL_GUARD_MAX_MB` | `256` | `src/lib/db/walMaintenance.ts` | Quando uma execução PASSIVE deteta que o ficheiro WAL excede este tamanho, executa `wal_checkpoint(RESTART)` para que o WAL recomece sem reescrever o wal-index mapeado. Os checkpoints em modo de truncamento durante a execução foram removidos (consulte a linha `OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS`). | | `OMNIROUTE_PRESSURE_SELF_RESTART` | `false` | `open-sse/utils/resourcePressure.ts` | Defina como `1`/`true`/`yes`/`on` para terminar o processo após a pressão crítica sobre os recursos se manter durante `OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS`, permitindo que um supervisor (systemd `Restart=always`, política de reinício do Docker) reponha um processo limpo, em vez de devolver respostas 503 indefinidamente. | | `OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS` | `120000` (2 min.) | `open-sse/utils/resourcePressure.ts` | Período durante o qual a pressão crítica tem de persistir antes de ser acionada a saída para reinício automático. | | `OMNIROUTE_PRESSURE_PSI_DISABLED` | `false` | `open-sse/utils/resourcePressurePolicy.ts` | Defina como `1`/`true`/`yes`/`on` para ignorar `/proc/pressure/memory` (`psi_some` / `psi_full`) ao nível do anfitrião quando um vizinho ruidoso provoca respostas 503 apesar de este processo estar a funcionar normalmente (#13124). As proteções de cgroup e da heap V8 permanecem ativas. O PSI também deixa de contar como prova de limitação pelo kernel para `cgroup_high`: um total de cgroup superior a `memory.high` passa então a ser considerado crítico apenas quando ocorre um aumento de `high`/`max` em `memory.events`. Sem `memory.events`, é mantido o rácio bruto. | | `OMNIROUTE_SQLJS_WASM_PATH` | _(deteção automática)_ | `src/lib/db/adapters/sqljsAdapter.ts` | Caminho explícito (absoluto ou relativo ao cwd) para `sql-wasm.wasm` ao utilizar o adaptador de recurso `sql.js` WASM. Quando não está definido, é detetado automaticamente através das dependências do pacote e das disposições candidatas. | | `OMNIROUTE_BATCH_RETENTION_DAYS` | `30` | `src/lib/db/cleanup.ts` | Número de dias durante os quais os checkpoints, os ficheiros de entrada/saída/erro referenciados e a linha de uma tarefa terminal (concluída/com falha/cancelada/expirada) da Batch API são mantidos pela limpeza automática antes de serem eliminados. Só entra em vigor quando `BATCH_AND_FILE_AUTO_CLEANUP_ENABLED` está ativada; corresponde ao período de retenção de resultados da Batch API da própria OpenAI. Não afeta a rota `DELETE /api/v1/batches/delete-completed` acionada pelo operador, que, por conceção, permanece incondicional (sem filtro de idade). | | `BATCH_AND_FILE_AUTO_CLEANUP_ENABLED` | `false` | `src/lib/db/cleanup.ts` | Quando definido como `true`, permite que a limpeza automática elimine tarefas terminais da Batch API (e os respetivos pontos de controlo) que tenham ultrapassado `OMNIROUTE_BATCH_RETENTION_DAYS` e limpe o conteúdo BLOB dos ficheiros carregados que tenham ultrapassado o respetivo `expires_at`. Desativado por predefinição: todas as instalações existentes mantêm estes dados exatamente como antes até um operador optar por ativar esta funcionalidade. É também um sinalizador de funcionalidade editável no painel — consulte `docs/reference/FEATURE_FLAGS.md` → Execução. | | `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 estado da base de dados 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 de verificação de estado da base de dados, mesmo quando normalmente seria ignorado (por exemplo, em tarefas de curta duração). | | `OMNIROUTE_SKIP_POSTINSTALL` | `0` | `scripts/postinstall.mjs` | Defina como `1` para ignorar o aquecimento do ambiente de execução nativo durante `npm install`. Útil em instalações de CI/sem interface, nas quais o sqlite já está compilado. | | `OMNIROUTE_MIGRATIONS_DIR` | _(deteção automática)_ | `src/lib/db/migrationRunner.ts` | Substitui o diretório analisado pelo executor de migrações. Útil ao distribuir migrações agrupadas em compilações personalizadas. | | `OMNIROUTE_EXTRA_MIGRATIONS_DIRS` | _(não definido)_ | `src/lib/db/migrationRunner/extraDirs.ts` | Diretórios de migração adicionais como entradas `namespace=dir`, separadas pelo delimitador de caminhos da plataforma (por exemplo, `ee=/opt/app/enterprise/db/migrations`). Os ficheiros aí encontrados são registados como `-`, para que uma distribuição que inclua as suas próprias migrações nunca entre em conflito com os intervalos numéricos do projeto original. Uma entrada malformada, um espaço de nomes inválido ou um diretório em falta provoca um erro 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). O arranque é interrompido se houver mais migrações pendentes do que este limite numa base de dados existente (protege contra uma tabela de controlo apagada). Aumente-o para restaurar uma cópia de segurança mais antiga; 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 controlo de lançamento `check:install-upgrade`. Necessita de aproximadamente 12 GB (duas árvores de instalação de ~3 GB, mais o tarball), pelo que não deve ser executado num tmpfs pequeno — no executor autoalojado, `/tmp` é um tmpfs de 12 GB suportado por RAM e o controlo esgotou-o, truncando o pacote. | | `OMNIROUTE_SPEND_FLUSH_INTERVAL_MS` | _(predefinição no código)_ | `src/lib/spend/batchWriter.ts` | Intervalo de descarga (ms) para o gravador de despesas/custos em lote. Valores inferiores reduzem a agregação de escritas; valores superiores reduzem a contenção na base de dados. | | `OMNIROUTE_SPEND_MAX_BUFFER_SIZE` | _(predefinição no código)_ | `src/lib/spend/batchWriter.ts` | Número máximo de entradas de despesas em memória intermédia antes de uma descarga forçada. Aumente-o em implementações com muitas consultas por segundo; reduza-o quando limitar a memória for mais importante. | | `OMNIROUTE_PROXY_FETCH_DEBUG` | _(não definido)_ | `open-sse/utils/proxyFetch.ts` | Defina como `"true"` para emitir registos de depuração `[ProxyFetch]` no caminho de reencaminhamento da Vercel. Desativado por predefinição para evitar a divulgação de indícios de encaminhamento. | | `OMNIROUTE_PROXY_CORE_BINARY_PATH` | _(não definido)_ | `src/lib/proxySubscription/coreConfig/sync.ts` | Caminho absoluto do binário principal do proxy local (um ficheiro denominado `sing-box`) que verifica uma configuração principal gerada antes de substituir o ficheiro adotado. Quando não definido, escreve apenas `.generated` junto do ficheiro adotado. Apenas para o ambiente anfitrião: nunca é armazenado na base de dados nem aceite através da API de gestão, porque o binário é executado. | | `OMNIROUTE_PROXY_CORE_RELOAD_COMMAND` | _(não definido)_ | `src/lib/proxySubscription/coreConfig/reload.ts` | Forma como o núcleo do proxy local é recarregado após a substituição por uma configuração verificada: uma matriz JSON de argumentos executada sem shell ou exatamente `external` quando um observador externo aplica o ficheiro. Nunca é armazenado na base de dados nem exposto através da API. | | `PROXY_LOG_INCLUDE_IPS` | `false` | `src/lib/proxyLogger.ts` | Defina como `"true"` ou `"1"` para incluir os IPs do cliente/saída e o prefixo da conta na linha detalhada `[ProxyEgress]` do registo do processo. Mantém-se DESATIVADO por predefinição para que o registo do processo não divulgue IPs nem o prefixo da conta. | | `OMNIROUTE_DEBUG` | _(não definido)_ | `bin/cli/commands/quota.mjs` | Defina como `1` para imprimir no stderr diagnósticos de tempo por pedido (`[omniroute] GET concluído em Nms`) a partir dos comandos de quota da CLI. | | `OMNIROUTE_HEALTHCHECK_PATH` | _(automático)_ | `scripts/dev/healthcheck.mjs` | Caminho explícito sondado pela verificação de estado de funcionamento do contentor. Quando não definido, a sonda deriva-o de `OMNIROUTE_BASE_PATH`; defini-lo volta a ativar o endpoint de monitorização aprofundada. | | `OMNIROUTE_DEBUG_COMPLETION` | _(não definido)_ | `bin/cli/commands/completion.mjs` | Defina como qualquer valor não vazio para emitir diagnósticos `[omniroute completion]` a partir dos caminhos da cache de conclusão da shell da CLI (leitura/atualização/escrita). Desativado por predefinição — essas caches falham silenciosamente, para que uma cache em falta ou danificada nunca impeça a conclusão com a tecla Tab. | | `BATCH_RETRY_DURATION_MS` | `86400000` (24 h) | `open-sse/services/batchProcessor.ts` | Janela máxima de repetição para itens individuais do lote (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 nas novas tentativas de itens do lote. | | `BATCH_BACKOFF_MAX_MS` | `3600000` (1 h) | `open-sse/services/batchProcessor.ts` | Limite máximo (ms) da espera exponencial entre novas tentativas de itens do lote. | | `BATCH_MAX_CONCURRENT` | `1` | `open-sse/services/batchProcessor.ts` | Número máximo de lotes processados em simultâneo. Aumente-o para melhorar o débito; mantenha-o baixo para evitar picos de pedidos que excedam os limites de taxa. | > [!IMPORTANT] > Antes de alterar uma base de dados persistente existente, o executor de migrações publica uma captura instantânea completa, > endereçada por conteúdo, em `DATA_DIR/db_backups/`. A publicação requer um sistema de ficheiros > que suporte ligações físicas no mesmo sistema de ficheiros, sem substituição, bem como sincronização durável de ficheiros. Os sistemas POSIX também > requerem sincronização de diretórios; no Windows, o Node pode rejeitar identificadores de diretório, pelo que o OmniRoute descarrega os dados do > ficheiro publicado e trata a sincronização da entrada do diretório como um processo de melhor esforço. > Se o `DATA_DIR` montado não conseguir fornecer essas garantias, o arranque falha de forma segura antes de aplicar > uma migração. Mova `DATA_DIR` para um volume com esses recursos; não utilize > `DISABLE_SQLITE_AUTO_BACKUP` para contornar a segurança das migrações. ### Cenários | Cenário | Configuração | | ------------------------- | ------------------------------------------------------------------------------------------------- | | **Desenvolvimento local** | Mantenha todos os valores predefinidos. A BD encontra-se em `~/.omniroute/omniroute.db`. | | **Docker** | `DATA_DIR=/data` + monte um volume em `/data`. | | **Encriptado em repouso** | Defina `STORAGE_ENCRYPTION_KEY` + mantenha cópias de segurança da chave! Perdê-la = perder dados. | | **CI/Testes** | `DATA_DIR=/tmp/omniroute-test` — efémero, sem necessidade de encriptação. | --- ## 3. Rede e Portas | Variável | Predefinição | Ficheiro de Origem | Descrição | | ------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PORT` | `20128` | `src/lib/runtime/ports.ts` | Porta principal para a interface do Dashboard e os endpoints da API (modo de porta única). | | `OMNIROUTE_BASE_PATH` | _(vazio = raiz)_ | `next.config.mjs`, `scripts/docker/ensure-docker-base-path.mjs` | Subcaminho do URL para servir o OmniRoute através de um proxy inverso (define o `basePath` do Next.js; os redirecionamentos de autenticação têm em conta o basePath). Por exemplo, `/omniroute`. No Docker, o valor é incorporado durante o `docker build` (`ARG OMNIROUTE_BASE_PATH`); as imagens pré-compiladas para a raiz podem aplicar uma vez um valor diferente em tempo de execução, no arranque do contentor e antes de o Next.js iniciar. Defina `NEXT_PUBLIC_BASE_URL` como a origem pública, incluindo o mesmo subcaminho. | | `NEXT_PUBLIC_OMNIROUTE_BASE_PATH` | _(vazio = raiz)_ | `src/shared/hooks/useDisplayBaseUrl.ts` | Reflexo de `OMNIROUTE_BASE_PATH` visível no navegador, incorporado durante a compilação para que a apresentação do endpoint no dashboard mostre `https://host/omniroute/v1` em vez de `https://host/v1`. Quando não está definido, utiliza `OMNIROUTE_BASE_PATH`. Volte a compilar após a alteração (o `basePath` do Next é definido em tempo de compilação). | | `DASHBOARD_ALLOW_EMBED` | _(não definido = nunca enquadrável)_ | `next.config.mjs`, `scripts/build/dashboardEmbed.mjs` | Permite explicitamente a incorporação das páginas HTML num iframe. Quando não está definido, todas as rotas incluem `frame-ancestors 'none'` + `X-Frame-Options: DENY`. Defina como `vscode` para servir as páginas (dashboard, início de sessão, documentação e página inicial) com `frame-ancestors 'self' vscode-webview:` e sem `X-Frame-Options`, para que o Simple Browser do VS Code possa apresentá-las (modo `dashboardOpen: "editor"` do OmniCopilot). A superfície da API (`/api`, `/v1`, `/v1beta`, `/a2a`, `/healthz`, aliases ao nível da raiz) mantém os cabeçalhos estritos em qualquer dos casos. Apenas `vscode` é reconhecido — `1`/`true` não ativa esta opção. Em tempo de compilação: volte a compilar após a alteração (`docker build --build-arg DASHBOARD_ALLOW_EMBED=vscode` para imagens; defini-la numa instalação pré-compilada não tem qualquer efeito). | | `API_PORT` | _(não definido)_ | `src/lib/runtime/ports.ts` | Quando definido, disponibiliza a API proxy `/v1/*` nesta porta separada. | | `API_HOST` | `0.0.0.0` | `src/lib/runtime/ports.ts` | Endereço de escuta para a porta da API. | | `DASHBOARD_PORT` | _(não definido)_ | `src/lib/runtime/ports.ts` | Quando definido, disponibiliza a interface do Dashboard nesta porta separada. | | `OMNI_MAX_CONCURRENT_CONNECTIONS` | `0` _(desativado)_ | `src/sse/utils/backpressure.ts` | Limita as ligações de chat simultâneas em curso; os pedidos acima do limite recebem `503` com `Retry-After`. Um número inteiro positivo ativa a proteção; não definido/`0` desativa-a. | | `OMNIROUTE_INSTANCE_ID` | _(não definido)_ | `src/shared/resilience/peerRouting.ts` | ID estável e exclusivo deste gateway ao encadear instâncias do OmniRoute. Ativa as verificações de ciclos entre pares na receção. Caracteres permitidos: letras, algarismos, `.`, `_`, `:` e `-`; máximo de 64 caracteres. | | `OMNIROUTE_PEER_URLS` | _(não definido)_ | `src/shared/resilience/peerRouting.ts`, `open-sse/executors/base.ts` | URLs base do OmniRoute, separadas por vírgulas, que podem receber `X-OmniRoute-Peer-Trace`. Apenas os URLs upstream explicitamente incluídos na lista de permissões recebem metadados de pares; todos os outros fornecedores permanecem inalterados. | | `OMNIROUTE_PEER_MAX_HOPS` | `4` | `src/shared/resilience/peerRouting.ts` | Número máximo de instâncias do OmniRoute visitadas anteriormente aceites num pedido encadeado (`1`-`32`). Instâncias repetidas ou um limite esgotado devolvem HTTP `508 Loop Detected`. | | `PROD_DASHBOARD_PORT` | `20130` | `docker-compose.prod.yml` | Porta publicada no anfitrião para o Painel no modo de produção do Docker. | | `PROD_API_PORT` | `20131` | `docker-compose.prod.yml` | Porta publicada no anfitrião para a API no modo de produção do Docker. | | `OMNIROUTE_PORT` | _(não definido)_ | `src/lib/runtime/ports.ts` | Tem precedência sobre `PORT` quando é executado no Electron ou noutros wrappers. | | `LIVE_WS_PORT` | `20129` | `src/server/ws/liveServer.ts` | Porta para o servidor WebSocket de monitorização em tempo real. | | `LIVE_WS_HOST` | `127.0.0.1` | `src/server/ws/liveServer.ts` | Endereço de escuta do servidor WebSocket em tempo real. Defina como `0.0.0.0` para o expor na LAN (configure também `LIVE_WS_ALLOWED_ORIGINS`). | | `LIVE_WS_ALLOWED_ORIGINS` | _(não definido)_ | `src/server/ws/liveServer.ts` | Origens adicionais, separadas por vírgulas, autorizadas a abrir um WebSocket em tempo real. As origens do painel em loopback já são permitidas por predefinição. | | `LIVE_WS_ALLOWED_HOSTS` | _(não definido)_ | `src/server/ws/liveServerAllowList.ts` | Nomes de anfitrião adicionais, separados por vírgulas, permitidos para origens WebSocket em tempo real. Ao contrário de `LIVE_WS_ALLOWED_ORIGINS` (URLs de origem completos), corresponde apenas à parte do anfitrião — útil para configurações LAN/Tailscale. | | `NEXT_PUBLIC_LIVE_WS_PUBLIC_URL` | _(não definido)_ | `src/hooks/useLiveDashboard.ts` | URL público do WebSocket do painel em tempo real (lado do navegador). Defina-o ao colocar o servidor WS atrás de um proxy inverso ou de um túnel Cloudflare (por exemplo, `wss://ws.my-ai.com/live-ws`); o navegador liga-se a esse endereço em vez de `ws://hostname:20132`. A parte do caminho também é utilizada como caminho de atualização do WebSocket (predefiniçã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 predefinição e associado ao loopback). Opção de alternância de CI/harness que desativa o script auxiliar autónomo do WebSocket em tempo real. | | `RELAY_IP_PER_MINUTE` | `30` | `src/app/api/v1/relay/chat/completions/route.ts` | Limite de taxa de retransmissão por (token, IP), em pedidos/minuto. Em memória, por instância. `0` ou um valor negativo desativa a restrição da dimensão IP (o limite da base de dados por token continua a aplicar-se). | | `NODE_ENV` | `production` | Núcleo do Next.js | Controla o nível de detalhe dos registos, a colocação em cache, a exposição de detalhes de erros e as otimizações do Next.js. | | `OMNIROUTE_USE_TURBOPACK` | `1` (Turbopack — predefinição no código) | `package.json` / Next.js 16 | O Turbopack é o empacotador predefinido para `npm run dev` e `npm run build` (compilações 2–3× mais rápidas, segundo testes de desempenho). Defina como `0` para voltar a usar o webpack no Windows, quando encontrar incompatibilidades de bindings nativos/compatibilidade do empacotador, **ou em máquinas com RAM limitada** — sabe-se que as compilações de produção do Turbopack nesta linha de versões do Next.js (16.2.x) atingem picos de utilização de memória muito superiores aos do webpack em grafos de módulos grandes (a correção de libertação de memória do Turbopack do Next 16.3 ainda não é estável); a alternativa com webpack atinge picos muito inferiores. Consulte #6409. **As compilações de imagens Docker usam `0` (webpack) por predefinição**: o `Dockerfile` declara `ARG OMNIROUTE_USE_TURBOPACK=0`, para que um simples `docker build .` (Railway e outros serviços de alojamento de um clique, instalações próprias ad hoc) não seja terminado por falta de memória num construtor com memória limitada; indique `--build-arg OMNIROUTE_USE_TURBOPACK=1` para compilar a imagem com o Turbopack. Consulte `docs/guides/DOCKER_GUIDE.md` → Recursos durante a compilação. | | `OMNIROUTE_SKIP_DB_HEALTHCHECK` | _(não definida)_ | `src/lib/db/core.ts` / `src/lib/db/healthCheck.ts` | Defina como `1` para ignorar a verificação de integridade do SQLite durante o arranque. Útil para um arranque mais rápido com bases de dados grandes. | | `NOTIFY_SOCKET` | _(não definida)_ | systemd (protocolo sd_notify) | Definida pelo systemd quando o processo é executado numa unidade de serviço com integração sd_notify; o OmniRoute lê-a (consulte `OMNIROUTE_DISABLE_SD_NOTIFY`) para enviar notificações READY/WATCHDOG. Nunca deve ser definida pelo utilizador. | | `OMNIROUTE_DISABLE_SD_NOTIFY` | _(não definida)_ | `scripts/dev/systemd-notify.mjs` | Defina como `1` para desativar o sd_notify do systemd (Type=notify / WatchdogSec=), mesmo durante a execução numa unidade systemd. O notificador não efetua qualquer operação fora do systemd, independentemente desta definição. | | `CREDENTIAL_HEALTH_CHECK_INTERVAL` | `3600000` | `open-sse/config/constants.ts` / `src/lib/credentialHealth/scheduler.ts` | Intervalo (ms) do agendador de verificação do estado das credenciais em segundo plano. Mínimo: 10000 (10 s). | | `CREDENTIAL_HEALTH_CACHE_TTL` | `300000` | `open-sse/config/constants.ts` / `src/lib/credentialHealth/cache.ts` | TTL (ms) do estado do funcionamento das credenciais 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 aos fornecedores. Os fornecedores de pesquisa (SEARCH_VALIDATOR_CONFIGS em `src/lib/providers/validation/searchProviders.ts`, por exemplo, `tavily-search`) são sempre excluídos da verificação — a respetiva «validação» é uma consulta real e faturada ao serviço a montante, pelo que nunca são sujeitos a verificações de funcionamento periódicas (#9970). | | `DEEP_HEALTH_CHECK_ENABLED` | `0` | `src/app/api/monitoring/health/route.ts` | Defina como `1` para permitir que um cliente autenticado solicite `/api/monitoring/health?deep=1`, que testa a interface de conclusões uma vez por TTL. Os clientes anónimos nunca acionam a sondagem. | | `HOST` | `0.0.0.0` | `scripts/dev/run-next.mjs` | Endereço de escuta do servidor de desenvolvimento/inicialização do Next.js. Quando definido, substitui o valor predefinido `0.0.0.0`. | | `HOSTNAME` | `127.0.0.1` | `scripts/dev/run-next-playwright.mjs` | Endereço de escuta utilizado pelo executor Playwright ao iniciar o Next.js. A predefinição é `127.0.0.1` para testes herméticos. **Não utilize com `omniroute serve`** — utilize `OMNIROUTE_SERVER_HOST` (as shells POSIX definem automaticamente `HOSTNAME` como o nome da máquina; o ficheiro `.env` não consegue substituí-lo). | | `OMNIROUTE_SERVER_HOST` | `0.0.0.0` | `bin/cli/commands/serve.mjs` | Endereço de escuta para `omniroute serve`. Evita conflitos com a variável `HOSTNAME` da shell POSIX (sempre definida como o nome da máquina pelo bash/zsh). Assume `0.0.0.0` quando não está definida. (#6194) | ### Modos de porta ``` ┌─────────────────────────── Porta única (predefinição) ──────────────────────┐ │ PORT=20128 │ │ → Painel: http://localhost:20128 │ │ → API: http://localhost:20128/v1/chat/completions │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────── Portas separadas ────────────────────────────────┐ │ DASHBOARD_PORT=20128 │ │ API_PORT=20129 │ │ API_HOST=0.0.0.0 │ │ → Painel: http://localhost:20128 │ │ → API: http://0.0.0.0:20129/v1/chat/completions │ │ Caso de uso: Expor a API à LAN, restringindo o Painel ao localhost. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────── Docker em produção ──────────────────────────────┐ │ PROD_DASHBOARD_PORT=443 PROD_API_PORT=8443 │ │ → Mapeia as portas do contentor para as portas do anfitrião em │ │ docker-compose.prod.yml. │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 4. Segurança e Autenticação | Variável | Predefinição | Ficheiro de Origem | Descrição | | ------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MACHINE_ID_SALT` | `endpoint-proxy-salt` | `src/lib/auth` | Salt combinado com identificadores de hardware para gerar a impressão digital da máquina. Altere-o em cada implementação para garantir o isolamento. | | `OMNIROUTE_CLI_SALT` | _(não definido = salt aleatório por instalação, guardado em `/cli-token-salt.json`)_ | `src/lib/machineToken.ts` | Salt HMAC para derivar o token de autenticação local da CLI. Definir este valor renova todos os tokens da CLI na máquina e tem sempre prioridade sobre o salt guardado. Consulte `docs/security/CLI_TOKEN.md`. | | `AUTH_COOKIE_SECURE` | `false` | `src/lib/auth` | Define o sinalizador `Secure` nos cookies de sessão. **Tem de ser `true`** quando executado atrás de HTTPS. | | `REQUIRE_API_KEY` | `false` | Middleware da API | Quando definido como `true`, todos os pedidos ao proxy `/v1/*` têm de incluir uma chave de API válida. **Este sinalizador não controla o acesso a `GET /v1/models`**, que segue a configuração de início de sessão do painel (`requireAuthForModels`) — portanto, uma resposta `401` de `/v1/models` NÃO significa que a inferência esteja protegida. Consulte `docs/security/INFERENCE_AUTH_POSTURE.md` (#13695). | | `ALLOW_API_KEY_REVEAL` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | Permite revelar os valores completos das chaves de API na interface do Painel. Configurável nas Funcionalidades Experimentais do Painel; constitui um risco de segurança em instâncias partilhadas. | | `NO_LOG_API_KEY_IDS` | _(vazio)_ | `src/lib/compliance/index.ts` | IDs de chaves de API, separados por vírgulas, que ignoram o registo de pedidos (conformidade com o RGPD). | | `DEFAULT_RATE_LIMIT_PER_DAY` | _(não definido = ilimitado)_ | `src/shared/utils/apiKeyPolicy.ts` | Orçamento diário alternativo de pedidos, aplicado às chaves de API cuja coluna `rate_limits` seja nula. Não definido ou vazio: sem limite implícito (#2289, #11017). `0` é equivalente (ilimitado). Um número inteiro positivo N ativa N/dia, 5N/semana e 20N/mês. Valores não vazios malformados recorrem aos limites legados de 1000/dia, 5000/semana e 20000/mês. | | `MAX_BODY_SIZE_BYTES` | `10485760` (10 MB) | `src/shared/middleware/bodySizeGuard.ts` | Tamanho máximo permitido para o corpo do pedido. Rejeita cargas que excedam este limite. | | `OMNIROUTE_CHAT_LARGE_BODY_BYTES` | `262144` (256 KB) | `src/shared/middleware/chatBodyAdmission.ts` | Os corpos reais dos pedidos iguais ou superiores a este limiar obtêm a concessão atómica local ao processo para admissão de cargas pesadas antes da análise de JSON (percurso BYTE, incluindo `POST /v1/responses`). A mesma salvaguarda de margem saudável de [#10437](https://github.com/diegosouzapw/OmniRoute/pull/10437) usada para estruturas pesadas; continua limitada por `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` / [#10110](https://github.com/diegosouzapw/OmniRoute/issues/10110), para que [#7849](https://github.com/diegosouzapw/OmniRoute/issues/7849) não volte a ocorrer. | | `OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES` | `52428800` (50 MB) | `src/shared/middleware/chatBodyAdmission.ts` | Limite máximo estrito da rota de chat, aplicado aos bytes lidos durante a ingestão limitada, incluindo pedidos com `Content-Length` em falta, inválido ou falso; o excesso recebe `413`. | | `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` | _(não definido — sem limite de contagem de pedidos)_ | `src/shared/middleware/chatBodyAdmission.ts` | **#503-fanout:** este limite legado de CONTAGEM de pedidos passa agora a ser aplicado apenas quando explicitamente definido. Quando não está definido (a predefinição), a admissão de pedidos de chat pesados é, em alternativa, controlada por `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` — um orçamento de BYTES derivado automaticamente, dimensionado a partir do limite real de memória do processo em **um processo** (uma heap V8). Dois pedidos `/v1/responses` sobrepostos com ~750 mil tokens provocam o aborto de heaps de ~12 GiB (#7849) — um aviso de **orçamento de memória**, não um máximo estrito de produto de 2. Um processo saudável (heap abaixo do rácio de rejeição) PODE admitir mais pedidos `/v1/responses` longos em simultâneo através de `OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM`. Dezenas de clientes SSE de longa duração (40–50) dependem da heap + `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` / #10110, não de um «máximo de 2». Aumentar este valor indiscriminadamente para «utilizar o anfitrião» reintroduz o problema #7849. Multiplique as **heaps** com **N `DATA_DIR`s independentes** (#11024); nunca utilize `replicas>1` com um único ficheiro SQLite. | | `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` | _(derivado automaticamente)_ | `src/shared/middleware/admissionBudget.ts` | **#503-fanout:** substituição do orçamento de bytes de ingestão derivado automaticamente (25% do limite de memória mais restritivo entre V8/cgroup, dividido por uma amplificação transitória de 8x). Os valores derivados e explícitos são limitados ao intervalo de 8 MiB–2 GiB. Um corpo maior do que o orçamento efetivo falha imediatamente com `413 body_exceeds_budget`; a contenção entre corpos individualmente processáveis continua a resultar num `503` que permite nova tentativa. A existência de 40–50 clientes SSE longos em simultâneo depende deste orçamento + heap, não de um «máximo de 2» estrito. Consulte `chatAdmission.maxInflightBytes` / `budgetSource` / `pressureSeverity` em `/api/monitoring/health` antes de efetuar ajustes. | | `OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO` | `0.75` | `src/shared/middleware/chatBodyAdmission.ts` | Rácio de rejeição por pressão da heap (`heapUsed / heap_size_limit`) para a admissão de pedidos pesados por BYTES e ESTRUTURA (#10183, #10268, #10437). Um pedido pesado simultâneo para além de `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` só é rejeitado com o `503` que permite nova tentativa quando a heap TAMBÉM se encontra neste rácio ou acima dele; numa heap saudável, é admitido através da margem de capacidade saudável. | | `OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM` | `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` (predefinição `1`) | `src/shared/middleware/chatBodyAdmission.ts` | Capacidade adicional limitada para o caminho rápido de heap saudável (#10437), tanto para ESTRUTURA como para BYTES (`admitChatRequest`, incluindo corpos ≥ `OMNIROUTE_CHAT_LARGE_BODY_BYTES`). Sem este limite, todos os pedidos com o sistema ocupado, mas com uma heap saudável, contornavam a admissão sem qualquer limite máximo. Quando este número de concessões simultâneas estiver ativo através do caminho de heap saudável, os pedidos adicionais com o sistema ocupado passam para o MESMO caminho de espera limitada/rejeição utilizado sob pressão real da heap. `0` desativa completamente o desvio. | | `OMNIROUTE_CHAT_HEAVY_MESSAGE_COUNT` | `200` | `src/shared/middleware/chatBodyAdmission.ts` | Número de mensagens que classifica um pedido de chat como pesado, mesmo quando o respetivo corpo está abaixo do limiar de bytes. | | `OMNIROUTE_CHAT_HEAVY_TOOL_COUNT` | `64` | `src/shared/middleware/chatBodyAdmission.ts` | Número de ferramentas que classifica um pedido de chat como pesado, mesmo quando o respetivo corpo está abaixo do limiar de bytes. | | `OMNIROUTE_CHAT_HEAVY_ESTIMATED_TOKENS` | `32000` | `src/shared/middleware/chatBodyAdmission.ts` | Estimativa conservadora de tokens baseada no tamanho das cadeias de carateres que classifica um pedido como pesado; trata-se de uma aproximação do custo de admissão, não da tokenização de faturação do fornecedor. | | `OMNIROUTE_CHAT_HARD_MAX_MESSAGES` | `0` (desativado) | `src/shared/middleware/chatBodyAdmission.ts` | Limite opcional e explicitamente ativado para o histórico de chat. Desativado por predefinição: o número de mensagens é uma política de implementação, não uma propriedade universal de um pedido, e limitar aqui rejeita conversas com um `413` terminal antes de o pipeline de compressão poder torná-las processáveis. O crescimento da heap é limitado por `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` e pela rejeição por pressão da heap. Defina um valor positivo em implementações com memória limitada que necessitem de um limite máximo estrito; o excesso recebe então um `413` estruturado que indica a necessidade de compactação. | | `OMNIROUTE_MAX_NONSTREAMING_RESPONSE_BYTES` | `67108864` (64 MB) | `open-sse/handlers/chatCore/nonStreamingResponseBody.ts` | Limite máximo estrito para uma resposta upstream sem streaming, integralmente armazenada em memória. Acima deste limite, o leitor upstream é cancelado e o pedido falha imediatamente, em vez de aumentar uma cadeia de carateres sem limites até esgotar a heap. | | `OMNIROUTE_FORWARDING_HEADER_BUDGET_BYTES` | `768` | `open-sse/handlers/chatCore/responseHeaders.ts` | Número máximo de bytes transmitidos encaminhados a partir dos cabeçalhos da resposta do serviço a montante. Quando o limite é excedido, os cabeçalhos de menor prioridade (por exemplo, `x-codex-*`, `x-oai-request-id`) são removidos para respeitar os limites de cabeçalhos comuns dos proxies inversos. Defina um valor superior para encaminhar mais metadados do serviço a montante, à custa de um tamanho maior dos cabeçalhos da resposta. | | `CORS_ORIGIN` | _(não definido)_ | `src/server/cors/origins.ts` | Lista legada de origens únicas permitidas por CORS. Para novas implementações, dê preferência a `CORS_ALLOWED_ORIGINS`. O CORS destina-se apenas a clientes de API de navegador entre origens; em alternativa, as escritas autenticadas no painel utilizam pedidos da mesma origem e proteção CSRF associada à sessão. | | `CORS_ALLOWED_ORIGINS` | _(não definido)_ | `src/server/cors/origins.ts` | Lista de origens permitidas por CORS, separadas por vírgulas. Não é enviado qualquer caráter universal, a menos que `CORS_ALLOW_ALL=true` seja configurado explicitamente. | | `CORS_ALLOW_ALL` | `false` | `src/server/cors/origins.ts` | Mecanismo de exceção apenas para desenvolvimento que devolve qualquer `Origin` do navegador. Não o ative em implementações partilhadas ou de produção. | | `OUTBOUND_SSRF_GUARD_ENABLED` | `true` | `src/shared/network/outboundUrlGuardPolicy.ts` | Alias legado. A respetiva opção no painel (uma substituição na base de dados) é lida antes deste valor de ambiente; `false`, `0`, `no` ou `off` em qualquer um deles desativa as verificações de anfitriões da mesma forma que `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true`, mesmo quando a opção dessa variável no painel está guardada como desativada; outros valores deixam a proteção ao cuidado das duas variáveis abaixo. | | `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` | `false` | `src/shared/network/outboundUrlGuardPolicy.ts` | Desativa as verificações de anfitriões da proteção de URLs de saída, incluindo o bloqueio de metadados da nuvem (todo o intervalo 169.254.0.0/16 e metadata.google.internal), nos caminhos do fornecedor que seguem o modo de proteção: validação de URLs, deteção de modelos, URLs de base de nós do fornecedor (incluindo nós remotos de reordenação) e teste de contingência do proxy, entre outros caminhos de saída adjacentes ao fornecedor, como a obtenção remota de imagens/conteúdos multimédia. Também permite destinos privados de webhooks, exceto pontos finais de metadados da nuvem/ligação local, que permanecem bloqueados mesmo com esta variável ativa. Os pedidos de conversação enviados através de `BaseExecutor.execute()` mantêm a respetiva verificação de metadados da nuvem. Os fornecedores locais funcionam com as predefinições: `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` (predefinição `true`) já permite URLs locais e da LAN nos caminhos de validação, deteção e nós do fornecedor; o teste de contingência do proxy e os destinos privados de webhooks consultam apenas esta variável e bloqueiam anfitriões locais/da LAN enquanto estiver desativada. Sobrepõe-se a `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=false`. Um valor guardado através da opção no painel tem precedência sobre esta variável. | | `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` | `true` | `src/shared/network/outboundUrlGuardPolicy.ts` | Permite URLs de fornecedores em endereços locais/privados (127.0.0.1, localhost, LAN, intervalos privados) para a validação de fornecedores, deteção de modelos, conversação e os outros caminhos de saída adjacentes ao fornecedor regidos pelo modo de proteção. **Predefinição `true`** (prioridade local): a proteção bloqueia então pontos finais de metadados da nuvem — todo o intervalo 169.254.0.0/16, bem como os nomes de anfitrião de metadados conhecidos (metadata.google.internal, metadata.goog, IMDS da Alibaba/Azure/Oracle, fd00:ec2::254). Defina `false` para o modo apenas público, que também bloqueia anfitriões privados e de loopback. A proteção verifica o nome de anfitrião ou o literal de IP tal como está escrito, antes de qualquer consulta DNS; no modo apenas público, o wrapper de obtenção segura resolve adicionalmente o nome de anfitrião e recusa qualquer resposta privada. `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` desativa estas verificações nos caminhos indicados na respetiva linha. Os fornecedores locais incorporados, como LM Studio, Ollama, vLLM, Llamafile e Triton, ignoram todas as verificações de anfitriões para a validação de chaves e a conversação. Um valor guardado através da opção no painel tem precedência sobre esta variável. (#5066) | | `AUDIO_REMOTE_PROVIDER_NODES` | `false` | `src/app/api/v1/_shared/audioProviderNodes.ts` | Permite que as rotas `/v1/audio/*` (transcrições, voz, traduções) utilizem um nó de fornecedor compatível com OpenAI alojado fora do localhost. Desativado por predefinição — encaminhar áudio para um anfitrião remoto altera a identidade de saída e tem de ser uma decisão explícita do operador. Os nós de loopback/privados (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` | Permite que `POST /v1/rerank` (e o passo de reordenação de loopback do motor de memória) utilize um nó de fornecedor compatível com OpenAI alojado fora do localhost — uma máquina na LAN ou um par Tailscale que execute TEI, Infinity, vLLM, etc. Desativado por predefinição — o encaminhamento para um anfitrião remoto altera a identidade de saída e tem de 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 de base de um nó remoto também tem de cumprir a política de URLs 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 anfitrião (separados por vírgulas ou espaços em branco) que o encaminhamento de nós fornecedores trata como locais — normalmente, o nome do serviço Docker/Compose de um reranker, TEI ou sidecar de áudio na própria rede Docker do OmniRoute (`http://reranker:8080/v1`), para que o nó não necessite de um IP de contentor codificado de forma rígida. Os anfitriões indicados são elegíveis para `/v1/rerank`, `/v1/audio/*` e para a verificação de estado local sem ativar `RERANK_REMOTE_PROVIDER_NODES` / `AUDIO_REMOTE_PROVIDER_NODES` para cada nó remoto, e são contactados diretamente — nunca através de `HTTP(S)_PROXY` ou do proxy fixado de uma ligação. Continuam a enviar a chave de API da ligação. Apenas são aceites nomes de um único nível e nomes `.internal`/`.local`; FQDNs públicos, literais de IP e nomes de metadados da cloud são ignorados com um aviso. (#14635) | | `OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | `src/app/api/auth/login/route.ts` | Quando o OIDC está ativado, desativa o início de sessão com palavra-passe para que os utilizadores apenas possam autenticar-se através do início de sessão único OIDC. O alias simples `OIDC_DISABLE_PASSWORD_LOGIN` também é aceite; o sinalizador de funcionalidade do Painel com a 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). | ### Lista de Verificação de Reforço da Segurança ```bash # Requisitos mínimos de segurança para produção: AUTH_COOKIE_SECURE=true # Requer HTTPS REQUIRE_API_KEY=true # Autenticar todas as chamadas ao proxy ALLOW_API_KEY_REVEAL=false # Nunca expor chaves na interface CORS_ALLOWED_ORIGINS=https://your.domain.com MAX_BODY_SIZE_BYTES=5242880 # Limite de 5 MB ``` --- ## 5. Saneamento de entradas e proteção de PII O OmniRoute fornece uma defesa em duas camadas: análise de injeções do lado dos pedidos e remoção de PII do lado das respostas. > **⚠️ Limitações:** Estas proteções são deteções heurísticas de _melhor esforço_, não uma firewall completa contra injeções de prompts nem um sistema DLP de PII. Podem produzir falsos positivos (prompts inofensivos de personas/RPG sinalizados) e falsos negativos (leetspeak, espaçamento, padrões não ingleses). Por si só, não são suficientes para garantir a conformidade. Ajuste os modos e teste-os com o seu tráfego antes de confiar neles. ### Lado dos pedidos: proteção contra injeção de prompts | Variável | Predefinição | Ficheiro de origem | Descrição | | --------------------------------- | ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `INPUT_SANITIZER_ENABLED` | `true` | `src/middleware/promptInjectionGuard.ts` | Ativa a análise das mensagens recebidas para detetar padrões de injeção de prompts. | | `INPUT_SANITIZER_MODE` | `warn` | `src/middleware/promptInjectionGuard.ts` | Política de injeção: `warn` = apenas registar, `block` = rejeitar o pedido com 400. O modo legado `redact` **não** remove texto de injeção; utilize `PII_REDACTION_ENABLED` para reescrever PII nos pedidos. | | `INJECTION_GUARD_MODE` | _(não definido)_ | `src/middleware/promptInjectionGuard.ts` | Nome alternativo legado de `INPUT_SANITIZER_MODE` — mesmo comportamento. | | `INPUT_SANITIZER_BLOCK_THRESHOLD` | `high` | `src/shared/utils/injectionSeverity.ts` | Gravidade mínima rejeitada por `MODE=block`: `high` (predefinição), `medium` ou `low`. Os padrões de gravidade média são apenas observados, a menos que o limiar seja reduzido. | | `INJECTION_GUARD_BLOCK_THRESHOLD` | _(não definido)_ | `src/shared/utils/injectionSeverity.ts` | Nome alternativo legado de `INPUT_SANITIZER_BLOCK_THRESHOLD` — mesmo comportamento. | | `PII_REDACTION_ENABLED` | `false` | `src/lib/guardrails/piiMasker.ts` | Quando definido como `true`, oculta PII nos pedidos recebidos (independentemente do modo de injeção). | | `CREDENTIAL_REDACTION_ENABLED` | `false` | `src/lib/guardrails/credentialMasker.ts` | Oculta padrões conhecidos de chaves de API/tokens secretos dos conteúdos dos pedidos e das respostas. Opcional; reflete `PII_REDACTION_ENABLED`. | ### Lado das respostas: saneador de PII | Variável | Predefinição | Ficheiro de origem | Descrição | | -------------------------------- | ------------ | ------------------------- | ---------------------------------------------------------------------------------------- | | `PII_RESPONSE_SANITIZATION` | `false` | `src/lib/piiSanitizer.ts` | Analisa as respostas do LLM para detetar PII divulgadas antes de as devolver ao cliente. | | `PII_RESPONSE_SANITIZATION_MODE` | `redact` | `src/lib/piiSanitizer.ts` | `redact` = ocultar PII, `warn` = apenas registar, `block` = descartar toda a resposta. | ### Saneador de contexto de rotas tokenizadas do VS Code | Variável | Predefinição | Ficheiro de origem | Descrição | | ----------------------------------- | ------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_VSCODE_SANITIZE_CONTEXT` | `1` | `src/app/api/v1/vscode/contextSanitizer.ts` | Remove o contexto implícito do editor ativo (`editorContext`, `activeEditor`, `currentFile`, `selection`, `openTabs`…) dos pedidos para `/v1/vscode/[token]/*` e oculta o conteúdo de ficheiros sensíveis anexados explicitamente. Seguro por predefinição; 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` (bloqueio de injeções + ocultação de PII nos pedidos/respostas; os modos são independentes) | | **Apenas monitorização** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=warn` — regista, mas nunca bloqueia | | **Utilização pessoal** | Deixe tudo desativado — sobrecarga nula | --- ## 6. Políticas de Ferramentas e Encaminhamento | Variável | Predefinição | Ficheiro de Origem | Descrição | | ----------------------------------------------------------- | ------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TOOL_POLICY_MODE` | `disabled` | `src/lib/toolPolicy.ts` | Controla o acesso do LLM a ferramentas/chamadas de funções. `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 de regras de manipulação do payload (ajustes a montante por modelo/protocolo). | | `OMNIROUTE_PAYLOAD_RULES_RELOAD_MS` | `5000` | `open-sse/services/payloadRules.ts` | Intervalo de recarregamento (ms) para o recarregamento automático do ficheiro de regras de payload. Mínimo de `1000`. | | `OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS` | `false` | `open-sse/services/model.ts` | Adesão opcional: encaminha IDs de modelos `claude-*` sem prefixo provenientes de clientes Claude Code através da conta OAuth do Claude Code, em vez de exigir um prefixo de fornecedor. Os prefixos explícitos de fornecedor continuam a ter prioridade. Também é configurável através de uma opção no painel da página do fornecedor Claude. | | `BARE_MODEL_DEFAULT_OVERRIDE_LEGACY` | `false` | `open-sse/services/model.ts` | Comportamento legado de `resolveBareModelToConnectionDefault` (#4825): substitui qualquer nome de modelo sem prefixo pelo `defaultModel` da ligação selecionada. Desativado por predefinição; apenas `auto` ou um modelo vazio são substituídos; quando ativado, regista um aviso por par. | | `COMBO_CONCURRENCY_PER_MODEL` | `3` | `open-sse/services/comboConfig.ts` | Limite de concorrência por modelo para combinações round-robin (#9100). O semáforo de combinação round-robin tinha um limite rígido de 3 pedidos simultâneos por modelo, sem possibilidade de substituição, serializando o tráfego com maior concorrência atrás desse limite. Validado para `>= 1` e limitado a `<= 32`. | | `DISABLE_CONTEXT_WINDOW_CHECKS` | `false` | `open-sse/handlers/chatCore.ts` | Opção perigosa que ignora a verificação local do OmniRoute relativa à janela de contexto/aos tokens máximos de entrada para pedidos diretos a um único modelo. Os fornecedores a montante continuam a aplicar os respetivos limites reais; a compressão do prompt e o limite de tokens de saída do próprio modelo permanecem ativos. A precedência efetiva é: substituição na base de dados de Feature Flags > variável de ambiente > predefinição; não é necessário reiniciar. | | `OMNIROUTE_SELF_HOSTED_PROVIDERS` | _(não definido)_ | `open-sse/services/selfHostedEntry.ts` | Documento YAML `providers:` inline (RIC-738, D4). Quando definido (com ou sem um bloco `strategy:`), `/v1/chat/completions` é desviado para o ponto de entrada unificado autoalojado compatível com OpenAI, em vez de seguir o pipeline na nuvem. Quando não definido (a predefinição), a rota passa diretamente para o pipeline na nuvem existente. Consulte `docs/routing/SELF_HOSTED_OPENAI_ENTRY.md`. | | `OMNIROUTE_SELF_HOSTED_PROVIDERS_FILE` | _(não definido)_ | `open-sse/services/selfHostedEntry.ts` | Caminho para um ficheiro YAML que contém o mesmo documento `providers:` que `OMNIROUTE_SELF_HOSTED_PROVIDERS`, para implementações que prefiram um ficheiro a uma variável de ambiente inline. Qualquer uma das opções ativa o ponto de entrada autoalojado. | | `OMNIROUTE_SELF_HOSTED_API_KEY` | _(não definido — rota aberta)_ | `open-sse/services/selfHostedEntry.ts` | Chave de API partilhada opcional para o ponto de entrada unificado autoalojado (estrutura D5, reservada para o sistema de quotas por chave). Quando definida, os pedidos têm de incluir `Authorization: Bearer `. Quando não definida, a rota fica aberta, em conformidade com o padrão existente de fornecedores locais autoalojados (implementação em loopback/rede de confiança). | | `OMNIROUTE_SELF_HOSTED_STRATEGY` | _(não definido)_ | `open-sse/services/routingStrategies.ts` | Documento YAML `strategy:` inline para o motor de encaminhamento determinístico (M2/RIC-740, D3) — lista de bloqueio/lista de permissões, disjuntor com período de espera, prioridade de custo, sensível à latência e cadeia de contingência. Substitui, por chave, um bloco `strategy:` inline aninhado em `OMNIROUTE_SELF_HOSTED_PROVIDERS`. Consulte `docs/routing/DETERMINISTIC_ROUTING.md`. | | `OMNIROUTE_SELF_HOSTED_STRATEGY_FILE` | _(não definida)_ | `open-sse/services/routingStrategies.ts` | Caminho para um ficheiro YAML que contém o mesmo documento `strategy:` que `OMNIROUTE_SELF_HOSTED_STRATEGY`, para implementações que preferem um ficheiro a uma variável de ambiente em linha. | | `OMNIROUTE_DISABLE_CONVERSATION_TRACKING` | _(não definida)_ | `open-sse/services/conversationTracker.ts` | Defina como `1` para deixar de recolher o histórico de conversas. `resolveConversationId()` devolve um resultado sem rastreio antes de ler o SQLite ou analisar o histórico de mensagens, abrangendo também os IDs de sessão fornecidos pelo cliente. O processamento da sessão de encaminhamento permanece inalterado e os registos existentes não são eliminados. Destina-se a implementações que não utilizam a vista de conversas do painel e pretendem impedir que a tabela de turnos continue a crescer. | | `OMNIROUTE_NADIR_API_KEY` | _(não definida)_ | `open-sse/services/autoCombo/nadirStrategy.ts` | Chave de API para a estratégia opcional `nadir` do router auto-combo, utilizada quando `config.nadir.apiKey` do próprio combo não está definida. Opcional: as chamadas sem chave são encaminhadas para o nível anónimo do Nadir, que tem limites de frequência por IP e, por isso, não pode ser utilizado através de um gateway partilhado. É um valor sensível; prefira o campo específico de cada combo quando os combos utilizarem contas diferentes. | | `OMNIROUTE_NADIR_BASE_URL` | `https://api.getnadir.com` | `open-sse/services/autoCombo/nadirStrategy.ts` | Origem base da API de decisão do Nadir, utilizada quando `config.nadir.baseUrl` do próprio combo não está definida. Apenas é necessária para uma instância autoalojada do Nadir, que mantém os inícios dos prompts dentro da sua própria rede. Uma terminação `/v1` é aceite e removida. | | `OMNIROUTE_API_KEY_WEEKLY_WINDOW` | `provider` | `src/lib/usage/apiKeyUsageLimits.ts` | Janela semanal para limites de utilização em USD por chave de API (aplicação em pedidos, `GET /api/keys/{id}/usage-limits`, `@@om-usage`). `provider`: a semana termina na primeira reposição semanal entre as ligações a fornecedores a montante às quais a chave pode aceder, ou corresponde a um período móvel de 7 dias quando não existe nenhuma reposição conhecida. `calendar`: a semana local, desde segunda-feira às 00:00 até à segunda-feira seguinte às 00:00, idêntica para todas as chaves. Recomenda-se `calendar` quando um conjunto de contas a montante é partilhado por muitas chaves com orçamentos individuais. Os valores inválidos revertem 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 a segunda-feira às 00:00 para a janela semanal `calendar`. Não definido ou inválido: é utilizado o fuso horário do processo OmniRoute (o `TZ` do anfitrião ou contentor, que muitas vezes 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 predefinido de ferramentas permitidas num pedido (predefinição do OpenAI). Apenas números inteiros positivos; valores não definidos ou inválidos mantêm `128`. Um fornecedor com um limite conhecido/proativo (`grok-cli` 200, `nvidia` 1536) continua a aplicar o seu próprio limite — isto apenas altera o limite máximo predefinido. | | `OMNIROUTE_PROMPT_EMULATE_TOOLS` | _(ativada)_ | `open-sse/executors/syntxChat.ts` | Chamada de ferramentas emulada por prompt do SYNTX.ai: um valor não definido ou `1`/`true`/`on`/`yes` injeta o catálogo local de ferramentas no prompt; qualquer outro valor (por exemplo, `0`) ignora essa injeção. | --- ## 7. URLs e sincronização na nuvem | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------------------- | --------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BASE_URL` | `http://localhost:20128` | `src/lib/cloudSync.ts` | URL do lado do servidor utilizada pelas tarefas internas de sincronização para chamar `/api/sync/cloud`. Mantenha-a como um URL de loopback/contentor, mesmo quando a aplicação for disponibilizada publicamente através de um proxy. | | `CLOUD_URL` | _(vazio)_ | `src/lib/cloudSync.ts` | URL do endpoint de retransmissão na nuvem (funcionalidade premium). | | `CLOUD_SYNC_TIMEOUT_MS` | `12000` | `src/lib/cloudSync.ts` | Tempo limite de HTTP para pedidos de sincronização na nuvem. | | `OMNIROUTE_BUILD_PROFILE` | `full` | Configuração de compilação do Webpack | Perfil em tempo de compilação (defina como `minimal` para excluir fisicamente os módulos privilegiados do pacote). | | `OMNIROUTE_STANDALONE_DIR` | _saída standalone de .build/_ | `scripts/build/colocate-standalone.mjs` | Substituição, em tempo de compilação, do diretório de saída standalone utilizado pelo passo de colocação pós-compilação. Não é uma definiçã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 da sincronização na nuvem. | | `OMNIROUTE_CLOUD_SYNC_SECRETS` | `false` | `src/lib/cloudSync.ts` | Defina como `true` para permitir que o endpoint da sincronização na nuvem substitua as credenciais locais. A predefinição é `false`. | | `OMNIROUTE_CLOUD_SYNC_ENFORCE_SIGNATURE` | `false` | `src/lib/cloudSync.ts` | Defina como `true` para rejeitar uma resposta da sincronização na nuvem sem assinatura quando não estiver configurado qualquer segredo local (#13679). Uma assinatura presente é sempre verificada — e sempre rejeitada quando `OMNIROUTE_CLOUD_SYNC_SECRET` não está definido — independentemente deste sinalizador. A predefinição passa a ser obrigatória 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 um só passo «importar tudo» da v3.8.5, sem confirmação do utilizador. | | `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | OAuth, painel, sincronização | URL pública para o redirect_uri do OAuth, as ligações do painel e os URLs públicos gerados. Defina-a como o URL público estável quando as chamadas de retorno do OAuth ou as ligações geradas para o navegador tiverem de utilizar um anfitrião canónico de proxy inverso. | | `NEXT_PUBLIC_CLOUD_URL` | _(vazio)_ | Lado do cliente | Espelho de `CLOUD_URL` do lado do cliente. | | `NEXT_PUBLIC_APP_URL` | _(não definida)_ | `src/shared/services/cloudSyncScheduler.ts` | Alternativa legada para `NEXT_PUBLIC_BASE_URL`. | | `NEXT_PUBLIC_PORT` | _(não definida — recorre a `PORT`)_ | `src/shared/hooks/useDisplayBaseUrl.ts` | Porta alternativa do lado do cliente para URLs de apresentação quando não é conhecida qualquer origem (SSR/testes); lida antes de `PORT`. | | `OMNIROUTE_PUBLIC_BASE_URL` | _(não definida)_ | Resolvedor de origem pública, URLs de imagens | Origem do OmniRoute visível pelo browser com a prioridade mais elevada, utilizada para gerar URLs públicas e validar a origem do browser fora do painel. Defina esta variável quando o OpenWebUI ou outro retransmissor acede ao OmniRoute através de um URL interno, mas o browser do utilizador tem de obter os conteúdos multimédia gerados a partir de uma LAN, túnel ou origem pública. **Não** inclua `/v1`. | | `OMNIROUTE_PROVIDER_MANIFEST_URL` | _(não definida)_ | `open-sse/config/providerPluginManifestUrl.ts` | URL absoluto do manifesto de plugins de fornecedores anunciado aos clientes auxiliares. Quando não está definido, o OmniRoute deriva `/api/v1/provider-plugin-manifest` da origem do pedido ou de HOST/PORT. | | `OMNIROUTE_PUBLIC_PROTOCOL` | `http` | `open-sse/config/providerPluginManifestUrl.ts` | Protocolo utilizado ao derivar o URL do manifesto de plugins de fornecedores a partir de HOST/PORT sem uma origem do pedido. Defina como `https` por detrás de um proxy público que termine TLS quando não estiver definido um `OMNIROUTE_PROVIDER_MANIFEST_URL` explícito. | | `OMNIROUTE_TRUST_PROXY` | _(não definida)_ | `src/server/origin/publicOrigin.ts` | Modo de confiança opcional para cabeçalhos encaminhados de origem pública. Não definida = não confiar em `Forwarded` / `X-Forwarded-*` para decisões de segurança. `true` / `loopback` confia no anfitrião/protocolo encaminhado apenas a partir de um proxy de loopback com um token. `private` / `lan` também confia em pares de proxy de LAN privada e permite que a ponte `API_PORT` preserve o `X-Forwarded-For` desse par. Em produção, dê preferência a um `NEXT_PUBLIC_BASE_URL` explícito. | | `KIE_CALLBACK_URL` | _(não definida)_ | `open-sse/utils/kieTask.ts` | URL público de callback para tarefas kie.ai assíncronas. Substituição com a prioridade mais elevada, antes de `OMNIROUTE_KIE_CALLBACK_URL` e `OMNIROUTE_PUBLIC_URL`. | | `OMNIROUTE_KIE_CALLBACK_URL` | _(não definida)_ | `open-sse/utils/kieTask.ts` | Forma alternativa de escrever `KIE_CALLBACK_URL`. É utilizada como alternativa quando a variável principal não está definida. | | `OMNIROUTE_PUBLIC_URL` | _(não definida)_ | `open-sse/utils/kieTask.ts` | Origem pública utilizada para compor URLs de callback assíncronos. Alternativa com a prioridade mais baixa para callbacks kie.ai; também é utilizada como URL público genérico para outros retransmissores. | | `OMNIROUTE_CROF_USAGE_URL` | `https://crof.ai/usage_api/` | `open-sse/services/usage.ts` | Endpoint de consulta da quota CrofAI utilizado pela página Utilização. Substitua-o para retransmissores / acessórios 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 de 5 horas / semanal / mensal do ClinePass utilizado pela página Utilização. Substitua-o para retransmissores / acessórios de teste. | | `OMNIROUTE_OPENCODE_QUOTA_URL` | `https://opencode.ai/zen/go/v1/usage` | `open-sse/services/opencodeQuotaFetcher.ts` | Endpoint oficial de utilização do OpenCode Go, autenticado por chave de API e utilizado pela página Utilização. Substitua-o para retransmissores / acessórios de teste. | | `OPENCODE_SYNTHESIZE_CLI_HEADERS` | `true` | `open-sse/executors/opencode.ts` | Sintetiza os cabeçalhos de identidade da CLI do OpenCode (User-Agent, x-opencode-client/project, UUIDs de pedido/sessão) em pedidos a montante opencode-go/zen que o cliente não tenha enviado, para que a Cloudflare os aceite na saída de VPS (#6210/#5997). Ativo por predefinição desde #10571; desative com `false`/`0`/`no`/`off`. | | `OPENCODE_USER_AGENT` | `opencode/1.18.31` | `open-sse/utils/opencodeHeaders.ts` | User-Agent predefinido utilizado quando `OPENCODE_SYNTHESIZE_CLI_HEADERS` está ativado e não está definida nenhuma substituição `_USER_AGENT` específica do fornecedor. Aplicado apenas a executores opencode. Num pedido sem chave que seja bloqueado pelo serviço a montante, um valor configurado que não contenha `opencode/= 1.17>` é substituído por este valor predefinido, em vez de o pedido ser recusado. | | `OMNIROUTE_FORWARD_ATTRIBUTION` | `1` (ativado) | `open-sse/utils/opencodeHeaders.ts` | Reencaminha os cabeçalhos de atribuição da aplicação cliente (`x-session-id`, `x-title`, `http-referer`) para os fornecedores a montante, para que um pedido iniciado num dos ambientes listados mantenha a sua identidade ao passar pelo router (os controlos de publicação do OpenRouter baseiam-se nestes cabeçalhos). `0`/`false`/`no`/`off` mantém a identidade do registo/operador e elimina os valores fornecidos pelo cliente. Os cabeçalhos personalizados configurados pelo operador têm sempre precedência sobre os valores do cliente. | | `OPENCODE_CLIENT` | `desktop` | `open-sse/executors/opencode.ts` | Valor do cabeçalho `x-opencode-client` sintetizado quando `OPENCODE_SYNTHESIZE_CLI_HEADERS` está ativado. | | `OPENCODE_PROJECT` | `global` | `open-sse/executors/opencode.ts` | Valor do cabeçalho `x-opencode-project` sintetizado quando `OPENCODE_SYNTHESIZE_CLI_HEADERS` está ativado. | | `OMNIROUTE_EGRESS_IP_LOCK_PROVIDERS` | _(não definido)_ | `open-sse/config/providerErrorRules.ts` | Conjunto efetivo de fornecedores cujas falhas a montante são agrupadas por IP de saída (um erro 429 suspende todas as ligações relacionadas que partilhem esse IP). Quando não está definido, utiliza a predefinição do plano 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 agrupados por conta a montante e podem desativá-la em segurança (#9611). | | `OPENCODE_FREE_TIER_REQUEST_CONTRACT` | _(não definido)_ | `open-sse/executors/opencodeFreeTierContract.ts` | Defina como `off` para deixar de ajustar o corpo dos pedidos OpenCode sem chave (indicador de streaming e lista de ferramentas). Os cabeçalhos continuam a ser aplicados. É lido em cada pedido, pelo que qualquer alteração produz efeitos imediatos. | | `OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS` | _(não definido)_ | `open-sse/executors/opencodeFreeTierContract.ts` | Nomes de ferramentas separados por vírgulas a declarar num pedido OpenCode sem chave que não inclua nenhuma, quando ainda nada tiver sido observado para esse modelo. Se estiver vazio, recorre a um único marcador de posição que o modelo é instruído a não invocar. No máximo 32 entradas, `[A-Za-z_][A-Za-z0-9_-]{0,63}`; as entradas inválidas são ignoradas. | | `OMNIROUTE_OLLAMA_CLOUD_USAGE_URL` | `https://ollama.com/settings` | `open-sse/services/usage.ts` | URL das definições do Ollama Cloud utilizada para extrair informações sobre a quota. Substitua-a para retransmissores/cenários de teste. | | `OLLAMA_USAGE_COOKIE` | _(não definido)_ | `open-sse/services/usage.ts` | Cookie `__Secure-session` do Ollama Cloud utilizado para extrair informações sobre a quota a partir da página de definições. Sensível; quando estiverem configuradas várias contas, prefira o campo por ligação do Dashboard. | | `OLLAMA_CLOUD_USAGE_COOKIE` | _(não definido)_ | `open-sse/services/usage.ts` | Variável de ambiente alternativa para o cookie `__Secure-session` do Ollama Cloud. Sensível; quando estiverem configuradas várias contas, prefira o campo por ligação do Dashboard. | | `OMNIROUTE_OLLAMA_USAGE_COOKIE` | _(não definido)_ | `open-sse/services/usage.ts` | Variável de ambiente alternativa para o cookie `__Secure-session` do Ollama Cloud, utilizada antes dos aliases mais curtos. Sensível; quando estiverem configuradas várias contas, prefira o campo por ligação do Dashboard. | | `OMNIROUTE_CODEWHISPERER_BASE_URL` | `https://codewhisperer.us-east-1.amazonaws.com` | `open-sse/services/usage.ts` | Endpoint dos limites de utilização do CodeWhisperer (AWS Kiro). Substitua-o para retransmissores/cenários de teste. | > [!IMPORTANT] > Ao implementar atrás de um proxy inverso (nginx, Caddy), defina `NEXT_PUBLIC_BASE_URL` como o seu URL público estável (por exemplo, `https://omniroute.example.com`) quando os callbacks OAuth ou as ligações públicas geradas tiverem de utilizar esse nome de anfitrião. Sem isto, os callbacks OAuth podem falhar porque o redirect_uri não corresponderá, e as ligações públicas geradas podem apontar para a origem interna do contentor. > > Mantenha `BASE_URL` como um URL interno de loopback/contentor para tarefas entre servidores. Não utilize um `Origin` do navegador nem um nome de anfitrião público para pedidos internos à própria aplicação que incluam credenciais. > > As operações de escrita autenticadas do painel não exigem um URL base público estático: o painel envia pedidos não seguros para a mesma origem com um token CSRF associado à sessão. O OmniRoute continua a centralizar a validação da origem pública para integrações de navegador que não utilizem o painel: as variáveis de ambiente explícitas do URL público são consideradas fidedignas em primeiro lugar; os cabeçalhos `Forwarded` / `X-Forwarded-*` em bruto são ignorados, a menos que `OMNIROUTE_TRUST_PROXY` esteja ativado e o par proxy imediato esteja identificado por token como fidedigno. Não utilize definições de CORS para corrigir pedidos do painel para a mesma origem; o CORS destina-se apenas a clientes de navegador entre origens. --- ## 8. Proxy de saída Encaminhe as chamadas aos fornecedores de LLM a montante através de um proxy HTTP ou SOCKS5 para controlo de saída, encaminhamento geográfico ou ocultação de IP. `OMNIROUTE_UPSTREAM_HTTP2_ENABLED` tem como predefinição `true`. Defina-o como `false`, `0`, `no` ou `off` para forçar HTTP/1.1 nos dispatchers Undici em `open-sse/utils/proxyDispatcher.ts` e `open-sse/utils/proxyFetch.ts`: saída direta, proxies HTTP(S)/SOCKS, relays e respetivas novas tentativas com sockets novos. Isto preserva a verificação de certificados TLS, a autenticação do proxy, os limites de ligações e as definições de keep-alive. Reinicie o OmniRoute depois de alterar esta definição, porque os dispatchers são armazenados em cache e os agentes de relay são criados no arranque. Esta opção não controla a impressão digital TLS do wreq nem os transportes específicos dos fornecedores. | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------------------- | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ENABLE_SOCKS5_PROXY` | `true` | `open-sse/executors` | Ativa o agente proxy SOCKS5 para chamadas a serviços a montante. Desative com `false`. | | `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` | `true` | Lado do cliente | Conhecimento, no lado do cliente, da disponibilidade de SOCKS5. | | `PROXY_SKIP_RECENTLY_FAILED` | `true` | `src/shared/utils/featureFlags.ts` | Sinalizador de funcionalidade ativado por predefinição (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md); uma substituição na BD do painel tem precedência). Os conjuntos de proxies e a rotação por conta deixam de voltar a selecionar temporariamente um membro que acabou de falhar (sondagem TCP recusada ou erro 429 através dele), durante um período que duplica a cada repetição, até um limite máximo. `false` repõe a seleção simples. | | `SELECTOR_CONTROL_ALLOWLIST` | _(não definido)_ | `src/lib/proxySubscription/selectorGuard.ts` | Lista de permissões para alvos de controlo do seletor do núcleo local além do endereço de loopback (anfitriões ou IPs separados por vírgulas/espaços; `*` permite LAN/endereços privados, mas nunca metadados/link-local). O loopback através de http/https é permitido por predefinição. Quando definido e não vazio, um valor na BD do painel tem precedência sobre esta variável. | | `PROXY_QUOTA_429_BASE_MS` | `300000` | `open-sse/utils/proxyRefusalMemory.ts` | Período base (ms) de colocação de parte devido a um erro 429, duplicado a cada repetição. Lido uma vez no arranque. Limitado a `1000..3600000`; valores fora do intervalo ou ilegíveis fazem com que seja usado o valor predefinido, com um aviso. | | `PROXY_QUOTA_429_MAX_MS` | `900000` | `open-sse/utils/proxyRefusalMemory.ts` | Limite máximo (ms) de colocação de parte devido a um erro 429. Lido uma vez no arranque. Limitado a `1000..3600000`; valores fora do intervalo ou ilegíveis fazem com que seja usado o valor predefinido, com um aviso. Quando o limite máximo é inferior ao valor base, é usado o valor predefinido. Reduzir o limite máximo também antecipa o esquecimento das sequências: as entradas são eliminadas `2 x max` após expirarem. | | `PROXY_POOL_SHARED_EGRESS_ORDER` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de funcionalidade opcional (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md); uma substituição na BD do painel tem precedência). Para fornecedores cuja quota é agrupada por endereço de saída, posiciona um membro do conjunto que partilhe o endereço de saída observado de um membro recentemente recusado imediatamente abaixo dos membros em bom estado. Afeta apenas a ordem, sem qualquer exclusão. Requer `PROXY_SKIP_RECENTLY_FAILED`, que produz o sinal de recusa que este sinalizador lê. | | `PROXY_WEBHOOK_REBOUND_MS` | `300000` | `src/lib/proxyEvents/proxyTransitionBridge.ts` | Janela de recuperação (ms) que limita alertas webhook `proxy.set_aside` repetidos por membro do conjunto, para que uma sequência rápida de recusas envie apenas um evento. Lida em cada emissão. Limitada a `1000..3600000`; valores fora do intervalo ou ilegíveis fazem com que seja usado silenciosamente o valor predefinido. | | `HTTP_PROXY` | _(não definido)_ | Norma do Node.js | Proxy HTTP para chamadas a serviços a montante. | | `HTTPS_PROXY` | _(não definido)_ | Norma do Node.js | Proxy HTTPS para chamadas a serviços a montante. | | `ALL_PROXY` | _(não definido)_ | Norma do Node.js | Proxy universal (suporta `socks5://`). | | `OMNIROUTE_PROXY_ECHO_URL` | _(não definido)_ | `src/lib/proxyEchoTarget.ts` | Fixa o destino de eco de IP utilizado pelas sondagens de saída do proxy num único URL. Quando não está definido, a sondagem tenta `api64.ipify.org` e, em seguida, `api4.ipify.org`, para que os túneis apenas com IPv4 não sejam indicados como inativos (#9694). | | `NO_PROXY` | _(não definido)_ | Padrão do Node.js | Nomes de anfitrião/IP separados por vírgulas para ignorar o proxy. | | `OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS` | `32` | `open-sse/utils/proxyDispatcher.ts` | Número máximo de sockets simultâneos por dispatcher de proxy HTTP/SOCKS em cache. Os fluxos SSE de longa duração, como o Codex `/v1/responses`, precisam de mais do que uma ligação quando vários pedidos partilham o mesmo proxy ao nível da conta. Os valores superiores a `256` são limitados. | | `SOCKS_HANDSHAKE_TIMEOUT_MS` | `10000` | `open-sse/utils/socksConnectorWithFamily.ts` | Tempo limite, em ms, para o handshake (ligação) SOCKS5. Aumente-o quando um único anfitrião de gateway residencial estiver sujeito a elevada concorrência (por exemplo, 100 pedidos simultâneos) — o handshake real pode exceder 10 s com um conjunto saturado, mesmo que o proxy esteja acessível, o que, caso contrário, é apresentado incorretamente como `[Proxy Fast-Fail] Proxy unreachable`. Limitado a `120000`. | | `PROXY_FAIL_OPEN` | `false` | `src/sse/handlers/chatHelpers.ts` | Quando definido como `false` (predefinição), um pedido cujo proxy atribuído não seja resolvido é **recusado (fail-closed)**, em vez de recorrer a uma ligação direta — isto evita fugas do IP real. Defina como `true` para restaurar o fallback DIRECT antigo. | | `ENABLE_TLS_FINGERPRINT` | `false` | `open-sse/executors` | Falsifica a impressão digital TLS através de wreq-js (imita o Chrome 124). Contorna bloqueios JA3/JA4. | | `TLS_FINGERPRINT_PROVIDERS` | _(não definido)_ | `open-sse/utils/proxyFetch.ts` | Lista de fornecedores permitidos, separada por vírgulas, para o novo encaminhamento TLS através de proxy (`open-sse/utils/proxyFetch.ts`). Quando não está definido, o TLS direto mantém o comportamento antigo; apenas estes fornecedores são encaminhados através da ponte de impressão digital do Chrome 124. O Groq (`api.groq.com`) é excluído mesmo quando a lista de permissões não está definida, porque o JA3 do Chrome aciona o erro 1010 do Cloudflare, enquanto o undici nativo consegue aceder à API. | | `OMNIROUTE_TURNSTILE_IGNORE_TLS_ERRORS` | `false` | `open-sse/services/claudeTurnstileSolver.ts` | Permite que o contexto do navegador Playwright do Claude Turnstile ignore erros de certificado HTTPS. | ### Cenários | Cenário | Configuração | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **SOCKS5 através de túnel SSH** | `ALL_PROXY=socks5://127.0.0.1:7890`, `ENABLE_SOCKS5_PROXY=true` | | **Proxy HTTP empresarial** | `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** | Mantenha `PROXY_FAIL_OPEN=false` (predefinição). Os pedidos falham imediatamente quando o proxy não está disponível, em vez de exporem dados através de uma ligação direta. | | **Antigo/desenvolvimento — permitir fallback direto** | `PROXY_FAIL_OPEN=true`. Restaura o comportamento anterior ao reforço de segurança: é utilizada uma ligação direta quando a resolução do proxy falha. | > **Nota (omissão da validação da NVIDIA — #3226):** o endpoint de validação de chaves de API da NVIDIA > fica bloqueado quando é encaminhado através do fetch global com patch de proxy/TLS (dispatcher do undici → 504). > `src/lib/providers/validation.ts::directHttpsRequest()` ignora intencionalmente o > patch de proxy apenas para essa chamada de validação através de `safeOutboundFetch({ bypassProxyPatch: true })`. > Esta é uma exceção documentada e de âmbito limitado — **não** afeta a saída de chat/utilização. > O âmbito da omissão é fixado por `tests/unit/proxy-bypass-scope-guard-3226.test.ts`. --- ## 9. Integração de Ferramentas CLI Controla a forma como o OmniRoute deteta e inicia sidecars de CLI (Claude Code, Codex, etc.). | Variável | Predefinição | Ficheiro de origem | Descrição | | --------------------------------- | -------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLI_MODE` | `auto` | `src/shared/services/cliRuntime.ts` | `auto` = procurar no PATH do sistema; `manual` = utilizar apenas caminhos explícitos. | | `CLI_EXTRA_PATHS` | _(não definido)_ | `src/shared/services/cliRuntime.ts` | Entradas PATH adicionais para a deteção de binários da CLI (separadas por dois-pontos). | | `CLI_CONFIG_HOME` | _(não definido)_ | `src/shared/services/cliRuntime.ts` | Substitui o diretório pessoal utilizado para ler as configurações da CLI (`~/.claude`, `~/.codex`). Tem de ser absoluto e estar dentro do diretório pessoal do processo — **ou**, num contentor, ser um caminho montado através de bind (é assim que `/host-home` funciona). Qualquer outro caminho faz com que seja utilizado o diretório pessoal. | | `CLI_ALLOW_CONFIG_WRITES` | `true` | `src/shared/services/cliRuntime.ts` | Permite que o OmniRoute escreva ficheiros de configuração da CLI (renovação de tokens, dados de sessão). Defina como `false` para que qualquer escrita na configuração da CLI falhe com um erro explícito de «escritas desativadas». | | `CLI_CLAUDE_BIN` | `claude` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Claude. | | `CLI_CODEX_BIN` | `codex` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Codex. | | `CLI_DROID_BIN` | `droid` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Droid. | | `CLI_OPENCLAW_BIN` | `openclaw` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do OpenClaw. | | `CLI_CURSOR_BIN` | `agent`, depois `cursor` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário do agente Cursor. Se não for definido, a deteção tenta primeiro `agent` e, se não o encontrar, utiliza `cursor`. | | `CLI_CLINE_BIN` | `cline` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Cline. | | `CLI_5DIVE_BIN` | `5dive` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do 5dive. | | `CLI_5DIVE_STATE_DIR` | `/var/lib/5dive` | `src/shared/services/cliRuntime.ts` | Diretório de estado do sistema do 5dive (perfis de autenticação pertencentes ao utilizador root); corresponde à predefinição STATE_DIR do próprio 5dive. | | `CLI_CONTINUE_BIN` | `cn` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Continue. | | `CLI_QODER_BIN` | `qodercli` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Qoder. | | `CLI_QWEN_BIN` | `qwen` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Qwen Code. | | `CLI_AIDER_BIN` | `aider` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Aider. | | `CLI_GOOSE_BIN` | `goose` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Goose. | | `CLI_GEMINI_BIN` | `gemini` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Google Gemini — apenas para deteção/verificações de estado no lado do servidor; `omniroute run gemini` resolve o binário `gemini` a partir do PATH do sistema. | | `CLI_KILO_BIN` | `kilocode` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do Kilo Code. | | `CLI_OPENCODE_BIN` | `opencode` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI do OpenCode. | | `CLI_HERMES_BIN` | `hermes` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário do 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 da CLI ForgeCode. | | `CLI_JCODE_BIN` | `jcode` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI jcode. | | `CLI_DEEPSEEK_TUI_BIN` | `deepseek-tui` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da TUI DeepSeek. | | `CLI_CODEWHALE_BIN` | `codewhale` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI CodeWhale. | | `CLI_SMELT_BIN` | `smelt` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI Smelt. | | `CLI_PI_BIN` | `pi` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário do Pi (pi-coding-agent). | | `CLI_CRUSH_BIN` | `crush` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário da CLI Crush. | | `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 da CLI Letta. | | `CLI_PRIME_AGENT_BIN` | `prime-agent` | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário do Prime Agent (Prime Intellect). | | `CLI_WINDSURF_BIN` | _(nenhum)_ | `src/shared/services/cliRuntime.ts` | Caminho personalizado para o binário do Windsurf. O Windsurf é distribuído **sem comando predefinido** — a deteção do binário permanece desativada até esta opção ser definida. | | `CLI_DEVIN_BIN` | `devin` | `open-sse/executors/devin-cli.ts` | Caminho personalizado para o binário da CLI Devin (v3.8.0). Utilizado pelo executor Windsurf/Devin. | | `DEVIN_DESKTOP_VERSION` | `3.6.27` | `open-sse/executors/devin-desktop.ts` | `ide_version` do Devin Desktop. As substituições têm de utilizar o formato `x.y.z`; os valores inválidos revertem para o valor predefinido verificado. | | `DEVIN_DESKTOP_EXTENSION_VERSION` | `1.48.2` | `open-sse/executors/devin-desktop.ts` | `extension_version` do Codeium/servidor de linguagem incluído, distinta da `ide_version` do Desktop. As substituições têm de utilizar `x.y.z`; os valores inválidos utilizam o valor predefinido incluído. | | `CLI_DEVIN_AGENTIC_BIN` | `devin` | `open-sse/executors/devin-cli-agentic.ts` | Substituição da CLI Devin apenas para a ponte agêntica. O executor aceita apenas o upstream ACP stdio local. | | `DEVIN_AGENTIC_HOME` | _(obrigatório)_ | `open-sse/executors/devin-cli-agentic.ts` | Diretório pessoal absoluto e isolado para o subprocesso Devin agêntico; os caminhos de ponte aceites são `/home/bridge` e caminhos `.sandbox` locais à tarefa (no Windows, `C:\...\.sandbox\...`). | | `DEVIN_AGENTIC_ACP_TIMEOUT_MS` | `120000` | `open-sse/executors/devin-cli-agentic.ts` | Duração máxima de um turno ACP do Devin antes de a ponte terminar o processo filho e devolver explicitamente um tempo limite. | | `DEVIN_BRIDGE_MODEL` | `devin-cli-agentic/swe-1-7` | `docker/devin-bridge/compose.yml` | Alias do modelo principal do Claude Code para a ponte isolada. O ambiente de testes em execução substitui o exemplo por um modelo devolvido pela conta Devin atual. | | `DEVIN_BRIDGE_SONNET_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias da ponte isolada utilizado quando o Claude Code solicita o seu modelo Sonnet predefinido. | | `DEVIN_BRIDGE_OPUS_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias da ponte isolada utilizado quando o Claude Code solicita o seu modelo Opus predefinido. | | `DEVIN_BRIDGE_HAIKU_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias da ponte isolada utilizado quando o Claude Code solicita o seu modelo Haiku predefinido. | | `DEVIN_BRIDGE_SUBAGENT_MODEL` | `DEVIN_BRIDGE_MODEL` | `docker/devin-bridge/compose.yml` | Alias da ponte isolada utilizado para os subagentes do Claude Code. | | `DEVIN_SEAT_API_URL` | `https://server.codeium.com` | `open-sse/services/usage/devinCli.ts` | Substituição opcional para a API de gestão de licenças do Codeium utilizada pela quota da CLI do Devin (`GetUserStatus`). | | `AUGGIE_BIN` | `auggie` | `open-sse/executors/auggie.ts` | Substituição por caminho absoluto para o binário da CLI do Augment (Auggie) utilizado pelo fornecedor local `auggie`. Como alternativa, utiliza `CLI_AUGGIE_BIN` e, em seguida, procura no PATH. | | `CLI_AUGGIE_BIN` | `auggie` | `open-sse/executors/auggie.ts` | Substituição alternativa para o caminho do binário da CLI do Augment (Auggie) (verificada após `AUGGIE_BIN`). | | `ZCODE_BIN` | `zcode` | `open-sse/executors/zcode.ts` | Binário utilizado pelo cliente stdio do fornecedor local `zcode`. Como alternativa, utiliza `zcode` no PATH. | | `ZCODE_ARGS` | — | `open-sse/executors/zcode.ts` | Matriz JSON (≤16 cadeias de caracteres) de argumentos adicionais transmitidos ao binário `zcode` quando iniciado através de `cliTools`. | | `ZCODE_CWD` | `process.cwd()` | `open-sse/executors/zcode.ts` | Diretório de trabalho do subprocesso do servidor de aplicações ZCode. | | `ZCODE_PROVIDER_ID` | `builtin:zai-coding-plan` | `open-sse/executors/zcode.ts` | Substituição do ID do fornecedor enviado ao servidor de aplicações. | | `ZCODE_SERVER_RUNTIME_ROOT` | `~/.zcode/server` | `open-sse/executors/zcode.ts` | Raiz do ambiente de execução do servidor de aplicações ZCode (onde se encontram o `node` e o `zcode-server.cjs` incluídos). | | `ZCODE_SERVER_NODE` | `/node` | `open-sse/executors/zcode.ts` | Executável Node 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) após o qual o início de um servidor de aplicações ZCode é considerado como falhado. | | `ZCODE_RPC_TIMEOUT_MS` | `30000` | `open-sse/executors/zcode.ts` | Tempo limite de RPC por pedido (ms) para uma chamada ao servidor de aplicações ZCode. | | `ZCODE_TURN_TIMEOUT_MS` | `120000` | `open-sse/executors/zcode.ts` | Duração máxima (ms) de um turno do ZCode antes de o supervisor atingir o tempo limite. | | `ZCODE_POLL_INTERVAL_MS` | `250` | `open-sse/executors/zcode.ts` | Intervalo de consulta (ms) para a conclusão de turnos do ZCode. | | `HERMES_HOME` | `~/.hermes` | `src/lib/cli-helper/config-generator/hermesHome.ts` | Diretório inicial do Hermes Agent onde o OmniRoute lê/escreve a configuração da CLI do Hermes. Corresponde à variável de ambiente definida no Windows pelo instalador PowerShell do Hermes (`%LOCALAPPDATA%\hermes`). | ### Sincronização automática de perfis da CLI Estes sinalizadores de funcionalidades são opcionais e estão desativados por predefinição. Também podem ser ativados ou desativados a partir do painel CLI Code. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------- | ------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_AUTO_SYNC_CODEX_PROFILES` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | Após uma sincronização dos modelos do fornecedor, reescreve automaticamente os ficheiros de perfil `~/.codex/*.config.toml` a partir do catálogo ativo. Requer `CLI_ALLOW_CONFIG_WRITES`; nunca altera a configuração ativa/predefinida do 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 uma sincronização dos modelos do fornecedor, reescreve automaticamente os ficheiros de perfil do Claude Code `~/.claude/profiles//settings.json` a partir do catálogo ativo. Requer `CLI_ALLOW_CONFIG_WRITES`; nunca altera a configuração ativa/predefinida do Claude, a autenticação ou a escolha do fornecedor. | ### Exemplo de Docker ```bash # Monte os binários do anfitrião no contentor e indique ao OmniRoute onde se encontram: 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ó produz efeito quando o caminho é efetivamente montado por bind a partir do anfitrião — utilize-o em conjunto com montagens como `~/.codex:/host-home/.codex:rw` (consulte o perfil `host` em `docker-compose.yml`). Um caminho que não esteja dentro do diretório pessoal do utilizador do contentor nem seja uma montagem bind é ignorado, porque tudo o que fosse escrito nesse local seria descartado quando o contentor fosse recriado. A imagem é executada como `USER node`, pelo que um `/root` não montado **não** é uma substituição válida. | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------------------- | -------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_CONTAINER` | _(automático)_ | `src/shared/utils/containerEnv.ts` | Força a deteção de contentor a estar ativa (`1`/`true`) ou inativa (`0`/`false`). Só é necessário em ambientes de execução que a deteção automática não identifique. | | `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE` | `false` | `src/shared/services/cliRuntime.ts` | Permite, ainda assim, que a ferramenta CLI escreva a configuração num caminho não montado do contentor. O equivalente na CLI é `--allow-container-write`. | ### Auxiliares do binário CLI (`omniroute`) Estas variáveis ajustam o comportamento do próprio binário CLI `omniroute` (não a deteção do sidecar acima). | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------- | --------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OMNIROUTE_LANG` | _(sistema)_ | `bin/cli/i18n.mjs` | Força o idioma de saída da CLI. Localidade BCP-47 (por exemplo, `en`, `pt-BR`). Substitui as variáveis de ambiente de localidade do sistema (LC_ALL, LC_MESSAGES). | | `OMNIROUTE_SHOW_LOG` | _(não definida)_ | `bin/cli/runtime/processSupervisor.mjs` | Defina como `1` para encaminhar o stdout/stderr do servidor para o terminal no modo supervisionado. Equivale à opção `--log` em `omniroute serve`. | | `OMNIROUTE_CLI_TOKEN` | _(não definida)_ | `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` | _(não definida)_ | `bin/cli/commands/setup-gemini.mjs` | Raiz persistente do diretório pessoal do Gemini; uma execução única utiliza um diretório pessoal temporário e isolado. | | `OMNIROUTE_CHILD_SIGNAL_TIMEOUT_MS` | `5000` | `bin/cli/commands/run.mjs` | Período de tolerância, em milissegundos, antes de terminar à força um processo-filho da CLI ao qual foi enviado um sinal. | | `OMNIROUTE_CLI_SKIP_DEFAULT_DATA_ENV` | _(não definida)_ | `bin/omniroute.mjs` | Defina como 1 juntamente com um DATA_DIR explícito para ignorar o ficheiro de ambiente predefinido do diretório de dados do utilizador. | | `OMNIROUTE_SYNC_TOKEN` | _(não definida)_ | `bin/cli/commands/sync.mjs` | Token de sincronização para `omniroute sync bundle` (`GET /api/sync/bundle` aceita apenas um token de sincronização, não uma chave de API). Equivale a `--token`. | | `OMNIROUTE_HTTP_TIMEOUT_MS` | `30000` | `bin/cli/api.mjs` | Tempo limite HTTP por tentativa (ms) para pedidos da CLI → servidor. | | `OMNIROUTE_READY_TIMEOUT_MS` | `60000` | `bin/cli/utils/pid.mjs` | Tempo máximo (ms) durante o qual a CLI aguarda pelo endpoint de estado do servidor antes de apresentar um aviso de tempo limite. Útil para arranques a frio lentos (por exemplo, no Windows). Também pode ser definido através de `--ready-timeout`. | | `OMNIROUTE_VERBOSE` | `0` | `bin/cli/api.mjs` | Defina como `1` para apresentar diagnósticos de novas tentativas/recuo em stderr durante os comandos da CLI. | | `OMNIROUTE_PLUGIN_PATH` | _(não definida)_ | `bin/cli/plugins.mjs` | Diretório personalizado para a deteção de plugins da CLI (pacotes `omniroute-cmd-*`). Quando não está definida, a predefinição é `~/.omniroute/plugins/`. Apenas para a CLI — nunca chega ao analisador de plugins do lado do servidor, que é indicado por `OMNIROUTE_PLUGINS_DIR` (secção 2). | | `OMNIROUTE_NO_UPDATE_NOTIFIER` | _(não definida)_ | `bin/omniroute.mjs` | Suprime a notificação de atualização da CLI ao terminar o processo quando definida com qualquer valor não vazio. O aviso permanece desativado de forma independente em CI, no modo silencioso e nos modos de saída que não sejam de texto. | | `OMNIROUTE_DOCTOR_LIVENESS_URL` | _(derivada)_ | `bin/cli/commands/doctor.mjs` | URL de disponibilidade verificado por `omniroute doctor`. Uma opção programática `livenessUrl` tem precedência; caso contrário, este valor é utilizado literalmente. Quando não está definida, a 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 de fornecedores utilizado pelos comandos de fornecedor da CLI. Uma opção programática `catalogPath` tem precedência. Os caminhos absolutos são utilizados tal como estão; os caminhos relativos são resolvidos a partir da raiz do projeto. Quando não está definida, a CLI utiliza o diretório de constantes dos fornecedores, recorrendo ao ficheiro antigo `providers.ts` como alternativa. | | `OMNIROUTE_PROVIDER_TEST_MODEL` | _(predefinição do fornecedor)_ | `bin/cli/provider-test.mjs` | Modelo alternativo global para testes de ligação a fornecedores através da CLI. A ordem de precedência é: modelo de ligação configurado, substituição do modelo específica do fornecedor, este valor e, por fim, o modelo de teste incorporado do fornecedor. | --- ## 10. Integrações internas do agente e MCP | Variável | Predefinição | Ficheiro de origem | Descrição | | ----------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OMNIROUTE_BASE_URL` | deteção automática | `open-sse/mcp-server/server.ts` | URL explícito para as ferramentas MCP/A2A acederem ao OmniRoute. Substitui a deteção automática de localhost. | | `OMNIROUTE_API_KEY` | _(não definida)_ | Módulos MCP/A2A | Chave de API para chamadas internas de ferramentas MCP e competências A2A. | | `OMNIROUTE_API_KEY_ID` | _(não definida)_ | `open-sse/mcp-server/audit.ts` | ID da chave para atribuição no registo de auditoria MCP. | | `ROUTER_API_KEY` | _(não definida)_ | Legado | Nome alternativo legado para `OMNIROUTE_API_KEY`. | | `OMNIROUTE_A2A_HISTORY_RETENTION_DAYS` | `30` | `src/lib/a2a/taskManager.ts` | Número de dias durante os quais o histórico de tarefas A2A é mantido na base de dados local antes de a limpeza diária eliminar uma linha. Se não estiver definido, não for numérico ou for `<= 0`, é utilizado `30`. | | `OMNIROUTE_A2A_MEMORY_HITS` | `1` | `src/lib/a2a/taskExecution.ts` | Interruptor de desativação da funcionalidade de observabilidade de ocorrências de memória A2A. Defina como `0` para ignorar totalmente a consulta de recuperação de memória de uma tarefa; qualquer outro valor (incluindo não definido) mantém-na ativada. | | `OMNIROUTE_ISSUE_AGENT_ENABLED` | `false` | `src/app/api/issue-agent/runs/route.ts` | Ativa o endpoint de triagem registada offline/local do Issue Agent. Mantenha-o desativado, salvo se estiver explicitamente a executar fluxos de trabalho locais de triagem registada. | | `OMNIROUTE_ISSUE_AGENT_TIMEOUT_MS` | _(não definida)_ | `src/lib/issueAgent/execution.ts` | Tempo limite (ms) para uma única execução de triagem registada do Issue Agent. É limitado a um máximo interno; recorre ao valor predefinido incorporado quando não está definido ou é inválido. | | `OMNIROUTE_CONTEXT` | _(contexto ativo)_ | `bin/cli/program.mjs`, `bin/cli/api.mjs` | Contexto/perfil do modo remoto da CLI para comandos `omniroute`; substitui o contexto ativo no armazenamento local de contextos. Equivalente a `--context `. | | `OMNIROUTE_CONTEXT_KEYCHAIN_DISABLED` | `0` | `bin/cli/contexts.mjs` | Desativa o backend opcional do porta-chaves do sistema operativo `keytar` para credenciais de contexto da CLI. Quando ativado, as credenciais permanecem em `config.json` com o modo `0600` e a CLI emite um aviso único sobre a alternativa; destina-se à utilização deliberada em ambientes sem interface gráfica/contentores. | | `OMNIROUTE_MCP_ENFORCE_SCOPES` | `false` | `open-sse/mcp-server/server.ts` | Impõe controlo de acesso baseado em âmbitos nas chamadas de ferramentas MCP. | | `OMNIROUTE_MCP_SCOPES` | _(todos)_ | `open-sse/mcp-server/server.ts` | Âmbitos separados por vírgulas: `admin`, `combos`, `health`, `models`, `routing`, `budget`, `metrics`, `pricing`, `memory`, `skills`. | | `OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS` | `false` | `open-sse/mcp-server/descriptionCompressor.ts` | Comprime as descrições das ferramentas MCP antes de serializar o manifesto. Valores de ativação: `1`, `true`, `on`. | | `OMNIROUTE_MCP_DESCRIPTION_COMPRESSION` | `rtk` | `open-sse/mcp-server/descriptionCompressor.ts` | Algoritmo/perfil de compressão. Valores de desativação: `0`, `false`, `off`. | | `OMNIROUTE_MCP_FETCH_TIMEOUT_MS` | `10000` | `open-sse/mcp-server/fetchTimeout.ts` | Limite de cancelamento (ms) para leituras internas de gestão do servidor MCP (estado, resiliência, combinações, quota, utilização). | | `OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS` | `60000` | `open-sse/mcp-server/fetchTimeout.ts` | Limite de tempo para cancelamento (ms) em saltos MCP que aguardam um fornecedor (`route_request`, `web_search`, `web_fetch`). | | `OMNIROUTE_CORPUS_CACHE_SIZE` | `5` | `src/lib/localCorpus/configured.ts` | Número máximo de instâncias do índice do corpus local mantidas em cache na memória (LRU, uma por diretório raiz indexado). Limitado 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` | Intervalo de consulta dos limites de utilização e das quotas do fornecedor. | | `PROVIDER_LIMITS_SYNC_SPACING_MS` | `1500` | `src/lib/usage/providerLimits.ts` | Intervalo (ms) entre obtenções consecutivas de quotas OAuth numa sincronização em massa; as ligações OAuth são consultadas uma de cada vez para evitar sobrecarregar o serviço a montante. `0` desativa este comportamento (execução em simultâneo). | | `OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS` | `250` | `open-sse/services/quotaFetchThrottle.ts` | Intervalo mínimo (ms) entre obtenções consecutivas de quotas a montante no caminho de pré-verificação/monitorização por pedido; espaça as chamadas de rede simultâneas para que várias contas num único IP não sobrecarreguem o serviço a montante. Integrado nos mecanismos de obtenção de quotas do Codex (`/wham/usage`), DeepSeek, Bailian (em ambos os locais de obtenção), OpenCode e Crof (#6009, #6911). O caminho genérico de encaminhamento `usage.ts::getUsageForProvider` (github/glm/minimax/nanogpt/xai/etc.) ainda não está abrangido — é acompanhado separadamente. Os acertos de cache não são afetados. `0` desativa; limitado ao intervalo `0..5000`. | | `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 à API de quotas a montante para registar o consumo. | | `OMNIROUTE_LOGIN_BROWSER_PATH` | deteção automática | `open-sse/services/adobeFireflyBrowserLogin.ts` | Caminho absoluto para um executável do Chrome ou Edge do sistema, utilizado para o início de sessão interativo no Adobe Firefly e para a renovação em segundo plano. | | `ADOBE_FIREFLY_BROWSER_REFRESH` | ativado | `open-sse/services/adobeFireflySession.ts` | Mantém atualizados o IMS e o estado de risco do navegador através de sessões Chrome CDP associadas à conta. Defina como `0` para desativar a renovação pelo navegador. | | `ADOBE_FIREFLY_SESSION_DISK` | ativado | `open-sse/services/adobeFireflySession.ts` | Mantém as sessões Adobe reparadas em `DATA_DIR` após reinícios do processo. Defina como `0` para manter as sessões apenas na memória. | | `ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS` | `12000` | `open-sse/services/adobeFireflySession.ts` | Intervalo mínimo, em milissegundos, entre submissões de geração ao Adobe Firefly; `0` desativa o intervalo. | | `ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS` | `15000` | `open-sse/services/adobeFireflySession.ts` | Período de pausa adicional, em milissegundos, após cada terceira submissão bem-sucedida à Adobe. | | `ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS` | `8000` | `open-sse/services/adobeFireflyClient.ts` | Tempo base de espera progressiva, em milissegundos, após respostas 408 transitórias da Adobe; combinado com o espaçamento entre submissões ao longo de, no máximo, cinco tentativas. | | `OMNIROUTE_DISABLE_BACKGROUND_SERVICES` | `false` | `src/instrumentation-node.ts` | Desativa todos os serviços em segundo plano (sincronização, preços, atualização de modelos). Útil para CI/testes. | | `OMNIROUTE_HEADLESS` | _(não definido)_ | `src/lib/system/headless.ts` | Arranque apenas do motor de proxy: ignora subsistemas opcionais, `/dashboard` → 404. Equivalente a `omniroute serve --headless`. Consulte [HEADLESS.md](../guides/HEADLESS.md). | | `OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS` | _(não definido)_ | `src/lib/config/runtimeSettings.ts` | Força a ativação das tarefas em segundo plano quando é detetado um teste automatizado. Defina como `1` para substituir a heurística de teste. | | `OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS` | `600000` | `src/lib/jobs/budgetResetJob.ts` | Cadência da verificação de reposição do orçamento (ms). Mínimo `10000`. | | `OMNIROUTE_CONNECTION_RECOVERY_INTERVAL_MS` | `60000` | `src/lib/quota/connectionRecovery.ts` | Cadência da recuperação proativa do período de espera das ligações (ms): revalida as ligações cujo `rate_limited_until` transitório terminou, fora do caminho crítico dos pedidos. Mínimo `5000`. | | `OMNIROUTE_DISABLE_CONNECTION_RECOVERY` | `false` | `src/lib/quota/connectionRecovery.ts` | Desativa o agendador de recuperação proativa do período de espera das ligações (a recuperação tardia em `getProviderCredentials` continua a aplicar-se). | | `OMNIROUTE_REASONING_CACHE_CLEANUP_INTERVAL_MS` | `1800000` | `src/lib/jobs/reasoningCacheCleanupJob.ts` | Cadência da limpeza da cache de raciocínio (ms). Mínimo `60000`. | | `OMNIROUTE_REASONING_MIN_BUDGET` | _não definido_ (desativado) | `open-sse/services/reasoningTokenBuffer.ts` | Limite mínimo opcional para orçamentos de saída de modelos de raciocínio: o `max_tokens` do autor da chamada no intervalo `[256, mínimo)` é aumentado para o mínimo (limitado pelo limite de saída do modelo). Não definido = os orçamentos do cliente nunca são aumentados (#9507). | | `OMNIROUTE_REASONING_EFFORT_PROBE_PROVIDERS` | _não definido_ (desativado) | `open-sse/services/learnedReasoningEffortCaps.ts` | IDs de fornecedores opcionais, separados por vírgulas (ou `*`): quando uma resposta 400/422 a `reasoning_effort` não indica qualquer conjunto aceite, tenta novamente uma vez com um nível inferior (nunca abaixo de `low`) e aprende esse nível apenas se a tentativa exploratória obtiver resposta (#14895). | | `OMNIROUTE_LOG_EXPORT_CRON` | `0 * * * *` | `src/lib/jobs/logExportJob.ts` | Expressão cron (UTC) para a tarefa de exportação dos registos de chamadas, que esvazia todos os destinos de exportação de registos ativados. | | `OMNIROUTE_CONFIG_HOT_RELOAD_MS` | `5000` | `src/lib/config/hotReload.ts` | Intervalo de consulta (ms) para o recarregamento dinâmico da configuração. Valores inferiores a `1000` são rejeitados. | | `OMNIROUTE_DISABLE_REDIS_AUTH_CACHE` | _(ativado)_ | `src/lib/db/apiKeys.ts` | Defina como `1` para ignorar a cache de autenticação de chaves de API baseada no Redis (força leituras da base de dados). | | `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS` | `0` | `open-sse/services/compression/engines/rtk/filterLoader.ts` | Confia nas regras de filtragem de projetos 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 o truncamento proativo dos resultados de ferramentas no Lite quando `lite.maxToolLength` não está definido. Intervalo 256–1000000. A definição do painel prevalece sobre esta variável de ambiente. | | `OMNI_COMPRESSION_WORKERS` | `2` | `open-sse/services/compression/compressionWorkerPool.ts` | Número máximo de workers RTK/Caveman síncronos em simultâneo; as tarefas excedentes aguardam em ordem FIFO. | | `OMNI_COMPRESSION_WORKER_TIMEOUT_MS` | `120000` | `open-sse/services/compression/compressionWorkerPool.ts` | Tempo limite por tarefa, em milissegundos. Os workers que excedam o tempo limite são terminados e o pedido prossegue sem alterações. | | `OMNI_COMPRESSION_WORKER_IDLE_MS` | `60000` | `open-sse/services/compression/compressionWorkerPool.ts` | Tempo de inatividade, em milissegundos, antes de um worker de compressão não utilizado ser terminado. | | `OMNI_COMPRESSION_WORKER_MAX_OLD_MB` | `1024` | `open-sse/services/compression/compressionWorkerPool.ts` | Limite, em MB, da heap de geração antiga do V8 para cada worker de compressão, em todos os modos (mínimo `128`). Uma tarefa que o exceda prossegue sem compressão, em vez de aumentar a heap do gateway. | | `COMPRESSION_PIPELINE_BREAKER_ENABLED` | `false` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Interruptor principal do disjuntor por motor do pipeline empilhado T02. **Opcional (desativado por predefinição)** — quando ativado, um motor que gere erros repetidamente entre pedidos é ignorado (prosseguindo sem falha) durante um período de espera; desativado = comportamento legado idêntico ao nível dos bytes. | | `COMPRESSION_PIPELINE_BREAKER_THRESHOLD` | `3` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Número de falhas consecutivas entre pedidos antes de o disjuntor de um motor abrir. | | `COMPRESSION_PIPELINE_BREAKER_COOLDOWN_MS` | `30000` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Milissegundos durante os quais um motor aberto permanece ignorado antes de uma tentativa em estado semiaberto. | | `COMPRESSION_CCR_RETRIEVAL_RAMP_FACTOR` | `2` | `open-sse/services/compression/engines/ccr/index.ts` | Rampa de feedback de recuperação CCR T08/H8: cada recuperação anterior de um bloco armazenado aumenta linearmente o seu `minChars` efetivo (o conteúdo recuperado frequentemente é menos comprimido; `>=3` recuperações = nunca comprimido). `1` desativa a rampa (apenas omissão binária no limiar). | | `COMPRESSION_CCR_DURABLE_STORE` | `true` | `open-sse/services/compression/engines/ccr/index.ts` | Armazenamento duradouro de blocos CCR (#9061). Complementa o armazenamento em memória com SQLite, permitindo que um bloco sobreviva à expulsão LRU, ao TTL, a um reinício ou a uma recuperação que seja encaminhada para outra instância. Defina como `false` para manter os blocos apenas em memória. Os blocos com mais de 512KB e os ambientes de execução na cloud permanecem apenas em memória, independentemente desta definição. | | `COMPRESSION_PREFIX_FREEZE_ENABLED` | `false` | `open-sse/services/compression/prefixFreeze.ts` | Interruptor principal do congelamento de prefixos observado pela utilização T08/H5. **Ativação opcional (desativado por predefinição)** — quando ativado, um prompt de sistema observado `>=` ao limiar é tratado como um prefixo estável passível de armazenamento em cache e preservado da compressão, mesmo para fornecedores que a heurística estática de cache não deteta (o congelamento apenas _preserva_, nunca altera). | | `COMPRESSION_PREFIX_FREEZE_THRESHOLD` | `3` | `open-sse/services/compression/prefixFreeze.ts` | Número de observações de um prompt de sistema antes de este ser tratado como um prefixo estável congelado. | | `OMNIROUTE_BOOTSTRAPPED` | `false` | `src/app/(dashboard)/dashboard/page.tsx` | Definido como `true` pelo script de inicialização 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` | Mecanismo de escape: permite que o corpo do pedido substitua o campo de projeto do Antigravity. | | `ANTIGRAVITY_CREDITS` | `off` | `open-sse/services/antigravityCredits.ts` | Política de créditos do Google One AI: `off` nunca injeta créditos, `retry` injeta-os uma vez após um erro 429 de quota elegível e `always` injeta-os no primeiro pedido. | | `ANTIGRAVITY_ALLOW_SIGNATURE_BYPASS` | `0` | `open-sse/translator/request/openai-to-gemini.ts` | Permite que o tradutor de pedidos do Antigravity ignore a validação rigorosa da assinatura de pedidos da CLI quando o serviço a montante recusa assinaturas reais (modo de depuração/CLI obsoleta). Um valor diferente de zero ativa a omissão. | | `AGY_TOKEN_FILE` | `~/.gemini/antigravity-cli/antigravity-oauth-token` | `src/app/api/providers/agy-auth/apply-local/route.ts` | Substitui o caminho do ficheiro de token da CLI do Antigravity (agy) para a importação do início de sessão local detetado automaticamente. | ### Ponte OAuth da CLI (Interna) | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------- | ------------------ | ------------------------------- | ----------------------------------------------------------- | | `OMNIROUTE_SERVER` | deteção automática | `src/lib/oauth/config/index.ts` | URL do servidor para a ponte de autenticação CLI↔OmniRoute. | | `OMNIROUTE_TOKEN` | _(não definido)_ | `src/lib/oauth/config/index.ts` | Token de autenticação para a ponte da CLI. | | `OMNIROUTE_USER_ID` | `cli` | `src/lib/oauth/config/index.ts` | ID de utilizador para sessões da ponte da CLI. | | `SERVER_URL` | _(não definido)_ | `src/lib/oauth/config/index.ts` | Alias legado de `OMNIROUTE_SERVER`. | | `CLI_TOKEN` | _(não definido)_ | `src/lib/oauth/config/index.ts` | Alias legado de `OMNIROUTE_TOKEN`. | | `CLI_USER_ID` | _(não definido)_ | `src/lib/oauth/config/index.ts` | Alias legado de `OMNIROUTE_USER_ID`. | --- ## 11. Credenciais do Fornecedor OAuth Credenciais incorporadas para **desenvolvimento local**. Para implementações remotas, registe as suas próprias na consola de programador de cada fornecedor. | Variável | Fornecedor | Notas | | :------------------------------------------ | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLAUDE_OAUTH_CLIENT_ID` | Claude Code (Anthropic) | Cliente público — não é necessário segredo. | | `CLAUDE_CODE_REDIRECT_URI` | Claude Code | Substituir URI de redirecionamento. 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 `_SECRET` correspondente. | | `GEMINI_OAUTH_CLIENT_SECRET` | Gemini (Google) | — | | `KIMI_CODING_OAUTH_CLIENT_ID` | Kimi Coding (Moonshot) | Cliente público. | | `MUSE_CODE_OAUTH_CLIENT_ID` | Muse Code (Meta) | Substituição opcional para o ID de cliente de fluxo de dispositivo do Muse CLI público. Deixe por definir para usar o cliente público incorporado. | | `ANTIGRAVITY_OAUTH_CLIENT_ID` | Antigravity (Google) | Requer `_SECRET` correspondente. | | `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 para o ID de cliente OAuth do GitHub Enterprise Copilot. Reverte para o padrão público de `GITHUB_OAUTH_CLIENT_ID` quando não definido. | | `COPILOT_INTEGRATION_ID` | GitHub Copilot | Substituição opcional para o ID de integração do cliente GitHub Copilot enviado nos cabeçalhos `Copilot-Integration-Id` e `Editor-Plugin-Version`. O padrão é `copilot-developer-cli`. | | `WINDSURF_API_KEY` | Windsurf / Devin (v3.8) | Chave de API de fallback usada por `open-sse/executors/devin-cli.ts` quando nenhuma credencial por conexão está disponível. Opcional. | | `CLI_DEVIN_BIN` | Devin CLI (v3.8) | Caminho personalizado para o binário Devin CLI (`devin`). Resolvido por `open-sse/executors/devin-cli.ts`. | | `GITLAB_DUO_OAUTH_CLIENT_ID` | GitLab Duo (v3.8) | ID de cliente OAuth para GitLab Duo. Registe uma aplicação em `https://gitlab.com/-/profile/applications` com URI de redirecionamento `/callback` e âmbitos `api, read_user, openid, profile, email`. Reverte para `GITLAB_OAUTH_CLIENT_ID`. | | `GITLAB_DUO_OAUTH_CLIENT_SECRET` | GitLab Duo (v3.8) | Segredo de cliente OAuth para GitLab Duo. Opcional — o fluxo PKCE não requer um segredo. Reverte para `GITLAB_OAUTH_CLIENT_SECRET`. | | `GITLAB_DUO_BASE_URL` | GitLab Duo (v3.8) | Substituir o URL base do GitLab (GitLab auto-hospedado). O padrão é `https://gitlab.com`. Reverte para `GITLAB_BASE_URL`. | | `GITLAB_BASE_URL` | GitLab Duo (v3.8) | Fallback legado para `GITLAB_DUO_BASE_URL`. Usado 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 | Definido para ativar o 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 de API (ignora o OAuth). | | `QODER_CLI_WORKSPACE` | Qoder | ID do espaço de trabalho para o Qoder CLI. | | `OMNIROUTE_QODER_WORKSPACE` | Qoder | Pseudónimo para `QODER_CLI_WORKSPACE`. | | `QODER_CLI_CONFIG_DIR` | Qoder | Substitui o diretório de configuração do Qoder CLI (sessão PAT isolada, evita sobrescrever um login de navegador). | | `BLACKBOX_WEB_VALIDATED_TOKEN` | Blackbox Web | Token `tk` de frontend para enviar como `validated` em `/api/chat`. Necessário quando o Blackbox impõe a correspondência de tokens; caso contrário, o OmniRoute recorre a um UUID aleatório. Ver issue #2252. | | `VISION_BRIDGE_BASE_URL` | Vision Bridge guardrail | URL base compatível com OpenAI para chamadas vision-bridge não-Anthropic. Predefine para a variável de ambiente do URL legado do OpenAI ou api.openai.com. Aponta para o self-loop `/v1` do OmniRoute ou qualquer endpoint compatível com OpenAI (Gemini OpenAI-compat, OpenRouter). Issue #2232. Quando o URL é o próprio `/v1` do OmniRoute, o sub-pedido de descrição envia `x-omniroute-admission-bypass: internal` e autentica com a credencial de self-loop resolvida (sentinela `sk_omniroute` em modo local, ou `OMNIROUTE_API_KEY` / `ROUTER_API_KEY` — #1350) para que as implementações `REQUIRE_API_KEY=true` funcionem. | | `VISION_BRIDGE_API_KEY` | Vision Bridge guardrail | Chave de API para o URL acima. Substitui as variáveis de ambiente OpenAI / Google por provedor para chamadas vision-bridge não-Anthropic. Os modelos Anthropic mantêm o seu caminho de chave Anthropic dedicado. Issue #2232. | | `OMNIROUTE_VISION_BRIDGE_NEGATIVE_CACHE_MS` | Vision Bridge guardrail | Quanto tempo um resultado de encaminhamento "nenhum candidato utilizável" é armazenado em cache, em ms (predefinição `30000`). Valores inválidos ou negativos revertem para o padrão; `0` desativa a cache negativa. Fonte: `src/lib/guardrails/visionBridgeRouter.ts`. | > [!WARNING] > > 1. Vá a [Google Cloud Console → Credenciais](https://console.cloud.google.com/apis/credentials) > 2. Crie um ID de Cliente OAuth 2.0 (tipo: "Aplicação web") > 3. Adicione o URL do seu servidor como URI de redirecionamento autorizado > 4. Substitua os valores das credenciais em `.env`. --- ## 12. Substituições do User-Agent do fornecedor Substitua o cabeçalho `User-Agent` enviado para cada fornecedor a montante. 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 predefinido | Quando atualizar | | -------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CLAUDE_USER_AGENT` | `claude-cli/2.1.280 (external, cli)` | Quando a Anthropic lançar uma nova versão da CLI | | `CLAUDE_DISABLE_TOOL_NAME_CLOAK` | `false` | `executors/base.ts` + `executors/cliproxyapi.ts` | Defina como `1`/`true` para encaminhar literalmente para a Anthropic os nomes de ferramentas de sistemas de terceiros em ambos os percursos destinados à Anthropic (OAuth nativo e CLIProxyAPI). Por predefinição, o executor atribui deterministicamente aliases aos nomes de ferramentas que não sejam do Claude Code (mapeamento canónico do Claude Code, quando existir, ou PascalCase nos restantes casos) e reverte-os na resposta através de `_toolNameMap`, para que sistemas com ferramentas em snake_case não sejam recusados por serem identificados como clientes de terceiros. Apenas para depuração. | | `CODEX_USER_AGENT` | `codex-cli/0.155.0 (Windows 10.0.26200; x64)` | Quando a OpenAI atualizar a CLI do Codex | | `CODEX_CLIENT_VERSION` | `0.155.0` | Substituir a versão do cliente Codex independentemente da cadeia completa do UA | | `CLAUDE_CODE_CLIENT_VERSION` | `2.1.280` | Substituir a versão anunciada do Claude Code independentemente de `CLAUDE_USER_AGENT`. A Anthropic restringe alguns modelos com base neste valor (#12417). | | `CLAUDE_CODE_CLIENT_BUILD_REVISION` | `1e2` | Substituir o sufixo de 3 caracteres que o OmniRoute acrescenta a `cc_version=` no bloco de faturação do Claude. Incremente-o juntamente com `CLAUDE_CODE_CLIENT_VERSION` — fixar apenas a versão anuncia um par `version.revision` que nenhum binário real emite. | | `GITHUB_COPILOT_CLI_VERSION` | `1.0.91` | Substituir a versão anunciada da CLI do Copilot independentemente de `GITHUB_USER_AGENT` | | `GITHUB_USER_AGENT` | `GitHubCopilotChat/0.54.0` | Quando o GitHub Copilot Chat for atualizado | | `ANTIGRAVITY_USER_AGENT` | `antigravity/2.0.1 darwin/arm64` | Quando o IDE Antigravity for atualizado | | `KIRO_USER_AGENT` | `AWS-SDK-JS/3.0.0 kiro-ide/1.0.0` | Quando o IDE Kiro for atualizado | | `KIRO_OAUTH_CLIENT_ID` | `kiro-cli` | Substituir o `clientId` (ID público) do código de dispositivo social do Kiro | | `KIRO_VERIFY_FULL_CRC` | `false` | Opção de adesão: validação completa do CRC por trama no fluxo de eventos do Kiro (para depurar fluxos corrompidos) | | `QODER_USER_AGENT` | `Qoder-Cli` | Quando a CLI do Qoder for atualizada | | `CURSOR_USER_AGENT` | `Cursor/3.3` | Quando o Cursor for atualizado | > [!TIP] > Pode adicionar substituições do User-Agent para **qualquer** fornecedor utilizando o padrão `{PROVIDER_ID}_USER_AGENT`. O executor constrói dinamicamente o nome da variável de ambiente. --- ## 13. Compatibilidade de impressão digital da CLI Quando ativado, o 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 da conta, preservando simultaneamente o seu IP de proxy. **Origem:** `open-sse/config/cliFingerprints.ts`, `open-sse/executors/base.ts` ### Por fornecedor | Variável | Ativação | Efeito | | ------------------------ | -------- | ------------------------------------------------ | | `CLI_COMPAT_CODEX` | `=1` | Imita a assinatura dos pedidos da CLI Codex | | `CLI_COMPAT_CLAUDE` | `=1` | Imita a assinatura dos pedidos do Claude Code | | `CLI_COMPAT_GITHUB` | `=1` | Imita a assinatura dos pedidos do GitHub Copilot | | `CLI_COMPAT_ANTIGRAVITY` | `=1` | Imita a assinatura dos pedidos do Antigravity | | `CLI_COMPAT_CURSOR` | `=1` | Imita a assinatura dos pedidos do Cursor | | `CLI_COMPAT_KIMI_CODING` | `=1` | Imita a assinatura dos pedidos do Kimi Coding | | `CLI_COMPAT_KILOCODE` | `=1` | Imita a assinatura dos pedidos do Kilo Code | | `CLI_COMPAT_CLINE` | `=1` | Imita a assinatura dos pedidos do Cline | ### Global | Variável | Ativação | Efeito | | ---------------- | -------- | ------------------------------------------------------------------------------------------ | | `CLI_COMPAT_ALL` | `=1` | Ativa a compatibilidade de impressão digital para **todos** os fornecedores de uma só vez. | ### Substituições da identidade da CLI Kimi Coding | Variável | Predefinição | Ficheiro de origem | Descrição | | ----------------------- | ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- | | `KIMI_CLI_VERSION` | `1.36.0` | `src/lib/oauth/providers/kimi-coding.ts` | Substitui a versão da CLI Kimi enviada durante as chamadas OAuth/API. | | `KIMI_CODING_DEVICE_ID` | _(predefinição obtida)_ | `src/lib/oauth/providers/kimi-coding.ts` | Substitui o ID de dispositivo Kimi obtido e utilizado nos cabeçalhos do cliente. | > [!NOTE] > Esta funcionalidade funciona em conjunto com as substituições de User-Agent (§12). O sistema de impressão digital gere a ordenação dos cabeçalhos e dos campos do corpo, enquanto as substituições de User-Agent gerem a cadeia UA específica. Ambos podem ser ativados de forma independente. --- ## 14. Fornecedores de chaves de API Chaves de API para fornecedores que utilizam autenticação direta. **Configuração preferencial:** Painel → Fornecedores → Adicionar chave de API. A configuração através de variáveis de ambiente é uma alternativa para implementações Docker ou sem interface gráfica. Padrão reconhecido: `{PROVIDER_ID}_API_KEY` | Variável | Fornecedor | | ------------------ | ------------------------------------------------------ | | `DEEPSEEK_API_KEY` | DeepSeek | | `NVIDIA_API_KEY` | NVIDIA NIM | | `JINA_AI_API_KEY` | Jina AI (API Foundation + recurso ao Reader) | | `JINA_API_KEY` | Jina AI (alias de `JINA_AI_API_KEY`) | | `GEMINI_API_KEY` | Gemini (Google AI Studio) embeddings + recurso ao chat | | `GOOGLE_API_KEY` | Gemini (alias de `GEMINI_API_KEY`) | > [!NOTE] > As entradas estáticas `${PROVIDER}_API_KEY` para Groq, xAI, Mistral, Perplexity, Together AI, Fireworks, Cerebras, Cohere, Nebius e Qianfan foram removidas na v3.8.0 porque o runtime já não as lê — esses fornecedores dependem exclusivamente do Painel / `data/provider-credentials.json` / da base de dados encriptada. Consulte a secção _Auditoria: variáveis removidas/inativas_ no final deste documento para conhecer o procedimento de migração. > [!TIP] > As chaves configuradas através do Painel são armazenadas de forma encriptada no SQLite e têm precedência sobre as variáveis de ambiente. > > **Jina:** os embeddings `jina-ai/…`, bem como rerank, classify, segment e `jina-search`, **não** faturam uma chave de ambiente do cluster quando existe uma ligação `jina-ai` (ou `jina-reader` partilhada) no painel — `getProviderCredentials` utiliza preenchimento prioritário. `JINA_AI_API_KEY` / `JINA_API_KEY` são utilizadas apenas quando não existe uma chave utilizável no painel. Os registos de chamadas atribuem o recurso à variável de ambiente como `connection_id=env:JINA_AI_API_KEY`. O cartão Reader (`jina-reader`, `r.jina.ai`) nunca serve `/v1/embeddings` nem `/v1/rerank`. > > **Gemini:** `gemini/gemini-embedding-2` (alias `google/gemini-embedding-2`) utiliza primeiro a ligação `gemini` do painel. `GEMINI_API_KEY` / `GOOGLE_API_KEY` são utilizadas apenas quando não existe uma chave utilizável no painel. Os registos de chamadas atribuem o recurso à variável de ambiente como `connection_id=env:GEMINI_API_KEY`. O tráfego multimodal nativo utiliza `x-goog-api-key` com `:embedContent` / `:batchEmbedContents` — N itens OpenAI em `input` tornam-se N vetores. --- ## 15. Definições de tempo limite Todos os valores estão em **milissegundos**. Resolução centralizada em `src/shared/utils/runtimeTimeouts.ts`. ### Hierarquia de tempos limite ``` REQUEST_TIMEOUT_MS (sobreposição global) ├─→ FETCH_TIMEOUT_MS (chamadas a fornecedores a montante, predefinição: 600000) │ ├─→ FETCH_HEADERS_TIMEOUT_MS (herda de FETCH_TIMEOUT_MS) │ ├─→ FETCH_BODY_TIMEOUT_MS (herda de FETCH_TIMEOUT_MS) │ ├─→ TLS_CLIENT_TIMEOUT_MS (herda de FETCH_TIMEOUT_MS) │ │ └── TLS_FIRST_BYTE_WATCHDOG_MS (independente, predefinição: 10000) │ ├── RESPONSES_FIRST_BYTE_TIMEOUT_MS (independente, predefinição: 15000) │ ├── OPENCODE_RESPONSES_HEADERS_WAIT_MS (independente, predefinição: 0 = desativado, sugerido: 30000) │ ├── OPENCODE_RESPONSES_HEADERS_WAIT_MAX_ROTATIONS (independente, predefinição: 2) │ ├── FETCH_CONNECT_TIMEOUT_MS (independente, predefinição: 30000) │ └── FETCH_KEEPALIVE_TIMEOUT_MS (independente, predefinição: 4000) ├─→ STREAM_IDLE_TIMEOUT_MS (herda de REQUEST_TIMEOUT_MS, predefinição: 600000) ├─→ STREAM_ACTIVE_TIMEOUT_MS (independente, predefinição: 1260000; 0 desativa) ├─→ STREAM_READINESS_TIMEOUT_MS (herda de REQUEST_TIMEOUT_MS, predefinição: 80000) ├─→ STREAM_READINESS_MAX_TIMEOUT_MS (limita as extensões adaptativas de prontidão, predefinição: 180000) └─→ API_BRIDGE_PROXY_TIMEOUT_MS (herda de REQUEST_TIMEOUT_MS, predefinição: 30000) ├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS (derivado, predefinição: 300000) ├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS (predefinição: 60000) ├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS (predefinição: 5000) └── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (predefinição: 0 = desativado) ``` | Variável | Predefinição | Descrição | | ----------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REQUEST_TIMEOUT_MS` | _(não definido)_ | Atalho global — substitui as predefinições de `FETCH_TIMEOUT_MS` e `STREAM_IDLE_TIMEOUT_MS`. | | `FETCH_TIMEOUT_MS` | `600000` | Tempo limite total do pedido HTTP para chamadas a fornecedores a montante. | | `STREAM_IDLE_TIMEOUT_MS` | `600000` | Período máximo de silêncio entre bytes em bruto a montante antes de abortar. Os modelos de raciocínio prolongado raramente fazem pausas >90s. | | `STREAM_ACTIVE_TIMEOUT_MS` | `1260000` | Duração total máxima de um fluxo SSE ativo; nunca é reiniciada por bytes a montante e é independente de `REQUEST_TIMEOUT_MS`. Derivada do maior `timeoutMs` por modelo no registo (1200000, Codex), acrescido de uma margem de 60000, para que um modelo autorizado a utilizar todo o seu limite nunca seja terminado a meio da resposta. Defina como `0` para desativar. | | `OMNIROUTE_SSE_COMMENTS` | _(desativado)_ | Indica se o OmniRoute pode emitir linhas de comentário SSE `:` (por exemplo, o sinal periódico `: keepalive` e os trailers de metadados `x-omniroute-*`). Desativado por predefinição (#10524), uma vez que clientes estritamente compatíveis com OpenAI executam JSON.parse em cada linha SSE e falham em comentários `:`; os sinais periódicos `data:` não são afetados. Defina como `on`/`true`/`1`/`yes` para reativar. Utilizado por `open-sse/utils/sseHeartbeat.ts`. | | `SSE_COALESCE_MS` | `0` (desativado) | Adesão opcional: combina eventos Claude `content_block_delta` consecutivos (mesmo índice de bloco e tipo de delta) enviados a clientes Claude, efetuando o envio pelo menos a cada N ms. Sem perdas; os eventos `signature_delta` e de limite nunca são combinados. Aplica-se a todos os tipos de delta, salvo se for definida abaixo uma variável específica do tipo. Utilizado por `open-sse/utils/sseDeltaCoalesce.ts`. | | `SSE_COALESCE_THINKING_MS` | `0` (desativado) | Substituição por tipo de `SSE_COALESCE_MS` para `thinking_delta`. | | `SSE_COALESCE_TEXT_MS` | `0` (desativado) | Substituição por tipo de `SSE_COALESCE_MS` para `text_delta`. | | `SSE_COALESCE_INPUT_JSON_MS` | `0` (desativado) | Substituição por tipo de `SSE_COALESCE_MS` para `input_json_delta`. | | `SSE_FRAME_COALESCE_MS` | `0` (desativado) | Adesão opcional: agrupa os frames SSE encaminhados num intervalo de N ms numa única escrita para o cliente. O primeiro frame e os frames terminais (`[DONE]`, `message_stop`, `error`, `response.completed`/`failed`/`incomplete`) nunca são atrasados; com o agrupamento ativo, o ITL mede os intervalos entre lotes. Utilizado por `open-sse/utils/sseOutputSink.ts`. | | `SSE_STALL_WATCHDOG` | `timer` | Implementação do mecanismo de vigilância de interrupção de bytes para respostas transmitidas em fluxo. `timer` rearma um temporizador por fragmento a montante (é acionado exatamente no limite de interrupção); `interval` mantém uma verificação por fluxo com o período `clamp(budget/4, 1s, 5s)`, pelo que uma interrupção é detetada dentro do limite + período. Utilizado por `open-sse/utils/streamStallWatchdog.ts`. | | `STREAM_READINESS_TIMEOUT_MS` | `80000` | Tempo para receber o primeiro evento SSE que não seja um ping. Herda `REQUEST_TIMEOUT_MS` quando este está definido. | | `STREAM_READINESS_MAX_TIMEOUT_MS` | `180000` | Janela adaptativa máxima de prontidão para o primeiro evento em pedidos de streaming grandes, com utilização intensiva de ferramentas ou com raciocínio elevado. | | `OMNIROUTE_AGENT_GOAL_POLICY_ENABLED` | `true` | Interruptor de desativação para a heurística `/goal`. Defina como `false`/`0`/`off` para desativar totalmente a deteção — os tempos limite de prontidão e a recuperação do fluxo nunca são aumentados pelo corpo/cabeçalhos do pedido, mitigando a amplificação do tempo limite controlada pelo cliente. | | `OMNIROUTE_AGENT_GOAL_READINESS_MAX_TIMEOUT_MS` | `600000` | Janela máxima de prontidão para o primeiro evento em execuções de agentes `/goal` detetadas ou pedidos forçados com `x-omniroute-agent-goal`. | | `OMNIROUTE_AGENT_GOAL_STREAM_RECOVERY` | `true` | Ativa automaticamente a recuperação antecipada do fluxo para execuções de agentes `/goal` detetadas. Defina como `false`/`0`/`off` para desativar a adesão específica de objetivos. Isto apenas pode ADICIONAR recuperação à predefinição do operador — nunca substitui uma opção de desativação explícita nas definições de `STREAM_RECOVERY_ENABLED`/BD. | | `OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS` | `true` | Remove eventos SSE `codex.*` não padrão (por exemplo, `codex.rate_limits`) que fazem com que `responses.stream()` do SDK da OpenAI falhe com um erro 502. ATIVADO por predefinição (#11014). Defina como `0`/`false`/`no`/`off` para os encaminhar. | | `OMNIROUTE_CODEX_APPSERVER_WS` | _(não definido)_ | Transporte opcional do app-server Codex. Endpoint WebSocket (`ws://`/`wss://`) de um sidecar `codex app-server` local. Quando definido juntamente com um token, os pedidos Codex são encaminhados através de JSON-RPC para o sidecar, em vez de utilizarem a API HTTP Responses. Também pode ser definido por ligação através de `providerSpecificData.codexAppServerUrl`. Utilizado por `open-sse/executors/codex/appServerConfig.ts`. | | `OMNIROUTE_CODEX_APPSERVER_WS_TOKEN` | _(não definido)_ | Token de capacidade/bearer inline apresentado ao app-server. Substituição por ligação: `providerSpecificData.codexAppServerToken`. | | `OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE` | _(não definido)_ | Caminho para um ficheiro que contém o token de capacidade do app-server (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 é executado o turno do app-server. Substituição por ligação: `providerSpecificData.codexAppServerCwd`. | | `OMNIROUTE_CODEX_APPSERVER_APPROVAL` | _(não definido)_ | Política de aprovação transmitida ao turno do app-server (por exemplo, `never`, `on-request`). Substituição por ligação: `providerSpecificData.codexAppServerApprovalPolicy`. | | `OMNIROUTE_CODEX_APPSERVER_SANDBOX` | _(não definido)_ | Política de sandbox transmitida ao turno do app-server (por exemplo, `read-only`, `workspace-write`, `danger-full-access`). Quando não está definida, o executor utiliza `workspace-write` por predefinição (reforçado; anteriormente, `danger-full-access`). Substituição por ligação: `providerSpecificData.codexAppServerSandbox`. | | `OMNIROUTE_CODEX_APPSERVER_AUTO_APPROVE` | `false` | Aprova automaticamente os pedidos de aprovação do próprio app-server (execução de comandos/ficheiros/permissões no anfitrião). Desativado por predefinição — os pedidos são automaticamente recusados; as chamadas de ferramentas do harness não são afetadas (percorrem o mecanismo de passagem separado `item/tool/call`). Aceita `true`/`1`/`yes`. Substituição por ligação: `providerSpecificData.codexAppServerAutoApprove`. | | `FETCH_HEADERS_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Tempo para receber os cabeçalhos da resposta. | | `OMNIROUTE_FETCH_START_TIMEOUT_CAP_MS` | `110000` | Tempo máximo de espera pelos cabeçalhos da resposta em pedidos de streaming (ms). `0` desativa este limite; um `fetchStartTimeoutCapMs` explícito do fornecedor tem precedência. | | `OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS` | `30000` (30 s) | Tempo máximo de espera pelo início da resposta (ms) para cada tentativa direta sem proxy. Em caso de timeout, é efetuada uma nova tentativa uma vez num socket novo; defina como `0` para desativar o limite e manter o comportamento anterior. | | `OMNIROUTE_LOCAL_DIRECT_HEADERS_TIMEOUT_MS` | `300000` (5 min) | Limite mínimo para o início da resposta (ms) em tentativas diretas sem proxy cujo anfitrião de destino seja privado/LAN/loopback (por exemplo, `localhost`, `host.docker.internal`, `192.168.x.x`), para que um arranque a frio nativo do Ollama não seja interrompido pelo valor predefinido de 30 s acima. Funciona como um limite mínimo: a espera efetiva é o maior valor entre este e `OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS`; `0` ou um valor inválido remove o limite mínimo local. Os anfitriões remotos não são afetados. | | `OMNIROUTE_DIRECT_RESPONSE_RETRY_TIMEOUT_MS` | `600000` (10 min) | Limite máximo (ms) para a tentativa RETRY num socket novo após o timeout de início da resposta de uma tentativa com ligação reutilizada acima (#13703). Aplica-se apenas quando o chamador já associou o seu próprio sinal de prazo-limite (a cascata resolvida de ligação/modelo/fornecedor/`FETCH_TIMEOUT_MS`); esse sinal é o limite real e é acionado primeiro no percurso previsto, pelo que este é um mecanismo de salvaguarda generoso, e não um limite fixo — sem ele, a nova tentativa reutilizava a mesma janela curta de `OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS` da tentativa com ligação reutilizada e devolvia um erro 504 para modelos de raciocínio funcionais com TTFB lento. Nunca pode ser inferior ao limite mínimo fixo acima; quando o chamador não fornece qualquer sinal de prazo-limite, a nova tentativa mantém inalterado o limite mínimo fixo. | | `FETCH_BODY_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Tempo para receber o corpo completo da resposta. | | `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Timeout para o estabelecimento da ligação TCP. | | `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Timeout de inatividade do socket keep-alive. | | `TLS_CLIENT_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Timeout do proxy de impressão digital TLS (wreq-js). | | `TLS_FIRST_BYTE_WATCHDOG_MS` | `10000` | Limita especificamente o tempo até ao primeiro byte do corpo no transporte de impressão digital TLS wreq-js; `TLS_CLIENT_TIMEOUT_MS`, por si só, não consegue detetar um corpo bloqueado, uma vez que é resolvido assim que os cabeçalhos chegam (#12656). Um timeout cancela o leitor wreq e recorre ao dispatcher direto/proxy; `0` desativa o mecanismo de vigilância. | | `RESPONSES_FIRST_BYTE_TIMEOUT_MS` | `15000` | Apenas para o executor OpenCode, e somente enquanto o sinalizador de funcionalidade `OPENCODE_RESPONSES_STALL_ROTATION` estiver ativo (desativado por predefinição): limita a espera pelo primeiro byte do corpo de uma resposta Responses transmitida em streaming após os respetivos cabeçalhos (#13484). Um stream Responses é iniciado com `response.created`, pelo que o silêncio para além desta janela constitui um bloqueio: a conta entra em período de espera e o pedido passa para a conta seguinte uma vez; um segundo bloqueio falha imediatamente. `0` desativa a proteção, mesmo com o sinalizador ativo. | | `OPENCODE_RESPONSES_HEADERS_WAIT_MS` | `0` (= desativado) | Apenas para o executor OpenCode: limita a espera pelos cabeçalhos da resposta do serviço a montante numa chamada Responses em streaming quando ainda está disponível outra conta — um pedido em fila deixa de esperar e avança, em vez de ocupar toda a janela dos cabeçalhos. Apenas as chamadas Responses em streaming são afetadas (o stream Responses é iniciado com `response.created`, pelo que o silêncio nessa fase representa uma fila, não geração); as conclusões de chat e as chamadas sem streaming não são alteradas, e a janela apenas reduz o limite máximo efetivo para o início do fetch, nunca o aumenta. Valor sugerido ao ativar: `30000`. `0` desativa. | | `OPENCODE_RESPONSES_HEADERS_WAIT_MAX_ROTATIONS` | `2` | Apenas para o executor OpenCode: número de vezes por pedido que o limite de espera pelos cabeçalhos acima pode avançar para a conta seguinte. A última conta restante mantém sempre a janela completa de espera pelos cabeçalhos. | | `OPENCODE_PARK_AND_RESUME` | `false` | Apenas para o executor OpenCode: suspende o pedido com um heartbeat após vários erros 429 transitórios (ou um marcador recente de sobrecarga do conjunto) e, em seguida, repete uma etapa limitada de até 3 contas sequenciais, em vez de distribuir o pedido por todo o conjunto (#13924). Desativado por predefinição: cada erro 429 passa para a conta seguinte, exatamente como anteriormente. | | `OPENCODE_PARK_REPLAY_SERVE_SETASIDE` | `false` | Apenas para o executor OpenCode: quando todas as contas cujo período de espera já terminou na etapa de repetição após suspensão e retoma são postas de parte pela memória de recusas do proxy, utiliza-as na mesma em vez de não repetir nada (#14851, continuação de #14750). Desativado por predefinição: nesse caso, a etapa de repetição fica vazia, tal como antes de #14750. | | `STREAM_READINESS_STALL_RETRY` | `false` | Apenas para conversas em streaming: quando o primeiro corpo recebido do serviço a montante fica bloqueado antes de produzir um evento utilizável, efetua uma segunda tentativa limitada através do mesmo caminho de encaminhamento, com o mesmo orçamento de prontidão e sem penalizar a conta. Desativado por predefinição: o bloqueio do primeiro corpo faz com que o pedido falhe sem nova tentativa. | | `OPENCODE_POOL_RESELECT` | `false` | Apenas para o executor OpenCode: após um erro 429 de um fornecedor agrupado por saída numa conta sem proxy e num contexto de conjunto ambiente, solicita ao conjunto de ligações outro membro para a tentativa seguinte, em vez de repetir através do mesmo endereço de saída. Ordena, nunca exclui: um conjunto esgotado mantém o comportamento atual. Desativado por predefinição: cada erro 429 passa para a conta seguinte, exatamente como anteriormente. | | `OPENCODE_POOL_STRAIN_MARKER_PATH` | _(não definido)_ | Apenas para o executor OpenCode: substitui o caminho do marcador de sobrecarga do conjunto lido antes da suspensão (`{since, reason, ttl_s}`, predefinição `/tmp/opencode-pool-strain.json`, #13924). Um marcador recente suspende sem voltar a contar; se estiver ausente ou desatualizado, recorre ao contador de picos. | | `API_BRIDGE_PROXY_TIMEOUT_MS` | `30000` | Tempo limite do salto pelo proxy para pedidos da ponte `/v1`. | | `FIRECRAWL_BASE_URL` | `https://api.firecrawl.dev` | Direciona o executor de obtenção de conteúdos Web Firecrawl para uma instância autoalojada (chave de API opcional fora da nuvem). | | `FIRECRAWL_TIMEOUT_MS` | `30000` | Tempo limite por pedido para o executor de obtenção de conteúdos Web Firecrawl. | | `TAVILY_BASE_URL` | _(não definido)_ | URL base do serviço de obtenção da quota `/usage` do Tavily (Limites do Fornecedor); ignorado quando aponta para `api.tavily.com`. Se não estiver definido, utiliza o URL base da ligação. | | `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `300000` | Tempo limite global dos pedidos do servidor para a ponte. | | `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Tempo disponível para enviar os cabeçalhos da resposta através da ponte. | | `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Tempo limite de inatividade da ligação persistente da ponte. | | `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Tempo limite do socket em bruto (0 = desativado). | | `SHUTDOWN_TIMEOUT_MS` | `30000` | Período de tolerância após SIGTERM/SIGINT antes de forçar o encerramento. | | `OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS` | `120000` | Valor alternativo utilizado por `src/shared/utils/fetchTimeout.ts` quando `FETCH_TIMEOUT_MS` não está definido. | | `OMNIROUTE_PROVIDER_PROBE_TIMEOUT_MS` | `8000` | Tempo limite (ms) das predefinições `validationRead` e `modelsProbe` em `src/shared/network/safeOutboundFetch.ts`. Aumente-o para pontos finais lentos (Cerebras, Cloudflare AI, Groq), de modo a evitar alternâncias entre os estados ativo/erro no painel. Para valores inválidos (<1000) ou não numéricos, recorre a 8000 ms. | | `OMNIROUTE_RELAY_FETCH_TIMEOUT_MS` | `25000` | Tempo limite de obtenção específico do retransmissor em `open-sse/utils/proxyFetch.ts` (#9158). Um retransmissor bloqueado deve falhar antes do tempo limite do cliente/agente (~30 s), para que os autores dos pedidos vejam uma falha específica do retransmissor em vez de um erro genérico de tempo limite do serviço a montante. Limitado a `29000` para garantir que é sempre acionado primeiro. | | `OMNIROUTE_RETRY_BACKOFF_MS` | `10` | Intervalo de espera partilhado entre novas tentativas para os caminhos direto/retransmissor/proxy que repetem uma vez em `open-sse/utils/proxyFetch.ts` (#9158). `0` = repetir imediatamente. | | `OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS` | `60000` | Tempo limite nativo dos pedidos wreq-js (`claudeTlsClient.ts`). | | `OMNIROUTE_CLAUDE_TLS_GRACE_MS` | `10000` | Período de tolerância do prazo-limite absoluto do JS, adicionado ao tempo limite nativo. | | `OMNIROUTE_PPLX_TLS_TIMEOUT_MS` | `30000` | Tempo limite nativo dos pedidos wreq-js (`perplexityTlsClient.ts`). | | `OMNIROUTE_PPLX_TLS_GRACE_MS` | `10000` | Período de tolerância do prazo-limite absoluto de JS adicionado ao tempo limite nativo. | | `OMNIROUTE_PPLX_SEARCH_HINT` | `0` (desativado) | Acrescenta "Tem uma pesquisa Web incorporada. Responda diretamente às perguntas utilizando os resultados da pesquisa." à mensagem de sistema do autor da chamada (`perplexity-web/protocol.ts`). Desativado por predefinição — o Perplexity pesquisa de qualquer forma e a frase aparece nas respostas como metacomentário para clientes de programação. Defina como `1`/`true`/`yes`/`on` para repor. | | `OMNIROUTE_GROK_TLS_TIMEOUT_MS` | `60000` | Tempo limite nativo do pedido wreq-js (`grokTlsClient.ts`). | | `OMNIROUTE_GROK_TLS_GRACE_MS` | `10000` | Período de tolerância do prazo-limite absoluto de JS adicionado ao tempo limite nativo. | | `OMNIROUTE_NOTION_TLS_TIMEOUT_MS` | `30000` | Tempo limite nativo do pedido wreq-js (`notionTlsClient.ts`); o `notion-web` aumenta-o por pedido para `180000` no caso de gerações longas. | | `OMNIROUTE_NOTION_TLS_GRACE_MS` | `10000` | Período de tolerância do prazo-limite absoluto de JS adicionado ao tempo limite nativo. | | `OMNIROUTE_BROWSER_POOL` | `on` | Pool de navegadores Playwright partilhado para conversas com cookies Web suportadas por navegador (`browserPool.ts`); defina como `off` para desativar. | | `OBSCURA_BIN` | `auto-detect` | Caminho para o binário `obscura` utilizado como motor principal pelo pool de navegadores e pelo executor do Cloudflare Playground (`open-sse/services/obscura.ts`); detetado automaticamente a partir do PATH do sistema quando não está definido. | | `OBSCURA_CDP_ENDPOINT` | _(não definido)_ | Aponta para uma instância do Obscura já em execução (`http://host:port`), em vez de iniciar uma; o módulo não é proprietário desse processo (`open-sse/services/obscura.ts`). | | `OBSCURA_PORT` | `porta livre aleatória` | Porta explícita para o `obscura serve` iniciado; é escolhida automaticamente uma porta livre quando não está definida (`open-sse/services/obscura.ts`). | | `WEB_COOKIE_USE_BROWSER` | `0` | Encaminha um pedido de conversa com cookies Web para o percurso suportado por navegador (`browserBackedChat.ts`); `1` para ativar. | | `KIMI_WEB_BASE_URL` | `https://www.kimi.ai` | URL base do executor Kimi Web (Connect-RPC internacional de kimi.ai) (`kimi-web.ts`); substitua apenas para endpoints de espelho/proxy. | | `KIMI_WEB_CHAT_URL` | `/apiv2/kimi.gateway.chat.v1.ChatService/Chat` | Endpoint de conversação completo para o executor Kimi Web (`kimi-web.ts`). | | `OMNIROUTE_LOGIN_BROWSER_PATH` | _(detetado automaticamente)_ | Caminho para um executável Chrome/Edge do sistema para o início de sessão interativo no navegador do Adobe Firefly (`adobeFireflyBrowserLogin.ts`); substitui a deteção automática específica de cada SO. | | `OMNIROUTE_STANDALONE_DIR` | _saída autónoma .build/_ | Substituição, durante a compilação, do diretório de saída autónoma utilizado pelo passo de colocação conjunta pós-compilação (`scripts/build/colocate-standalone.mjs`); ferramentas de compilação, não de execução. | As tentativas de destinos combinados herdam o tempo limite resolvido do pedido a montante (`FETCH_TIMEOUT_MS` ou `REQUEST_TIMEOUT_MS`, quando este fornece o valor predefinido da obtenção). Defina `targetTimeoutMs` numa combinação, nos valores predefinidos das combinações ou na substituição do fornecedor apenas para tornar a contingência da combinação mais rápida; os valores acima do tempo limite a montante atual são limitados ao tempo limite a montante. `comboTimeoutMs` é um orçamento de tempo real separado para toda a combinação, abrangendo os destinos de comutação por falha. Deixe-o por definir ou em `0` para manter a iteração ilimitada (continua a aplicar-se um mecanismo de interrupção predefinido de 10 minutos em caso de bloqueio em `comboPredicates.ts`). Um valor positivo substitui essa proteção para a combinação. Mantenha `comboTimeoutMs` superior a `targetTimeoutMs`, para que a comutação por falha ainda tenha tempo após um primeiro destino lento. ### Limiares do Disjuntor Ajuste do disjuntor ao nível do fornecedor. Os valores predefinidos refletem os valores dimensionados utilizados desde a v3.6 para mais de 500 ligações. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------------------------------- | ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD` | `8` | `open-sse/config/constants.ts` | Limiar de falhas consecutivas para fornecedores OAuth antes de o disjuntor disparar. | | `OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS` | `60000` | `open-sse/config/constants.ts` | Janela de reposição (ms) do disjuntor de fornecedores OAuth. | | `OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD` | `12` | `open-sse/config/constants.ts` | Limiar de falhas consecutivas para fornecedores com chave de API. | | `OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS` | `30000` | `open-sse/config/constants.ts` | Janela de reposição (ms) do disjuntor de fornecedores com chave de API. | | `OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD` | `2` | `open-sse/config/constants.ts` | Limiar de falhas consecutivas para fornecedores locais (Ollama, LM Studio, ...). | | `OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS` | `15000` | `open-sse/config/constants.ts` | Janela de reposição (ms) do disjuntor de fornecedores locais. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_THRESHOLD` | `10` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: falhas dentro da janela antes de todo o fornecedor OAuth entrar em período de espera. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_WINDOW_MS` | `900000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: janela deslizante 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: período de espera (ms) após ser atingido o limiar do fornecedor OAuth. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_DEGRADATION_THRESHOLD` | `5` | `open-sse/config/constants.ts` | O fornecedor OAuth entra no estado DEGRADED ao atingir este número de falhas. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_MAX_BACKOFF_MULTIPLIER` | `8` | `open-sse/config/constants.ts` | Multiplicador máximo do aumento progressivo de resetTimeout para o fornecedor OAuth. | | `OMNIROUTE_PROVIDER_BREAKER_OAUTH_BACKOFF_ESCALATION_COUNT` | `2` | `open-sse/config/constants.ts` | O fornecedor OAuth aumenta o tempo de espera após este número de ciclos em estado aberto. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_THRESHOLD` | `15` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: falhas dentro da janela antes de todo o fornecedor com chave de API entrar em período de espera. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_WINDOW_MS` | `1800000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: janela deslizante de contagem de falhas (ms) para fornecedores com chave de API. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_COOLDOWN_MS` | `600000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: período de espera (ms) após ser atingido o limiar do fornecedor com chave de API. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_DEGRADATION_THRESHOLD` | `7` | `open-sse/config/constants.ts` | O fornecedor com chave de API entra no estado DEGRADED ao atingir este número de falhas. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_MAX_BACKOFF_MULTIPLIER` | `4` | `open-sse/config/constants.ts` | Multiplicador máximo do aumento progressivo de resetTimeout para o fornecedor com chave de API. | | `OMNIROUTE_PROVIDER_BREAKER_API_KEY_BACKOFF_ESCALATION_COUNT` | `3` | `open-sse/config/constants.ts` | O fornecedor com chave de API aumenta o tempo de espera após este número de ciclos em estado aberto. | | `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 período de espera. | | `OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_WINDOW_MS` | `300000` | `open-sse/config/constants.ts` | Disjuntor ao nível do fornecedor: janela deslizante 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: período de espera (ms) após ser atingido o limiar do fornecedor local. | | `OMNIROUTE_API_KEY_COOLDOWN_MS` | `60000` | `open-sse/services/apiKeyRotator.ts` | Período de espera por chave (ms), aplicado pela rotação de múltiplas chaves de API quando uma resposta 429 do serviço a montante não inclui `Retry-After` (#14573). Os valores não positivos ou não numéricos revertem para a predefinição. | | `PIN_DROP_BACKOFF_LEVEL` | `2` | `open-sse/services/combo.ts` | Nível de espera progressiva no qual o fornecedor de uma afixação da cache de contexto é considerado persistentemente indisponível e a afixação é removida para permitir a comutação pós-falha. | | `PIN_DROP_GRACE_MS` | `20000` | `open-sse/services/combo.ts` | Janela antioscilação (ms) que tolera breves períodos de espera transitórios antes de remover uma afixação da cache de contexto. | ### Cenários | Cenário | Configuração | | -------------------------------------- | ---------------------------------------------------- | | **Geração de código de longa duração** | `REQUEST_TIMEOUT_MS=900000` (15 min) | | **Limitar a duração total do fluxo** | `STREAM_ACTIVE_TIMEOUT_MS=1260000` (21 min) | | **Falha rápida para API de produção** | `API_BRIDGE_PROXY_TIMEOUT_MS=10000` | | **Modelos de raciocínio prolongado** | `STREAM_IDLE_TIMEOUT_MS=300000` (5 min entre blocos) | --- ## 16. Registo de logs O sistema de registo de logs escreve tanto em stdout como em ficheiros de log sujeitos a rotação. 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 log: `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` | Escreve os logs num ficheiro, além de stdout. | | `APP_LOG_FILE_PATH` | `logs/application/app.log` | Caminho do ficheiro de log (relativo à raiz do projeto ou a `DATA_DIR`). | | `APP_LOG_MAX_FILE_SIZE` | `50M` | Tamanho máximo do ficheiro antes da rotação. Aceita: `50M`, `1G`, `512K` ou bytes sem unidade. | | `APP_LOG_RETENTION_DAYS` | `7` | Número de dias durante os quais são mantidos os ficheiros de log da aplicação sujeitos a rotação. | | `APP_LOG_MAX_FILES` | `20` | Número máximo de cópias de segurança dos ficheiros de log sujeitos a rotação. | | `CALL_LOG_RETENTION_DAYS` | `7` | Número de dias durante os quais são mantidas na base de dados as entradas de log de pedidos/chamadas. | | `CALL_LOG_MAX_ENTRIES` | `10000` | Número máximo de entradas do log de chamadas na memória intermédia. | | `CALL_LOGS_TABLE_MAX_ROWS` | `100000` | Número máximo de linhas na tabela SQLite `call_logs` antes da eliminação das mais antigas. | | `ENABLE_REQUEST_LOGS` | _(não definido)_ | Força a ativação ou desativação do registo detalhado de pedidos, substituindo a definição do painel. | | `MAX_PENDING_REQUEST_AGE_MS` | `3600000` (1 hora) | Idade máxima das entradas órfãs de log de pedidos ativos antes da limpeza em memória. | | `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS` | `false` | Armazena segmentos do fluxo nos artefactos do pipeline quando `call_log_pipeline_enabled=true`. Ativação opcional (`true`) — desativado por predefinição para poupar espaço em disco. | | `CALL_LOG_PIPELINE_MAX_SIZE_KB` | `512` | Tamanho máximo, em KB, do artefacto de log de chamadas do pipeline quando `call_log_pipeline_enabled=true`. | | `PROXY_LOGS_TABLE_MAX_ROWS` | `100000` | Número máximo de linhas na tabela SQLite `proxy_logs` antes da eliminação das mais antigas. | | `PROXY_LOG_INCLUDE_IPS` | `false` | Inclui os IPs do cliente/de saída e os prefixos das contas nos logs da consola `[ProxyEgress]`. Os registos de log do proxy no painel/na base de dados mantêm todos os detalhes. | | `PROXY_LOG_FIRST_CHUNK_TIMING` | `false` | Defina como `"true"` ou `"1"` para registar `first_chunk_ms` (desde o início do envio até ao primeiro byte útil do corpo) nas linhas de log do proxy. Encapsula cada corpo a montante num fluxo de passagem preguiçoso e atualiza a linha assim que o byte chega; está desativado por predefinição para que as respostas passem sem alterações. | | `APP_LOG_ROTATION_CHECK_INTERVAL_MS` | `60000` (1 min) | Frequência com que `src/lib/logRotation.ts` volta a verificar o tamanho do ficheiro de log ativo. | | `CHAT_LOG_TEXT_LIMIT` | `65536` | Comprimento máximo das cadeias de caracteres mantidas nos artefactos de log de conversação (predefinição: 64 KB). | | `CHAT_LOG_ARRAY_TAIL_ITEMS` | `128` | Número de itens da matriz mantidos a partir do fim ao truncar os payloads do log de conversação. | | `CHAT_LOG_MAX_DEPTH` | `6` | Profundidade máxima de aninhamento antes de os payloads do log de conversação serem truncados. | | `CHAT_LOG_MAX_OBJECT_KEYS` | `80` | Número máximo de chaves de objeto mantidas nos payloads do log de conversação (0 = ilimitado). | | `CHAT_LOG_MAX_BODY_KB` | `1024` | Tamanho total do corpo do pedido/resposta (KB) a partir do qual este é substituído por um resumo simples, em vez da cópia completa. Aumente este valor se as conversações agênticas longas apresentarem um marcador de posição no painel em vez das mensagens reais. | | `CHAT_DEBUG_FILE` | `false` | Quando definido como true, `serializeArtifactForStorage` ignora o truncamento baseado no tamanho. Apenas para depuração. | --- ## 17. Otimização de memória | Variável | Predefinição | Descrição | | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_MEMORY_MB` | _automático_ (máquina física); **`1024` na imagem Docker** | Limite **recomendado** da heap do V8 (MB) para Docker/modo autónomo. Quando não definido, é calibrado dinamicamente (~35% da RAM do sistema, limitado ao intervalo `[512, 4096]`); `512` é apenas o limite mínimo quando não é possível determinar a memória total. Em `run-standalone.mjs` (Docker CMD), um valor **explícito** é acrescentado como `--max-old-space-size` e **prevalece** sobre um sinalizador de heap NODE_OPTIONS em conflito (último sinalizador do V8). `omniroute serve` continua a dar preferência a uma definição de heap NODE_OPTIONS existente (#5238). Não defina ambos com números diferentes — o processo regista um aviso que indica ambos os valores e qual prevalece. **A imagem Docker oficial define sempre `1024`, pelo que a calibração nunca é executada nessa imagem.** O endpoint `/v1/responses` do agente de programação necessita de `8192`–`12288`, além de margem no cgroup — consulte o [Guia do Docker — RAM em tempo de execução](../guides/DOCKER_GUIDE.md#runtime-ram-for-coding-agents). | | `OMNIROUTE_RSS_PRESSURE_MB` | _automático_ (`max(3072, 2 × OMNIROUTE_MEMORY_MB)`; desativado quando `OMNIROUTE_MEMORY_MB` não está definido) | `open-sse/utils/resourcePressure.ts` | Limite absoluto do RSS do processo (MB) para memória nativa/externa que `heapUsed` do V8 não consegue detetar; acima deste limite, os novos pedidos recebem 503 `resource_pressure`. O RSS raramente diminui após um pico, pelo que deve ser utilizado em conjunto com `OMNIROUTE_PRESSURE_SELF_RESTART`. | | `PROMPT_CACHE_MAX_SIZE` | `50` | Número máximo de entradas de instruções do sistema em cache. | | `PROMPT_CACHE_MAX_BYTES` | `2097152` (2 MB) | Tamanho total máximo da cache de instruções. | | `PROMPT_CACHE_TTL_MS` | `300000` (5 min) | TTL das entradas da cache de instruções. | | `SEMANTIC_CACHE_MAX_SIZE` | `100` | Número máximo de respostas com temperature=0 em cache. | | `SEMANTIC_CACHE_MAX_BYTES` | `4194304` (4 MB) | Tamanho total máximo da cache semântica. | | `SEMANTIC_CACHE_TTL_MS` | `1800000` (30 min) | TTL das entradas da cache semântica. | | `OMNIROUTE_CORPUS_CACHE_SIZE` | `5` | Raízes de corpus local que mantêm simultaneamente um índice ativo na memória (`src/lib/localCorpus/configured.ts`). LRU: ao atingir o limite, o índice da raiz utilizada há mais tempo é removido e reconstruído na consulta seguinte. Limitado a um mínimo de `1`; um valor não numérico faz com que seja utilizada a predefinição. | | `STREAM_HISTORY_MAX` | `50` | Número máximo de eventos recentes de fluxo na memória intermédia da vista em tempo real do Painel. | | `CONTEXT_LENGTH_DEFAULT` | _(não definido)_ | Substituição global do comprimento de contexto (tokens) para todos os fornecedores que não tenham uma variável `CONTEXT_LENGTH_`. Quando definido, **substitui** os valores do catálogo, da substituição do painel e do registo para esses fornecedores; quando não definido, o OmniRoute utiliza a respetiva cadeia incorporada, cujo último recurso é `128000`. Consulte [Comprimento de contexto por fornecedor](#per-provider-context-length-context_length_provider). | | `USAGE_TOKEN_BUFFER` | `100` | Margem adicional de tokens reservada ao monitorizar quotas de utilização. | ### Comprimento de contexto por fornecedor (`CONTEXT_LENGTH_`) `open-sse/services/contextManager.ts` (`getEnvOverride()` / `resolveTokenLimit()`) também lê uma forma **específica de cada fornecedor**, cujo nome é criado a partir do ID do fornecedor durante a execução, pelo que não pode ser apresentada linha a linha na tabela acima nem em `.env.example`. **Nome.** `CONTEXT_LENGTH_`, em que `` é o ID do fornecedor em maiúsculas, com todos os caracteres fora de `A-Z` / `0-9` substituídos por `_`. O ID do fornecedor é o ID canónico após a resolução de aliases (a parte `provider` de uma cadeia `provider/model` depois de um alias curto ter sido resolvido). Os nós personalizados compatíveis com OpenAI ou Anthropic utilizam o respetivo ID de nó gerado, pelo que o UUID faz parte do nome da variável. O valor é um número inteiro positivo de tokens; qualquer outro valor (vazio, `0`, negativo, não numérico) é ignorado e a resolução avança para o passo seguinte. | ID do fornecedor | Nome da variável | | ----------------------------------------------------------- | -------------------------------------------------------------------------- | | agentrouter | CONTEXT_LENGTH_AGENTROUTER | | openrouter | 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`, prevalece o primeiro passo que produza um valor: 1. `CONTEXT_LENGTH_` para esse fornecedor. 2. `CONTEXT_LENGTH_DEFAULT` (substituição global através do ambiente). 3. A janela por modelo: uma substituição persistida do contexto (definida no painel ou fixada automaticamente pelo reconciliador de descoberta; consulte `CONTEXT_WINDOW_RECONCILE_INTERVAL`), caso contrário, o valor do catálogo sincronizado / models.dev. 4. O `defaultContextLength` do registo do fornecedor. 5. Heurísticas baseadas no nome do modelo (`claude` 200000, `gemini` 1000000, `gpt` / `o1` / `o3` / `o4` / `codex` 400000). 6. Predefinições incorporadas por fornecedor e, em seguida, `128000`. Ambos os passos relativos ao ambiente aplicam-se ao **fornecedor inteiro**: todos os modelos desse fornecedor recebem o mesmo limite, que prevalece sobre as substituições por modelo definidas no painel. Quando apenas um modelo de um fornecedor necessitar de uma janela diferente, utilize antes uma substituição por modelo no painel. **Âmbito.** Esta cadeia controla 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`), os orçamentos de compressão de pedidos e os limites de contexto de combinações. O `context_length` anunciado por `GET /v1/models` pode continuar a ser obtido a partir dos metadados do catálogo ou do registo e não é garantido que reflita a substituição através do ambiente. **Exemplo.** Um fornecedor cujo modelo aceita uma janela de 1 050 000 tokens, enquanto o catálogo indica 128 000: ```dotenv CONTEXT_LENGTH_AGENTROUTER=1050000 ``` Reinicie o servidor depois de alterar o valor: este é lido a partir do ambiente do processo do servidor. Na **aplicação de ambiente de trabalho**, o servidor é executado como um processo subordinado e não deteta uma variável do sistema definida depois de a aplicação ter sido iniciada; coloque a linha no ficheiro `.env` carregado pela aplicação (ordem de pesquisa em [Guia do Electron: pesquisa do ficheiro de ambiente](../guides/ELECTRON_GUIDE.md#environment-file-lookup)) e, em seguida, encerre completamente e volte a iniciar a aplicação. ### Compressão | Variável | Predefinição | Descrição | | ------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS` | não definida | Confiar no ficheiro `.rtk/filters.json` do projeto sem um hash em `.rtk/trust.json`. Utilize apenas em desenvolvimento local controlado. | ### Motor de memória (plano 21) ### Custo no ciclo de eventos da memória, das competências e da atualização de tokens (#10349) O OmniRoute é um **único processo Node**. A extração/obtenção da memória, a injeção de competências e a atualização de tokens do fornecedor são executadas no **mesmo ciclo de eventos** que `GET /healthz` e o painel. Não são executadas num thread de trabalho. | Trabalho | Código | Predefinição | Controlo do operador | | ------------------------------ | ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Extração / obtenção da memória | `src/lib/memory/` | **memoryEnabled** no painel (ativada por predefinição) | Desative **Definições → Memória**. Não existe uma variável de ambiente separada para desativação imediata além de desativar a funcionalidade nas definições. | | Injeção de competências | `src/lib/skills/injection.ts` | **skillsEnabled** no painel (ativada por predefinição) | Desative **Definições → Memória/Competências** (`skillsEnabled`). As opções de sandbox abaixo apenas limitam a execução depois de a injeção já estar ativada. | | Atualização de tokens | `src/sse/services/tokenRefresh.ts` | Ativada para fornecedores OAuth/Web ligados | Desligue o fornecedor ou deixe os tokens permanecerem válidos; atualmente, não existe uma variável de ambiente `TOKEN_REFRESH=0`. | Se `/healthz` estiver lento num sistema sem carga, desative primeiro a memória e as competências e, em seguida, verifique a carga do catálogo/compressão (#10303, #9685). Estas funcionalidades cedem a execução em pontos `await`, mas continuam a competir pelo único thread. Opções da camada de embeddings, do armazenamento vetorial e da reordenaçã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 da cache de embeddings em memória (por assinatura de origem/modelo/dimensão). | | `MEMORY_EMBEDDING_CACHE_MAX` | `1000` | Número máximo de entradas LRU mantidas na cache de embeddings. | | `MEMORY_TRANSFORMERS_MODEL` | `Xenova/all-MiniLM-L6-v2` | ID do repositório HF para o pipeline MiniLM local opcional `@huggingface/transformers` (~23 MB int8, ~400 MB de RAM). | | `MEMORY_STATIC_MODEL` | `minishlab/potion-base-8M` | ID do repositório HF para o gerador de embeddings estático potion/Model2Vec baseado numa tabela de consulta. Transferido de forma diferida para o diretório da cache. | | `MEMORY_STATIC_CACHE_DIR` | `/embeddings` | Diretório utilizado para armazenar em cache os ficheiros do modelo potion estático. Quando não definido, a predefinição é um diretório em `DATA_DIR`. | | `HF_HUB_ENDPOINT` | `https://huggingface.co` | Substitui o URL base do Hugging Face Hub utilizado por `staticPotion.ts` (por exemplo, um endpoint de espelho para configurações isoladas da rede). | | `MEMORY_VEC_TOP_K` | `20` | Valor top-K predefinido utilizado pela pesquisa vetorial por força bruta do `sqlite-vec` em `src/lib/memory/vectorStore.ts`. | | `MEMORY_RRF_K` | `60` | Constante `k` da Reciprocal Rank Fusion para recuperação híbrida FTS5 + vetorial (receita sqlite-vec). | | `VECTOR_STORE_DISABLE_VEC` | `false` | Mecanismo de teste/diagnóstico em `getVectorStore()` (`src/lib/memory/vectorStore.ts`): quando definido como `true`, força o armazenamento vetorial a `null` (simula um ambiente de cloud/WASM sem `sqlite-vec`), reduzindo a recuperação de memória à pesquisa por palavras-chave FTS5. Deixe por definir em produção. | | `NOTION_API_KEY` | _(não definido)_ | Chave da API para o backend do Notion (utilizada pela predefinição de backend conhecido de `genericBackend.ts`). | | `NOTION_API_URL` | `https://api.notion.com/v1` | URL base da API do Notion (pode ser substituído para alternativas ao Notion autoalojadas). | | `OBSIDIAN_API_KEY` | _(não definido)_ | Chave da API para o backend do Obsidian Vault (utilizada pela predefinição de backend conhecido de `genericBackend.ts`). | | `OBSIDIAN_API_URL` | `http://localhost:27123` | URL base da API do Obsidian Vault (pode ser substituído para um cofre remoto). | | `MEMORY_TYPED_DECAY_ENABLED` | `false` | Interruptor principal da degradação de memória tipada TV6. **Opcional (desativado por predefinição)** — a limpeza **elimina** memórias degradadas. Quando está desativado, `access_count`/`last_accessed_at` são apenas telemetria e nada é eliminado. | | `MEMORY_TYPED_DECAY_EPISODIC_DAYS` | `30` | TTL (dias) após o qual uma memória `episodic` não utilizada se degrada. `0` também torna as memórias episódicas imunes. Os tipos duradouros (`factual`/`procedural`/`semantic`) são sempre imunes. O relógio de degradação é reiniciado com base em `last_accessed_at`. | | `MEMORY_TYPED_DECAY_ACCESS_IMMUNITY` | `3` | Uma memória injetada `>=` este número de vezes torna-se imune à degradação, independentemente do tipo. `0` desativa a imunidade por acesso. | | `MEMORY_TYPED_DECAY_SWEEP_INTERVAL` | `0` (desativado) | Intervalo (segundos) para a limpeza periódica opcional da degradação em `src/lib/memory/typedDecay.ts`. `0`/não definido = sem limpeza periódica. Duplamente opcional: também requer `MEMORY_TYPED_DECAY_ENABLED=true`. | | `OMNIROUTE_STRICT_SYSTEM_PROVIDERS` | _(não definido)_ | IDs de fornecedores separados por vírgulas (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 inserção da memória a meio do array, segura para a cache, não é segura em conversas com vários turnos, pelo que a memória é combinada/adicionada no início como a primeira mensagem de sistema. Por predefinição, inclui apenas `xiaomi-mimo`/`mimo`; expanda para endpoints compatíveis com OpenAI autoalojados (por exemplo, Qwen3.5+/3.6) cujo modelo de chat imponha a mesma restrição de uma única mensagem de sistema inicial. | ### Exemplo de Docker com pouca RAM `128` destina-se apenas ao painel. Os agentes de programação com este heap apresentam `FATAL ERROR` durante pedidos `/v1/responses` longos. Não utilize este exemplo como gateway Claude/Codex/Grok. ```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 dos dados de preços dos modelos a partir de fontes externas. | Variável | Predefinição | Ficheiro de origem | Descrição | | ----------------------- | ------------- | ------------------------ | ------------------------------------------- | | `PRICING_SYNC_ENABLED` | `false` | `src/lib/pricingSync.ts` | Sincronização periódica de preços opcional. | | `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írgulas. | --- ## Sincronização do ELO da Arena | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------- | ------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ARENA_ELO_SYNC_ENABLED` | `true` | `src/shared/constants/featureFlagDefinitions.ts` | Sincronização periódica do ELO da tabela classificativa da Arena AI, configurável nas funcionalidades experimentais do Painel ou com `false` para a desativar. | | `MODELS_CATALOG_PREFIX_MODE` | `dual` | `src/shared/constants/featureFlagDefinitions.ts`, `src/app/api/v1/models/catalog.ts` | Forma do prefixo utilizada nos identificadores de modelos em `GET /v1/models`. `dual` anuncia tanto o prefixo curto do alias como o prefixo canónico do fornecedor para cada modelo (retrocompatibilidade — aproximadamente duplica o catálogo); `alias` emite um identificador por modelo; `canonical` emite apenas o prefixo completo do identificador do fornecedor (os fornecedores cujo alias já é o identificador canónico mantêm a sua única entrada). Os clientes podem substituir esta definição em cada pedido com `?prefix=alias`. Consulte [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 do Playground do PromptQL (não oficial/experimental) Ponte de sessão GraphQL obtida por engenharia inversa para prompt.ql.app (`src/shared/constants/providers/web-cookie.ts`). Todas as opções são facultativas — as predefinições apontam para os endpoints públicos do playground; substitua-as apenas para uma implementação do PromptQL autoalojada/alternativa. | Variável | Predefinição | Ficheiro 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 de chat/sessão. | | `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 o saldo/a utilização de créditos. | | `PROMPTQL_TOKEN_REFRESH_URL` | `https://auth.pro.ql.app/ddn/project/token` | `open-sse/executors/promptql.ts` | Endpoint utilizado para tentar atualizar o token. | | `PROMPTQL_POLL_TIMEOUT_MS` | `180000` | `open-sse/executors/promptql.ts` | Tempo máximo (ms) para consultar `thread_events` antes de expirar. | --- ## Fornecedor Web HyperAgent (Não oficial/Experimental) Ponte de sessão obtida por engenharia inversa para hyperagent.com (`src/shared/constants/providers/web-cookie.ts`). Opcional — a predefinição aponta para o endpoint público de faturação/utilização; substitua-a apenas para uma implementação HyperAgent autoalojada/alternativa. | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------- | --------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- | | `HYPERAGENT_USAGE_URL` | `https://hyperagent.com/api/settings/billing/usage` | `open-sse/services/usage/hyperagent.ts` | Endpoint utilizado para obter blocos de créditos de faturação/utilização. | --- ## Quotas de utilização do Kilo Code Consulta do saldo pessoal em USD e da utilização do Kilo Pass para o fornecedor Kilo Code. Opcional — a predefinição aponta para a API pública do Kilo; substitua-a apenas para um relay/fixture de teste. A autenticação utiliza o token de acesso OAuth existente da ligação. | Variável | Predefinição | Ficheiro de origem | Descrição | | -------------- | --------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- | | `KILO_API_URL` | `https://api.kilo.ai` | `open-sse/services/usage/kilocode.ts` | URL base utilizado para obter o saldo pessoal do Kilo Code e a utilização do Kilo Pass. | --- ## Fornecedor Web Adobe Firefly (Não oficial/Experimental) Atualização de sessão controlada pelo browser para o fornecedor Web Adobe Firefly (`open-sse/services/adobeFireflyBrowserLogin.ts`, `open-sse/services/adobeFireflySession.ts`, `open-sse/services/adobeFireflyClient.ts`). Opcional — todas as predefinições estão otimizadas para uma instalação normal em computador. > **Removido em #9255.** O antigo runtime do Chrome associado através de CDP (adobeFireflyChromeRuntime.ts) foi > substituído por um serviço de início de sessão no browser com Playwright, e as respetivas opções deixaram de existir. As > variáveis ADOBE_FIREFLY_CHROME_ CDP_PORT / VISIBLE / HEADED / PING / FORCE_RESTART, bem como > ADOBE_FIREFLY_LOGIN_WAIT_MS e ADOBE_FIREFLY_FORTER_WAIT_MS, não são lidas em nenhum ponto da > base de código — defini-las não produz qualquer efeito. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------ | ---------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ADOBE_FIREFLY_CHROME_HEADLESS` | `0` | `open-sse/services/adobeFireflyBrowserLogin.ts` | Defina como `1` para utilizar o Chrome verdadeiramente sem interface gráfica (não funciona para geração; apenas para depuração). | | `ADOBE_FIREFLY_BROWSER_REFRESH` | `1` | `open-sse/services/adobeFireflySession.ts` | Adesão/desativação do aquecimento proativo do browser. `0` desativa o aquecimento proativo (a recuperação de erros 408 a meio de um lote continua a aplicar-se). | | `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` | _(não definido)_ | `open-sse/services/adobeFireflySession.ts` | Intervalo mínimo (ms) imposto entre envios sucessivos, substituindo a predefinição incorporada. | | `ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS` | _(não definido)_ | `open-sse/services/adobeFireflySession.ts` | Intervalo adicional (ms) acrescentado após um lote bem-sucedido, substituindo a predefinição incorporada. | | `ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS` | _(não definido)_ | `open-sse/services/adobeFireflyClient.ts` | Atraso base (ms) antes do envio de um pedido de geração, substituindo a predefinição incorporada. | --- ## 19. Sincronização de modelos (Desenvolvimento) | Variável | Predefinição | Ficheiro de origem | Descrição | | ----------------------------------- | ---------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MODELS_DEV_SYNC_ENABLED` | _(não definida)_ | `src/lib/modelsDevSync.ts` | Substituição rígida para a sincronização de preços do models.dev. Não definida = respeita Definições > IA (`modelsDevSyncEnabled`). `0`/`false`/`off`/`no` **prevalece sobre a BD** e ignora tanto a sincronização periódica como as análises SQL/JSON de `getModelsDevPricing()` (recuperação quando o painel está bloqueado no mesmo ciclo de eventos). `1`/`true`/`on`/`yes` força a ativação da sincronização. Guardar/limpar preços continua a chamar `backupDbFile("pre-write")`, que não efetua qualquer operação durante a limitação de 60 minutos ou com `DISABLE_SQLITE_AUTO_BACKUP`. | | `MODELS_DEV_SYNC_INTERVAL` | `86400` (24 h) | `src/lib/modelsDevSync.ts` | Intervalo de sincronização do catálogo de modelos durante o desenvolvimento, em segundos. | | `CONTEXT_WINDOW_RECONCILE_INTERVAL` | `86400` (24 h) | `src/lib/contextWindowResolver.ts` | Intervalo (segundos) para o reconciliador autocorretivo da janela de contexto (5004): fixa as janelas declaradas pelo fornecedor, obtidas através da deteção em `/models`, como substituições `auto:discovery` quando divergem do catálogo. Defina como `0` para desativar. Reutiliza dados já sincronizados (sem nova obtenção); nunca substitui substituições `manual`. | --- ## 20. Definições específicas do fornecedor | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OPENROUTER_CATALOG_TTL_MS` | `86400000` (24h) | `src/lib/catalog/openrouterCatalog.ts` | TTL da cache do catálogo de modelos do OpenRouter. | | `MODEL_CATALOG_INCLUDE_NAMES` | `true` | `src/shared/constants/featureFlagDefinitions.ts` | Inclui campos `name` adequados para apresentação nas respostas de `/v1/models`. Desative para clientes que esperam apenas IDs. | | `CATALOG_BUILD_TIMEOUT_MS` | `8000` (8s) | `src/app/api/v1/models/catalogCache.ts` | Limite de espera no caminho frio para uma reconstrução agregada do catálogo de `GET /v1/models` (#12627). Em caso de tempo limite, é fornecida a última resposta 200 válida, caso exista. | | `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 sincronizada de uma ligação deixa de ser considerada autoritativa para o encaminhamento, recorrendo ao registo sem bloquear (#12849). As linhas que nunca receberam um carimbo de data/hora são consideradas desatualizadas. | | `OMNIROUTE_ANALYTICS_CACHE_TTL_MS` | `60000` (60s) | `src/lib/usage/analyticsResponseCache.ts` | Período durante o qual uma resposta lenta de `GET /api/usage/analytics` é reutilizada para a mesma cadeia de consulta (#15629). `0` desativa a cache. | | `OMNIROUTE_ANALYTICS_CACHE_MIN_COMPUTE_MS` | `1000` (1s) | `src/lib/usage/analyticsResponseCache.ts` | Apenas são colocadas em cache as respostas analíticas cuja criação tenha demorado, pelo menos, este período, para que as instâncias pequenas apresentem sempre dados atualizados. | | `NANOBANANA_POLL_TIMEOUT_MS` | `120000` | `open-sse/handlers/imageGeneration.ts` | Tempo máximo de espera por tarefas de geração de imagens do NanoBanana. | | `NANOBANANA_POLL_INTERVAL_MS` | `2500` | `open-sse/handlers/imageGeneration.ts` | Frequência de consulta das tarefas do NanoBanana. | | `ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS` | `8000` | `open-sse/services/adobeFireflyUpscale.ts` | Atraso base para o recuo exponencial das novas tentativas de submissão do aumento de resolução do Adobe Firefly. | | `AWS_REGION` | _(não definida)_ | `src/lib/providers/validation.ts`, `open-sse/handlers/audioSpeech.ts` | Região utilizada para construir os endpoints do AWS Bedrock (Kiro, áudio). | | `AWS_DEFAULT_REGION` | _(não definida)_ | `src/lib/providers/validation.ts`, `open-sse/handlers/audioSpeech.ts` | Valor de recurso quando `AWS_REGION` não está definida. | | `CLOUDFLARE_ACCOUNT_ID` | _(não definida)_ | `open-sse/executors/cloudflare-ai.ts` | ID da conta do Cloudflare Workers AI. | | `CLOUDFLARE_PLAYGROUND_CHROME_PATH` | _(não definida)_ | `open-sse/executors/cloudflare-playground.ts` | Caminho completo para o binário do Chrome para computador utilizado pelo executor do Cloudflare AI Playground quando a verificação da impressão digital em modo headless bloqueia o Chromium incluído no Playwright. | | `CODEBUDDY_SYSTEM_PROMPT_MAX_LEN` | ∅ (∞) | `open-sse/executors/codebuddy/shared.ts` | Limite de comprimento opcional para as instruções de sistema do chamador enviadas para o CodeBuddy (CN e Internacional). Por predefinição, apenas uma instrução que contenha um marcador de identidade de agente de programação é substituída por uma instrução neutra (o filtro de conteúdos da Tencent rejeita essas instruções); as instruções longas são mantidas. Um número inteiro > 0 também substitui qualquer instrução de sistema que ultrapasse esse número de caracteres; um valor não definido, `0` ou não inteiro desativa o limite. Cada substituição regista a regra acionada (marcador de identidade ou comprimento). | | `CLOUDFLARE_API_BASE` | `https://api.cloudflare.com/client/v4` | `src/app/api/settings/proxy/cloudflare-deploy/route.ts` | Substitui a base da API REST do Cloudflare utilizada pelo implementador do relay de Workers do conjunto de proxies (#4640 / 9router#1360). | | `NEXT_PUBLIC_CLOUDFLARE_RELAY_DEFAULT_PROJECT` | `omniroute-relay` | `src/app/(dashboard)/dashboard/settings/components/proxy/CloudflareRelayModal.tsx` | Nome predefinido do projeto Worker sugerido na janela modal "Implementar Relay" do conjunto de proxies. | | `NEXT_PUBLIC_CLOUDFLARE_RELAY_ENABLED` | `true` | `src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx` | Defina como `false` para ocultar a opção de relay do Cloudflare Workers no separador Conjunto de Proxies. | | `CLOUDFLARED_BIN` | deteção automática | `src/lib/cloudflaredTunnel.ts` | Caminho personalizado para o binário `cloudflared`. | | `CLOUDFLARED_PROTOCOL` | `http2` | `src/lib/cloudflaredTunnel.ts` | Protocolo de transporte do túnel: `http2` (predefinição), `quic` ou `auto`. | | `CLOUDFLARED_CONFIG` | _(não definido)_ | `src/lib/cloudflaredTunnel.ts` | Caminho para um `config.yml` do cloudflared gerido localmente (com `tunnel:`, `credentials-file:`, `ingress:`). Quando definido, o OmniRoute executa `tunnel --config run` (túnel com nome) em vez de um túnel rápido efémero. | | `CLOUDFLARED_HOSTNAME` | _(da entrada da configuração)_ | `src/lib/cloudflaredTunnel.ts` | Substituição do nome de anfitrião público do túnel com nome (por exemplo, `ai.example.com`), indicado como `publicUrl`/`apiUrl`. Quando não está definido, é lido a partir do primeiro nome de anfitrião de `ingress` da configuração. | | `DENO_DEPLOY_API_BASE` | `https://api.deno.com/v2` | `src/app/api/settings/proxy/deno-deploy/route.ts` | Substitui a base da API REST do Deno Deploy utilizada pelo implementador do retransmissor do conjunto de proxies (#4643 / 9router#1437). | | `NEXT_PUBLIC_DENO_RELAY_DEFAULT_PROJECT` | `omniroute-deno-relay` | `src/app/(dashboard)/dashboard/settings/components/proxy/DenoRelayModal.tsx` | Nome predefinido da aplicação Deno Deploy sugerido na caixa de diálogo «Implementar retransmissor» do conjunto de proxies. | | `NEXT_PUBLIC_DENO_RELAY_ENABLED` | `true` | `src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx` | Defina como `false` para ocultar a opção de retransmissor do Deno Deploy no separador do conjunto de proxies. | | `SEARCH_CACHE_TTL_MS` | `300000` (5 min) | `open-sse/services/searchCache.ts` | TTL da colocação em cache das respostas da API de pesquisa (Perplexity, Brave, etc.). | | `ENABLE_CC_COMPATIBLE_PROVIDER` | `false` | `src/shared/utils/featureFlags.ts` | Apresenta a interface experimental do fornecedor compatível com CC para retransmissores exclusivos do Claude Code. | | `NINEROUTER_HOST` | `127.0.0.1` | `open-sse/executors/ninerouter.ts` | Substitui o anfitrião onde a instância incorporada do 9router escuta. | | `NINEROUTER_PORT` | `20130` | `open-sse/executors/ninerouter.ts` | Substitui a porta onde a instância incorporada do 9router escuta. | | `EMBED_WS_PROXY_HOST` | `127.0.0.1` | `src/lib/services/embedWsProxy.ts` | Anfitrião de escuta do proxy WebSocket do serviço incorporado (apenas interface de loopback por predefinição). | | `EMBED_WS_PROXY_PORT` | `20131` | `src/lib/services/embedWsProxy.ts` | Porta do servidor proxy WebSocket do serviço incorporado. | | `CLIPROXYAPI_HOST` | `127.0.0.1` | `open-sse/executors/cliproxyapi.ts` | Anfitrião da ponte CLIProxyAPI (integração antiga). | | `CLIPROXYAPI_PORT` | `5544` | `open-sse/executors/cliproxyapi.ts` | Porta da ponte CLIProxyAPI. | | `CLIPROXYAPI_API_KEY` | _(vazio)_ | `open-sse/handlers/chatCore/cliproxyapiCredentials.ts` | Chave de contingência do plano de dados quando a definição `cliproxyapi_api_key` está ausente. | | `CLIPROXYAPI_MANAGEMENT_KEY` | _(vazio)_ | `src/lib/services/cliproxyAccountHealth.ts` | Chave de gestão para leituras do estado de funcionamento das contas a partir de uma instância CLIProxyAPI gerida externamente. | | `CLIPROXYAPI_CONFIG_DIR` | `~/.cli-proxy-api` | `src/lib/versionManager/processManager.ts` | Diretório de configuração da CLIProxyAPI. | | `CLIPROXY_BIND_HOST` | `127.0.0.1` | `docker-compose.yml` | Interface de anfitrião na qual o docker-compose publica o sidecar `cliproxyapi` (#12578). O respetivo volume de dados contém as credenciais OAuth/API do fornecedor e a imagem fixada não permite substituir as `api-keys` do plano de dados através de variáveis de ambiente (apenas através de um `config.yaml` montado), pelo que `0.0.0.0` expõe um serviço que contém credenciais a toda a LAN. | | `MUX_SERVICE_PORT` | `8322` | `src/lib/services/bootstrap.ts` | Substitui a porta na qual o daemon incorporado de orquestração de agentes Mux (coder/mux) escuta (sempre 127.0.0.1). | | `OPENWA_SERVICE_PORT` | `8323` | `src/lib/services/bootstrap.ts` | Substitui a porta na qual o daemon incorporado open-wa (automatização do WhatsApp Web) escuta (sempre 127.0.0.1). | | `DARIO_HOST` | `127.0.0.1` | `open-sse/executors/dario.ts` | Anfitrião de associação/ligação do serviço incorporado Dario (apenas loopback por predefinição). | | `DARIO_PORT` | `3456` | `open-sse/executors/dario.ts` | Porta do serviço incorporado Dario. | | `DARIO_HOST` | `127.0.0.1` | `open-sse/executors/dario.ts` | Anfitrião de associação/ligação do serviço incorporado Dario (apenas loopback por predefinição). | | `DARIO_PORT` | `3456` | `open-sse/executors/dario.ts` | Porta do serviço incorporado Dario. | | `LOCAL_HOSTNAMES` | _(vazio)_ | `open-sse/config/providerRegistry.ts` | Nomes de anfitrião adicionais, separados por vírgulas, tratados como "locais" (nomes de serviços Docker, etc.). | `ENABLE_CC_COMPATIBLE_PROVIDER` destina-se apenas a relays de terceiros que aceitam exclusivamente clientes Claude Code. O OmniRoute reescreve os pedidos para que esses relays os aceitem. Se apenas pretende utilizar a CLI Claude Code, ou se não sabe ao certo o que são estes relays, mantenha esta opção desativada e adicione, em alternativa, um fornecedor normal compatível com Anthropic. --- ## 21. Estado dos Proxies | Variável | Predefinição | Ficheiro de Origem | Descrição | | ------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000` | `src/lib/proxyHealth.ts` | Tempo limite da verificação rápida de estado. | | `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 conjunto otimizada para a latência. | | `PROXY_HEALTH_CACHE_TTL_MS` | `30000` | `src/lib/proxyHealth.ts` | TTL da cache dos resultados da verificação de estado. | | `PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS` | `2000` | `src/lib/proxyHealth.ts` | TTL da cache para sondagens de estado de proxies que falharam. Mantenha este valor inferior a `PROXY_HEALTH_CACHE_TTL_MS` para que os tempos limite transitórios dos proxies, sob elevada concorrência, sejam repetidos rapidamente sem desativar a falha rápida para proxies que estejam efetivamente inativos. | | `PROXY_HEALTH_ENABLED` | `true` | `src/lib/proxyHealth/scheduler.ts` | Defina como `false` para desativar o agendador de estado dos proxies em segundo plano, que sonda periodicamente os proxies registados. | | `PROXY_HEALTH_INTERVAL_MS` | `600000` | `src/lib/proxyHealth/scheduler.ts` | Intervalo de varrimento do agendador de estado em segundo plano, em ms (mínimo de `60000`). | | `PROXY_HEALTH_RELAY_INTERVAL_MS` | `21600000` | `src/lib/proxyHealth/relayCadence.ts` | Intervalo de sondagem em ms para proxies de retransmissão de periferia (`deno`/`vercel`/`cloudflare`), cujas sondagens ativam uma instância isolada sem servidor faturada (mínimo de `60000`). | | `PROXY_HEALTH_RECOVERY_INTERVAL_MS` | `600000` | `src/lib/proxyHealth/scheduler.ts` | Intervalo em ms da passagem de recuperação em segundo plano: a frequência com que os proxies anteriormente indisponíveis são novamente sondados, para que um proxy recuperado volte à rotação sem ser necessário reiniciar. Os valores inferiores a `60000` revertem para o valor predefinido. | | `PROXY_HEALTH_TEST_URL` | `https://httpbin.org/ip` | `src/lib/proxyHealth/probeTarget.ts` | Destino da sondagem de acessibilidade utilizado pelo agendador e pelo endpoint `/api/settings/proxies/auto-test`. Defina-o como um URL interno/alojado pelo próprio utilizador para evitar o destino público predefinido. | | `PROXY_HEALTH_TEST_CONCURRENCY` | `10` | `src/lib/proxyHealth/probeTarget.ts` | Número de sondagens iniciadas simultaneamente por lote, partilhado pelo agendador e pelo endpoint `/api/settings/proxies/auto-test`. Arredondado por defeito para um mínimo de 1 e limitado a 50. | | `PROXY_HEALTH_TEST_STAGGER_MS` | `100` | `src/lib/proxyHealth/probeTarget.ts` | Atraso em ms entre o início de duas sondagens num lote. Sem este atraso, todo o lote é enviado ao mesmo tempo e um IP de saída partilhado pode acionar a limitação de pedidos do destino. Defina como `0` para desativar o espaçamento; limitado a 5000. | | `PROXY_HEALTH_USE_PROVIDER_TARGET` | `true` | `src/lib/proxyHealth/providerProbeTarget.ts` | Defina como "false" para deixar de sondar o anfitrião real do fornecedor atribuído a um proxy (`GET /models`, sem chave de API) e utilizar sempre `PROXY_HEALTH_TEST_URL` em alternativa. | | `PROXY_HEALTH_AUTO_DEACTIVATE` | `false` | `src/lib/proxyHealth/statusPolicy.ts` | Quando definido como `false` (predefinição), as sondagens automatizadas de acessibilidade (o agendador + o botão "Testar tudo" de `/api/settings/proxies/auto-test`) são **apenas de leitura** e nunca alteram o estado de um proxy — apenas o operador o define como ativo/inativo, para que uma sondagem instável não deixe um proxy atribuído sem utilização (#6246). Defina como `true` para restaurar o comportamento legado de testar e definir o estado. | | `FLUSH_EMPTY_RETRY_ENABLED` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de funcionalidade de adesão voluntária (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md); uma substituição na base de dados do painel tem precedência). `true` (ou `1`, `yes`) repete os turnos de transmissão traduzidos vazios através do caminho normal de credenciais (até `STREAM_RECOVERY.EMPTY_TURN_RETRY_MAX` novas tentativas), em vez de expor uma resposta 200 vazia ou uma resposta 502 sem conteúdo. | | `PROXY_POOL_EGRESS_OBSERVATION` | `false` | `src/shared/utils/featureFlags.ts` | Sinalizador de funcionalidade de adesão voluntária (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md); uma substituição na base de dados do painel tem precedência). `true` (ou `1`, `yes`) apresenta a observação apenas de leitura da saída do conjunto sob um conjunto de proxies no painel (IPs de saída distintos, ligações e o maior número observado atrás de um único IP nas últimas 24 h, com base no registo do proxy). Nunca é utilizado para encaminhamento. | | `PROXY_OPERATOR_EGRESS_ENABLED` | `false` | `src/shared/utils/featureFlags.ts` | Flag de funcionalidade de adesão explícita (consulte [FEATURE_FLAGS.md](./FEATURE_FLAGS.md); uma substituição na BD do painel tem precedência). `true` (ou `1`, `yes`) aceita endereços observados datados, enviados pelo operador, por membro do conjunto, e combina-os com a leitura do diário para apresentação e ordenação do conjunto. | | `PROXY_OPERATOR_EGRESS_WINDOW_HOURS` | `24` | `src/lib/db/proxyOperatorEgress.ts` | Janela de observação, em horas, para linhas de saída enviadas pelo operador (lida em cada leitura; não é necessário reiniciar). Limitada a 1..168; um valor fora do intervalo, não numérico ou vazio reverte para 24, com um único aviso para todo o processo, sem nunca lançar uma exceção. | | `PROXY_AUTO_REMOVE` | `false` | `src/lib/proxyHealth/scheduler.ts` | Defina como `true` para permitir que o agendador remova automaticamente proxies após falhas consecutivas repetidas. | | `PROXY_AUTO_REMOVE_AFTER` | `3` | `src/lib/proxyHealth/scheduler.ts` | Número de 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 como `true` para permitir que o agendador desative logicamente (estado `dead`, nunca eliminado) um proxy após falhas consecutivas repetidas, em vez de o remover. Alternativa não destrutiva a `PROXY_AUTO_REMOVE`: o proxy deixa imediatamente de ser considerado na resolução do conjunto/rotação (o filtro de estado ativo utilizado pela resolução do conjunto de âmbito já o exclui) e é reativado automaticamente assim que voltar a passar nas sondagens. Partilha o limiar `PROXY_AUTO_REMOVE_AFTER`. Se ambos os flags forem `true`, `PROXY_AUTO_REMOVE` tem precedência. | | `PROXY_HEALTH_PASSIVE_SKIP` | `false` | `src/lib/proxyHealth/scheduler.ts` | Omissão passiva de adesão explícita: quando `true`, o agendador omite a sondagem em tempo real de um endpoint cujo tráfego de produção recente já comprova o seu funcionamento (pelo menos um sucesso e nenhuma falha de proxy atribuída na janela, com exatamente um fornecedor observado). Desativada por predefinição: todos os proxies são sondados. | | `PROXY_PASSIVE_WINDOW_MS` | `300000` | `src/lib/proxyHealth/passiveVerdict.ts` | Janela, em ms, do tráfego de produção analisado pela omissão passiva (limitada a `60000..599999`). É inferior ao intervalo de verificação de 10 minutos, para que uma falha recente prevaleça em vez de ser diluída. | | `OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | Permite que os fluxos de validação de OAuth e de fornecedores contornem um proxy fixado e estabeleçam ligação diretamente quando as pré-verificações de acessibilidade do proxy falham. A precedência efetiva é: substituição na BD de Flags de Funcionalidade > variável de ambiente > predefinição. | | `RATE_LIMIT_MAX_WAIT_MS` | `30000` (30 s) | `src/lib/resilience/settings.ts` | Limite predefinido de **espera na fila**: durante quanto tempo um pedido pode aguardar por uma vaga do fornecedor e permanecer em fila antes de ser rejeitado, sem nunca chegar ao serviço a montante. O temporizador é cancelado assim que a tarefa começa a ser executada — a execução é limitada separadamente por `RATE_LIMIT_EXECUTION_MAX_WAIT_MS`. A variável de ambiente define apenas o valor predefinido: uma definição persistente `resilienceSettings.requestQueue.maxWaitMs` e, depois, uma definição `rateLimitOverrides.maxWaitMs` por ligação têm, cada uma, precedência sobre este valor. | | `RATE_LIMIT_EXECUTION_MAX_WAIT_MS` | `600000` (10 min) | `open-sse/services/rateLimitManager.ts` | Limite máximo do tempo durante o qual um pedido admitido pode permanecer em execução antes de a respetiva reserva de limite de taxa expirar — separado do limite de espera na fila para que um início lento da obtenção de dados em gateways não incrementais não exceda o tempo limite (#12027). | | `RATE_LIMIT_MAX_QUEUE_DEPTH` | `0` (desativado) | `open-sse/services/rateLimitManager.ts` | Limite de admissão na fila: rejeita com um erro 429 `queue_full` quando já estiverem em fila tantos pedidos quanto este valor. `0` = ilimitado (predefinição). | | `RATE_LIMIT_AUTO_ENABLE` | _(não definida)_ | `open-sse/services/rateLimitManager.ts` | Força a ativação/desativação automática da proteção de segurança do limite de taxa, independentemente da definição persistente do Dashboard. Aceita `true`/`1`/`on` para forçar a ativação e `false`/`0`/`off` para forçar a desativação. | | `PROVIDER_COOLDOWN_ENABLED` | _(não definida → desativado)_ | `open-sse/services/providerCooldownTracker.ts` | Monitorização global opcional, entre pedidos, do período de espera do fornecedor/ligação. DESATIVADA por predefinição (sobrepõe-se ao Período de Espera da Ligação/Disjuntor do Fornecedor). Aceita `true`/`1`/`on` para ativar. | | `PROVIDER_COOLDOWN_MIN_MS` | `5000` | `open-sse/services/providerCooldownTracker.ts` | Período de espera mínimo (ms) antes de voltar a tentar um fornecedor/uma ligação com falha. Aumenta exponencialmente com falhas consecutivas. Utilizado apenas quando `PROVIDER_COOLDOWN_ENABLED` está ativo. | | `PROVIDER_COOLDOWN_MAX_MS` | `300000` (5 min) | `open-sse/services/providerCooldownTracker.ts` | Limite máximo do período de espera (ms) antes de voltar a tentar um fornecedor/uma ligação com falha, independentemente das circunstâncias. Utilizado apenas quando `PROVIDER_COOLDOWN_ENABLED` está ativo. | | `STREAM_RECOVERY_ENABLED` | _(não definida → desativado)_ | `src/lib/resilience/settings.ts` (inicialização) → `open-sse/services/streamRecovery.ts` (lógica) | **O quê:** recuperação transparente de fluxos a montante truncados (adaptação de free-claude-code). Retém a janela SSE inicial durante até `STREAM_RECOVERY.HOLDBACK_MS` (750 ms), para que uma interrupção _pré-confirmação_ — que ocorra antes de qualquer byte chegar ao cliente — seja reaberta e repetida de forma invisível. **Quando ativar:** serviços a montante instáveis/que truncam frequentemente com 0 bytes no início do fluxo; deixe DESATIVADO se não puder tolerar até 750 ms de tempo adicional até ao primeiro token em todos os fluxos. Aceita `true`/`1`/`on`. Inicializa a definição persistente de Resiliência; a definição do Dashboard tem precedência depois de configurada. | | `STREAM_RECOVERY_MIDSTREAM_ENABLED` | _(não definido → desativado)_ | `src/lib/resilience/settings.ts` (inicialização) → `open-sse/services/streamRecovery.ts` (lógica) | **O quê:** continuação a meio do fluxo (Fase 4.4) — após um truncamento _pós-confirmação_ (os bytes já chegaram ao cliente), efetua novamente o pedido com o texto parcial como preenchimento prévio do assistente e concatena o sufixo em falta. Apenas para fluxos de texto simples compatíveis com a OpenAI; nunca é acionada enquanto estiver em curso uma chamada de ferramenta. **Quando ativar:** gerações longas que sejam interrompidas a meio da resposta e quando for aceitável que a parte final recuperada chegue de uma só vez, em vez de token a token. Independente de `STREAM_RECOVERY_ENABLED` (perfil de risco diferente). Aceita `true`/`1`/`on`. | | `STREAM_THROUGHPUT_WATCHDOG_ENABLED` | _(não definido → desativado)_ | `src/lib/resilience/settings.ts` → `open-sse/services/throughputWatchdog.ts` | Monitor opcional da taxa de saída útil do fluxo ativo. Deteta fluxos que continuam a enviar fragmentos, mas permanecem abaixo da taxa configurada de saída do assistente; sinais de atividade, eventos de utilização, deltas vazios e fases de ferramentas/raciocínio não são confundidos com progresso. Separado dos tempos limite de inatividade e do prazo máximo. | | `STREAM_THROUGHPUT_WATCHDOG_WARMUP_MS` | `30000` | `src/lib/resilience/settings/normalize.ts` | Período de tolerância antes da avaliação da taxa de saída, limitado a 0–600000 ms. | | `STREAM_THROUGHPUT_WATCHDOG_WINDOW_MS` | `30000` | `src/lib/resilience/settings/normalize.ts` | Janela deslizante de saída útil, limitada a 1000–600000 ms; é necessária uma janela completa antes da interrupção. | | `STREAM_THROUGHPUT_WATCHDOG_MIN_BYTES_PER_SECOND` | `4` | `src/lib/resilience/settings/normalize.ts` | Taxa mínima, em bytes UTF-8, da saída do assistente (aproximação conservadora de tokens), limitada a 1–1000000. | | `STREAM_THROUGHPUT_WATCHDOG_MIN_USEFUL_BYTES` | `1` | `src/lib/resilience/settings/normalize.ts` | Amostra mínima não nula de saída útil considerada mensurável, limitada a 1–1000000 bytes. | | `HEALTHCHECK_STAGGER_MS` | `3000` | `src/lib/tokenHealthCheck.ts` | Intervalo de escalonamento (ms) entre as verificações de integridade dos tokens dos fornecedores no arranque. | | `HEALTHCHECK_JITTER_MIN_MS` | `500` | `src/lib/tokenHealthCheck.ts` | Variação aleatória mínima (ms) adicionada a `HEALTHCHECK_STAGGER_MS` entre as verificações de integridade dos tokens dos fornecedores, para evitar picos de pedidos (Problema #1220). | | `HEALTHCHECK_JITTER_MAX_MS` | `5000` | `src/lib/tokenHealthCheck.ts` | Variação aleatória máxima (ms) adicionada a `HEALTHCHECK_STAGGER_MS` entre as verificações de integridade dos tokens dos fornecedores, para evitar picos de pedidos (Problema #1220). | | `HEALTHCHECK_BATCH_SIZE` | `20` | `src/lib/tokenHealthCheck.ts` | Tamanho do lote de verificações simultâneas para a análise de integridade dos tokens no arranque; valores maiores verificam mais ligações em paralelo, enquanto valores menores reduzem a carga em picos (Problema #7875, regressão de #7719). | | `REQUEST_RETRY` | `2` | `src/sse/services/cooldownAwareRetry.ts` | Número de novas tentativas automáticas em respostas de período de espera específicas do modelo antes de devolver o erro ao cliente. | | `MAX_RETRY_INTERVAL_SEC` | `30` | `src/sse/services/cooldownAwareRetry.ts` | Intervalo máximo de espera exponencial (segundos) entre novas tentativas após o período de arrefecimento. Limitado por este valor, independentemente do `Retry-After` a montante. | | `HEADROOM_URL` | `http://localhost:8787` | `src/lib/headroom/detect.ts` | URL do proxy de poupança de tokens Headroom. Por predefinição, o ciclo de vida do painel (`api/headroom/*`) inicia uma CLI `headroom-ai` local na interface de loopback; substitua este valor apenas para apontar para um proxy sidecar externo do Docker. | ### Constantes de ajuste da recuperação de streams O comportamento de retenção da recuperação é ajustado através de constantes integradas em `open-sse/config/constants.ts` (`STREAM_RECOVERY`), apresentadas aqui como referência — a sua alteração requer uma modificação do código, não uma variável de ambiente: - `STREAM_RECOVERY.HOLDBACK_MS = 750` — durante quanto tempo a janela SSE inicial é retida, para que uma truncagem precoce possa ser repetida antes de qualquer byte ser enviado ao cliente. - `STREAM_RECOVERY.BUFFER_MAX_BYTES = 65536` — limite rígido da janela retida; efetua a confirmação (descarregamento + passagem direta) assim que este número de bytes for acumulado, independentemente do temporizador. - `STREAM_RECOVERY.EARLY_RETRY_MAX = 4` — número máximo de reaberturas transparentes do stream a montante enquanto a retenção ainda não tiver sido confirmada. > **Limite de taxa por fornecedor com janela deslizante (sem variável de ambiente):** o mecanismo de > contingência do limite de taxa por fornecedor com janela deslizante, adaptado do FCC, existe no código > (`open-sse/services/providerDefaultRateLimit.ts`, interligado através de > `open-sse/services/rateLimitManager.ts`), mas é fornecido com um **mapa predefinido vazio** > e atualmente **não tem qualquer variável de ambiente para operadores** — só é ativado através de um hook de teste / > alteração do código. Intencionalmente, não está indicado na tabela acima. O limitador de retransmissão por > `(token, IP)` que _tem_ um parâmetro configurável é `RELAY_IP_PER_MINUTE` (§3 Rede e portas). --- ## 22. Depuração > [!CAUTION] > Estas variáveis produzem **resultados detalhados** e podem expor dados sensíveis. **Nunca as ative em produção.** | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CURSOR_DEBUG` | _(não definida)_ | `open-sse/executors/cursor.ts` | Defina como `1` para ativar registos detalhados do executor Cursor (blocos SSE descodificados, etc.). | | `CURSOR_STREAM_DEBUG` | _(não definida)_ | `open-sse/executors/cursor.ts` | Alias retrocompatível de `CURSOR_DEBUG`. | | `CURSOR_DUMP_FILE` | _(não definida)_ | `open-sse/executors/cursor.ts` | Caminho de ficheiro opcional que recebe blocos 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` | Período de tolerância (ms) após um terminador suave composer kv_after_text quando permanecem bytes em memória intermédia — permite que uma chamada de ferramenta exec_mcp subsequente tenha tempo para concluir a respetiva trama. | | `CURSOR_TOOL_DIRECTIVE` | ativada (`!== "0"`) | `open-sse/executors/cursor.ts` | Diretiva de confirmação de ferramenta que faz com que composer-2.5 emita chamadas de ferramentas de forma fiável. Defina como `0` para desativar. | | `OMNIROUTE_SYSTEM_INSTRUCTION_APPEND` | _(não definida)_ | `open-sse/translator/request/claude-to-openai.ts`, `open-sse/translator/response/openai-to-claude.ts` | Texto de instrução de sistema definido pelo operador, anexado à mensagem de sistema APÓS a tradução (injeção pós-tradução), chegando aos caminhos codex/Responses e `/v1/messages`. Também é utilizado como prefixo da diretiva removido dos blocos de preâmbulo de sistema repetidos. Deixe por definir para desativar. | | `OMNIROUTE_STRIP_SYSTEM_PREAMBLE` | `0` (desativada) | `open-sse/translator/response/openai-to-claude.ts`, `open-sse/utils/directivePreambleStripper.ts` | Defina como `1` para remover blocos de preâmbulo da instrução de sistema do início de um fluxo openai→claude. Desativada por predefinição — as heurísticas foram concebidas para prosa em inglês e alteram o conteúdo da resposta, pelo que uma resposta que comece legitimamente com uma secção desse tipo iria perdê-la. | | `CURSOR_IMAGE_FETCH_TIMEOUT_MS` | `15000` | `open-sse/utils/cursorImages.ts` | Tempo limite de obtenção por imagem (ms) para entrada visual remota `image_url`. | | `CURSOR_STATE_DB_PATH` | _(detetada)_ | `open-sse/utils/cursorVersionDetector.ts` | Substitui a pesquisa da base de dados de estado do Cursor IDE utilizada para detetar a versão do IDE. | | `CURSOR_AGENT_CLI_VERSION` | _(detetar / fixar)_ | `open-sse/utils/cursorAgentCliVersion.ts` | ID da compilação do Agent CLI (`YYYY.MM.DD-`) para `x-cursor-client-version: cli-…` no Agent Run. | | `CURSOR_AGENT_BIN` | _(não definida)_ | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Caminho para o binário do Cursor Agent utilizado para geração de imagens. Se não estiver definida, o processador utiliza `providerSpecificData.agentBin` e, em seguida, PATH. | | `CURSOR_IMG_TIMEOUT_MS` | `210000` | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Tempo real máximo por imagem (ms) para tarefas de imagem do Cursor Agent. | | `CURSOR_IMG_MAX_CONCURRENT` | `2` | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Limite de simultaneidade do posto partilhado para tarefas de imagem do Cursor. | | `CURSOR_IMG_MODEL` | pedido / `auto` | `open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts` | Substitui `--model` da CLI do Cursor para tarefas de imagem. | | `UC_IMAGE_POLL_INTERVAL_MS` | `2000` | `open-sse/handlers/imageGeneration/providers/ucImage.ts` | Cadência de consulta de resultados da geração de imagens da UC (uncensored.com) (ms). | | `UC_IMAGE_POLL_TIMEOUT_MS` | `60000` | `open-sse/handlers/imageGeneration/providers/ucImage.ts` | Tempo real máximo (ms) para a consulta de resultados da geração de imagens da UC. | | `UC_VIDEO_POLL_INTERVAL_MS` | `3000` | `open-sse/handlers/videoGeneration/providers/ucVideo.ts` | Cadência de consulta de resultados da geração de vídeos da UC (uncensored.com) (ms). | | `UC_VIDEO_POLL_TIMEOUT_MS` | `300000` | `open-sse/handlers/videoGeneration/providers/ucVideo.ts` | Tempo real máximo (ms) para a consulta de resultados da geração de vídeos da UC. | | `CURSOR_DATA_DIR` | _(detetado)_ | `open-sse/utils/cursorAgentCliVersion.ts` | Substitui o diretório de dados da CLI do Cursor Agent (`…/versions/`); é a mesma variável utilizada pelo agente oficial. | | `CURSOR_TOKEN` | _(não definida)_ | `scripts/ad-hoc/cursor-tap.cjs` | Token de portador direto do Cursor utilizado pelas ferramentas de desenvolvimento. | | `OMNIROUTE_LOG_REQUEST_SHAPE` | desativada (ativação explícita através de `"1"`) | `src/app/api/v1/chat/completions/route.ts` | Regista marcadores de tipo/comprimento de conteúdo para cargas úteis de conversação grandes quando `"1"` está definido. Desativada por predefinição para reduzir o ruído dos registos. | | `DEBUG_RESPONSES_SSE_TO_JSON` | _(não definida)_ | `open-sse/handlers/responseTranslator.ts` | Defina como `true` para registar detalhes da tradução SSE→JSON da Responses API. | | `DEBUG_CLAUDE_NONSTREAM` | _(não definida)_ | `open-sse/handlers/responseTranslator.ts` | Defina como `true` para apresentar blocos textContent vazios no caminho de tradução de respostas do Claude (apenas para depuração). | | `NEXT_PUBLIC_OMNIROUTE_E2E_MODE` | _(não definida)_ | Infraestrutura de testes E2E | Defina como `true` para ativar o modo de teste E2E (autenticação menos restritiva, pontos de integração de teste). | --- ## 23. Integração com o GitHub Permita que os utilizadores comuniquem problemas diretamente a partir do Dashboard. | Variável | Predefinição | Ficheiro de origem | Descrição | | --------------------- | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `GITHUB_ISSUES_REPO` | _(não definido)_ | `src/app/api/v1/issues/report/route.ts` | Repositório no formato `owner/repo`. | | `GITHUB_ISSUES_TOKEN` | _(não definido)_ | `src/app/api/v1/issues/report/route.ts` | Token de acesso pessoal do GitHub com o âmbito `issues:write`. | | `GITHUB_TOKEN` | _(não definido)_ | triagem de problemas/auxiliares do agente na cloud | Token genérico de acesso ao GitHub utilizado como alternativa a `GITHUB_ISSUES_TOKEN` e pelos auxiliares do agente na cloud em `src/lib/cloudAgent/*`. | --- ## Cenários de Implementação Para obter orientações de SRE sobre o backend de retransmissão (comportamento de ts/bifrost/auto, posicionamento de 9router vs CLIProxyAPI e estratégia de contingência para débitos elevados), consulte [Estratégia do 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 com 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 ``` ### Ambiente Isolado / 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 Inverso (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 Skills (v3.8.0+) Limites e controlos de segurança aplicados quando a framework Skills (`src/lib/skills/`) executa automatizações definidas pelo utilizador num ambiente isolado. | Variável | Predefinição | Ficheiro de origem | Descrição | | --------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SKILLS_SANDBOX_TIMEOUT_MS` | `10000` (10 s) | `src/lib/skills/builtins.ts` | Limite de tempo real por execução para código de skills no sandbox. Limite rígido; qualquer execução mais longa é terminada. | | `SKILLS_EXECUTION_TIMEOUT_MS` | _(recorre a `SKILLS_SANDBOX_TIMEOUT_MS`)_ | `src/lib/skills/` | Limite de tempo da orquestração de skills de alto nível. Defina-o acima de `SKILLS_SANDBOX_TIMEOUT_MS` para permitir fluxos com vários passos. | | `SKILLS_MAX_FILE_BYTES` | `1048576` (1 MB) | `src/lib/skills/builtins.ts` | Número máximo de bytes que uma skill pode ler de um único ficheiro no sandbox. | | `SKILLS_MAX_HTTP_RESPONSE_BYTES` | `256000` (250 KB) | `src/lib/skills/builtins.ts` | Número máximo de bytes capturados de uma única resposta HTTP numa skill. | | `SKILLS_MAX_SANDBOX_OUTPUT_CHARS` | `100000` | `src/lib/skills/builtins.ts` | Limite rígido de carateres de stdout/stderr devolvidos por uma invocação do sandbox. | | `SKILLS_SANDBOX_NETWORK_ENABLED` | `false` | `src/lib/skills/builtins.ts` | Defina como `1`/`true` para permitir ligações de saída a partir do sandbox. Por predefinição, é **isolado** por segurança. | | `SKILLS_ALLOWED_SANDBOX_IMAGES` | _(vazio)_ | `src/lib/skills/builtins.ts` | Lista de imagens de contentor permitidas para execução no sandbox, separadas por vírgulas. Vazio significa apenas a predefinição integrada. | | `SKILLS_SANDBOX_DOCKER_IMAGE` | _(predefinição integrada)_ | `src/lib/skills/` | Imagem de contentor utilizada ao iniciar um sandbox baseado em Docker. Substitua-a para fixar uma imagem base personalizada e reforçada. | | `SKILLS_SANDBOX_RUNTIME` | `auto` | `src/lib/skills/sandbox.ts`, `src/lib/skills/containerProvider.ts` | Runtime de contentores para o isolamento de skills: `auto` \| `docker` \| `apple` \| `wsl` \| `orbstack` \| `podman`. `auto` seleciona o melhor runtime instalado para o SO anfitrião (Apple Container/OrbStack no macOS, WSL Container no Windows, Podman no Linux), recorrendo ao Docker como alternativa. | > [!CAUTION] > Ativar `SKILLS_SANDBOX_NETWORK_ENABLED=true` abre um caminho de saída para código arbitrário de skills. Combine esta opção com `OUTBOUND_SSRF_GUARD_ENABLED=true` e uma política rigorosa de `CORS_ORIGIN`/proxy em implementações partilhadas. --- ## 25. Quotas de Fornecedores, Túneis, Cópias de Segurança e Diversos do Runtime Endpoints de quotas de fornecedores, túneis de rede (Tailscale, Ngrok, proxy de depuração MITM), o pool de saída 1Proxy, cópias de segurança da base de dados e pequenas substituições específicas por funcionalidade referenciadas pela camada de execução ou por scripts. | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REDIS_URL` | `redis://localhost:6379` | `src/shared/utils/rateLimiter.ts` | Cadeia de ligação ao Redis para o backend do limitador de taxa. | | `ALIBABA_CODING_PLAN_HOST` | _(servidor de produção)_ | `open-sse/services/bailianQuotaFetcher.ts` | Substitui o servidor utilizado para obter as quotas do plano de programação do Alibaba Bailian. | | `ALIBABA_CODING_PLAN_QUOTA_URL` | derivado do servidor | `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 da API de inferência não permite consultá-las). Copie todo o cabeçalho `Cookie` do pedido — contém `login_qwencloud_ticket` — de qualquer chamada a `api.json` para `cs-data.qwencloud.com` em home.qwencloud.com › Billing › Subscription (F12 › Network). É sensível e específico da sessão; dê preferência ao 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 está definido, o mecanismo de obtenção 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 servidor do gateway para o mecanismo de obtenção de quotas 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 Dashboard utilizado para resolver `sec_token` a partir do HTML da sessão iniciada. | | `XIAOMI_MIMO_CONSOLE_COOKIE` | _(não definido)_ | `open-sse/services/usage/xiaomi-mimo.ts` | Cookie de sessão da consola para a API de quotas do Token Plan do Xiaomi MiMo (`platform.xiaomimimo.com/api/v1/tokenPlan/usage` + `tokenPlan/detail` — a chave da API de inferência não permite consultá-las). Copie todo o cabeçalho `Cookie` do pedido — contém `api-platform_serviceToken` e `userId` — de qualquer pedido para `platform.xiaomimimo.com` na página Token Plan (F12 › Network). É sensível e específico da sessão; dê preferência ao campo `xiaomiMimoConsoleCookie` por ligação no Dashboard. | | `XIAOMI_MIMO_MONTHLY_TOKEN_LIMIT` | `4100000000` | `open-sse/services/usage/xiaomi-mimo.ts` | Orçamento mensal (Créditos) para o fallback Xiaomi MiMo monitorizado pelo OmniRoute, utilizado quando não está configurado nenhum cookie da consola. A predefinição é 4,1 mil milhões do nível Lite; defina-o com os Créditos do plano (Standard 11 mil milhões / Pro 38 mil milhões / Max 82 mil milhões). Uma substituição por ligação em `providerSpecificData.monthlyTokenLimit` prevalece 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 de front-end da consola para obter a quota gratuita de visão/mé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 de front-end da consola para obter a quota gratuita multimodal do Alibaba Model Studio. | | `ALIBABA_FREE_TIER_AUDIO_FE_PATH` | `/costing-balance/free-quota-audio` | `open-sse/services/alibabaFreeTierQuotaFetcher.ts` | Substituição do caminho de front-end da consola para obter a quota gratuita de áudio do Alibaba Model Studio. | | `ALIBABA_FREE_TIER_ALLOWLIST_PATH` | _(não definido)_ | `open-sse/services/alibabaFreeTierAllowlist.ts` | Caminho opcional para uma substituição JSON local da lista de permissões integrada de modelos de texto do nível gratuito da Alibaba. Utiliza `$DATA_DIR/alibaba-free-tier-allowlist.json` como alternativa e, depois, `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 as mais antigas para caberem na janela de contexto (#8560). | | `MODEL_ALIAS_COMPAT_ENABLED` | ativado | `open-sse/services/model.ts` | Ativa ou desativa a camada de compatibilidade legada de aliases de modelos utilizada por clientes mais antigos. | | `OMNIROUTE_EMERGENCY_FALLBACK` | ativado | `open-sse/services/emergencyFallback.ts` | Defina como `false` (ou `0`) para desativar o fallback de emergência por esgotamento do orçamento, que reencaminha os pedidos falhados para o modelo gratuito `nvidia`/`openai/gpt-oss-120b`. 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 utiliza o valor bruto da variável de ambiente como alternativa. | | `COMMAND_CODE_CALLBACK_PORT` | _(não definido)_ | `src/app/api/providers/command-code/auth/shared.ts` | Porta local utilizada para callbacks do tipo OAuth provenientes do auxiliar da CLI Command Code. | | `COMMAND_CODE_VERSION` | `0.33.2` | `open-sse/executors/commandCode.ts` | Valor enviado como cabeçalho `x-command-code-version` ao serviço a montante Command Code. Substitua para incrementar a versão da CLI. | | `COMMANDCODE_API_URL` | `https://api.commandcode.ai` | `open-sse/services/usage/command-code.ts` | URL base do serviço a montante de utilização/quota do Command Code, usado pela telemetria de obtenção de quotas para smartphones. Substitua para utilizar uma API Command Code autoalojada/alternativa. | | `MITM_LOCAL_PORT` | `443` | `src/mitm/server.cjs` | Porta de associação local do proxy de depuração MITM. | | `MITM_DISABLE_TLS_VERIFY` | `0` | `src/mitm/server.cjs` | Defina como `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 encaminhadas por proxy; os sockets que excedam este período de inatividade são encerrados para evitar a fuga de túneis semiabertos. | | `BRIDGE_PORT` | `20129` | `bin/antigravity-bridge.mjs` | Porta na qual a ponte MITM Antigravity fica à escuta. | | `ROUTER_URL` | `http://127.0.0.1:20128/v1/antigravity` | `bin/antigravity-bridge.mjs` | Endpoint do router para o qual a ponte encaminha o tráfego 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 da mesma forma que no servidor AgentBridge: `server.crt`/`server.key` para uma instalação legada com certificado final; caso contrário, `ca.crt`/`ca.key` (AC raiz e um certificado final por anfitrião intercetado; imposto por `MITM_ROOT_CA_ENABLED=true`). A ponte termina durante o arranque se os ficheiros do modelo ativo estiverem em falta. | | `MITM_VERBOSE` | `1` | `src/mitm/server.cjs`, `src/mitm/_internal/bypass.cjs` | Nível de detalhe dos registos de decisões de encaminhamento: `0` silencia-os; valores superiores registam mais decisões de desvio/encaminhamento. | | `MITM_ROOT_CA_ENABLED` | `false` | `src/mitm/manager.ts` | Defina como `true` para optar pelo modelo de AC raiz + certificado final por anfitrião (#6684). As novas instalações recebem-no automaticamente; as instalações com um certificado final legado previamente considerado fidedigno mantêm o certificado SAN fixo legado, salvo opção em contrário. | | `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 dos certificados; não se destina a ser definido manualmente. | | `OMNIROUTE_NO_SUDO` | `0` | `src/mitm/systemCommands.ts` | Defina como `1` (verdadeiro) 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 AC (por exemplo, através do mecanismo extra-CA-certs do Node). | | `SKIP_ANTIGRAVITY_DNS` | _(não definido)_ | `src/mitm/dns/provision.ts` | Defina como `true` para ignorar totalmente o aprovisionamento de entradas DNS em `/etc/hosts` para os nomes de anfitrião do proxy Antigravity — para contentores sem sudo/root disponível. | | `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 que a instalação/desinstalação da confiança em certificados não produza qualquer efeito, garantindo que o conjunto de testes nunca altera o repositório de confiança do SO. É definido automaticamente pela configuração de testes e pelos fluxos de trabalho de CI. | | `CHANGELOG_BASE_REF` | _(automático)_ | `scripts/check/check-changelog-integrity.mjs` | Referência de base explícita para a barreira anti-devoração do CHANGELOG (a predefinição é o ramo base do PR em CI ou o `release/v*` mais elevado). | | `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. Ativação opcional, 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 do 1proxy por sincronização. | | `FREE_PROXY_1PROXY_MIN_QUALITY` | `50` | `src/lib/freeProxyProviders/oneproxy.ts` | Limite mínimo da pontuação de qualidade para importações do 1proxy. | | `FREE_PROXY_PROXIFLY_ENABLED` | `true` | `src/lib/freeProxyProviders/proxifly.ts` | Ativa a fonte de proxies gratuitos Proxifly. Defina como `false` para a 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 de nível de anonimato para o Proxifly (`elite`, `anonymous`, `transparent`). | | `FREE_PROXY_IPLOCATE_ENABLED` | `false` | `src/lib/freeProxyProviders/iplocate.ts` | Ativa 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` | Ativa a fonte do conjunto de proxies Webshare. Defina como `false` para a desativar; também requer que `FREE_PROXY_WEBSHARE_API_KEY` esteja definida. | | `FREE_PROXY_WEBSHARE_API_KEY` | _(nenhum)_ | `src/lib/freeProxyProviders/webshare.ts` | Token da API da conta Webshare (`Authorization: Token `). Obrigatório — o fornecedor permanece desativado sem este token. | | `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 do 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 Implementar 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 de projeto predefinido, pré-preenchido 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` | _(deteção automática)_ | `src/lib/tailscaleTunnel.ts` | Caminho explícito para o binário do daemon `tailscaled`. | | `TAILSCALE_AUTHKEY` | _(não definido)_ | `src/lib/tailscaleTunnel.ts` | Chave de autenticação pré-partilhada do Tailscale para executar `tailscale up` de forma não interativa/sem interface gráfica (transmitida através de `--auth-key=`). Quando não está definida, o início de sessão recorre ao URL de autenticação interativa no navegador. | | `NGROK_AUTHTOKEN` | _(não definido)_ | `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 de cópias de segurança manuais/agendadas. Os instantâneos de migração são endereçados pelo conteúdo e reutilizados para um estado idêntico da BD; não são eliminados dentro da janela de migração simultânea. 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 de cópias de segurança manuais/agendadas. `0` desativa a eliminação com base na idade. Os instantâneos de migração não são eliminados dentro da janela de migração simultânea. 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) da tarefa do lado do servidor que executa `backup-schedule.json`. Deve permanecer bastante abaixo da granularidade de 1 minuto do cron; valores inferiores a `5000` ou que não possam ser analisados regressam a `30000`. | | `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | Indicação do ambiente de execução 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 se é acedido através do Podman Machine, o aviso mantém-se neutro quanto à topologia e remete para `contrib/podman/README.md`. | | `QUOTA_STORE_DRIVER` | `sqlite` | `src/lib/quota/storeFactory.ts` | Backend de armazenamento do consumo de quotas partilhadas: `sqlite` (predefinido) ou `redis`. | | `QUOTA_STORE_REDIS_URL` | _(não definido)_ | `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 conjunto (0..1); quando esse valor é atingido ou ultrapassado, o conjunto entra em 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 reduz a sua 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 da combinação automática quando o limite de quota prévio está DESATIVADO (#4540). | | `QUOTA_CONSUMPTION_RETENTION_DAYS` | `14` | `src/lib/db/quotaConsumption.ts` | Período de retenção (dias) dos agrupamentos de `quota_consumption` antes da recolha de lixo (`gcQuotaConsumption`). | | `QUOTA_PREFLIGHT_CUTOFF_ENABLED` | `false` | `src/lib/resilience/settings.ts` | Adesão opcional (DESATIVADA por predefinição): ativa o limite rígido de quota do encaminhamento automático, que remove os candidatos com quota reduzida antes da pontuação. | | `OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL` | `false` | `open-sse/services/autoCombo/virtualFactory.ts` | Adesão opcional (DESATIVADA por predefinição): quando um filtro `auto/:` não encontra candidatos ligados, restaura o comportamento antigo de recorrer ao conjunto completo (não filtrado), em vez de devolver um conjunto vazio. A predefinição DESATIVADA faz com que `:free` signifique «apenas o escalão gratuito». | | `OMNIROUTE_CHAOS_MAX_PANEL` | `5` | `open-sse/services/autoCombo/virtualFactory.ts` | Limite do tamanho do painel (restringido a 1–10) para a variante de difusão `auto/*:chaos` — um pedido é distribuído por, no máximo, este número de modelos de fornecedores diferentes. | | `OMNIROUTE_CHAOS_MIN_PANEL` | _(predefinição do motor)_ | `open-sse/services/autoCombo/virtualFactory.ts` | Ajuste do tamanho mínimo do painel encaminhado para o processador de difusão de caos; se não estiver definido, mantém a predefinição do motor. | | `OMNIROUTE_CHAOS_PANEL_TIMEOUT_MS` | _(predefinição do motor)_ | `open-sse/services/autoCombo/virtualFactory.ts` | Tempo limite máximo (ms) para toda a distribuição do painel de caos; se não estiver definido, mantém a predefinição do motor. | | `GROK_AUTH_PATH` | `~/.grok/auth.json` | `open-sse/services/grokQuotaFetcher.ts` | Caminho para o `auth.json` da CLI Grok utilizado 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` | _(não definido)_ | `src/mitm/manager.ts` | Certificado de AC adicional (PEM) considerado fidedigno para ligações TLS a montante do AgentBridge. | | `INSPECTOR_BUFFER_SIZE` | `1000` | `src/mitm/inspector/buffer.ts` | Número máximo de pedidos capturados mantidos na memória intermédia circular do Inspetor de Tráfego. | | `INSPECTOR_MAX_BODY_KB` | `1024` | `src/mitm/inspector/buffer.ts` | Tamanho máximo (KB) do corpo capturado do pedido/resposta antes de ser truncado. | | `INSPECTOR_HTTP_PROXY_PORT` | `8080` | `src/mitm/inspector/httpProxyServer.ts` | Porta local do proxy HTTP do Inspetor de Tráfego. | | `INSPECTOR_HTTP_PROXY_AUTOSTART` | `false` | `src/mitm/inspector/httpProxyServer.ts` | Inicia automaticamente o proxy HTTP do inspetor no arranque. | | `INSPECTOR_LLM_HOSTS_EXTRA` | _(não definido)_ | `src/lib/inspector/captureState.ts` | Nomes de anfitrião adicionais (separados por vírgulas) tratados como endpoints de LLM para 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é o mecanismo de proteção do proxy de sistema reverter automaticamente as definições de proxy do SO. | | `INSPECTOR_INTERNAL_INGEST_TOKEN` | _(automático)_ | `src/app/api/tools/traffic-inspector/internal/ingest/route.ts` | Token que autentica a ingestão de capturas internas 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` | _(não definido)_ | `src/app/(dashboard)/dashboard/playground/` | Modelo predefinido para a ação «melhorar prompt» do Playground (utiliza o modelo ativo como alternativa quando não estiver definido). | | `BIFROST_ENABLED` | `1` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Interruptor principal de desativação do proxy sidecar 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 para desativar o sidecar sem voltar a implementar (incidente no router de nível 1, rotação de chaves). | | `BIFROST_BASE_URL` | _(não definido)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Quando definido, a rota do proxy sidecar Bifrost reencaminha o tráfego de `/v1/chat/completions` para este gateway Go, em vez de o enviar para o 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 incorporado Bifrost supervisionado se associa (`127.0.0.1:`) quando o OmniRoute gere o ciclo de vida do sidecar Bifrost. A predefinição é `8080`. | | `LLMLINGUA_PORT` | `20135` | `src/lib/services/bootstrap.ts` | Porta à qual o serviço de compressão LLMLingua supervisionado se associa (`127.0.0.1:`). A predefinição é `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 de compressão HTTP LLMLingua local. A predefinição é `http://127.0.0.1:20135`. | | `LLMLINGUA_MODEL` | `atjsh/llmlingua-2-js-tinybert-meetingbank` | `src/lib/services/installers/llmlingua.ts` | ID do modelo Hugging Face que o sidecar LLMLingua supervisionado carrega (transmitido para o ambiente do processo subordinado). | | `BIFROST_API_KEY` | _(não definido)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Chave de API para o gateway Bifrost (enviada como `Authorization: Bearer ...`). Se não estiver definida, a rota espera que o pedido contenha uma chave de API OmniRoute válida; esta chave destina-se apenas à autenticação no gateway. | | `BIFROST_STREAMING_ENABLED` | `true` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Quando definido como true, a rota do sidecar Bifrost devolve as respostas em streaming através de SSE pelo gateway, em vez de usar o executor de streaming TS. Defina 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 encaminhar para o gateway Bifrost (ms). Em caso de tempo limite, 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` | Nome alternativo 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 (predefinição 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 (modo estrito, sem fallback). A autenticação, limitação de taxa, proteção contra injeção e lista de permissões são sempre executadas 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` | Nome alternativo 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 tentativa através do sidecar Bifrost falhar no modo `auto`, antes de o relay voltar a tentar o sidecar; enquanto o período de espera estiver ativo, encaminha diretamente para o caminho TS e, depois, volta a testar. `0` desativa esta funcionalidade. 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 o certificado ou a chave, ou se o caminho não puder ser lido, é registado um aviso e o servidor permanece em HTTP. | | `OMNIROUTE_TLS_KEY` | _(não definido)_ | `bin/cli/commands/serve.mjs` | Caminho para a chave privada TLS PEM do HTTPS de `omniroute serve` (equivalente a `--tls-key`). Tem de ser utilizado em conjunto com `OMNIROUTE_TLS_CERT`. Consulte `OMNIROUTE_TLS_CERT`. | | `OMNIROUTE_LOCAL_ENDPOINTS_ENABLED` | `0` | `src/lib/security/localEndpoints.ts` | Interruptor principal das rotas `/api/local/*`. Quando não está definido ou é `0`, todas as rotas `/api/local/*` devolvem 503 em produção. Tem de ser `1` em implementações fora da interface de loopback para ativar o iniciador de Redis e iniciadores semelhantes de serviços locais com um clique. Proteção redundante 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 na interface de loopback (por exemplo, a aplicação de ambiente de trabalho). Quando definido, os pedidos provenientes de IPs fora da interface de loopback têm de incluir `Authorization: Bearer `. Obrigatório quando `OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=1` em implementações fora da interface de 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 GUI `RedisLauncherPanel`. | | `OMNIROUTE_REDIS_HOST_PORT` | `6379` | `bin/cli/commands/redis.mjs` | Porta do anfitrião para o iniciador Redis de 1 clique. Altere-a se o anfitrião já tiver a porta 6379 associada. 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 é publicado. O iniciador executa o Redis SEM palavra-passe, pelo que associá-lo a `0.0.0.0` disponibiliza a todos os anfitriões da sua LAN um Redis não autenticado — apenas alargue este acesso se também definir 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 executadas no anfitrião. `0.0.0.0` expõe um Redis não autenticado 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 portas do painel/API/WS em tempo real da própria aplicação (#12568). Com `REQUIRE_API_KEY=false` como predefinição fornecida no `.env.example`, `0.0.0.0` expõe o proxy LLM anónimo `/v1` a toda a LAN/WAN — apenas alargue este acesso depois de definir `REQUIRE_API_KEY=true` ou de colocar à frente um proxy inverso que imponha 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 para `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 router Bifrost (#12578). Aplica-se o mesmo raciocínio de exposição à LAN que para `REDIS_BIND_HOST`. | | `REDIS_KEY_PREFIX` | `omniroute:` | `src/shared/utils/rateLimiter.ts` | Prefixo de espaço de nomes aplicado a todas as chaves Redis do OmniRoute (limitador de taxa, cache de autenticação, armazenamento de quotas, disjuntor de aquecimento). Evita colisões de chaves quando a instância Redis é partilhada com outras aplicações (#11042). | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN` | _(não definido — mecanismo desativado)_ | `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 original da chamada seja preservada. Comparado com `timingSafeEqual`. | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE` | _(não definido)_ | `src/lib/api/internalServiceAuth.ts` | Variante de ficheiro secreto do token de serviço interno: caminho para um ficheiro cujo conteúdo, após a remoção dos espaços em branco no início e no fim, corresponde ao token. Apenas é 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 da classificação semanal do OpenRouter (#9324). Ativado por predefinição; defina como `false` para ignorar totalmente a obtenção em segundo plano (não bloqueante e nunca fatal). | | `OPENROUTER_PROVIDER_STATS_TTL_MS` | `86400000` (24 h) | `src/lib/catalog/openrouterProviderStats.ts` | TTL da cache para o instantâneo das estatísticas de fornecedores do OpenRouter, em milissegundos. | | `OMNIROUTE_REDIS_IMAGE` | `redis:7-alpine` | `bin/cli/commands/redis.mjs` | Imagem Redis utilizada pelo iniciador do Redis com 1 clique. Substitua por `redis:8-alpine` ou por um espelho de registo privado, conforme necessário. | | `QDRANT_HOST` | `qdrant` | _(perfil de cluster opcional)_ | Nome de anfitrião do sidecar do Qdrant quando `--profile memory` está ativo. A predefinição aponta para o nome do serviço qdrant na rede; substitua-o no caso de uma implementação externa. Apenas é utilizado quando `qdrantEnabled` é `true` no código (`src/lib/memory/vectorStore.ts:108`). | | `QDRANT_PORT` | `6333` | _(perfil de cluster opcional)_ | Porta REST do sidecar do Qdrant. | | `QDRANT_GRPC_PORT` | `6334` | _(perfil de cluster opcional)_ | Porta gRPC do sidecar do Qdrant. Utilizada por bibliotecas de cliente que preferem gRPC a REST para operações de streaming. | | `QDRANT_API_KEY` | _(não definido)_ | _(perfil de cluster opcional)_ | Chave de API opcional para o Qdrant Cloud ou para uma instância local autenticada. Vazio → não é enviado qualquer cabeçalho `api-key`. | | `QDRANT_COLLECTION` | `omniroute-memory` | _(perfil de cluster opcional)_ | Nome da coleção para os embeddings da memória de conversações do OmniRoute. Criada na primeira execução com as dimensões especificadas em `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 o campo `embeddingModel` nas definições do OmniRoute aponta. | | `QDRANT_VECTOR_SIZE` | `1536` | _(perfil de cluster opcional)_ | Dimensão do vetor de incorporação. Tem de corresponder ao modelo utilizado para a incorporação (text-embedding-3-small → 1536; ada-002 → 1536; nomic-embed-text → 768). | | `QDRANT_HNSW_EF_CONSTRUCT` | `128` | _(perfil de cluster opcional)_ | Precisão do índice HNSW durante a construção. Um valor mais elevado implica uma construção mais lenta e uma 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 definido como `false`, nenhuma das classes `OMNIROUTE_ROTATE_*` abaixo aciona a contingência de conta (o estado principal desativado também bloqueia as classes 429/500/502 ativadas por predefinição). Permite que um front-end de supervisão (por exemplo, a aplicação de ambiente de trabalho VibeProxy) replique as suas próprias regras de rotação no motor de contingência de contas do back-end. | | `OMNIROUTE_ROTATION_RATE_LIMIT_RESET_SECONDS` | `0` | `open-sse/services/rotationConfig.ts` | Período de espera (segundos) aplicado a uma conta cuja taxa foi limitada quando o serviço a montante 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` | Reflexo da preferência do front-end «não marcar como tendo a taxa limitada sem uma hora de reposição». | | `OMNIROUTE_ROTATE_ON_429` | `true` | `open-sse/services/rotationConfig.ts` | Ativação da contingência por estado para erros `429`. Quando definido como `false` (e `OMNIROUTE_ROTATION_ENABLED=true`), um erro `429` deixa de acionar a rotação de contas 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) efetua a rotação imediatamente, preservando o comportamento histórico. | | `OMNIROUTE_ROTATE_429_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (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 da contingência por estado para erros de servidor `5xx` (excluindo `502`, que tem a sua própria classe). Quando definido como `false`, estes erros deixam de acionar a rotação de contas. | | `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) efetua a rotação imediatamente. | | `OMNIROUTE_ROTATE_500_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (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 da contingência por estado para erros `502` (gateway inválido). Quando definido como `false`, os erros `502` deixam de acionar a rotação de contas. | | `OMNIROUTE_ROTATE_502_THRESHOLD` | `1` | `open-sse/services/rotationConfig.ts` | Número de erros `502` durante `OMNIROUTE_ROTATE_502_WINDOW_SECONDS` necessário antes de a conta ser alternada. `1` (predefinição) efetua a rotação imediatamente. | | `OMNIROUTE_ROTATE_502_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (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` | Adesão opcional (DESATIVADA por predefinição): quando definido como `true`, um simples `400` (pedido inválido) também aciona a rotação de contas. Isto é apenas aditivo — nunca bloqueia o comportamento existente do motor, segundo o qual um `400` que contenha texto relativo a limites de taxa/quota continua a acionar a contingência, independentemente deste sinalizador. | | `OMNIROUTE_ROTATE_400_THRESHOLD` | `1` | `open-sse/services/rotationConfig.ts` | Número de erros `400` durante `OMNIROUTE_ROTATE_400_WINDOW_SECONDS` necessário antes de a conta ser alternada (apenas considerado quando `OMNIROUTE_ROTATE_ON_400=true`). | | `OMNIROUTE_ROTATE_400_WINDOW_SECONDS` | `120` | `open-sse/services/rotationConfig.ts` | Janela deslizante (segundos) durante a qual os erros `400` são contabilizados para `OMNIROUTE_ROTATE_400_THRESHOLD`. | ### Agendador de aquecimento do Claude Aquecimento acionado por cron para ligações Anthropic OAuth que tenham aderido, para que a janela de limite de taxa de 5 horas seja aberta por um pedido agendado trivial, em vez de pelo primeiro pedido real (#8848). O agendador permanece desativado, a menos que `OMNIROUTE_WARMUP_ENABLED` tenha um valor verdadeiro **e** a ligação esteja assinalada em `settings.claudeWarmup.connections`; uma lista de ligações vazia significa que nada é aquecido, mesmo com a variável de ambiente ativada. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------ | ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OMNIROUTE_WARMUP_ENABLED` | _(não definida → desativado)_ | `src/lib/warmupScheduler.ts` | Interruptor principal do agendador de aquecimento. Aceita `1`/`true`/`yes`/`on` (sem distinção entre maiúsculas e minúsculas, sem espaços). 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 a execução do aquecimento, 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 execução. Limitado ao intervalo `1`-`10`; um valor não numérico utiliza `3` como alternativa. | | `OMNIROUTE_WARMUP_MODEL` | `claude-3-5-haiku-20241022` | `src/lib/warmupScheduler.ts` | Modelo utilizado no pedido de aquecimento. Substitua-o apenas se a predefinição não estiver disponível no seu plano; escolha o modelo mais barato que ainda permita abrir a janela. | ### Sessões VNC de início de sessão no navegador 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 navegador (`/api/vnc-session`), além de um alias `DATA_DIR` legado. Tudo é opcional — as predefinições do VNC destinam-se à imagem `omniroute-vnc-chromium:local` incluída e só são substituídas para utilizar uma imagem de contentor personalizada, portas diferentes 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 com 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 ambiente de execução 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 do 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 persistentes de início de sessão no navegador. | | `OMNIROUTE_VNC_IDLE_MS` | `600000` (10 min) | `src/lib/vncSession/manifest.ts` | Tempo limite de inatividade (ms) após o qual uma sessão VNC inativa é terminada. | | `OMNIROUTE_VNC_MAX_MS` | `1800000` (30 min) | `src/lib/vncSession/manifest.ts` | Limite máximo absoluto (ms) para a 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) de espera até que o navegador em contentor esteja pronto para CDP. | | `OMNIROUTE_VNC_HARVEST_MS` | `20000` | `src/lib/vncSession/manifest.ts` | Tempo limite (ms) para recolher a sessão/os 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` | Opções adicionais da linha de comandos transmitidas 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 adjacentes não consigam aceder à respetiva porta da bridge CDP. | | `VIBEPROXY_DATA_DIR` | _(não definida)_ | `open-sse/services/notionThreadSessions.ts` | **Alias legado** de `DATA_DIR`, verificado apenas quando `DATA_DIR` e `OMNIROUTE_DATA_DIR` não estão definidas. Localiza a cache de sessões de threads Web do Notion (`/notion-web-thread-sessions.json`). | --- ## 26. Infraestrutura de Testes e E2E Utilizada 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 por definir em implementações de produção. | Variável | Predefinição | Ficheiro 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 do Playwright. | | `OMNIROUTE_E2E_PASSWORD` | recorre a `INITIAL_PASSWORD` | `scripts/dev/run-next-playwright.mjs` | Palavra-passe de administrador injetada no ambiente do Playwright. | | `OMNIROUTE_DISABLE_LOCAL_HEALTHCHECK` | `true` | `scripts/dev/run-next-playwright.mjs` | Desativa a consulta periódica da verificação de integridade local durante as execuções do Playwright. | | `OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK` | `true` | `scripts/dev/run-next-playwright.mjs` | Desativa o ciclo de verificação de integridade dos tokens OAuth durante os testes. | | `OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS` | _(não definida)_ | `src/lib/tokenHealthCheck.ts` | Fornecedores separados por vírgulas excluídos da verificação proativa de atualização de tokens (por exemplo, `codex,openai`). Alternativa direcionada à desativação total da verificação de integridade — os fornecedores com TTL curto continuam a ser atualizados, enquanto os fornecedores em cascata permanecem apenas reativos. | | `OMNIROUTE_HIDE_HEALTHCHECK_LOGS` | `true` | `scripts/dev/run-next-playwright.mjs` | Suprime as mensagens da verificação de integridade no stdout do Playwright. | | `OMNIROUTE_PLAYWRIGHT_SKIP_BUILD` | `0` | `scripts/dev/run-next-playwright.mjs` | Ignora a compilação de produção do Next.js antes de o Playwright iniciar (otimização de CI). | | `OMNIROUTE_SKIP_UNINSTALL_HOOK` | `0` | `scripts/build/uninstall.mjs` | Ignora o hook de desinstalação do OmniRoute (utilizado pela 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 operacional antes de executar testes de ecossistema/protocolo. | | `ELECTRON_SMOKE_URL` | `http://127.0.0.1:20128/login` | `scripts/dev/smoke-electron-packaged.mjs` | URL na qual a infraestrutura de testes de fumo do Electron espera que a aplicação empacotada esteja disponível. | | `ELECTRON_SMOKE_TIMEOUT_MS` | `45000` | `scripts/dev/smoke-electron-packaged.mjs` | Tempo limite total (ms) antes de a infraestrutura de testes de fumo desistir. | | `ELECTRON_SMOKE_SETTLE_MS` | `2000` | `scripts/dev/smoke-electron-packaged.mjs` | Período de estabilização (ms) após o carregamento da página. | | `ELECTRON_SMOKE_APP_EXECUTABLE` | _(automático)_ | `scripts/dev/smoke-electron-packaged.mjs` | Caminho explícito para o executável empacotado do Electron. | | `ELECTRON_SMOKE_DATA_DIR` | _(diretório temporário)_ | `scripts/dev/smoke-electron-packaged.mjs` | Diretório de dados para a execução dos testes de fumo do Electron. | | `ELECTRON_SMOKE_KEEP_DATA` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | Defina como `1` para preservar o diretório de dados do teste de fumo após a execução. | | `ELECTRON_SMOKE_STREAM_LOGS` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | Defina como `1` para transmitir os registos do Electron para stdout durante a execução. | | `ELECTRON_SMOKE_COLD_RESTART` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | #7592: reinicia com o mesmo diretório de dados e confirma que o segundo arranque seleciona o controlador SQLite nativo. | | `CLI_DEVIN_BIN` | _(pesquisa no PATH)_ | `open-sse/executors/devin-cli.ts` | Substitui o caminho do binário da CLI do Devin. | ### Pipeline de tradução da documentação Utilizado por `scripts/i18n/run-translation.mjs` (o comando `npm run i18n:run`). As cinco variáveis não estão definidas por predefinição — defina-as em `.env` apenas nas máquinas que devem poder executar o tradutor da documentação. | Variável | Predefinição | Ficheiro de origem | Descrição | | ----------------------------------- | ---------------- | ---------------------------------- | ---------------------------------------------------------------------- | | `OMNIROUTE_TRANSLATION_API_URL` | _(não definida)_ | `scripts/i18n/run-translation.mjs` | URL base compatível com a OpenAI para o backend de tradução. | | `OMNIROUTE_TRANSLATION_API_KEY` | _(não definida)_ | `scripts/i18n/run-translation.mjs` | Token Bearer para o backend de tradução (nunca é registado). | | `OMNIROUTE_TRANSLATION_MODEL` | _(não definida)_ | `scripts/i18n/run-translation.mjs` | ID do modelo, por exemplo, `gpt-4o-mini` ou `cx/gpt-5.4-mini`. | | `OMNIROUTE_TRANSLATION_TIMEOUT_MS` | `60000` | `scripts/i18n/run-translation.mjs` | Tempo limite por pedido, em milissegundos. | | `OMNIROUTE_TRANSLATION_CONCURRENCY` | `4` | `scripts/i18n/run-translation.mjs` | Pedidos de tradução em paralelo ao processar vários ficheiros/idiomas. | --- ## 27. Feed do Radar (Alojamento Próprio) Extensão opcional controlada pela flag de funcionalidade RADAR_ENABLED (desativada por predefinição — uma flag de funcionalidade ativada através das Definições/BD, e não uma variável de ambiente; consulte [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 autoalojado ou derivado e para os fluxos de chaves de apoiantes. A quinta, `RADAR_ADMIN_URL`, é uma ligação separada, sem valor predefinido, para o painel de operações privado do proprietário. Consulte [docs/frameworks/RADAR.md](../frameworks/RADAR.md) para obter a documentação completa do módulo e a respetiva [sequência integral de ativação e configuração guiada](../frameworks/RADAR.md#end-to-end-activation-and-guided-setup). O leitor genérico de anúncios da página inicial/registo de alterações não é configurado através de uma variável de ambiente e não depende da flag de funcionalidade RADAR_ENABLED. Este lê apenas através de GET o URL público de `news.json` do repositório, declarado em `src/shared/utils/releaseNotes.ts`; os IDs de dispensa permanecem no armazenamento local do navegador. | Variável | Predefinição | Ficheiro de origem | Descrição | | ----------------------------- | -------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RADAR_FEED_URL` | `https://radar.omniroute.online` | `src/lib/radar/{sync,referralsSync,offersSync,intelSync}.ts` | URL base partilhado pelos feeds, assinados separadamente, de catálogo, referências, ofertas para apoiantes e Intel. Substitua-o para apontar para um serviço autoalojado ou derivado. | | `RADAR_FEED_PUBKEY` | _(chave predefinida fixada)_ | `src/lib/radar/pinnedKeys.ts` | Chave pública Ed25519 (SPKI DER em base64 ou PEM) utilizada para verificar as assinaturas de um feed personalizado. | | `RADAR_CONTRIBUTOR_CLAIM_URL` | `https://radar.omniroute.online/auth/github` | `src/lib/radar/links.ts` | URL aberto pelo botão "Sou colaborador" do painel (fluxo de reivindicação de chave de apoiante através do GitHub OAuth). | | `RADAR_SUPPORTER_PLANS_URL` | `https://radar.omniroute.online/planos` | `src/lib/radar/links.ts` | URL aberto pelo botão "Apoiar o projeto" do painel (página de pagamentos/planos). | | `RADAR_ADMIN_URL` | _(não definido)_ | `src/lib/radar/links.ts` | Ligação ao painel de operações privado, exclusiva do proprietário. HTTPS é obrigatório, exceto para um reencaminhamento SSH de loopback HTTP; valores não definidos ou inválidos não criam qualquer item de navegação. | --- ## Auditoria: Variáveis Removidas / Obsoletas As seguintes variáveis apareciam em versões anteriores de `.env.example`, mas **não têm referências em tempo de execução** na base de código atual. Foram removidas: | Variável | Motivo | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STORAGE_DRIVER=sqlite` | Nunca é lida por qualquer ficheiro de código-fonte. SQLite é o único driver suportado — não é necessária qualquer seleção. | | `INSTANCE_NAME=omniroute` | Presente em documentação/modelos de ambiente antigos, mas não utilizada em tempo de execução. Poderá regressar numa futura funcionalidade de múltiplas instâncias. | | `SQLITE_MAX_SIZE_MB=2048` | Não é referenciada no código-fonte. O tamanho da base de dados não é limitado artificialmente. | | `SQLITE_CLEAN_LEGACY_FILES=true` | Não é referenciada no código-fonte. A limpeza de ficheiros legados foi provavelmente removida. | | `CLI_ROO_BIN` | Não está registada em `src/shared/services/cliRuntime.ts`. | | `CLI_KIMI_CODING_BIN` | Não está registada em `src/shared/services/cliRuntime.ts` (o Kimi Coding utiliza OAuth, não um binário da CLI). | | `IFLOW_OAUTH_CLIENT_ID` / `IFLOW_OAUTH_CLIENT_SECRET` | Não são referenciadas em nenhuma parte 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` | Removidas na v3.8.0. O runtime deixou de ler estas variáveis de ambiente — as credenciais provêm do Dashboard / `data/provider-credentials.json` / base de dados encriptada. | | `CURSOR_PROTOBUF_DEBUG` | Removida na v3.8.0. O executor do Cursor utiliza `CURSOR_DEBUG` / `CURSOR_STREAM_DEBUG` (consulte a secção §22). | | `CLI_COMPAT_KIRO` | Removida na v3.8.0. O Kiro está em `CLI_COMPAT_OMITTED_PROVIDER_IDS` — a respetiva opção não tem efeito. | | `QIANFAN_API_KEY` | Removida juntamente com outros stubs de chaves de API de fornecedores não utilizados na v3.8.0. | ### Correções dos valores predefinidos | Variável | Valor antigo em `.env.example` | Valor predefinido real no código | Correção | | ------------------------- | ------------------------------ | -------------------------------- | -------------------------------------------------------------- | | `APP_LOG_RETENTION_DAYS` | `90` | `7` | ✅ Valor enganador removido; `7` documentado como predefinição | | `CALL_LOG_RETENTION_DAYS` | `90` | `7` | ✅ Valor enganador removido; `7` documentado como predefinição | ### Regeneração da configuração do OpenCode (ferramenta ad hoc) Utilizada por `scripts/ad-hoc/regen-opencode-config.ts` para regenerar um `opencode.json` com valores exatos de `limit.context` e `limit.output` obtidos da instância do OmniRoute em execução. Nenhuma destas variáveis é necessária para o funcionamento normal — o script é apenas uma ferramenta para programadores. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------ | ------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_URL` | `http://localhost:20128` | `scripts/ad-hoc/regen-opencode-config.ts` | URL base da instância do OmniRoute a consultar para `/v1/models`. | | `OMNIROUTE_KEY` | _(não definida)_ | `scripts/ad-hoc/regen-opencode-config.ts` | Chave de API para autenticação no endpoint `/v1/models` do OmniRoute. Se não estiver definida, utiliza `OPENCODE_API_KEY`. | | `OPENCODE_API_KEY` | _(não definida)_ | `scripts/ad-hoc/regen-opencode-config.ts` | Chave de API ao estilo do OpenCode (`sk-...`) escrita no `opencode.json` regenerado. Se não estiver definida, utiliza `OMNIROUTE_KEY`. | ### Ferramenta ad hoc de avaliação offline da compressão Utilizada por `scripts/compression-eval/index.ts`, a CLI de avaliação offline da compressão. Não é necessária para o funcionamento normal — destina-se apenas a ferramentas de desenvolvimento. | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------- | ------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_EVAL_CREDENTIALS` | `{}` (vazio) | `scripts/compression-eval/index.ts` | Credenciais JSON fornecidas pelo operador para o fornecedor utilizado pela CLI de avaliação offline da compressão (analisadas com `JSON.parse`). Deixe por definir para uma execução de teste. | ### Sessões de navegador VNC Utilizadas por `src/lib/vncSession/manifest.ts` para configurar sessões do Chromium sem interface gráfica baseadas em Docker para fornecedores de automatização de navegadores. Todas são opcionais — as predefinições são apresentadas abaixo. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------- | ------------------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------- | | `OMNIROUTE_DOCKER_BIN` | `docker` | `src/lib/vncSession/manifest.ts` | Caminho para o binário do Docker utilizado para iniciar contentores VNC. | | `OMNIROUTE_VNC_IMAGE` | `omniroute-vnc-chromium:local` | `src/lib/vncSession/manifest.ts` | Imagem Docker para o contentor VNC do Chromium. | | `OMNIROUTE_VNC_CHROMIUM_ARGS` | _(opções incorporadas)_ | `src/lib/vncSession/manifest.ts` | Argumentos adicionais da CLI do Chromium transmitidos ao navegador 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 Chrome DevTools Protocol dentro do contentor. | | `OMNIROUTE_VNC_CONTAINER_PROFILE_DIR` | `/config` | `src/lib/vncSession/manifest.ts` | Diretório do perfil dentro do contentor. | | `OMNIROUTE_VNC_PROFILE_DIR` | _(não definida)_ | `src/lib/vncSession/manifest.ts` | Diretório no anfitrião para perfis persistentes do navegador. | | `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` | Número máximo de sessões VNC simultâneas. | | `OMNIROUTE_VNC_READY_MS` | `45000` | `src/lib/vncSession/manifest.ts` | Tempo limite para o navegador ficar pronto (ms). | | `OMNIROUTE_VNC_HARVEST_MS` | `20000` | `src/lib/vncSession/manifest.ts` | Tempo limite para recolha/limpeza (ms). | | `OMNIROUTE_VNC_NETWORK` | `omniroute-vnc-browser-login` | `src/lib/vncSession/manifest.ts` | Rede Docker dedicada à qual o contentor se liga (#12571), fora da ponte predefinida. | | `VIBEPROXY_DATA_DIR` | _(não definida)_ | `open-sse/services/notionThreadSessions.ts` | Diretório para persistência das sessões de conversação do Notion. | ### Autenticação de serviços internos | Variável | Predefinição | Descrição | | --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN` | – | Token inline para autenticação serviço a serviço do plano de gestão. | | `OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE` | – | Caminho para um ficheiro que contém o token de serviço interno (preferível em contentores; substitui a variável inline). | ### Estatísticas de fornecedores do OpenRouter | Variável | Predefinição | Descrição | | ----------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | `OPENROUTER_PROVIDER_STATS_ENABLED` | `true` | Defina como `false` para não obter estatísticas por fornecedor do OpenRouter para enriquecimento do catálogo. | | `OPENROUTER_PROVIDER_STATS_TTL_MS` | `3600000` | TTL da cache (ms) para as estatísticas obtidas dos fornecedores do OpenRouter. | ### Associação do Redis incorporado | Variável | Predefinição | Descrição | | --------------------------- | ------------ | ------------------------------------------------------------------------------------ | | `REDIS_BIND_HOST` | `127.0.0.1` | Endereço de escuta do serviço Redis incorporado. | | `REDIS_PORT` | `6379` | Porta do serviço Redis incorporado. | | `OMNIROUTE_REDIS_BIND_HOST` | – | Substituição específica do OmniRoute para o endereço de escuta do Redis incorporado. | --- ## 24. Adições da versão v3.8.50 Estas definições foram introduzidas após o instantâneo anterior do contrato de ambiente. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_CHAT_ADMISSION_QUEUE_MS` | `2000` | `src/shared/middleware/chatBodyAdmission.ts` | Tempo máximo de espera por uma vaga de admissão de chat de elevado consumo antes de um `503` repetível; uma espera curta e limitada serializa picos de agentes em vez de devolver instantaneamente um `503`. `0` repõe 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 de corpos colocados em memória intermédia e em espera em todo o processo, para que a espera não amplifique o heap (#4380). As esperas que excedam o orçamento recebem imediatamente um `503` repetível. | | `OMNIROUTE_CHAT_VIRTUAL_TTL_MS` | `60000` (60 s) | `src/shared/middleware/chatBodyAdmission.ts` | Operação sem efeito obsoleta desde #10110: as vias de admissão por sessão foram removidas em favor de um único orçamento para todo o processo. Aceite para compatibilidade de configuração; ignorada. | | `OMNIROUTE_CHAT_VIRTUAL_MAX_SESSIONS` | `64` | `src/shared/middleware/chatBodyAdmission.ts` | Operação sem efeito obsoleta desde #10110: as vias de admissão por sessão foram removidas em favor de um único orçamento para todo o processo. Aceite para compatibilidade de configuração; ignorada. | | `OMNIROUTE_CHAT_VIRTUAL_LANES` | `0` (desativado) | `open-sse/services/admission/runtime.ts` | Vias virtuais adaptativas de admissão em tempo de execução (#9654): interruptor principal para o controlo adaptativo por inquilino (sistema 2). Distintas das variáveis obsoletas de vias por ligação acima (TTL_MS / MAX_SESSIONS, sem efeito desde #10110). Sinalizador de funcionalidade com o mesmo nome no painel; a variável de ambiente prevalece sobre a substituição do painel; requer reinício. | | `OMNIROUTE_RUNNOW_TIMEOUT_MS` | `30000` | `src/app/api/jobs/[id]/run-now/route.ts` | Limita o tempo durante o qual uma chamada de execução imediata aguarda por uma tarefa em curso antes de iniciar a execução em fila. | | `ADOBE_FIREFLY_BROWSER_REFRESH` | ativado | `open-sse/services/adobeFireflySession.ts` | Mantém atualizados o IMS e o estado de risco do navegador através de sessões Chrome CDP ao nível da conta; defina como `0` para desativar. | | `ADOBE_FIREFLY_SESSION_DISK` | ativado | `open-sse/services/adobeFireflySession.ts` | Mantém as sessões Adobe reparadas em `DATA_DIR`; defina como `0` para manter o estado apenas em memória. | | `ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS` | `12000` | `open-sse/services/adobeFireflySession.ts` | Intervalo mínimo entre submissões de geração do Adobe Firefly. | | `ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS` | `15000` | `open-sse/services/adobeFireflySession.ts` | Período de pausa adicional após cada terceira submissão bem-sucedida à Adobe. | | `ADOBE_FIREFLY_CHROME_HEADLESS` | `0` | `open-sse/services/adobeFireflyBrowserLogin.ts` | Modo verdadeiramente sem interface, apenas para depuração; normalmente, o Adobe colligo rejeita a sessão de risco resultante. | | `CHROME_PATH` | deteçã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 controlados pelo navegador quando a deteção automática da plataforma é insuficiente. | | `TELEGRAM_BOT_TOKEN` | _(não definido)_ | `src/lib/telegram/config.ts` | Token do BotFather que ativa o webhook de entrada e assina o `initData` da Mini App. | | `TELEGRAM_WEBHOOK_SECRET` | _(não definido)_ | `src/lib/telegram/config.ts` | Segredo partilhado registado através de `setWebhook` e verificado em relação ao cabeçalho `X-Telegram-Bot-Api-Secret-Token` em cada entrega de webhook. Obrigatório para o caminho do webhook; se não estiver definido, as entregas de webhook são recusadas com 503. | | `TELEGRAM_DEFAULT_MODEL` | `auto/chat` | `src/lib/telegram/chatProxy.ts` | Modelo utilizado para respostas de chat do Telegram. | | `TELEGRAM_BOT_API_BASE` | `https://api.telegram.org` | `src/lib/telegram/config.ts` | Substituição do URL base da Bot API para proxies ou servidores Bot API autoalojados. | | `TELEGRAM_WEBHOOK_TIMEOUT_MS` | `60000` | `src/lib/telegram/config.ts` | Tempo limite, em milissegundos, para chamadas de saída à Bot API. | | `OMNIROUTE_OPTIONAL_PACK_TAR` | `1` (ativado) | `scripts/build/optionalPackStaging.mjs` | Defina como `0` para não emitir arquivos `.tar.gz` durante a preparação de pacotes opcionais de ML/navegador para a árvore autónoma do Electron (os diretórios dos pacotes e `optional-packs.index.json` continuam a ser produzidos). Utilizado pelo fluxo de trabalho de lançamento para computadores para reduzir o tamanho do carregamento dos artefactos. | | `GROK_SUBSCRIPTION_IMAGES_ENABLED` | `false` | `open-sse/config/imageRegistry.ts` | Ativa o registo das rotas de imagens da subscrição xAI; desativado por predefinição para que o caminho de imagens da chave de API permaneça inalterado. | | `OMNIROUTE_API_KEY_COOLDOWN_MS` | `60000` | `open-sse/services/apiKeyRotator.ts` | Período de suspensão por chave, em milissegundos, quando uma resposta `429` não contém uma indicação `Retry-After` utilizável. | | `OMNIROUTE_ESTIMATOR_CALIBRATION` | ativado | `open-sse/services/estimatorCalibration.ts` | Defina como `off`, `0` ou `false` para desativar o registo e a aplicação em memória da calibração do estimador. | | `NEXT_MANUAL_SIG_HANDLE` | _(interno)_ | `scripts/dev/standalone-server-ws.mjs` | Substituição interna do processador de sinais do servidor autónomo; normalmente, é definida e limpa pelo iniciador, em vez de ser configurada pelos operadores. | ### ChatGPT Web (Codex) Predefinições globais para o navegador sem interface e o túnel de ferramentas de saída. Os valores de ligação definidos no painel têm precedência. | Variável | Predefinição | Ficheiro de origem | Descrição | | --------------------------------------- | ------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CHATGPT_WEB_CODEX_CHROME_PATH` | _(deteção automática)_ | `open-sse/executors/chatgpt-web-codex.ts` | Caminho explícito para o Chrome/Chromium para execução através de npm, systemd e PM2. | | `CHROME_PATH` | _(deteção automática)_ | `open-sse/executors/chatgpt-web-codex.ts` | Recurso comum para um caminho explícito para o Chrome/Chromium. | | `CHATGPT_WEB_CODEX_CDP_URL` | _(não definido)_ | `open-sse/executors/chatgpt-web-codex.ts` | Endpoint CDP interno; o Docker utiliza o sidecar na porta `9223`. | | `CDP_PROXY_TOKEN` | _(não definido)_ | `docker/chatgpt-web-codex-browser/cdp-proxy.mjs` | Quando definido, cada pedido ao sidecar do proxy CDP tem de incluir este valor no cabeçalho `X-Omni-Cdp-Token` (#13679). Sem um valor, o proxy reencaminha sem autenticação — nesse caso, apenas o isolamento de rede da rede Compose `chatgpt-web-codex-net` fornece proteção. Gere com `openssl rand -hex 32`. | | `CHATGPT_WEB_CODEX_TUNNEL_ID` | _(não definido)_ | `open-sse/executors/chatgpt-web-codex.ts` | ID de túnel OpenAI global para rondas locais da ferramenta Codex. | | `CHATGPT_WEB_CODEX_RUNTIME_KEY` | _(não definido)_ | `open-sse/executors/chatgpt-web-codex.ts` | Chave de runtime global do túnel; nunca a inclua nos registos. | | `CHATGPT_WEB_CODEX_CONNECTOR_NAME` | `OmniRoute Codex v2` | `open-sse/executors/chatgpt-web-codex.ts` | Nome exato do conector personalizado do ChatGPT recém-criado para a ponte MCP. | | `CODEX_CHATGPT_WEB_HOME` | `/chatgpt-web-codex` | `open-sse/vendor/codex-chatgpt-web/config.ts` | Diretório dedicado ao estado do browser, broker e túnel. | | `CODEX_CHATGPT_WEB_BROWSER_DIAGNOSTICS` | `0` | `open-sse/vendor/codex-chatgpt-web/adapters/chatgpt-web/browser-worker.ts` | Quando definido como `1`, são capturadas imagens de diagnóstico do browser em cada ponto de controlo. | | `CODEX_CHATGPT_WEB_LAUNCHER` | _(não definido)_ | `open-sse/vendor/codex-chatgpt-web/config.ts` | Caminho absoluto opcional para um binário de launcher persistente. | | `CODEX_CHATGPT_WEB_BUN` | _(deteção automática)_ | `open-sse/vendor/codex-chatgpt-web/config.ts` | Caminho absoluto opcional para o binário de runtime do Bun. | | `CODEX_WEB_GPT_BUN` | _(não definido)_ | `open-sse/vendor/codex-chatgpt-web/config.ts` | Recurso legado para `CODEX_CHATGPT_WEB_BUN`; as novas configurações utilizam o nome canónico. | --- ## Ponte OmniConductor Consumidor SSE de longa duração que replica as tarefas do hub OmniConductor no A2A TaskManager local (`src/lib/conductor/`). Opcional — a ponte só é iniciada quando `CONDUCTOR_HUB_URL` está definida. Apenas no lado do servidor: o token do hub nunca pode chegar ao navegador. | Variável | Predefinição | Ficheiro de origem | Descrição | | ------------------------------ | ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `CONDUCTOR_HUB_URL` | _(vazio)_ | `src/lib/conductor/boot.ts` | URL base do hub OmniConductor (por exemplo, `http://127.0.0.1:7910`). Não definida = ponte desativada. | | `CONDUCTOR_HUB_TOKEN` | _(vazio)_ | `src/lib/conductor/boot.ts` | Credencial do hub para o feed SSE — emita um peer do tipo `spokesperson` no hub (`POST /v1/peers`, administrador). | | `CONDUCTOR_ORCHESTRATOR_TOKEN` | _(vazio)_ | `src/lib/conductor/hubProxy.ts` | Credencial para delegação de tarefas A2A→hub recebidas (`POST /v1/tasks`); recorre a `CONDUCTOR_HUB_TOKEN` quando não definida. | | `CONDUCTOR_SPOKESPERSON_URL` | `http://127.0.0.1:7920` | `src/lib/conductor/faroProxy.ts` | URL base do serviço de porta-voz (Faro) subjacente ao proxy de conversação do painel (`/api/conductor/ask`). | ### Agendamento sensível às quotas Utilizado por `open-sse/services/combo.ts` e `src/lib/quota/quotaScheduler.ts` para verificações do orçamento de tokens antes do pedido. Opcional — o comportamento de encaminhamento predefinido permanece inalterado quando não está definido. | Variável | Predefinição | Ficheiro de origem | Descrição | | ---------------------------------- | ------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OMNIROUTE_QUOTA_AWARE_ROUTING` | `0` | `open-sse/services/combo.ts` | Quando definido como `1`, ignora ligações cujo orçamento de tokens por janela (`rateLimitOverrides.tpm`, tabela `provider_quota_state`) não consegue suportar o custo estimado do pedido antes do envio. Em caso de ausência de orçamento configurado, permite o pedido. | | `OMNIROUTE_ESTIMATOR_CALIBRATION` | _(ativa)_ | `open-sse/services/estimatorCalibration.ts` | Calibração por feedback do estimador de tokens do context guard (#14931): média móvel exponencial, por (fornecedor, modelo, presença de ferramentas), de `usage.prompt_tokens` / estimativa, limitada a 0,15–2,0 e apenas em memória. `off`, `0` ou `false` desativa o registo e a aplicação. | | `GROK_SUBSCRIPTION_IMAGES_ENABLED` | `false` | `open-sse/config/imageRegistry.ts` | Regista as rotas de imagens `xai-oauth` (`xao`) e `grok-cli`. Feature flag com o mesmo nome no painel; uma substituição na base de dados prevalece sobre este valor. |