From 6bceda86d31dd77d9fc50fd1e149ccf9ddb9abb5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 14:59:41 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/ci.md | 106 +-- docs/pt-BR/gateway/authentication.md | 119 ++-- docs/pt-BR/gateway/cli-backends.md | 220 +++--- docs/pt-BR/help/testing.md | 983 ++++++++++++++------------- 4 files changed, 725 insertions(+), 703 deletions(-) diff --git a/docs/pt-BR/ci.md b/docs/pt-BR/ci.md index 68eefa454..83148ef42 100644 --- a/docs/pt-BR/ci.md +++ b/docs/pt-BR/ci.md @@ -2,13 +2,13 @@ read_when: - Você precisa entender por que um job de CI foi ou não executado - Você está depurando verificações do GitHub Actions com falha -summary: Grafo de jobs de CI, gates de escopo e equivalentes de comandos locais +summary: Grafo de jobs de CI, gates por escopo e equivalentes de comandos locais title: Pipeline de CI x-i18n: - generated_at: "2026-04-23T13:59:22Z" + generated_at: "2026-04-23T14:55:04Z" model: gpt-5.4 provider: openai - source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f + source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d source_path: ci.md workflow: 15 --- @@ -18,81 +18,80 @@ x-i18n: A CI é executada em cada push para `main` e em cada pull request. Ela usa escopo inteligente para pular jobs caros quando apenas áreas não relacionadas foram alteradas. O QA Lab tem lanes de CI dedicadas fora do workflow principal com escopo inteligente. O -workflow `Parity gate` é executado em alterações correspondentes de PR e em acionamento manual; ele -faz build do runtime privado do QA e compara os pacotes agentic simulados GPT-5.4 e Opus 4.6. -O workflow `QA-Lab - All Lanes` é executado nightly em `main` e em -acionamento manual; ele distribui em paralelo o parity gate simulado, a lane Matrix ao vivo e a lane -Telegram ao vivo como jobs paralelos. Os jobs ao vivo usam o ambiente `qa-live-shared`, +workflow `Parity gate` é executado em alterações de PR correspondentes e por disparo manual; ele +compila o runtime privado do QA e compara os pacotes agentic simulados GPT-5.4 e Opus 4.6. +O workflow `QA-Lab - All Lanes` é executado todas as noites em `main` e por +disparo manual; ele distribui o mock parity gate, a lane Matrix ao vivo e a lane Telegram ao vivo como jobs paralelos. Os jobs ao vivo usam o ambiente `qa-live-shared`, e a lane do Telegram usa leases do Convex. `OpenClaw Release -Checks` também executa essas mesmas lanes do QA Lab antes da aprovação de release. +Checks` também executa as mesmas lanes do QA Lab antes da aprovação da release. ## Visão geral dos jobs -| Job | Finalidade | Quando é executado | +| Job | Objetivo | Quando é executado | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------- | -| `preflight` | Detectar alterações somente em docs, escopos alterados, extensões alteradas e montar o manifesto de CI | Sempre em pushes e PRs que não são draft | -| `security-scm-fast` | Detecção de chave privada e auditoria de workflow via `zizmor` | Sempre em pushes e PRs que não são draft | -| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs que não são draft | -| `security-fast` | Agregador obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs que não são draft | -| `build-artifacts` | Build de `dist/`, UI de controle, verificações de artefatos construídos e artefatos reutilizáveis para jobs downstream | Alterações relevantes para Node | -| `checks-fast-core` | Lanes rápidas de correção em Linux, como verificações de plugins integrados/contratos de plugin/protocolo | Alterações relevantes para Node | -| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canal com um resultado agregado estável | Alterações relevantes para Node | -| `checks-node-extensions` | Shards completos de teste de plugins integrados em toda a suíte de extensões | Alterações relevantes para Node | -| `checks-node-core-test` | Shards de teste do core Node, excluindo lanes de canais, integrados, contratos e extensões | Alterações relevantes para Node | -| `extension-fast` | Testes focados apenas nos plugins integrados alterados | Pull requests com alterações em extensões | +| `preflight` | Detectar alterações apenas em docs, escopos alterados, extensões alteradas e compilar o manifesto de CI | Sempre em pushes e PRs que não são draft | +| `security-scm-fast` | Detecção de chaves privadas e auditoria de workflow via `zizmor` | Sempre em pushes e PRs que não são draft | +| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra advisories do npm | Sempre em pushes e PRs que não são draft | +| `security-fast` | Agregador obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs que não são draft | +| `build-artifacts` | Compilar `dist/`, Control UI, verificações de artefatos compilados e artefatos reutilizáveis para downstream | Alterações relevantes para Node | +| `checks-fast-core` | Lanes rápidas de corretude no Linux, como verificações de bundled/plugin-contract/protocol | Alterações relevantes para Node | +| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de channel com um resultado agregado estável | Alterações relevantes para Node | +| `checks-node-extensions` | Shards completos de testes de bundled-plugin em toda a suíte de extensões | Alterações relevantes para Node | +| `checks-node-core-test` | Shards de testes do core Node, excluindo lanes de channel, bundled, contract e extension | Alterações relevantes para Node | +| `extension-fast` | Testes focados apenas nos bundled plugins alterados | Pull requests com alterações em extensões | | `check` | Equivalente local principal fragmentado: tipos de prod, lint, guards, tipos de teste e smoke estrito | Alterações relevantes para Node | -| `check-additional` | Arquitetura, limites, guards de superfície de extensão, limites de pacote e shards de gateway-watch | Alterações relevantes para Node | -| `build-smoke` | Testes smoke da CLI construída e smoke de memória na inicialização | Alterações relevantes para Node | -| `checks` | Verificador para testes de canal com artefatos construídos mais compatibilidade Node 22 apenas em push | Alterações relevantes para Node | -| `check-docs` | Verificações de formatação, lint e links quebrados da documentação | Docs alteradas | -| `skills-python` | Ruff + pytest para Skills baseadas em Python | Alterações relevantes para Skills em Python | -| `checks-windows` | Lanes de teste específicas do Windows | Alterações relevantes para Windows | -| `macos-node` | Lane de teste TypeScript no macOS usando os artefatos construídos compartilhados | Alterações relevantes para macOS | -| `macos-swift` | Lint, build e testes Swift para o app macOS | Alterações relevantes para macOS | -| `android` | Testes unitários Android para ambas as variantes mais um build de APK debug | Alterações relevantes para Android | +| `check-additional` | Guards de arquitetura, limites, superfície de extensões, fronteira de pacote e shards de gateway-watch | Alterações relevantes para Node | +| `build-smoke` | Testes smoke da CLI compilada e smoke de memória na inicialização | Alterações relevantes para Node | +| `checks` | Verificador para testes de channel de artefatos compilados mais compatibilidade push-only com Node 22 | Alterações relevantes para Node | +| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alteradas | +| `skills-python` | Ruff + pytest para Skills com backend em Python | Alterações relevantes para Skills em Python | +| `checks-windows` | Lanes de teste específicas do Windows | Alterações relevantes para Windows | +| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos compilados compartilhados | Alterações relevantes para macOS | +| `macos-swift` | Lint, build e testes em Swift para o app macOS | Alterações relevantes para macOS | +| `android` | Testes unitários do Android para ambos os flavors mais um build de APK debug | Alterações relevantes para Android | -## Ordem de fail-fast +## Ordem de falha rápida -Os jobs são ordenados para que verificações baratas falhem antes que as caras sejam executadas: +Os jobs são ordenados para que verificações baratas falhem antes de as mais caras serem executadas: -1. `preflight` decide quais lanes existirão. A lógica `docs-scope` e `changed-scope` são etapas dentro desse job, não jobs independentes. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar pelos jobs mais pesados de artefatos e matriz de plataforma. -3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto. -4. Depois disso, as lanes mais pesadas de plataforma e runtime se distribuem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` apenas para PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. +1. `preflight` decide quais lanes existirão. A lógica `docs-scope` e `changed-scope` são steps dentro deste job, não jobs independentes. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar os jobs mais pesados de artefatos e matriz de plataforma. +3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que os consumidores downstream possam começar assim que o build compartilhado estiver pronto. +4. Depois disso, as lanes mais pesadas de plataforma e runtime são distribuídas: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` apenas para PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. A lógica de escopo fica em `scripts/ci-changed-scope.mjs` e é coberta por testes unitários em `src/scripts/ci-changed-scope.test.ts`. -Edições no workflow de CI validam o grafo de CI Node mais lint de workflow, mas não forçam por si só builds nativos de Windows, Android ou macOS; essas lanes de plataforma continuam com escopo restrito a alterações no código-fonte da plataforma. -As verificações Node do Windows têm escopo restrito a wrappers específicos de processo/caminho do Windows, auxiliares de runner npm/pnpm/UI, configuração do gerenciador de pacotes e superfícies do workflow de CI que executam essa lane; alterações não relacionadas em código-fonte, plugins, install-smoke e somente testes permanecem nas lanes Node de Linux para que não reservem um worker Windows de 16 vCPU para cobertura que já é exercitada pelos shards normais de teste. -O workflow separado `install-smoke` reutiliza o mesmo script de escopo por meio do seu próprio job `preflight`. Ele calcula `run_install_smoke` a partir do sinal mais restrito de smoke alterado, então o smoke de Docker/instalação é executado para alterações relevantes de instalação, empacotamento, contêiner, produção de extensão integrada e nas superfícies do core de plugin/canal/Gateway/Plugin SDK que os jobs smoke de Docker exercitam. Edições somente de teste e somente de docs não reservam workers Docker. O smoke de pacote QR dele força a camada Docker de `pnpm install` a ser executada novamente enquanto preserva o cache do BuildKit pnpm store, então ainda exercita a instalação sem baixar novamente as dependências em cada execução. O e2e `gateway-network` reutiliza a imagem de runtime criada anteriormente no job, então adiciona cobertura real de WebSocket entre contêineres sem adicionar outro build Docker. O `test:docker:all` local faz prebuild de uma imagem compartilhada de teste ao vivo e uma imagem compartilhada de app construído de `scripts/e2e/Dockerfile`, depois executa em paralelo as lanes smoke live/E2E com `OPENCLAW_SKIP_DOCKER_BUILD=1`; ajuste o paralelismo padrão de 4 com `OPENCLAW_DOCKER_ALL_PARALLELISM`. O agregador local para de agendar novas lanes no pool após a primeira falha por padrão, e cada lane tem um timeout de 120 minutos que pode ser substituído com `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lanes sensíveis à inicialização ou ao provedor são executadas exclusivamente após o pool paralelo. O workflow reutilizável live/E2E espelha o padrão de imagem compartilhada ao fazer build e push de uma imagem Docker E2E GHCR com tag SHA antes da matriz Docker, depois executa a matriz com `OPENCLAW_SKIP_DOCKER_BUILD=1`. O workflow agendado live/E2E executa diariamente a suíte Docker completa do caminho de release. Testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação. Um job separado `docker-e2e-fast` executa o perfil Docker limitado de plugins integrados sob um timeout de comando de 120 segundos: reparo de dependência no setup-entry mais isolamento sintético de falha do bundled-loader. A matriz completa de atualização/canal integrado permanece manual/suíte completa porque realiza repetidas passagens reais de atualização npm e reparo doctor. +Edições de workflow de CI validam o grafo de CI do Node mais o lint de workflow, mas não forçam, por si só, builds nativos de Windows, Android ou macOS; essas lanes de plataforma continuam com escopo restrito a alterações no código-fonte da plataforma. +As verificações Node do Windows têm escopo restrito a wrappers específicos de processo/caminho do Windows, helpers de npm/pnpm/UI runner, configuração do gerenciador de pacotes e superfícies de workflow de CI que executam essa lane; alterações não relacionadas em código-fonte, plugin, install-smoke e apenas testes permanecem nas lanes Node do Linux para não reservar um worker Windows de 16 vCPU para cobertura que já é exercida pelos shards normais de teste. +O workflow separado `install-smoke` reutiliza o mesmo script de escopo por meio do seu próprio job `preflight`. Ele calcula `run_install_smoke` a partir do sinal mais restrito de alteração de smoke, então o smoke de Docker/instalação é executado para alterações relevantes a instalação, empacotamento, contêiner, produção de extensões bundled e superfícies centrais de plugin/channel/gateway/Plugin SDK que os jobs de smoke em Docker exercitam. Edições apenas em testes e apenas em docs não reservam workers Docker. Seu smoke do pacote QR força a camada Docker `pnpm install` a ser reexecutada preservando o cache da store pnpm do BuildKit, então ele ainda exercita a instalação sem baixar novamente as dependências em cada execução. Seu gateway-network e2e reutiliza a imagem de runtime compilada anteriormente no job, então adiciona cobertura real de WebSocket entre contêineres sem adicionar outro build Docker. O `test:docker:all` local faz prebuild de uma imagem compartilhada de teste ao vivo e uma imagem compartilhada do app compilado em `scripts/e2e/Dockerfile`, depois executa as lanes smoke live/E2E em paralelo com `OPENCLAW_SKIP_DOCKER_BUILD=1`; ajuste a concorrência padrão de 4 com `OPENCLAW_DOCKER_ALL_PARALLELISM`. O agregador local para de agendar novas lanes no pool após a primeira falha por padrão, e cada lane tem um timeout de 120 minutos, substituível com `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lanes sensíveis à inicialização ou ao provider são executadas exclusivamente após o pool paralelo. O workflow reutilizável live/E2E espelha o padrão de imagem compartilhada ao compilar e publicar uma imagem Docker E2E única no GHCR com tag SHA antes da matriz Docker, então executa a matriz com `OPENCLAW_SKIP_DOCKER_BUILD=1`. O workflow live/E2E agendado executa diariamente a suíte Docker completa do caminho de release. Os testes Docker de QR e installer mantêm seus próprios Dockerfiles focados em instalação. Um job separado `docker-e2e-fast` executa o perfil Docker limitado de bundled-plugin sob um timeout de comando de 120 segundos: reparo de dependências em setup-entry mais isolamento sintético de falha do bundled-loader. A matriz completa de bundled update/channel continua manual/full-suite porque realiza passagens repetidas reais de atualização npm e reparo com doctor. -A lógica local de lane alterada fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate local é mais rigoroso quanto aos limites de arquitetura do que o escopo amplo de plataforma da CI: alterações de produção do core executam typecheck de produção do core mais testes do core, alterações somente em testes do core executam apenas typecheck/testes de teste do core, alterações de produção de extensão executam typecheck de produção de extensão mais testes de extensão, e alterações somente em testes de extensão executam apenas typecheck/testes de teste de extensão. Alterações no Plugin SDK público ou no contrato de plugin expandem para validação de extensões porque as extensões dependem desses contratos do core. Bumps de versão apenas em metadados de release executam verificações direcionadas de versão/configuração/dependência raiz. Alterações desconhecidas em raiz/configuração falham para o lado seguro em todas as lanes. +A lógica local de lanes alteradas fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate local é mais estrito quanto a limites de arquitetura do que o amplo escopo de plataforma da CI: alterações de produção do core executam typecheck de produção do core mais testes do core, alterações apenas em testes do core executam apenas typecheck/testes de teste do core, alterações de produção de extensões executam typecheck de produção de extensões mais testes de extensões, e alterações apenas em testes de extensões executam apenas typecheck/testes de teste de extensões. Alterações no Plugin SDK público ou em plugin-contract expandem para validação de extensões porque as extensões dependem desses contratos centrais. Incrementos de versão apenas em metadados de release executam verificações direcionadas de versão/config/dependências de raiz. Alterações desconhecidas em raiz/config falham com segurança para todas as lanes. -Em pushes, a matriz `checks` adiciona a lane `compat-node22` apenas para push. Em pull requests, essa lane é ignorada e a matriz continua focada nas lanes normais de teste/canal. +Em pushes, a matriz `checks` adiciona a lane `compat-node22`, exclusiva de push. Em pull requests, essa lane é ignorada e a matriz permanece focada nas lanes normais de teste/channel. -As famílias mais lentas de testes Node são divididas ou balanceadas para que cada job permaneça pequeno: contratos de canal dividem cobertura de registro e core em seis shards ponderados no total, testes de plugins integrados são balanceados em seis workers de extensão, auto-reply roda como três workers balanceados em vez de seis workers minúsculos, e configurações agentic de Gateway/plugin são distribuídas pelos jobs Node agentic já existentes somente de código-fonte em vez de esperarem por artefatos construídos. Testes amplos de navegador, QA, mídia e plugins diversos usam suas configurações dedicadas do Vitest em vez do catch-all compartilhado de plugin. A lane ampla de agents usa o agendador compartilhado de paralelismo por arquivo do Vitest porque é dominada por import/agendamento em vez de pertencer a um único arquivo de teste lento. `runtime-config` roda com o shard `infra core-runtime` para evitar que o shard de runtime compartilhado fique com a cauda. `check-additional` mantém juntos o trabalho de compile/canary de limite de pacote e separa arquitetura de topologia de runtime da cobertura de gateway watch; o shard de boundary guard executa seus pequenos guards independentes concorrentemente dentro de um único job. Gateway watch, testes de canal e o shard de limite de suporte do core executam concorrentemente dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram construídos, mantendo seus antigos nomes de verificação como jobs leves de verificação e evitando dois workers Blacksmith extras e uma segunda fila de consumidor de artefatos. -A CI Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest`, e depois faz build do APK debug Play. A variante third-party não tem source set nem manifest separado; sua lane de teste unitário ainda compila essa variante com as flags BuildConfig de SMS/log de chamadas, evitando ao mesmo tempo um job duplicado de empacotamento de APK debug em cada push relevante para Android. -`extension-fast` é apenas para PR porque execuções em push já executam os shards completos de plugins integrados. Isso mantém feedback de plugin alterado para revisões sem reservar um worker Blacksmith extra em `main` para cobertura já presente em `checks-node-extensions`. +As famílias de teste Node mais lentas são divididas ou balanceadas para que cada job permaneça pequeno sem reservar runners em excesso: contratos de channel são executados como três shards ponderados, testes de bundled plugin são balanceados em seis workers de extensões, pequenas lanes unitárias do core são pareadas, auto-reply é executado como três workers balanceados em vez de seis workers minúsculos, e configs agentic de gateway/plugin são distribuídas pelos jobs Node agentic existentes apenas de código-fonte, em vez de esperar por artefatos compilados. Testes amplos de browser, QA, mídia e plugins diversos usam suas configs Vitest dedicadas em vez do catch-all compartilhado de plugin. A lane ampla de agents usa o agendador compartilhado de paralelismo por arquivo do Vitest porque é dominada por import/agendamento, em vez de pertencer a um único arquivo de teste lento. `runtime-config` é executado com o shard infra core-runtime para impedir que o shard de runtime compartilhado fique com a cauda. `check-additional` mantém juntos o trabalho compile/canary de package-boundary e separa a arquitetura de topologia de runtime da cobertura de gateway watch; o shard de boundary guard executa seus pequenos guards independentes simultaneamente dentro de um único job. Gateway watch, testes de channel e o shard de support-boundary do core são executados simultaneamente dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram compilados, mantendo seus nomes antigos de check como jobs verificadores leves e evitando dois workers Blacksmith extras e uma segunda fila de consumidores de artefatos. +A CI de Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest`, depois compila o APK debug Play. O flavor third-party não tem source set nem manifest separado; sua lane de teste unitário ainda compila esse flavor com os flags SMS/call-log do BuildConfig, enquanto evita um job duplicado de empacotamento de APK debug em cada push relevante para Android. +`extension-fast` é exclusivo para PR porque execuções em push já executam os shards completos de bundled plugin. Isso mantém o feedback de plugins alterados para revisão sem reservar um worker Blacksmith extra em `main` para cobertura já presente em `checks-node-extensions`. -O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais novo chega na mesma ref de PR ou `main`. Trate isso como ruído de CI, a menos que a execução mais recente da mesma ref também esteja falhando. Verificações agregadas de shard usam `!cancelled() && always()` para que ainda informem falhas normais de shard, mas não entrem na fila depois que o workflow inteiro já tiver sido substituído. +O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais recente chega no mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais recente para a mesma ref também esteja falhando. Verificações agregadas de shards usam `!cancelled() && always()` para que ainda relatem falhas normais de shard, mas não entrem na fila depois que todo o workflow já tiver sido substituído. A chave de concorrência da CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas na main. ## Runners | Runner | Jobs | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregadores (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/integrados, verificações fragmentadas de contratos de canal, shards de `check` exceto lint, shards e agregadores de `check-additional`, verificadores agregados de testes Node, verificações de docs, Skills em Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de teste Node em Linux, shards de teste de plugins integrados, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, que continua sensível o suficiente a CPU a ponto de 8 vCPU custarem mais do que economizaram; builds Docker de install-smoke, em que o tempo de fila de 32 vCPU custou mais do que economizou | +| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregadores (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/bundled, verificações fragmentadas de contratos de channel, shards de `check` exceto lint, shards e agregadores de `check-additional`, verificadores agregados de testes Node, verificações de docs, Skills em Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Node no Linux, shards de testes de bundled plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, que continua sensível o suficiente a CPU para que 8 vCPU custem mais do que economizam; builds Docker de install-smoke, em que o custo de tempo de fila de 32 vCPU foi maior do que a economia | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks usam `macos-latest` como fallback | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks usam `macos-latest` como fallback | +| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks recorrem a `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks recorrem a `macos-latest` | ## Equivalentes locais ```bash pnpm changed:lanes # inspeciona o classificador local de lanes alteradas para origin/main...HEAD pnpm check:changed # gate local inteligente: typecheck/lint/testes alterados por lane de limite -pnpm check # gate local rápido: tsgo de produção + lint fragmentado + guards rápidos paralelos +pnpm check # gate local rápido: tsgo de produção + lint fragmentado + guards rápidos em paralelo pnpm check:test-types pnpm check:timed # mesmo gate com tempos por etapa pnpm build:strict-smoke @@ -101,7 +100,8 @@ pnpm test:gateway:watch-regression pnpm test # testes Vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # formatação + lint + links quebrados das docs -pnpm build # faz build de dist quando as lanes de artefato/build-smoke da CI forem relevantes -node scripts/ci-run-timings.mjs # resume tempo total, tempo em fila e jobs mais lentos +pnpm check:docs # formatação + lint + links quebrados de docs +pnpm build # compila dist quando as lanes artifact/build-smoke da CI forem relevantes +node scripts/ci-run-timings.mjs # resume tempo total, tempo em fila e os jobs mais lentos +node scripts/ci-run-timings.mjs --recent 10 # compara execuções recentes bem-sucedidas da CI na main ``` diff --git a/docs/pt-BR/gateway/authentication.md b/docs/pt-BR/gateway/authentication.md index 0aafd9efb..e74f882a6 100644 --- a/docs/pt-BR/gateway/authentication.md +++ b/docs/pt-BR/gateway/authentication.md @@ -1,14 +1,14 @@ --- read_when: - - Depurando autenticação de modelo ou expiração de OAuth - - Documentando autenticação ou armazenamento de credenciais -summary: 'Autenticação de modelo: OAuth, chaves de API, reutilização do Claude CLI e setup-token da Anthropic' + - Depuração da autenticação do modelo ou expiração do OAuth + - Documentação da autenticação ou do armazenamento de credenciais +summary: 'Autenticação de modelo: OAuth, chaves de API, reutilização do Claude CLI e token de configuração do Anthropic' title: Autenticação x-i18n: - generated_at: "2026-04-07T05:27:09Z" + generated_at: "2026-04-23T14:55:09Z" model: gpt-5.4 provider: openai - source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231 + source_hash: 37a7c20872b915d1d079f0578c933e43cbdb97eca1c60d8c4e6e5137ca83f8b2 source_path: gateway/authentication.md workflow: 15 --- @@ -16,25 +16,20 @@ x-i18n: # Autenticação (Provedores de modelo) -Esta página cobre a autenticação de **provedor de modelo** (chaves de API, OAuth, reutilização do Claude CLI e setup-token da Anthropic). Para autenticação de **conexão com o gateway** (token, senha, trusted-proxy), consulte [Configuration](/pt-BR/gateway/configuration) e [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth). +Esta página cobre a autenticação de **provedor de modelo** (chaves de API, OAuth, reutilização do Claude CLI e token de configuração do Anthropic). Para a autenticação de **conexão do gateway** (token, senha, trusted-proxy), consulte [Configuration](/pt-BR/gateway/configuration) e [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth). -O OpenClaw oferece suporte a OAuth e chaves de API para provedores de modelo. Para hosts de gateway -sempre ativos, chaves de API geralmente são a opção mais previsível. Fluxos de -assinatura/OAuth também são compatíveis quando correspondem ao modelo de conta do seu provedor. +O OpenClaw oferece suporte a OAuth e chaves de API para provedores de modelo. Para hosts de gateway sempre ativos, chaves de API geralmente são a opção mais previsível. Fluxos de assinatura/OAuth também são compatíveis quando correspondem ao modelo de conta do seu provedor. -Consulte [/concepts/oauth](/pt-BR/concepts/oauth) para o fluxo completo de OAuth e o layout -de armazenamento. -Para autenticação baseada em SecretRef (provedores `env`/`file`/`exec`), consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets). +Consulte [/concepts/oauth](/pt-BR/concepts/oauth) para o fluxo completo de OAuth e o layout de armazenamento. +Para autenticação baseada em SecretRef (provedores `env`/`file`/`exec`), consulte [Secrets Management](/pt-BR/gateway/secrets). Para regras de elegibilidade de credenciais/códigos de motivo usadas por `models status --probe`, consulte [Semântica de credenciais de autenticação](/pt-BR/auth-credential-semantics). ## Configuração recomendada (chave de API, qualquer provedor) -Se você estiver executando um gateway de longa duração, comece com uma chave de API para o provedor -escolhido. -Para Anthropic especificamente, a autenticação por chave de API ainda é a configuração de servidor -mais previsível, mas o OpenClaw também oferece suporte à reutilização de um login local do Claude CLI. +Se você estiver executando um gateway de longa duração, comece com uma chave de API para o provedor escolhido. +Especificamente para Anthropic, a autenticação por chave de API ainda é a configuração de servidor mais previsível, mas o OpenClaw também oferece suporte à reutilização de um login local do Claude CLI. 1. Crie uma chave de API no console do seu provedor. 2. Coloque-a no **host do gateway** (a máquina que executa `openclaw gateway`). @@ -53,7 +48,7 @@ cat >> ~/.openclaw/.env <<'EOF' EOF ``` -Em seguida, reinicie o daemon (ou reinicie seu processo do Gateway) e verifique novamente: +Em seguida, reinicie o daemon (ou reinicie o processo do Gateway) e verifique novamente: ```bash openclaw models status @@ -61,42 +56,54 @@ openclaw doctor ``` Se você preferir não gerenciar variáveis de ambiente por conta própria, o onboarding pode armazenar -chaves de API para uso do daemon: `openclaw onboard`. +chaves de API para uso pelo daemon: `openclaw onboard`. Consulte [Help](/pt-BR/help) para detalhes sobre herança de ambiente (`env.shellEnv`, `~/.openclaw/.env`, systemd/launchd). ## Anthropic: compatibilidade com Claude CLI e token -A autenticação por setup-token da Anthropic ainda está disponível no OpenClaw como um caminho -compatível de token. Desde então, a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw é -permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como -autorizados para esta integração, a menos que a Anthropic publique uma nova política. Quando -a reutilização do Claude CLI está disponível no host, esse agora é o caminho preferido. +A autenticação por token de configuração do Anthropic continua disponível no OpenClaw como um caminho de token compatível. Desde então, a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw é permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como autorizados para esta integração, a menos que a Anthropic publique uma nova política. Quando a reutilização do Claude CLI está disponível no host, esse agora é o caminho preferido. -Para hosts de gateway de longa duração, uma chave de API da Anthropic ainda é a configuração -mais previsível. Se você quiser reutilizar um login existente do Claude no mesmo host, use o -caminho do Anthropic Claude CLI no onboarding/configuração. +Para hosts de gateway de longa duração, uma chave de API do Anthropic ainda é a configuração mais previsível. Se você quiser reutilizar um login existente do Claude no mesmo host, use o caminho do Anthropic Claude CLI em onboarding/configure. -Entrada manual de token (qualquer provedor; grava `auth-profiles.json` + atualiza a configuração): +Configuração de host recomendada para reutilização do Claude CLI: + +```bash +# Execute no host do gateway +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Esta é uma configuração em duas etapas: + +1. Faça login do próprio Claude Code no Anthropic no host do gateway. +2. Diga ao OpenClaw para alternar a seleção de modelo Anthropic para o backend local `claude-cli` + e armazenar o perfil de autenticação correspondente do OpenClaw. + +Se `claude` não estiver em `PATH`, instale o Claude Code primeiro ou defina +`agents.defaults.cliBackends.claude-cli.command` para o caminho real do binário. + +Entrada manual de token (qualquer provedor; grava em `auth-profiles.json` + atualiza a configuração): ```bash openclaw models auth paste-token --provider openrouter ``` -Refs de perfil de autenticação também são compatíveis para credenciais estáticas: +Referências de perfil de autenticação também são compatíveis com credenciais estáticas: - credenciais `api_key` podem usar `keyRef: { source, provider, id }` - credenciais `token` podem usar `tokenRef: { source, provider, id }` -- perfis em modo OAuth não oferecem suporte a credenciais SecretRef; se `auth.profiles..mode` estiver definido como `"oauth"`, a entrada `keyRef`/`tokenRef` com respaldo em SecretRef para esse perfil será rejeitada. +- Perfis no modo OAuth não oferecem suporte a credenciais SecretRef; se `auth.profiles..mode` estiver definido como `"oauth"`, a entrada `keyRef`/`tokenRef` com suporte de SecretRef para esse perfil será rejeitada. -Verificação amigável para automação (saída `1` quando expirado/ausente, `2` quando prestes a expirar): +Verificação compatível com automação (saída `1` quando expirado/ausente, `2` quando está expirando): ```bash openclaw models status --check ``` -Sondagens de autenticação ao vivo: +Sondagens de autenticação em tempo real: ```bash openclaw models status --probe @@ -104,12 +111,12 @@ openclaw models status --probe Observações: -- Linhas de sonda podem vir de perfis de autenticação, credenciais de ambiente ou `models.json`. -- Se `auth.order.` explícito omitir um perfil armazenado, a sonda relatará +- Linhas de sondagem podem vir de perfis de autenticação, credenciais de ambiente ou `models.json`. +- Se `auth.order.` explícito omitir um perfil armazenado, a sondagem reportará `excluded_by_auth_order` para esse perfil em vez de tentar usá-lo. -- Se a autenticação existir, mas o OpenClaw não conseguir resolver um candidato de modelo sondável para - esse provedor, a sonda relatará `status: no_model`. -- Cooldowns de limite de taxa podem ser específicos do modelo. Um perfil em cooldown para um +- Se a autenticação existir, mas o OpenClaw não conseguir resolver um candidato sondável de modelo para + esse provedor, a sondagem reportará `status: no_model`. +- Resfriamentos por limite de taxa podem ser específicos por modelo. Um perfil em resfriamento para um modelo ainda pode ser utilizável para um modelo irmão no mesmo provedor. Scripts operacionais opcionais (systemd/Termux) estão documentados aqui: @@ -117,15 +124,15 @@ Scripts operacionais opcionais (systemd/Termux) estão documentados aqui: ## Observação sobre Anthropic -O backend `claude-cli` da Anthropic é compatível novamente. +O backend `claude-cli` do Anthropic voltou a ser compatível. - A equipe da Anthropic nos informou que esse caminho de integração do OpenClaw é permitido novamente. - Portanto, o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como autorizados - para execuções com respaldo da Anthropic, a menos que a Anthropic publique uma nova política. -- Chaves de API da Anthropic continuam sendo a escolha mais previsível para hosts de gateway - de longa duração e controle explícito de cobrança no lado do servidor. + para execuções com Anthropic, a menos que a Anthropic publique uma nova política. +- Chaves de API do Anthropic continuam sendo a escolha mais previsível para hosts de gateway de longa + duração e controle explícito de faturamento no lado do servidor. -## Verificando o status da autenticação do modelo +## Verificação do status de autenticação do modelo ```bash openclaw models status @@ -134,7 +141,7 @@ openclaw doctor ## Comportamento de rotação de chave de API (gateway) -Alguns provedores oferecem suporte a tentar novamente uma solicitação com chaves alternativas quando uma chamada de API +Alguns provedores oferecem suporte a repetir uma solicitação com chaves alternativas quando uma chamada de API atinge um limite de taxa do provedor. - Ordem de prioridade: @@ -142,7 +149,7 @@ atinge um limite de taxa do provedor. - `_API_KEYS` - `_API_KEY` - `_API_KEY_*` -- Provedores Google também incluem `GOOGLE_API_KEY` como fallback adicional. +- Provedores do Google também incluem `GOOGLE_API_KEY` como fallback adicional. - A mesma lista de chaves é deduplicada antes do uso. - O OpenClaw tenta novamente com a próxima chave apenas para erros de limite de taxa (por exemplo `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent @@ -151,7 +158,7 @@ requests`, `ThrottlingException`, `concurrency limit reached`, ou - Erros que não sejam de limite de taxa não são tentados novamente com chaves alternativas. - Se todas as chaves falharem, o erro final da última tentativa será retornado. -## Controlando qual credencial é usada +## Controlar qual credencial é usada ### Por sessão (comando de chat) @@ -159,7 +166,7 @@ Use `/model @` para fixar uma credencial específica de Use `/model` (ou `/model list`) para um seletor compacto; use `/model status` para a visualização completa (candidatos + próximo perfil de autenticação, além de detalhes do endpoint do provedor quando configurado). -### Por agente (substituição da CLI) +### Por agente (substituição na CLI) Defina uma substituição explícita da ordem de perfis de autenticação para um agente (armazenada no `auth-state.json` desse agente): @@ -169,25 +176,25 @@ openclaw models auth order set --provider anthropic anthropic:default openclaw models auth order clear --provider anthropic ``` -Use `--agent ` para direcionar um agente específico; omita-o para usar o agente padrão configurado. -Ao depurar problemas de ordem, `openclaw models status --probe` mostra perfis -armazenados omitidos como `excluded_by_auth_order` em vez de ignorá-los silenciosamente. -Ao depurar problemas de cooldown, lembre-se de que cooldowns de limite de taxa podem estar vinculados -a um ID de modelo, e não ao perfil inteiro do provedor. +Use `--agent ` para direcionar a um agente específico; omita-o para usar o agente padrão configurado. +Ao depurar problemas de ordem, `openclaw models status --probe` mostra perfis armazenados omitidos +como `excluded_by_auth_order` em vez de ignorá-los silenciosamente. +Ao depurar problemas de resfriamento, lembre-se de que resfriamentos por limite de taxa podem estar vinculados +a um ID de modelo em vez de a todo o perfil do provedor. ## Solução de problemas ### "Nenhuma credencial encontrada" -Se o perfil da Anthropic estiver ausente, configure uma chave de API da Anthropic no -**host do gateway** ou configure o caminho de setup-token da Anthropic, e depois verifique novamente: +Se o perfil do Anthropic estiver ausente, configure uma chave de API do Anthropic no +**host do gateway** ou configure o caminho de token de configuração do Anthropic, depois verifique novamente: ```bash openclaw models status ``` -### Token prestes a expirar/expirado +### Token expirando/expirado -Execute `openclaw models status` para confirmar qual perfil está prestes a expirar. Se um -perfil de token da Anthropic estiver ausente ou expirado, atualize essa configuração por meio do -setup-token ou migre para uma chave de API da Anthropic. +Execute `openclaw models status` para confirmar qual perfil está expirando. Se um +perfil de token do Anthropic estiver ausente ou expirado, atualize essa configuração via +token de configuração ou migre para uma chave de API do Anthropic. diff --git a/docs/pt-BR/gateway/cli-backends.md b/docs/pt-BR/gateway/cli-backends.md index 4aad62467..7c095917d 100644 --- a/docs/pt-BR/gateway/cli-backends.md +++ b/docs/pt-BR/gateway/cli-backends.md @@ -1,40 +1,40 @@ --- read_when: - - Você quer um fallback confiável quando provedores de API falham + - Você quer um fallback confiável quando os provedores de API falham - Você está executando o Codex CLI ou outras CLIs locais de IA e quer reutilizá-las - - Você quer entender a bridge MCP loopback para acesso a ferramentas do backend de CLI -summary: 'Backends de CLI: fallback de CLI local de IA com bridge opcional de ferramenta MCP' + - Você quer entender a ponte MCP de loopback para acesso a ferramentas do backend de CLI +summary: 'Backends de CLI: fallback local de CLI de IA com ponte opcional de ferramenta MCP' title: Backends de CLI x-i18n: - generated_at: "2026-04-23T14:02:31Z" + generated_at: "2026-04-23T14:55:05Z" model: gpt-5.4 provider: openai - source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e + source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316 source_path: gateway/cli-backends.md workflow: 15 --- # Backends de CLI (runtime de fallback) -O OpenClaw pode executar **CLIs locais de IA** como um **fallback somente de texto** quando provedores de API estão fora do ar, -com rate limit ou temporariamente se comportando mal. Isso é intencionalmente conservador: +O OpenClaw pode executar **CLIs locais de IA** como um **fallback somente de texto** quando os provedores de API estão fora do ar, +com limite de taxa ou temporariamente se comportando mal. Isso é intencionalmente conservador: - **As ferramentas do OpenClaw não são injetadas diretamente**, mas backends com `bundleMcp: true` - podem receber ferramentas do Gateway por meio de uma bridge MCP loopback. -- **Streaming JSONL** para CLIs que o suportam. -- **Sessões são compatíveis** (para que turnos de continuação permaneçam coerentes). + podem receber ferramentas do Gateway por meio de uma ponte MCP de loopback. +- **Streaming JSONL** para CLIs que oferecem suporte. +- **Sessões são suportadas** (para que as interações de continuação permaneçam coerentes). - **Imagens podem ser repassadas** se a CLI aceitar caminhos de imagem. Isso foi projetado como uma **rede de segurança** em vez de um caminho principal. Use quando você -quiser respostas de texto “sempre funcionam” sem depender de APIs externas. +quiser respostas de texto do tipo “sempre funciona” sem depender de APIs externas. Se você quiser um runtime de harness completo com controles de sessão ACP, tarefas em segundo plano, vinculação de thread/conversa e sessões externas persistentes de codificação, use -[Agentes ACP](/pt-BR/tools/acp-agents). Backends de CLI não são ACP. +[ACP Agents](/pt-BR/tools/acp-agents). Os backends de CLI não são ACP. -## Início rápido para iniciantes +## Início rápido amigável para iniciantes -Você pode usar o Codex CLI **sem nenhuma configuração** (o plugin OpenAI integrado +Você pode usar o Codex CLI **sem nenhuma configuração** (o Plugin OpenAI empacotado registra um backend padrão): ```bash @@ -60,14 +60,14 @@ caminho do comando: É só isso. Nenhuma chave, nenhuma configuração extra de autenticação além da própria CLI. -Se você usar um backend de CLI integrado como **provedor principal de mensagens** em um -host de Gateway, o OpenClaw agora carrega automaticamente o plugin integrado responsável quando sua configuração -faz referência explícita a esse backend em uma referência de modelo ou em +Se você usar um backend de CLI empacotado como o **provedor principal de mensagens** em um +host do Gateway, o OpenClaw agora carrega automaticamente o Plugin empacotado proprietário quando sua configuração +faz referência explicitamente a esse backend em uma referência de modelo ou em `agents.defaults.cliBackends`. ## Usando como fallback -Adicione um backend de CLI à sua lista de fallback para que ele só rode quando os modelos primários falharem: +Adicione um backend de CLI à sua lista de fallback para que ele só rode quando os modelos principais falharem: ```json5 { @@ -88,8 +88,8 @@ Adicione um backend de CLI à sua lista de fallback para que ele só rode quando Observações: -- Se você usar `agents.defaults.models` (lista de permissões), também deverá incluir ali os modelos do backend de CLI. -- Se o provedor primário falhar (autenticação, rate limits, timeouts), o OpenClaw +- Se você usa `agents.defaults.models` (lista de permissões), deve incluir seus modelos de backend de CLI lá também. +- Se o provedor principal falhar (autenticação, limites de taxa, timeouts), o OpenClaw tentará o backend de CLI em seguida. ## Visão geral da configuração @@ -100,7 +100,7 @@ Todos os backends de CLI ficam em: agents.defaults.cliBackends ``` -Cada entrada é indexada por um **id de provedor** (por exemplo `codex-cli`, `my-cli`). +Cada entrada é indexada por um **id de provedor** (por exemplo, `codex-cli`, `my-cli`). O id do provedor se torna o lado esquerdo da sua referência de modelo: ``` @@ -148,67 +148,79 @@ O id do provedor se torna o lado esquerdo da sua referência de modelo: ## Como funciona 1. **Seleciona um backend** com base no prefixo do provedor (`codex-cli/...`). -2. **Monta um prompt de sistema** usando o mesmo prompt + contexto de espaço de trabalho do OpenClaw. -3. **Executa a CLI** com um id de sessão (se compatível) para que o histórico permaneça consistente. - O backend integrado `claude-cli` mantém um processo stdio do Claude vivo por - sessão OpenClaw e envia turnos de continuação pelo stdin stream-json. +2. **Constrói um prompt de sistema** usando o mesmo prompt do OpenClaw + contexto do workspace. +3. **Executa a CLI** com um id de sessão (se compatível), para que o histórico permaneça consistente. + O backend empacotado `claude-cli` mantém um processo stdio do Claude vivo por + sessão do OpenClaw e envia interações de continuação pelo stdin stream-json. 4. **Analisa a saída** (JSON ou texto simples) e retorna o texto final. -5. **Persiste ids de sessão** por backend, para que continuações reutilizem a mesma sessão da CLI. +5. **Persiste ids de sessão** por backend, para que as continuações reutilizem a mesma sessão da CLI. -O backend integrado Anthropic `claude-cli` voltou a ser compatível. A equipe da Anthropic +O backend empacotado Anthropic `claude-cli` voltou a ser suportado. A equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw voltou a ser permitido, então o OpenClaw trata o uso de `claude -p` como autorizado para essa integração, a menos que a Anthropic publique uma nova política. -O backend integrado OpenAI `codex-cli` passa o prompt de sistema do OpenClaw via -substituição de configuração `model_instructions_file` do Codex (`-c +O backend empacotado OpenAI `codex-cli` passa o prompt de sistema do OpenClaw por meio +da substituição de configuração `model_instructions_file` do Codex (`-c model_instructions_file="..."`). O Codex não expõe uma flag no estilo Claude `--append-system-prompt`, então o OpenClaw grava o prompt montado em um arquivo temporário para cada nova sessão do Codex CLI. -O backend integrado Anthropic `claude-cli` recebe o snapshot de Skills do OpenClaw -de duas formas: o catálogo compacto de Skills do OpenClaw no prompt de sistema anexado e -um plugin temporário do Claude Code passado com `--plugin-dir`. O plugin contém -apenas as Skills elegíveis para aquele agent/sessão, de modo que o resolvedor nativo de Skills do Claude Code -vê o mesmo conjunto filtrado que o OpenClaw anunciaria no prompt. Substituições de env/chave de API -de Skill ainda são aplicadas pelo OpenClaw ao ambiente do processo filho durante a execução. +O backend empacotado Anthropic `claude-cli` recebe o snapshot de Skills do OpenClaw +de duas formas: o catálogo compacto de Skills do OpenClaw no prompt de sistema anexado, e +um Plugin temporário do Claude Code passado com `--plugin-dir`. O Plugin contém +apenas as Skills elegíveis para aquele agente/sessão, para que o resolvedor nativo de Skills do Claude Code +veja o mesmo conjunto filtrado que o OpenClaw anunciaria no prompt. As substituições de env/chave de API de Skill +ainda são aplicadas pelo OpenClaw ao ambiente do processo filho para a execução. + +Antes que o OpenClaw possa usar o backend empacotado `claude-cli`, o próprio Claude Code +já deve estar autenticado no mesmo host: + +```bash +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Use `agents.defaults.cliBackends.claude-cli.command` apenas quando o binário `claude` +ainda não estiver no `PATH`. ## Sessões -- Se a CLI for compatível com sessões, defina `sessionArg` (por exemplo `--session-id`) ou +- Se a CLI oferecer suporte a sessões, defina `sessionArg` (por exemplo, `--session-id`) ou `sessionArgs` (placeholder `{sessionId}`) quando o ID precisar ser inserido - em várias flags. + em múltiplas flags. - Se a CLI usar um **subcomando de retomada** com flags diferentes, defina - `resumeArgs` (substitui `args` ao retomar) e opcionalmente `resumeOutput` - (para retomadas não JSON). + `resumeArgs` (substitui `args` ao retomar) e, opcionalmente, `resumeOutput` + (para retomadas que não usam JSON). - `sessionMode`: - - `always`: sempre envia um id de sessão (novo UUID se nenhum estiver armazenado). - - `existing`: envia um id de sessão somente se um já tiver sido armazenado antes. + - `always`: sempre envia um id de sessão (um novo UUID se não houver nenhum armazenado). + - `existing`: só envia um id de sessão se um já tiver sido armazenado antes. - `none`: nunca envia um id de sessão. -- `claude-cli` usa como padrão `liveSession: "claude-stdio"`, `output: "jsonl"` - e `input: "stdin"` para que turnos de continuação reutilizem o processo Claude ativo enquanto +- `claude-cli` usa por padrão `liveSession: "claude-stdio"`, `output: "jsonl"`, + e `input: "stdin"` para que interações de continuação reutilizem o processo Claude ativo enquanto ele estiver ativo. stdio aquecido agora é o padrão, inclusive para configurações personalizadas que omitem campos de transporte. Se o Gateway reiniciar ou o processo ocioso - encerrar, o OpenClaw retoma a partir do id de sessão Claude armazenado. Ids de sessão - armazenados são verificados em relação a uma transcrição de projeto existente e legível antes da - retomada, de modo que vinculações fantasmas são limpas com `reason=transcript-missing` - em vez de iniciar silenciosamente uma nova sessão do Claude CLI sob `--resume`. -- Sessões de CLI armazenadas são continuidade controlada pelo provedor. A redefinição implícita - diária de sessão não as interrompe; `/reset` e políticas explícitas de `session.reset` ainda interrompem. + encerrar, o OpenClaw retoma a partir do id de sessão do Claude armazenado. Os ids de sessão armazenados + são verificados em relação a uma transcrição de projeto existente e legível antes da + retomada, então vínculos fantasmas são limpos com `reason=transcript-missing` + em vez de iniciar silenciosamente uma nova sessão do Claude CLI com `--resume`. +- Sessões de CLI armazenadas são continuidade pertencente ao provedor. A redefinição implícita diária da sessão + não as interrompe; `/reset` e políticas explícitas de `session.reset` ainda interrompem. Observações sobre serialização: -- `serialize: true` mantém execuções da mesma lane em ordem. -- A maioria das CLIs serializa em uma lane de provedor. -- O OpenClaw abandona a reutilização da sessão de CLI armazenada quando a identidade de autenticação selecionada muda, - incluindo mudança de id de perfil de autenticação, chave de API estática, token estático ou identidade - de conta OAuth quando a CLI a expõe. Rotação de token de acesso e refresh OAuth +- `serialize: true` mantém as execuções da mesma faixa em ordem. +- A maioria das CLIs serializa em uma faixa de provedor. +- O OpenClaw descarta a reutilização de sessão de CLI armazenada quando a identidade de autenticação selecionada muda, + incluindo um id de perfil de autenticação alterado, chave de API estática alterada, token estático alterado ou + identidade de conta OAuth alterada quando a CLI expõe uma. A rotação de token de acesso e de atualização OAuth não interrompe a sessão de CLI armazenada. Se uma CLI não expõe um id de conta OAuth estável, - o OpenClaw deixa essa CLI impor permissões de retomada. + o OpenClaw permite que essa CLI imponha as permissões de retomada. -## Imagens (pass-through) +## Imagens (repasse) Se a sua CLI aceitar caminhos de imagem, defina `imageArg`: @@ -218,17 +230,17 @@ imageMode: "repeat" ``` O OpenClaw gravará imagens base64 em arquivos temporários. Se `imageArg` estiver definido, esses -caminhos serão passados como argumentos da CLI. Se `imageArg` estiver ausente, o OpenClaw acrescenta os -caminhos dos arquivos ao prompt (injeção de caminho), o que basta para CLIs que carregam -arquivos locais automaticamente a partir de caminhos simples. +caminhos serão passados como argumentos da CLI. Se `imageArg` estiver ausente, o OpenClaw acrescentará os +caminhos dos arquivos ao prompt (injeção de caminho), o que é suficiente para CLIs que carregam +automaticamente arquivos locais a partir de caminhos simples. ## Entradas / saídas - `output: "json"` (padrão) tenta analisar JSON e extrair texto + id de sessão. -- Para saída JSON da Gemini CLI, o OpenClaw lê o texto da resposta de `response` e - o uso de `stats` quando `usage` estiver ausente ou vazio. -- `output: "jsonl"` analisa streams JSONL (por exemplo Codex CLI `--json`) e extrai a mensagem final do agent mais identificadores de sessão - quando presentes. +- Para saída JSON do Gemini CLI, o OpenClaw lê o texto da resposta de `response` e + uso de `stats` quando `usage` está ausente ou vazio. +- `output: "jsonl"` analisa streams JSONL (por exemplo, Codex CLI `--json`) e extrai a mensagem final do agente mais + identificadores de sessão quando presentes. - `output: "text"` trata stdout como a resposta final. Modos de entrada: @@ -237,9 +249,9 @@ Modos de entrada: - `input: "stdin"` envia o prompt via stdin. - Se o prompt for muito longo e `maxPromptArgChars` estiver definido, stdin será usado. -## Padrões (controlados por plugin) +## Padrões (pertencentes ao Plugin) -O plugin OpenAI integrado também registra um padrão para `codex-cli`: +O Plugin OpenAI empacotado também registra um padrão para `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -250,7 +262,7 @@ O plugin OpenAI integrado também registra um padrão para `codex-cli`: - `imageArg: "--image"` - `sessionMode: "existing"` -O plugin Google integrado também registra um padrão para `google-gemini-cli`: +O Plugin Google empacotado também registra um padrão para `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -265,28 +277,28 @@ Pré-requisito: a Gemini CLI local deve estar instalada e disponível como `gemini` no `PATH` (`brew install gemini-cli` ou `npm install -g @google/gemini-cli`). -Observações sobre JSON da Gemini CLI: +Observações sobre o JSON do Gemini CLI: - O texto da resposta é lido do campo JSON `response`. -- O uso recorre a `stats` quando `usage` estiver ausente ou vazio. -- `stats.cached` é normalizado para `cacheRead` do OpenClaw. +- O uso recorre a `stats` quando `usage` está ausente ou vazio. +- `stats.cached` é normalizado em `cacheRead` do OpenClaw. - Se `stats.input` estiver ausente, o OpenClaw deriva tokens de entrada de `stats.input_tokens - stats.cached`. -Substitua apenas se necessário (comum: caminho `command` absoluto). +Substitua apenas se necessário (comum: caminho absoluto de `command`). -## Padrões controlados por plugin +## Padrões pertencentes ao Plugin -Os padrões de backend de CLI agora fazem parte da superfície de plugin: +Os padrões de backend de CLI agora fazem parte da superfície do Plugin: -- Plugins os registram com `api.registerCliBackend(...)`. -- O `id` do backend se torna o prefixo do provedor em referências de modelo. -- A configuração do usuário em `agents.defaults.cliBackends.` ainda substitui o padrão do plugin. -- A limpeza de configuração específica do backend continua sendo responsabilidade do plugin por meio do hook opcional - `normalizeConfig`. +- Os Plugins os registram com `api.registerCliBackend(...)`. +- O `id` do backend se torna o prefixo do provedor nas referências de modelo. +- A configuração do usuário em `agents.defaults.cliBackends.` ainda substitui o padrão do Plugin. +- A limpeza de configuração específica do backend continua pertencendo ao Plugin por meio do hook + opcional `normalizeConfig`. -Plugins que precisam de pequenos shims de compatibilidade de prompt/mensagem podem declarar -transformações bidirecionais de texto sem substituir um provedor ou backend de CLI: +Plugins que precisem de pequenos shims de compatibilidade de prompt/mensagem podem declarar +transformações de texto bidirecionais sem substituir um provedor ou backend de CLI: ```typescript api.registerTextTransforms({ @@ -303,52 +315,52 @@ api.registerTextTransforms({ }); ``` -`input` reescreve o prompt de sistema e o prompt do usuário passados para a CLI. `output` -reescreve deltas em streaming do assistente e o texto final analisado antes que o OpenClaw trate seus -próprios marcadores de controle e a entrega por canal. +`input` reescreve o prompt de sistema e o prompt do usuário passados à CLI. `output` +reescreve deltas transmitidos do assistente e o texto final analisado antes de o OpenClaw processar +seus próprios marcadores de controle e a entrega no canal. -Para CLIs que emitem JSONL compatível com stream-json do Claude Code, defina +Para CLIs que emitem JSONL compatível com o stream-json do Claude Code, defina `jsonlDialect: "claude-stream-json"` na configuração desse backend. -## Overlays MCP de bundle +## Overlays MCP empacotados -Backends de CLI **não** recebem chamadas de ferramenta do OpenClaw diretamente, mas um backend pode -optar por um overlay de configuração MCP gerado com `bundleMcp: true`. +Os backends de CLI **não** recebem chamadas de ferramenta do OpenClaw diretamente, mas um backend pode +optar por uma sobreposição de configuração MCP gerada com `bundleMcp: true`. -Comportamento integrado atual: +Comportamento empacotado atual: - `claude-cli`: arquivo de configuração MCP estrito gerado - `codex-cli`: substituições de configuração inline para `mcp_servers` - `google-gemini-cli`: arquivo gerado de configurações de sistema do Gemini -Quando o bundle MCP está habilitado, o OpenClaw: +Quando o MCP empacotado está habilitado, o OpenClaw: -- inicia um servidor MCP HTTP loopback que expõe ferramentas do Gateway ao processo da CLI -- autentica a bridge com um token por sessão (`OPENCLAW_MCP_TOKEN`) -- limita o acesso às ferramentas ao contexto atual de sessão, conta e canal -- carrega os servidores MCP de bundle habilitados para o espaço de trabalho atual -- os mescla com qualquer formato existente de configuração/settings MCP do backend -- reescreve a configuração de inicialização usando o modo de integração controlado pelo backend da extensão responsável +- inicia um servidor MCP HTTP de loopback que expõe ferramentas do Gateway ao processo da CLI +- autentica a ponte com um token por sessão (`OPENCLAW_MCP_TOKEN`) +- limita o acesso às ferramentas à sessão, conta e contexto de canal atuais +- carrega servidores bundle-MCP habilitados para o workspace atual +- mescla isso com qualquer formato existente de configuração/ajustes MCP do backend +- reescreve a configuração de inicialização usando o modo de integração pertencente ao backend da extensão proprietária Se nenhum servidor MCP estiver habilitado, o OpenClaw ainda injeta uma configuração estrita quando um -backend opta por bundle MCP para que execuções em segundo plano permaneçam isoladas. +backend opta por MCP empacotado para que execuções em segundo plano permaneçam isoladas. ## Limitações -- **Sem chamadas diretas de ferramentas do OpenClaw.** O OpenClaw não injeta chamadas de ferramenta no - protocolo do backend de CLI. Backends só veem ferramentas do Gateway quando optam por +- **Sem chamadas diretas de ferramenta do OpenClaw.** O OpenClaw não injeta chamadas de ferramenta no + protocolo do backend de CLI. Os backends só veem ferramentas do Gateway quando optam por `bundleMcp: true`. -- **O streaming é específico do backend.** Alguns backends fazem streaming em JSONL; outros fazem buffer - até a saída. +- **O streaming é específico do backend.** Alguns backends fazem streaming em JSONL; outros acumulam + até encerrar. - **Saídas estruturadas** dependem do formato JSON da CLI. -- **Sessões do Codex CLI** são retomadas via saída em texto (sem JSONL), o que é menos +- **Sessões do Codex CLI** retomam via saída de texto (sem JSONL), o que é menos estruturado do que a execução inicial com `--json`. As sessões do OpenClaw ainda funcionam normalmente. ## Solução de problemas -- **CLI não encontrada**: defina `command` como um caminho completo. +- **CLI não encontrada**: defina `command` com um caminho completo. - **Nome de modelo incorreto**: use `modelAliases` para mapear `provider/model` → modelo da CLI. -- **Sem continuidade de sessão**: confirme que `sessionArg` está definido e que `sessionMode` não é - `none` (o Codex CLI atualmente não consegue retomar com saída JSON). -- **Imagens ignoradas**: defina `imageArg` (e confirme que a CLI oferece suporte a caminhos de arquivo). +- **Sem continuidade de sessão**: verifique se `sessionArg` está definido e se `sessionMode` não é + `none` (atualmente, o Codex CLI não pode retomar com saída JSON). +- **Imagens ignoradas**: defina `imageArg` (e verifique se a CLI oferece suporte a caminhos de arquivo). diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md index da0fb7e3f..bab192866 100644 --- a/docs/pt-BR/help/testing.md +++ b/docs/pt-BR/help/testing.md @@ -1,27 +1,27 @@ --- read_when: - - Executando testes localmente ou no CI - - Adicionando testes de regressão para bugs de modelo/provedor - - Depurando comportamento do Gateway + agente + - Executar testes localmente ou no CI + - Adicionar regressões para bugs de modelo/provedor + - Depurar o comportamento do Gateway + agent summary: 'Kit de testes: suítes unit/e2e/live, runners Docker e o que cada teste cobre' -title: Testes +title: Teste x-i18n: - generated_at: "2026-04-23T14:03:38Z" + generated_at: "2026-04-23T14:55:09Z" model: gpt-5.4 provider: openai - source_hash: fe0e9bdea78cba7e512358d2e4d428da04a2071188e74af2d5419d2c85eafe15 + source_hash: fbec4996699577321116c94f60c01d205d7594ed41aca27c821f1c3d65a7dca3 source_path: help/testing.md workflow: 15 --- # Testes -O OpenClaw tem três suítes Vitest (unit/integration, e2e, live) e um pequeno conjunto de runners Docker. +O OpenClaw tem três suítes do Vitest (unit/integration, e2e, live) e um pequeno conjunto de runners Docker. Este documento é um guia de “como testamos”: -- O que cada suíte cobre (e o que deliberadamente _não_ cobre) -- Quais comandos executar em fluxos de trabalho comuns (local, antes de enviar, depuração) +- O que cada suíte cobre (e o que ela deliberadamente _não_ cobre) +- Quais comandos executar para fluxos de trabalho comuns (local, antes de dar push, depuração) - Como os testes live descobrem credenciais e selecionam modelos/provedores - Como adicionar regressões para problemas reais de modelo/provedor @@ -29,145 +29,148 @@ Este documento é um guia de “como testamos”: Na maioria dos dias: -- Verificação completa (esperada antes de enviar): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Execução local mais rápida da suíte completa em uma máquina folgada: `pnpm test:max` +- Gate completo (esperado antes de dar push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Execução local mais rápida da suíte completa em uma máquina com bastante recurso: `pnpm test:max` - Loop direto de watch do Vitest: `pnpm test:watch` - O direcionamento direto por arquivo agora também encaminha caminhos de extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Prefira primeiro execuções direcionadas quando estiver iterando sobre uma única falha. -- Site de QA com Docker: `pnpm qa:lab:up` -- Faixa de QA com VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Prefira execuções direcionadas primeiro quando estiver iterando sobre uma única falha. +- Site de QA com suporte a Docker: `pnpm qa:lab:up` +- Lane de QA com suporte a VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando você altera testes ou quer mais confiança: +Quando você altera testes ou quer confiança extra: -- Verificação de cobertura: `pnpm test:coverage` +- Gate de cobertura: `pnpm test:coverage` - Suíte E2E: `pnpm test:e2e` -Ao depurar provedores/modelos reais (exige credenciais reais): +Ao depurar provedores/modelos reais (requer credenciais reais): - Suíte live (modelos + sondas de ferramenta/imagem do Gateway): `pnpm test:live` -- Direcionar silenciosamente um arquivo live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Direcione um arquivo live em silêncio: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Varredura live de modelos em Docker: `pnpm test:docker:live-models` - - Cobertura de CI: as execuções diárias `OpenClaw Scheduled Live And E2E Checks` e manuais - `OpenClaw Release Checks` chamam ambas o workflow reutilizável live/E2E com - `include_live_suites: true`, que inclui jobs separados da matriz live Docker + - Cada modelo selecionado agora executa um turno de texto mais uma pequena sonda no estilo leitura de arquivo. + Modelos cujos metadados anunciam entrada `image` também executam um pequeno turno de imagem. + Desative as sondas extras com `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` ou + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` ao isolar falhas do provedor. + - Cobertura no CI: as rotinas diárias `OpenClaw Scheduled Live And E2E Checks` e a manual + `OpenClaw Release Checks` chamam ambas o workflow reutilizável de live/E2E com + `include_live_suites: true`, que inclui jobs separados da matriz de modelos live em Docker fragmentados por provedor. - - Para novas execuções direcionadas de CI, dispare `OpenClaw Live And E2E Checks (Reusable)` + - Para reruns focados no CI, dispare `OpenClaw Live And E2E Checks (Reusable)` com `include_live_suites: true` e `live_models_only: true`. - - Adicione novos segredos de provedores de alto sinal a `scripts/ci-hydrate-live-auth.sh` - e também a `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` e seus - chamadores agendados/de release. -- Verificação de custo Moonshot/Kimi: com `MOONSHOT_API_KEY` definido, execute - `openclaw models list --provider moonshot --json` e depois execute um + - Adicione novos secrets de provedor de alto sinal a `scripts/ci-hydrate-live-auth.sh` + além de `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` e seus + chamadores de rotina agendada/release. +- Smoke de custo Moonshot/Kimi: com `MOONSHOT_API_KEY` definido, execute + `openclaw models list --provider moonshot --json`, depois execute um `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - isolado contra `moonshot/kimi-k2.6`. Verifique se o JSON informa Moonshot/K2.6 e se a - transcrição do assistente armazena `usage.cost` normalizado. + isolado contra `moonshot/kimi-k2.6`. Verifique se o JSON informa Moonshot/K2.6 e se o + transcript do assistente armazena `usage.cost` normalizado. -Dica: quando você só precisa de um caso com falha, prefira restringir os testes live pelas variáveis de ambiente de allowlist descritas abaixo. +Dica: quando você só precisa de um caso com falha, prefira restringir os testes live por meio das variáveis de ambiente de allowlist descritas abaixo. ## Runners específicos de QA Esses comandos ficam ao lado das suítes principais de teste quando você precisa do realismo do qa-lab: -O CI executa o QA Lab em workflows dedicados. `Parity gate` é executado em PRs correspondentes e -por acionamento manual com provedores simulados. `QA-Lab - All Lanes` é executado à noite em -`main` e por acionamento manual com a verificação de paridade simulada, a faixa Matrix live e a -faixa Telegram live gerenciada por Convex como jobs paralelos. `OpenClaw Release Checks` -executa as mesmas faixas antes da aprovação de release. +O CI executa o QA Lab em workflows dedicados. `Parity gate` roda em PRs correspondentes e +a partir de acionamento manual com provedores mockados. `QA-Lab - All Lanes` roda à noite na +`main` e a partir de acionamento manual com o gate de paridade mockado, a lane live do Matrix e a +lane live do Telegram gerenciada pelo Convex como jobs paralelos. `OpenClaw Release Checks` +executa as mesmas lanes antes da aprovação do release. - `pnpm openclaw qa suite` - - Executa cenários de QA respaldados pelo repositório diretamente no host. - - Executa vários cenários selecionados em paralelo por padrão com workers - isolados do gateway. `qa-channel` usa concorrência 4 por padrão (limitada pela + - Executa cenários de QA com suporte ao repositório diretamente no host. + - Executa vários cenários selecionados em paralelo por padrão com workers do + Gateway isolados. `qa-channel` usa concorrência 4 por padrão (limitada pela contagem de cenários selecionados). Use `--concurrency ` para ajustar a - contagem de workers, ou `--concurrency 1` para a faixa serial antiga. + quantidade de workers, ou `--concurrency 1` para a antiga lane serial. - Sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando - quiser artefatos sem um código de saída com falha. + quiser artefatos sem um código de saída de falha. - Oferece suporte aos modos de provedor `live-frontier`, `mock-openai` e `aimock`. - `aimock` inicia um servidor local de provedor respaldado por AIMock para cobertura experimental - de fixtures e mocks de protocolo sem substituir a faixa `mock-openai` - orientada por cenários. + `aimock` inicia um servidor de provedor local com suporte a AIMock para cobertura experimental + de fixtures e mocks de protocolo sem substituir a lane `mock-openai` orientada por cenários. - `pnpm openclaw qa suite --runner multipass` - Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável. - Mantém o mesmo comportamento de seleção de cenários de `qa suite` no host. - Reutiliza os mesmos sinalizadores de seleção de provedor/modelo de `qa suite`. - - Execuções live encaminham as entradas compatíveis de autenticação de QA que são práticas para o guest: + - Execuções live encaminham as entradas de autenticação de QA com suporte que são práticas para o guest: chaves de provedor baseadas em env, o caminho de configuração do provedor live de QA e `CODEX_HOME` quando presente. - - Diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta por meio + - Os diretórios de saída precisam permanecer sob a raiz do repositório para que o guest possa gravar de volta por meio do workspace montado. - - Grava o relatório + resumo normais de QA mais os logs do Multipass em + - Grava o relatório e resumo normais de QA, além dos logs do Multipass, em `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia o site de QA com Docker para trabalho de QA no estilo operador. + - Inicia o site de QA com suporte a Docker para trabalho de QA no estilo operador. - `pnpm test:docker:npm-onboard-channel-agent` - - Cria um tarball npm a partir do checkout atual, instala-o globalmente no - Docker, executa onboarding não interativo com chave de API da OpenAI, configura Telegram - por padrão, verifica se ativar o plugin instala dependências de runtime sob demanda, executa - doctor e executa um turno local de agente contra um endpoint OpenAI simulado. - - Use `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` para executar a mesma - faixa de instalação empacotada com Discord. + - Gera um tarball npm a partir do checkout atual, instala-o globalmente em + Docker, executa o onboarding não interativo com chave de API OpenAI, configura Telegram + por padrão, verifica se habilitar o plugin instala dependências de runtime sob demanda, + executa doctor e roda um turno de agent local contra um endpoint OpenAI mockado. + - Use `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` para executar a mesma lane de instalação empacotada + com Discord. - `pnpm test:docker:bundled-channel-deps` - - Empacota e instala a build atual do OpenClaw no Docker, inicia o Gateway - com OpenAI configurado e então ativa channel/plugins empacotados por meio - de edições de configuração. - - Verifica se a descoberta de configuração deixa ausentes as dependências de runtime de plugin não configuradas, - se a primeira execução configurada do Gateway ou doctor instala sob demanda as dependências de runtime de cada plugin empacotado - e se uma segunda reinicialização não reinstala dependências - que já foram ativadas. - - Também instala uma baseline npm antiga conhecida, ativa Telegram antes de executar - `openclaw update --tag ` e verifica se o - doctor pós-atualização do candidato repara dependências de runtime de canais empacotados sem um reparo pós-instalação do lado do harness. + - Empacota e instala a build atual do OpenClaw em Docker, inicia o Gateway + com OpenAI configurado, então habilita channels/plugins empacotados por meio de + edições de configuração. + - Verifica se a descoberta de setup mantém ausentes as dependências de runtime de plugins não configurados, + se a primeira execução configurada do Gateway ou do doctor instala sob demanda as dependências de runtime + de cada plugin empacotado e se um segundo reinício não reinstala dependências + que já haviam sido ativadas. + - Também instala uma baseline npm antiga conhecida, habilita Telegram antes de executar + `openclaw update --tag ` e verifica se o doctor pós-atualização do + candidato repara dependências de runtime de channels empacotados sem um reparo de postinstall + do lado do harness. - `pnpm openclaw qa aimock` - - Inicia apenas o servidor local de provedor AIMock para testes diretos - de fumaça do protocolo. + - Inicia apenas o servidor de provedor AIMock local para smoke tests diretos de protocolo. - `pnpm openclaw qa matrix` - - Executa a faixa de QA Matrix live contra um homeserver Tuwunel respaldado por Docker descartável. - - Este host de QA hoje é apenas para repositório/desenvolvimento. Instalações empacotadas do OpenClaw não incluem - `qa-lab`, portanto não expõem `openclaw qa`. - - Checkouts do repositório carregam o runner empacotado diretamente; nenhuma etapa separada - de instalação de plugin é necessária. - - Provisiona três usuários temporários do Matrix (`driver`, `sut`, `observer`) mais uma sala privada, então inicia um processo filho do gateway de QA com o plugin Matrix real como transporte do SUT. + - Executa a lane de QA live do Matrix contra um homeserver Tuwunel descartável com suporte a Docker. + - Este host de QA é apenas para repositório/desenvolvimento hoje. Instalações empacotadas do OpenClaw não incluem + `qa-lab`, então não expõem `openclaw qa`. + - Checkouts do repositório carregam o runner empacotado diretamente; não é necessário + um passo separado de instalação do plugin. + - Provisiona três usuários temporários do Matrix (`driver`, `sut`, `observer`) mais uma sala privada, depois inicia um processo filho de Gateway de QA com o plugin real do Matrix como transporte SUT. - Usa por padrão a imagem estável fixada do Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Substitua com `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando precisar testar outra imagem. - - O Matrix não expõe sinalizadores compartilhados de origem de credenciais porque a faixa provisiona usuários descartáveis localmente. - - Grava um relatório de QA Matrix, resumo, artefato de eventos observados e log combinado de saída stdout/stderr em `.artifacts/qa-e2e/...`. + - O Matrix não expõe sinalizadores compartilhados de fonte de credenciais porque a lane provisiona usuários descartáveis localmente. + - Grava um relatório de QA do Matrix, resumo, artefato de eventos observados e log combinado de stdout/stderr em `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Executa a faixa de QA Telegram live contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do env. - - Exige `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. O id do grupo deve ser o id numérico do chat do Telegram. + - Executa a lane de QA live do Telegram contra um grupo privado real usando os tokens dos bots driver e SUT a partir do env. + - Requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. O id do grupo deve ser o id numérico do chat do Telegram. - Oferece suporte a `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases em pool. - Sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando - quiser artefatos sem um código de saída com falha. - - Exige dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário do Telegram. - - Para observação estável de bot para bot, ative Bot-to-Bot Communication Mode em `@BotFather` para ambos os bots e garanta que o bot driver consiga observar o tráfego de bots no grupo. - - Grava um relatório de QA Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. Cenários de resposta incluem RTT desde a solicitação de envio do driver até a resposta observada do SUT. + quiser artefatos sem um código de saída de falha. + - Requer dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário do Telegram. + - Para observação estável de bot para bot, habilite o modo Bot-to-Bot Communication Mode no `@BotFather` para ambos os bots e garanta que o bot driver possa observar o tráfego de bots no grupo. + - Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. Cenários com resposta incluem RTT desde a requisição de envio do driver até a resposta observada do SUT. -As faixas de transporte live compartilham um contrato padrão para que novos transportes não sofram desvio: +As lanes de transporte live compartilham um contrato padrão para que novos transportes não se desviem: -`qa-channel` continua sendo a suíte ampla de QA sintética e não faz parte da matriz de cobertura de transporte live. +`qa-channel` continua sendo a ampla suíte sintética de QA e não faz parte da matriz de cobertura de transporte live. -| Faixa | Canary | Exigência de menção | Bloqueio por allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | -| -------- | ------ | ------------------- | ---------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Bloqueio por menção | Bloco de allowlist | Resposta de nível superior | Retomada após reinício | Continuação na thread | Isolamento de thread | Observação de reação | Comando help | +| -------- | ------ | ------------------- | ------------------ | -------------------------- | ---------------------- | --------------------- | -------------------- | -------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenciais compartilhadas do Telegram via Convex (v1) -Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está ativado para -`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool respaldado por Convex, envia Heartbeat -desse lease enquanto a faixa está em execução e libera o lease no encerramento. +Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para +`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool com suporte a Convex, envia Heartbeat +desse lease enquanto a lane está em execução e libera o lease ao encerrar. -Estrutura de projeto Convex de referência: +Estrutura de referência do projeto Convex: - `qa/convex-credential-broker/` Variáveis de ambiente obrigatórias: - `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo `https://your-deployment.convex.site`) -- Um segredo para a função selecionada: +- Um secret para a função selecionada: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` para `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` - Seleção da função de credencial: - CLI: `--credential-role maintainer|ci` - - Padrão por env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `ci` no CI, `maintainer` caso contrário) + - Padrão por env: `OPENCLAW_QA_CREDENTIAL_ROLE` (usa `ci` por padrão no CI, `maintainer` caso contrário) Variáveis de ambiente opcionais: @@ -177,14 +180,14 @@ Variáveis de ambiente opcionais: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (padrão `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (padrão `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreamento opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento somente local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback apenas para desenvolvimento local. `OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` em operação normal. -Comandos administrativos de mantenedor (adicionar/remover/listar pool) exigem +Os comandos administrativos do maintainer (adicionar/remover/listar pool) exigem `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` especificamente. -Helpers de CLI para mantenedores: +Helpers de CLI para maintainers: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -194,46 +197,46 @@ pnpm openclaw qa credentials remove --credential-id Use `--json` para saída legível por máquina em scripts e utilitários de CI. -Contrato de endpoint padrão (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Contrato padrão do endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - - Solicitação: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` + - Requisição: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Sucesso: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - Esgotado/tentável novamente: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - - Solicitação: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` + - Requisição: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) - `POST /release` - - Solicitação: `{ kind, ownerId, actorRole, credentialId, leaseToken }` + - Requisição: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) -- `POST /admin/add` (somente segredo de mantenedor) - - Solicitação: `{ kind, actorId, payload, note?, status? }` +- `POST /admin/add` (somente secret de maintainer) + - Requisição: `{ kind, actorId, payload, note?, status? }` - Sucesso: `{ status: "ok", credential }` -- `POST /admin/remove` (somente segredo de mantenedor) - - Solicitação: `{ credentialId, actorId }` +- `POST /admin/remove` (somente secret de maintainer) + - Requisição: `{ credentialId, actorId }` - Sucesso: `{ status: "ok", changed, credential }` - - Proteção contra lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (somente segredo de mantenedor) - - Solicitação: `{ kind?, status?, includePayload?, limit? }` + - Proteção de lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (somente secret de maintainer) + - Requisição: `{ kind?, status?, includePayload?, limit? }` - Sucesso: `{ status: "ok", credentials, count }` -Formato da carga para o tipo Telegram: +Formato de payload para o tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` deve ser uma string com o id numérico do chat do Telegram. -- `admin/add` valida esse formato para `kind: "telegram"` e rejeita cargas malformadas. +- `groupId` deve ser uma string numérica de id de chat do Telegram. +- `admin/add` valida esse formato para `kind: "telegram"` e rejeita payloads malformados. -### Adicionar um canal ao QA +### Adicionar um channel ao QA -Adicionar um canal ao sistema de QA em Markdown exige exatamente duas coisas: +Adicionar um channel ao sistema de QA em Markdown requer exatamente duas coisas: -1. Um adaptador de transporte para o canal. -2. Um pacote de cenários que exercite o contrato do canal. +1. Um adaptador de transporte para o channel. +2. Um pacote de cenários que exercite o contrato do channel. -Não adicione uma nova raiz de comando QA de nível superior quando o host compartilhado `qa-lab` puder -ser o responsável pelo fluxo. +Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder +ser dono do fluxo. -`qa-lab` é responsável pela mecânica compartilhada do host: +`qa-lab` é dono da mecânica compartilhada do host: - a raiz de comando `openclaw qa` - inicialização e encerramento da suíte @@ -243,37 +246,37 @@ ser o responsável pelo fluxo. - execução de cenários - aliases de compatibilidade para cenários antigos de `qa-channel` -Plugins de runner são responsáveis pelo contrato de transporte: +Os plugins de runner são donos do contrato de transporte: - como `openclaw qa ` é montado sob a raiz compartilhada `qa` -- como o gateway é configurado para esse transporte +- como o Gateway é configurado para esse transporte - como a prontidão é verificada - como eventos de entrada são injetados - como mensagens de saída são observadas -- como transcrições e o estado normalizado do transporte são expostos -- como ações respaldadas por transporte são executadas +- como transcripts e o estado normalizado do transporte são expostos +- como ações com suporte do transporte são executadas - como reset ou limpeza específicos do transporte são tratados -A barra mínima de adoção para um novo canal é: +A barra mínima de adoção para um novo channel é: -1. Manter `qa-lab` como responsável pela raiz compartilhada `qa`. -2. Implementar o runner de transporte na costura compartilhada de host do `qa-lab`. -3. Manter a mecânica específica do transporte dentro do plugin de runner ou do harness do canal. +1. Manter `qa-lab` como dono da raiz compartilhada `qa`. +2. Implementar o runner de transporte na interface compartilhada de host `qa-lab`. +3. Manter a mecânica específica do transporte dentro do plugin de runner ou do harness do channel. 4. Montar o runner como `openclaw qa ` em vez de registrar uma raiz de comando concorrente. - Plugins de runner devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array correspondente `qaRunnerCliRegistrations` de `runtime-api.ts`. - Mantenha `runtime-api.ts` leve; a CLI lazy e a execução do runner devem ficar atrás de entrypoints separados. + Os plugins de runner devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array correspondente `qaRunnerCliRegistrations` de `runtime-api.ts`. + Mantenha `runtime-api.ts` leve; CLI lazy e execução do runner devem ficar atrás de entrypoints separados. 5. Criar ou adaptar cenários em Markdown nos diretórios temáticos `qa/scenarios/`. -6. Usar os helpers genéricos de cenário para novos cenários. -7. Manter aliases de compatibilidade existentes funcionando, a menos que o repositório esteja realizando uma migração intencional. +6. Usar os helpers genéricos de cenários para novos cenários. +7. Manter os aliases de compatibilidade existentes funcionando, a menos que o repositório esteja fazendo uma migração intencional. A regra de decisão é rígida: -- Se o comportamento puder ser expresso uma vez em `qa-lab`, coloque-o em `qa-lab`. -- Se o comportamento depender de um transporte de canal, mantenha-o nesse plugin de runner ou harness de plugin. -- Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um helper genérico em vez de um branch específico de canal em `suite.ts`. +- Se um comportamento puder ser expresso uma única vez em `qa-lab`, coloque-o em `qa-lab`. +- Se um comportamento depender de um transporte de channel, mantenha-o nesse plugin de runner ou harness de plugin. +- Se um cenário precisar de uma nova capacidade que mais de um channel possa usar, adicione um helper genérico em vez de um branch específico de channel em `suite.ts`. - Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico do transporte e deixe isso explícito no contrato do cenário. -Nomes preferidos de helpers genéricos para novos cenários são: +Os nomes preferidos de helpers genéricos para novos cenários são: - `waitForTransportReady` - `waitForChannelReady` @@ -288,7 +291,7 @@ Nomes preferidos de helpers genéricos para novos cenários são: - `formatTransportTranscript` - `resetTransport` -Aliases de compatibilidade continuam disponíveis para cenários existentes, incluindo: +Os aliases de compatibilidade continuam disponíveis para cenários existentes, incluindo: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -296,103 +299,103 @@ Aliases de compatibilidade continuam disponíveis para cenários existentes, inc - `formatConversationTranscript` - `resetBus` -Novo trabalho de canal deve usar os nomes genéricos de helper. -Aliases de compatibilidade existem para evitar uma migração em dia D, não como modelo para -autoria de novos cenários. +O trabalho em novos channels deve usar os nomes genéricos de helper. +Os aliases de compatibilidade existem para evitar uma migração em flag day, não como modelo para +a criação de novos cenários. ## Suítes de teste (o que executa onde) -Pense nas suítes como “realismo crescente” (e custo/instabilidade crescentes): +Pense nas suítes como “realismo crescente” (e aumento de instabilidade/custo): ### Unit / integration (padrão) - Comando: `pnpm test` -- Configuração: execuções não direcionadas usam o conjunto de shards `vitest.full-*.config.ts` e podem expandir shards de vários projetos em configs por projeto para agendamento paralelo -- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes node permitidos de `ui` cobertos por `vitest.unit.config.ts` +- Configuração: execuções sem alvo usam o conjunto de shards `vitest.full-*.config.ts` e podem expandir shards de múltiplos projetos em configurações por projeto para agendamento paralelo +- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes Node com allowlist em `ui` cobertos por `vitest.unit.config.ts` - Escopo: - - Testes de unidade puros - - Testes de integração no processo (autenticação do gateway, roteamento, ferramentas, parsing, configuração) + - Testes unitários puros + - Testes de integração in-process (auth do Gateway, roteamento, ferramentas, parsing, config) - Regressões determinísticas para bugs conhecidos - Expectativas: - Executa no CI - - Não exige chaves reais + - Não requer chaves reais - Deve ser rápido e estável - Observação sobre projetos: - - `pnpm test` não direcionado agora executa doze configs menores em shards (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante de projeto-raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que trabalho de auto-reply/extension sufoque suítes não relacionadas. - - `pnpm test --watch` ainda usa o grafo de projetos da raiz nativa `vitest.config.ts`, porque um loop de watch com vários shards não é prático. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` encaminham primeiro destinos explícitos de arquivo/diretório por faixas com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo total de inicialização do projeto-raiz. - - `pnpm test:changed` expande caminhos git alterados nas mesmas faixas com escopo quando o diff toca apenas arquivos de origem/teste roteáveis; edições de config/setup ainda usam fallback para a reexecução ampla do projeto-raiz. - - `pnpm check:changed` é a verificação local inteligente normal para trabalho restrito. Ela classifica o diff em core, testes core, extensions, testes de extension, apps, docs, metadados de release e tooling, e então executa as faixas correspondentes de typecheck/lint/teste. Mudanças no SDK público de Plugin e no contrato de plugin incluem validação de extensions porque as extensions dependem desses contratos centrais. Aumentos de versão apenas em metadados de release executam verificações direcionadas de versão/config/dependência-raiz em vez da suíte completa, com uma proteção que rejeita mudanças de pacote fora do campo de versão de nível superior. - - Testes de unidade leves de importação vindos de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas semelhantes de utilitário puro são encaminhados pela faixa `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com estado/runtime pesado permanecem nas faixas existentes. - - Arquivos helper selecionados de origem em `plugin-sdk` e `commands` também mapeiam execuções em modo de alteração para testes irmãos explícitos nessas faixas leves, de modo que edições em helpers evitem reexecutar toda a suíte pesada desse diretório. - - `auto-reply` agora tem três buckets dedicados: helpers principais de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token. -- Observação sobre embedded runner: - - Quando você altera entradas de descoberta de ferramentas de mensagem ou o contexto de runtime de Compaction, + - `pnpm test` sem alvo agora executa doze configurações de shard menores (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo nativo gigante de projeto raiz. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extensions prejudique suítes não relacionadas. + - `pnpm test --watch` ainda usa o grafo de projetos nativo da raiz em `vitest.config.ts`, porque um loop de watch com múltiplos shards não é prático. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` encaminham primeiro alvos explícitos de arquivo/diretório por lanes com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo total de inicialização do projeto raiz. + - `pnpm test:changed` expande caminhos git alterados nas mesmas lanes com escopo quando o diff toca apenas arquivos de origem/teste roteáveis; edições de config/setup ainda voltam para a reexecução ampla do projeto raiz. + - `pnpm check:changed` é o gate local inteligente normal para trabalho estreito. Ele classifica o diff em core, testes do core, extensions, testes de extension, apps, docs, metadados de release e tooling, então executa as lanes correspondentes de typecheck/lint/test. Alterações no SDK público de Plugin e no contrato de plugin incluem validação de extensions porque extensions dependem desses contratos do core. Aumentos de versão apenas em metadados de release executam verificações direcionadas de versão/config/dependências raiz em vez da suíte completa, com uma proteção que rejeita alterações de pacote fora do campo de versão de nível superior. + - Testes unitários leves de importação de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas semelhantes de utilidades puras passam pela lane `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com muito estado/runtime permanecem nas lanes existentes. + - Arquivos helper de origem selecionados de `plugin-sdk` e `commands` também mapeiam execuções em modo changed para testes irmãos explícitos nessas lanes leves, para que edições em helpers evitem rerodar a suíte pesada completa daquele diretório. + - `auto-reply` agora tem três buckets dedicados: helpers do core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token. +- Observação sobre runner embutido: + - Ao alterar entradas de descoberta de ferramentas de mensagem ou o contexto de runtime de Compaction, mantenha ambos os níveis de cobertura. - - Adicione regressões focadas de helpers para limites puros de roteamento/normalização. - - Também mantenha saudáveis as suítes de integração do embedded runner: + - Adicione regressões de helper focadas para limites puros de roteamento/normalização. + - Também mantenha saudáveis as suítes de integração do runner embutido: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Essas suítes verificam se ids com escopo e o comportamento de Compaction continuam fluindo + - Essas suítes verificam que ids com escopo e o comportamento de Compaction ainda fluem pelos caminhos reais `run.ts` / `compact.ts`; testes apenas de helper não são um substituto suficiente para esses caminhos de integração. - Observação sobre pool: - A configuração base do Vitest agora usa `threads` por padrão. - - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o runner não isolado em projetos-raiz, configs e2e e live. - - A faixa UI da raiz mantém sua configuração `jsdom` e otimizador, mas agora também executa no runner compartilhado não isolado. + - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o runner não isolado em todos os projetos da raiz, nas configurações e2e e live. + - A lane UI da raiz mantém sua configuração e otimizador `jsdom`, mas agora também roda no runner compartilhado não isolado. - Cada shard de `pnpm test` herda os mesmos padrões `threads` + `isolate: false` da configuração compartilhada do Vitest. - - O lançador compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão para processos filhos Node do Vitest a fim de reduzir churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. + - O launcher compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão aos processos Node filhos do Vitest para reduzir a rotatividade de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. - Observação sobre iteração local rápida: - - `pnpm changed:lanes` mostra quais faixas arquiteturais um diff aciona. - - O hook de pre-commit executa `pnpm check:changed --staged` após formatação/lint dos arquivos staged, então commits somente de core não pagam o custo de testes de extension, a menos que toquem contratos públicos voltados a extensions. Commits apenas de metadados de release permanecem na faixa direcionada de versão/config/dependência-raiz. - - Se o conjunto exato de alterações staged já foi validado com verificações equivalentes ou mais fortes, use `scripts/committer --fast "" ` para ignorar apenas a nova execução do hook de escopo alterado. Formatação/lint staged ainda executam. Mencione as verificações concluídas na sua passagem. Isso também é aceitável após uma falha instável isolada do hook ser reexecutada e passar com prova de escopo. - - `pnpm test:changed` encaminha por faixas com escopo quando os caminhos alterados mapeiam claramente para uma suíte menor. + - `pnpm changed:lanes` mostra quais lanes arquiteturais um diff aciona. + - O hook de pre-commit executa `pnpm check:changed --staged` após format/lint dos arquivos staged, então commits apenas de core não pagam o custo de testes de extension, a menos que toquem contratos públicos voltados a extensions. Commits apenas de metadados de release ficam na lane direcionada de versão/config/dependências raiz. + - Se o conjunto exato de alterações staged já foi validado com gates equivalentes ou mais fortes, use `scripts/committer --fast "" ` para pular apenas a rerun do hook com escopo changed. Format/lint dos arquivos staged ainda executam. Mencione os gates concluídos no seu handoff. Isso também é aceitável depois que uma falha isolada e instável do hook é rerodada e passa com prova de escopo. + - `pnpm test:changed` encaminha por lanes com escopo quando os caminhos alterados mapeiam claramente para uma suíte menor. - `pnpm test:max` e `pnpm test:changed:max` mantêm o mesmo comportamento de roteamento, apenas com um limite maior de workers. - - A autoescala local de workers agora é intencionalmente conservadora e também reduz quando a média de carga do host já está alta, então várias execuções simultâneas do Vitest causam menos danos por padrão. - - A configuração base do Vitest marca os arquivos de projetos/config como `forceRerunTriggers` para que reexecuções em modo de alteração permaneçam corretas quando o encadeamento de testes muda. - - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` ativado em hosts compatíveis; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local explícito de cache para profiling direto. -- Observação sobre depuração de desempenho: - - `pnpm test:perf:imports` ativa relatórios de duração de importação do Vitest mais saída de detalhamento de importações. - - `pnpm test:perf:imports:changed` aplica o mesmo profiling com escopo aos arquivos alterados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto-raiz para esse diff commitado e imprime tempo total mais RSS máximo no macOS. -- `pnpm test:perf:changed:bench -- --worktree` mede a árvore suja atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração raiz do Vitest. - - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para sobrecarga de inicialização e transformação do Vitest/Vite. - - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do runner para a suíte unit com paralelismo de arquivo desativado. + - O autoescalonamento local de workers agora é intencionalmente conservador e também reduz quando a média de carga do host já está alta, então várias execuções concorrentes do Vitest causam menos impacto por padrão. + - A configuração base do Vitest marca os arquivos de projetos/config como `forceRerunTriggers`, para que reruns no modo changed permaneçam corretos quando o wiring de testes muda. + - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado em hosts com suporte; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local de cache explícito para profiling direto. +- Observação sobre depuração de performance: + - `pnpm test:perf:imports` habilita relatórios de duração de importação do Vitest mais a saída de detalhamento de importação. + - `pnpm test:perf:imports:changed` limita a mesma visualização de profiling aos arquivos alterados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para esse diff commitado e imprime tempo total mais RSS máximo no macOS. +- `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore atual suja roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração raiz do Vitest. + - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para overhead de inicialização e transformação do Vitest/Vite. + - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do runner para a suíte unit com paralelismo por arquivo desabilitado. -### Estabilidade (gateway) +### Estabilidade (Gateway) - Comando: `pnpm test:stability:gateway` - Configuração: `vitest.gateway.config.ts`, forçada para um worker - Escopo: - - Inicia um Gateway real em loopback com diagnósticos ativados por padrão - - Conduz churn sintético de mensagem, memória e carga grande do gateway pelo caminho de evento de diagnóstico - - Consulta `diagnostics.stability` pelo RPC WS do Gateway - - Cobre helpers de persistência de bundle de estabilidade de diagnóstico - - Afirma que o registrador permanece limitado, amostras sintéticas de RSS ficam abaixo do orçamento de pressão e profundidades de fila por sessão drenam de volta para zero + - Inicia um Gateway loopback real com diagnósticos habilitados por padrão + - Envia rotatividade sintética de mensagens do gateway, memória e payload grande pelo caminho de evento de diagnóstico + - Consulta `diagnostics.stability` via WS RPC do Gateway + - Cobre helpers de persistência do bundle de estabilidade de diagnóstico + - Garante que o recorder permaneça limitado, que amostras sintéticas de RSS fiquem abaixo do orçamento de pressão e que as profundidades de fila por sessão drenem de volta para zero - Expectativas: - Seguro para CI e sem chaves - - Faixa estreita para acompanhamento de regressões de estabilidade, não substitui a suíte completa do Gateway + - Lane estreita para acompanhamento de regressões de estabilidade, não um substituto para a suíte completa do Gateway -### E2E (smoke do gateway) +### E2E (smoke do Gateway) - Comando: `pnpm test:e2e` - Configuração: `vitest.e2e.config.ts` - Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` e testes E2E de plugins empacotados em `extensions/` - Padrões de runtime: - - Usa `threads` do Vitest com `isolate: false`, correspondendo ao restante do repositório. + - Usa `threads` do Vitest com `isolate: false`, em linha com o restante do repositório. - Usa workers adaptativos (CI: até 2, local: 1 por padrão). - - Executa em modo silencioso por padrão para reduzir overhead de E/S no console. + - Executa em modo silencioso por padrão para reduzir o overhead de I/O no console. - Substituições úteis: - - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16). - - `OPENCLAW_E2E_VERBOSE=1` para reativar saída detalhada no console. + - `OPENCLAW_E2E_WORKERS=` para forçar a quantidade de workers (limitada a 16). + - `OPENCLAW_E2E_VERBOSE=1` para reabilitar saída detalhada no console. - Escopo: - - Comportamento end-to-end do gateway com várias instâncias - - Superfícies WebSocket/HTTP, pareamento de Node e rede mais pesada + - Comportamento end-to-end de múltiplas instâncias do Gateway + - Superfícies WebSocket/HTTP, emparelhamento de Node e rede mais pesada - Expectativas: - - Executa no CI (quando ativado no pipeline) - - Não exige chaves reais - - Mais partes móveis que testes unitários (pode ser mais lento) + - Executa no CI (quando habilitado no pipeline) + - Não requer chaves reais + - Tem mais partes móveis do que testes unitários (pode ser mais lento) ### E2E: smoke do backend OpenShell @@ -401,14 +404,14 @@ Pense nas suítes como “realismo crescente” (e custo/instabilidade crescente - Escopo: - Inicia um Gateway OpenShell isolado no host via Docker - Cria um sandbox a partir de um Dockerfile local temporário - - Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` + execução SSH reais + - Exercita o backend OpenShell do OpenClaw por meio de `sandbox ssh-config` + execução SSH reais - Verifica o comportamento canônico remoto do sistema de arquivos por meio da bridge fs do sandbox - Expectativas: - - Somente por adesão explícita; não faz parte da execução padrão de `pnpm test:e2e` - - Exige uma CLI local `openshell` mais um daemon Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` isolados e então destrói o gateway e sandbox de teste + - Apenas opt-in; não faz parte da execução padrão de `pnpm test:e2e` + - Requer uma CLI local `openshell` e um daemon Docker funcional + - Usa `HOME` / `XDG_CONFIG_HOME` isolados, então destrói o Gateway de teste e o sandbox - Substituições úteis: - - `OPENCLAW_E2E_OPENSHELL=1` para ativar o teste ao executar manualmente a suíte e2e mais ampla + - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper ### Live (provedores reais + modelos reais) @@ -416,115 +419,115 @@ Pense nas suítes como “realismo crescente” (e custo/instabilidade crescente - Comando: `pnpm test:live` - Configuração: `vitest.live.config.ts` - Arquivos: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` e testes live de plugins empacotados em `extensions/` -- Padrão: **ativado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`) +- Padrão: **habilitado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`) - Escopo: - - “Esse provedor/modelo realmente funciona _hoje_ com credenciais reais?” - - Detecta mudanças de formato de provedor, peculiaridades de tool-calling, problemas de autenticação e comportamento de limite de taxa + - “Este provedor/modelo realmente funciona _hoje_ com credenciais reais?” + - Detectar mudanças de formato do provedor, peculiaridades de chamada de ferramenta, problemas de auth e comportamento de limite de taxa - Expectativas: - - Não é estável em CI por definição (redes reais, políticas reais de provedores, cotas, indisponibilidades) - - Custa dinheiro / consome limites de taxa + - Não é estável em CI por design (redes reais, políticas reais de provedores, cotas, indisponibilidades) + - Custa dinheiro / usa limites de taxa - Prefira executar subconjuntos restritos em vez de “tudo” -- Execuções live obtêm `~/.profile` para captar chaves de API ausentes. -- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/autenticação para uma home temporária de teste para que fixtures unit não mutem seu `~/.openclaw` real. -- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando você intencionalmente precisar que testes live usem seu diretório home real. -- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do gateway/ruído de Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser os logs completos de inicialização de volta. -- Rotação de chave de API (específica do provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou substituição por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. +- Execuções live carregam `~/.profile` para obter chaves de API ausentes. +- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para um home de teste temporário, para que fixtures unit não possam alterar seu `~/.openclaw` real. +- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando precisar intencionalmente que os testes live usem seu diretório home real. +- `pnpm test:live` agora usa por padrão um modo mais silencioso: ele mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do Gateway/conversas Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser recuperar os logs completos de inicialização. +- Rotação de chaves de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou substituição por live com `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. - Saída de progresso/Heartbeat: - - As suítes live agora emitem linhas de progresso em stderr para que chamadas longas de provedor mostrem atividade visível mesmo quando a captura de console do Vitest estiver silenciosa. - - `vitest.live.config.ts` desativa a interceptação de console do Vitest para que linhas de progresso de provedor/gateway sejam transmitidas imediatamente durante execuções live. + - As suítes live agora emitem linhas de progresso para stderr para que chamadas longas a provedores apareçam como ativas mesmo quando a captura de console do Vitest está silenciosa. + - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que linhas de progresso de provedor/Gateway sejam exibidas imediatamente durante execuções live. - Ajuste Heartbeat de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajuste Heartbeat de gateway/sonda com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Ajuste Heartbeat de Gateway/sonda com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Qual suíte devo executar? Use esta tabela de decisão: -- Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou muita coisa) -- Tocando rede do gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` -- Depurando “meu bot caiu” / falhas específicas de provedor / tool calling: execute um `pnpm test:live` restrito +- Ao editar lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou muita coisa) +- Ao tocar em rede do Gateway / protocolo WS / emparelhamento: adicione `pnpm test:e2e` +- Ao depurar “meu bot caiu” / falhas específicas de provedor / chamada de ferramenta: execute um `pnpm test:live` restrito -## Live: varredura de capacidades de Node Android +## Live: varredura de capacidades do Node Android - Teste: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **todos os comandos atualmente anunciados** por um Node Android conectado e afirmar o comportamento do contrato de comando. +- Objetivo: invocar **todos os comandos anunciados atualmente** por um Node Android conectado e validar o comportamento do contrato dos comandos. - Escopo: - - Configuração manual/pré-condicionada (a suíte não instala/executa/pareia o app). - - Validação `node.invoke` do gateway comando por comando para o Node Android selecionado. + - Configuração prévia/manual (a suíte não instala/executa/emparelha o app). + - Validação `node.invoke` do Gateway comando por comando para o Node Android selecionado. - Pré-configuração obrigatória: - - App Android já conectado + pareado ao gateway. + - App Android já conectado + emparelhado ao Gateway. - App mantido em primeiro plano. - - Permissões/consentimento de captura concedidos para capacidades que você espera que passem. -- Substituições de destino opcionais: + - Permissões/consentimento de captura concedidos para as capacidades que você espera que passem. +- Substituições opcionais de alvo: - `OPENCLAW_ANDROID_NODE_ID` ou `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detalhes completos de configuração do Android: [App Android](/pt-BR/platforms/android) +- Detalhes completos da configuração do Android: [App Android](/pt-BR/platforms/android) ## Live: smoke de modelo (chaves de perfil) Os testes live são divididos em duas camadas para que possamos isolar falhas: -- “Modelo direto” nos diz se o provedor/modelo consegue responder com a chave dada. -- “Smoke do gateway” nos diz se o pipeline completo gateway+agent funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox etc.). +- “Modelo direto” nos diz se o provedor/modelo consegue responder com aquela chave. +- “Smoke do Gateway” nos diz se todo o pipeline gateway+agent funciona para aquele modelo (sessões, histórico, ferramentas, política de sandbox etc.). -### Camada 1: conclusão direta de modelo (sem gateway) +### Camada 1: conclusão direta do modelo (sem Gateway) - Teste: `src/agents/models.profiles.live.test.ts` - Objetivo: - Enumerar modelos descobertos - Usar `getApiKeyForModel` para selecionar modelos para os quais você tem credenciais - Executar uma pequena conclusão por modelo (e regressões direcionadas quando necessário) -- Como ativar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se invocar Vitest diretamente) -- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário ela é ignorada para manter `pnpm test:live` focado no smoke do gateway +- Como habilitar: + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) +- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário ela é ignorada para manter `pnpm test:live` focado no smoke do Gateway - Como selecionar modelos: - - `OPENCLAW_LIVE_MODELS=modern` para executar a allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` é um alias para a allowlist moderna + - `OPENCLAW_LIVE_MODELS=modern` para executar a allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` é um alias para a allowlist modern - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por vírgulas) - - Varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. + - Varreduras modern/all usam por padrão um limite selecionado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura modern exaustiva ou um número positivo para um limite menor. - Como selecionar provedores: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por vírgulas) - De onde vêm as chaves: - - Por padrão: armazenamento de perfil e fallbacks de env - - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para impor **somente armazenamento de perfil** + - Por padrão: armazenamento de perfis e fallbacks por env + - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para impor **apenas armazenamento de perfis** - Por que isso existe: - - Separa “a API do provedor está quebrada / a chave é inválida” de “o pipeline do agente do gateway está quebrado” - - Contém regressões pequenas e isoladas (exemplo: replay de raciocínio do OpenAI Responses/Codex Responses + fluxos de tool-call) + - Separa “a API do provedor está quebrada / a chave é inválida” de “o pipeline do agent no Gateway está quebrado” + - Contém regressões pequenas e isoladas (exemplo: replay de raciocínio OpenAI Responses/Codex Responses + fluxos de chamada de ferramenta) -### Camada 2: smoke de Gateway + agente dev (o que `@openclaw` realmente faz) +### Camada 2: smoke do Gateway + agent dev (o que `@openclaw` realmente faz) - Teste: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - - Subir um gateway no processo + - Iniciar um Gateway in-process - Criar/aplicar patch em uma sessão `agent:dev:*` (substituição de modelo por execução) - - Iterar modelos com chaves e afirmar: + - Iterar modelos-com-chaves e garantir: - resposta “significativa” (sem ferramentas) - uma invocação real de ferramenta funciona (sonda de leitura) - - sondas extras opcionais de ferramenta (exec+read probe) - - caminhos de regressão OpenAI (somente tool-call → acompanhamento) continuam funcionando + - sondas extras opcionais de ferramenta (sonda exec+read) + - caminhos de regressão OpenAI (apenas chamada de ferramenta → continuação) continuam funcionando - Detalhes das sondas (para que você possa explicar falhas rapidamente): - - sonda `read`: o teste grava um arquivo nonce no workspace e pede que o agente o `read` e devolva o nonce. - - sonda `exec+read`: o teste pede que o agente grave um nonce em um arquivo temporário com `exec` e depois o `read` de volta. + - sonda `read`: o teste grava um arquivo nonce no workspace e pede ao agent para `read` esse arquivo e devolver o nonce. + - sonda `exec+read`: o teste pede ao agent para gravar um nonce via `exec` em um arquivo temporário e depois `read` esse arquivo. - sonda de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `. - Referência de implementação: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. -- Como ativar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se invocar Vitest diretamente) +- Como habilitar: + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) - Como selecionar modelos: - - Padrão: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` é um alias para a allowlist moderna + - Padrão: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` é um alias para a allowlist modern - Ou defina `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou lista separada por vírgulas) para restringir - - Varreduras modern/all do gateway usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. -- Como selecionar provedores (evitar “tudo via OpenRouter”): + - Varreduras modern/all do Gateway usam por padrão um limite selecionado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura modern exaustiva ou um número positivo para um limite menor. +- Como selecionar provedores (evite “tudo do OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por vírgulas) -- Sondas de ferramenta + imagem estão sempre ativadas neste teste live: - - sonda `read` + sonda `exec+read` (estresse de ferramenta) - - sonda de imagem executa quando o modelo anuncia suporte a entrada de imagem +- Sondas de ferramenta + imagem estão sempre ligadas neste teste live: + - sonda `read` + sonda `exec+read` (stress de ferramenta) + - a sonda de imagem executa quando o modelo anuncia suporte a entrada de imagem - Fluxo (alto nível): - O teste gera um PNG minúsculo com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`) - - Envia via `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - O Gateway faz parsing dos anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - O agente embutido encaminha uma mensagem multimodal do usuário para o modelo - - Afirmação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos) + - Envia por meio de `agent` `attachments: [{ mimeType: "image/png", content: "" }]` + - O Gateway faz parse dos anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - O agent embutido encaminha uma mensagem multimodal do usuário ao modelo + - Asserção: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos) Dica: para ver o que você pode testar na sua máquina (e os ids exatos `provider/model`), execute: @@ -536,23 +539,23 @@ openclaw models list --json ## Live: smoke de backend CLI (Claude, Codex, Gemini ou outras CLIs locais) - Teste: `src/gateway/gateway-cli-backend.live.test.ts` -- Objetivo: validar o pipeline Gateway + agente usando um backend CLI local, sem tocar na sua configuração padrão. -- Padrões de smoke específicos do backend ficam na definição `cli-backend.ts` da extension proprietária. -- Ativar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se invocar Vitest diretamente) +- Objetivo: validar o pipeline Gateway + agent usando um backend CLI local, sem tocar na sua config padrão. +- Os padrões de smoke específicos do backend ficam na definição `cli-backend.ts` da extension proprietária. +- Habilitar: + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Padrões: - Provedor/modelo padrão: `claude-cli/claude-sonnet-4-6` - - Comportamento de comando/args/imagem vem dos metadados do plugin proprietário do backend CLI. -- Substituições opcionais: + - O comportamento de comando/args/imagem vem dos metadados do plugin proprietário do backend CLI. +- Substituições (opcionais): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar um anexo de imagem real (os caminhos são injetados no prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivo de imagem como args da CLI em vez de injeção no prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivos de imagem como args da CLI em vez de injeção no prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) para controlar como args de imagem são passados quando `IMAGE_ARG` está definido. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar um segundo turno e validar o fluxo de retomada. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desativar a sonda padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina `1` para forçá-la quando o modelo selecionado oferecer suporte a um alvo de troca). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desabilitar a sonda padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina como `1` para forçá-la quando o modelo selecionado oferecer suporte a um alvo de troca). Exemplo: @@ -581,25 +584,25 @@ Observações: - O runner Docker fica em `scripts/test-live-cli-backend-docker.sh`. - Ele executa o smoke live do backend CLI dentro da imagem Docker do repositório como o usuário não root `node`. -- Resolve metadados de smoke da CLI a partir da extension proprietária e então instala o pacote CLI Linux correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável com cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` exige OAuth portátil de assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele comprova `claude -p` direto no Docker e depois executa dois turnos do backend CLI do Gateway sem preservar variáveis de ambiente de chave de API da Anthropic. Essa faixa de assinatura desativa por padrão as sondas Claude MCP/tool e imagem porque o Claude atualmente roteia uso de apps de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. -- O smoke live do backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem e depois chamada de ferramenta MCP `cron` verificada pela CLI do gateway. -- O smoke padrão do Claude também aplica patch na sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma anotação anterior. +- Ele resolve os metadados do smoke da CLI a partir da extension proprietária e depois instala o pacote CLI Linux correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável com cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` requer OAuth portátil da assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele prova `claude -p` direto no Docker e depois executa dois turnos do backend CLI do Gateway sem preservar variáveis de ambiente de chave de API da Anthropic. Essa lane de assinatura desabilita por padrão as sondas MCP/tool e de imagem do Claude porque o Claude atualmente roteia o uso de apps de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. +- O smoke live do backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem, depois chamada da ferramenta MCP `cron` verificada pela CLI do Gateway. +- O smoke padrão do Claude também aplica patch na sessão de Sonnet para Opus e verifica se a sessão retomada ainda lembra de uma anotação anterior. -## Live: smoke de vinculação ACP (`/acp spawn ... --bind here`) +## Live: smoke de bind ACP (`/acp spawn ... --bind here`) - Teste: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar o fluxo real de vinculação de conversa ACP com um agente ACP live: +- Objetivo: validar o fluxo real de bind de conversa ACP com um agent ACP live: - enviar `/acp spawn --bind here` - - vincular no local uma conversa sintética de canal de mensagem - - enviar um acompanhamento normal nessa mesma conversa - - verificar se o acompanhamento chega à transcrição da sessão ACP vinculada -- Ativar: + - vincular no lugar uma conversa sintética de canal de mensagem + - enviar uma continuação normal nessa mesma conversa + - verificar se a continuação chega ao transcript da sessão ACP vinculada +- Habilitar: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Padrões: - - Agentes ACP no Docker: `claude,codex,gemini` - - Agente ACP para `pnpm test:live ...` direto: `claude` + - Agents ACP em Docker: `claude,codex,gemini` + - Agent ACP para `pnpm test:live ...` direto: `claude` - Canal sintético: contexto de conversa no estilo DM do Slack - Backend ACP: `acpx` - Substituições: @@ -610,8 +613,8 @@ Observações: - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` - Observações: - - Essa faixa usa a superfície `chat.send` do gateway com campos sintéticos de rota de origem somente para admin para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro integrado de agentes do plugin embutido `acpx` para o agente de harness ACP selecionado. + - Essa lane usa a superfície `chat.send` do Gateway com campos sintéticos de rota de origem apenas para admin, para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro embutido de agents do plugin `acpx` selecionado para o agent de harness ACP. Exemplo: @@ -627,7 +630,7 @@ Receita Docker: pnpm test:docker:live-acp-bind ``` -Receitas Docker de agente único: +Receitas Docker de agent único: ```bash pnpm test:docker:live-acp-bind:claude @@ -635,38 +638,38 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Observações do Docker: +Observações sobre Docker: - O runner Docker fica em `scripts/test-live-acp-bind-docker.sh`. -- Por padrão, ele executa o smoke de vinculação ACP contra todos os agentes CLI live compatíveis em sequência: `claude`, `codex` e depois `gemini`. +- Por padrão, ele executa o smoke de bind ACP contra todos os agents CLI live suportados em sequência: `claude`, `codex`, depois `gemini`. - Use `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para restringir a matriz. -- Ele obtém `~/.profile`, prepara o material de autenticação CLI correspondente no contêiner, instala `acpx` em um prefixo npm gravável e então instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente. +- Ele carrega `~/.profile`, prepara no contêiner o material de auth da CLI correspondente, instala `acpx` em um prefixo npm gravável e então instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente. - Dentro do Docker, o runner define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que o acpx mantenha disponíveis para a CLI filha do harness as variáveis de ambiente do provedor vindas do profile carregado. -## Live: smoke do harness de app-server do Codex +## Live: smoke do harness app-server do Codex -- Objetivo: validar o harness do Codex controlado pelo plugin por meio do método normal - `agent` do gateway: +- Objetivo: validar o harness do Codex, de propriedade do plugin, pelo método + `agent` normal do Gateway: - carregar o plugin empacotado `codex` - selecionar `OPENCLAW_AGENT_RUNTIME=codex` - - enviar um primeiro turno de agente do gateway para `codex/gpt-5.4` + - enviar um primeiro turno do agent do Gateway para `codex/gpt-5.4` - enviar um segundo turno para a mesma sessão OpenClaw e verificar se a thread - do app-server pode ser retomada + do app-server consegue ser retomada - executar `/codex status` e `/codex models` pelo mesmo caminho de comando - do gateway - - opcionalmente executar duas sondas de shell elevadas revisadas pelo Guardian: um - comando benigno que deve ser aprovado e um upload de segredo falso que deve ser - negado para que o agente pergunte de volta + do Gateway + - opcionalmente executar duas sondas de shell escaladas e revisadas pelo Guardian: um comando benigno + que deve ser aprovado e um upload de secret falso que deve ser + negado para que o agent peça confirmação - Teste: `src/gateway/gateway-codex-harness.live.test.ts` -- Ativar: `OPENCLAW_LIVE_CODEX_HARNESS=1` +- Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modelo padrão: `codex/gpt-5.4` - Sonda opcional de imagem: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Sonda opcional de MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Sonda opcional do Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- O smoke define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness - quebrado do Codex não passe por fallback silencioso para PI. -- Autenticação: `OPENAI_API_KEY` do shell/profile, mais `~/.codex/auth.json` e `~/.codex/config.toml` - copiados opcionalmente +- O smoke define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness Codex + quebrado não passe silenciosamente por fallback para PI. +- Auth: `OPENAI_API_KEY` do shell/profile, além de opcionais + `~/.codex/auth.json` e `~/.codex/config.toml` copiados Receita local: @@ -687,32 +690,32 @@ source ~/.profile pnpm test:docker:live-codex-harness ``` -Observações do Docker: +Observações sobre Docker: - O runner Docker fica em `scripts/test-live-codex-harness-docker.sh`. -- Ele obtém o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de autenticação da CLI Codex +- Ele carrega o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de auth da CLI Codex quando presentes, instala `@openai/codex` em um prefixo npm montado e gravável, prepara a árvore de origem e então executa apenas o teste live do harness Codex. -- O Docker ativa por padrão as sondas de imagem, MCP/tool e Guardian. Defina +- O Docker habilita por padrão as sondas de imagem, MCP/tool e Guardian. Defina `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` ou `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` ou `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` quando precisar de uma execução de depuração mais restrita. -- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, correspondendo à configuração do - teste live para que fallback de `openai-codex/*` ou PI não esconda uma regressão +- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, em linha com a configuração do teste + live para que fallback para `openai-codex/*` ou PI não possa esconder uma regressão do harness Codex. ### Receitas live recomendadas -Allowlists restritas e explícitas são mais rápidas e menos instáveis: +Allowlists estreitas e explícitas são mais rápidas e menos instáveis: -- Modelo único, direto (sem gateway): +- Modelo único, direto (sem Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modelo único, smoke do gateway: +- Modelo único, smoke do Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling em vários provedores: +- Chamada de ferramenta em vários provedores: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Foco em Google (chave de API Gemini + Antigravity): @@ -722,34 +725,34 @@ Allowlists restritas e explícitas são mais rápidas e menos instáveis: Observações: - `google/...` usa a API Gemini (chave de API). -- `google-antigravity/...` usa a bridge OAuth Antigravity (endpoint de agente no estilo Cloud Code Assist). -- `google-gemini-cli/...` usa a CLI Gemini local na sua máquina (autenticação separada + peculiaridades de ferramentas). +- `google-antigravity/...` usa a ponte OAuth Antigravity (endpoint de agent no estilo Cloud Code Assist). +- `google-gemini-cli/...` usa a CLI local Gemini na sua máquina (auth separada + particularidades de tooling). - API Gemini vs CLI Gemini: - - API: o OpenClaw chama a API Gemini hospedada do Google por HTTP (autenticação por chave de API / profile); é isso que a maioria dos usuários quer dizer com “Gemini”. - - CLI: o OpenClaw executa um binário `gemini` local; ele tem sua própria autenticação e pode se comportar de forma diferente (streaming/suporte a ferramentas/desvio de versão). + - API: o OpenClaw chama a API Gemini hospedada do Google via HTTP (auth por chave de API / perfil); isso é o que a maioria dos usuários quer dizer com “Gemini”. + - CLI: o OpenClaw executa um binário local `gemini`; ele tem sua própria auth e pode se comportar de forma diferente (streaming/suporte a ferramentas/descompasso de versão). ## Live: matriz de modelos (o que cobrimos) -Não há uma “lista fixa de modelos de CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. +Não existe uma “lista fixa de modelos do CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. -### Conjunto smoke moderno (tool calling + imagem) +### Conjunto de smoke modern (chamada de ferramenta + imagem) Esta é a execução de “modelos comuns” que esperamos manter funcionando: -- OpenAI (não Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) +- OpenAI (não-Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (ou `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evite modelos antigos Gemini 2.x) +- Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evite modelos Gemini 2.x mais antigos) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` e `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Execute o smoke do gateway com ferramentas + imagem: +Execute o smoke do Gateway com ferramentas + imagem: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: tool calling (Read + Exec opcional) +### Baseline: chamada de ferramenta (Read + Exec opcional) -Escolha pelo menos um por família de provedores: +Escolha pelo menos um por família de provedor: - OpenAI: `openai/gpt-5.4` (ou `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (ou `anthropic/claude-sonnet-4-6`) @@ -760,27 +763,27 @@ Escolha pelo menos um por família de provedores: Cobertura adicional opcional (bom ter): - xAI: `xai/grok-4` (ou a mais recente disponível) -- Mistral: `mistral/`… (escolha um modelo com suporte a ferramentas que você tenha ativado) +- Mistral: `mistral/`… (escolha um modelo com capacidade de ferramentas que você tenha habilitado) - Cerebras: `cerebras/`… (se você tiver acesso) -- LM Studio: `lmstudio/`… (local; tool calling depende do modo da API) +- LM Studio: `lmstudio/`… (local; a chamada de ferramenta depende do modo da API) ### Visão: envio de imagem (anexo → mensagem multimodal) -Inclua pelo menos um modelo compatível com imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes do OpenAI com suporte a visão etc.) para exercitar a sonda de imagem. +Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes OpenAI com visão etc.) para exercitar a sonda de imagem. -### Agregadores / gateways alternativos +### Agregadores / Gateways alternativos -Se você tiver chaves ativadas, também oferecemos suporte a testes via: +Se você tiver chaves habilitadas, também oferecemos suporte a testes via: -- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com suporte a ferramentas + imagem) -- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (autenticação via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com capacidade de ferramenta+imagem) +- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (auth via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Mais provedores que você pode incluir na matriz live (se tiver credenciais/configuração): +Mais provedores que você pode incluir na matriz live (se tiver credenciais/config): - Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Via `models.providers` (endpoints personalizados): `minimax` (nuvem/API), mais qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.) +- Via `models.providers` (endpoints personalizados): `minimax` (cloud/API), além de qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.) -Dica: não tente codificar “todos os modelos” na documentação. A lista autoritativa é o que `discoverModels(...)` retorna na sua máquina + quaisquer chaves disponíveis. +Dica: não tente fixar “todos os modelos” na documentação. A lista autoritativa é aquilo que `discoverModels(...)` retorna na sua máquina + as chaves que estiverem disponíveis. ## Credenciais (nunca faça commit) @@ -789,32 +792,32 @@ Os testes live descobrem credenciais da mesma forma que a CLI. Implicações pr - Se a CLI funciona, os testes live devem encontrar as mesmas chaves. - Se um teste live disser “sem credenciais”, depure da mesma forma que você depuraria `openclaw models list` / seleção de modelo. -- Perfis de autenticação por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) -- Configuração: `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`) -- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para a home live preparada quando presente, mas não é o armazenamento principal de chaves de perfil) -- Execuções live locais copiam por padrão a configuração ativa, arquivos `auth-profiles.json` por agente, `credentials/` legado e diretórios de autenticação CLI externos compatíveis para uma home temporária de teste; homes live preparadas ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que as sondas não toquem seu workspace real do host. +- Perfis de auth por agent: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) +- Config: `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`) +- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para o home live preparado quando presente, mas não é o armazenamento principal de chaves de perfil) +- Execuções live locais copiam por padrão a config ativa, arquivos `auth-profiles.json` por agent, `credentials/` legados e diretórios de auth de CLI externa com suporte para um home de teste temporário; homes live preparados ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que as sondas não atinjam seu workspace real no host. -Se você quiser depender de chaves de env (por exemplo, exportadas no seu `~/.profile`), execute os testes locais após `source ~/.profile` ou use os runners Docker abaixo (eles podem montar `~/.profile` no contêiner). +Se quiser depender de chaves por env (por exemplo, exportadas em `~/.profile`), execute os testes locais após `source ~/.profile` ou use os runners Docker abaixo (eles podem montar `~/.profile` no contêiner). -## Deepgram live (transcrição de áudio) +## Live Deepgram (transcrição de áudio) - Teste: `extensions/deepgram/audio.live.test.ts` -- Ativar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` +- Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live do plano de codificação BytePlus - Teste: `extensions/byteplus/live.test.ts` -- Ativar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` +- Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Substituição opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI live de mídia por workflow +## Live de mídia de workflow ComfyUI - Teste: `extensions/comfy/comfy.live.test.ts` -- Ativar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` +- Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Escopo: - Exercita os caminhos empacotados de imagem, vídeo e `music_generate` do comfy - - Ignora cada capacidade a menos que `models.providers.comfy.` esteja configurado - - Útil após alterar envio de workflow do comfy, polling, downloads ou registro do plugin + - Ignora cada capacidade, a menos que `models.providers.comfy.` esteja configurado + - Útil após alterar envio de workflow comfy, polling, downloads ou registro do plugin ## Geração de imagem live @@ -823,15 +826,15 @@ Se você quiser depender de chaves de env (por exemplo, exportadas no seu `~/.pr - Harness: `pnpm test:live:media image` - Escopo: - Enumera todos os plugins de provedor de geração de imagem registrados - - Carrega variáveis de ambiente de provedor ausentes do seu shell de login (`~/.profile`) antes da sondagem - - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste desatualizadas em `auth-profiles.json` não escondam credenciais reais do shell - - Ignora provedores sem autenticação/profile/modelo utilizável - - Executa as variantes padrão de geração de imagem por meio da capacidade compartilhada de runtime: + - Carrega variáveis de ambiente de provedor ausentes do seu shell de login (`~/.profile`) antes de sondar + - Usa por padrão chaves de API live/env antes dos perfis de auth armazenados, para que chaves de teste desatualizadas em `auth-profiles.json` não escondam credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável + - Executa as variantes padrão de geração de imagem por meio da capacidade de runtime compartilhada: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Provedores empacotados atualmente cobertos: +- Provedores empacotados cobertos atualmente: - `fal` - `google` - `minimax` @@ -842,75 +845,75 @@ Se você quiser depender de chaves de env (por exemplo, exportadas no seu `~/.pr - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições somente por env +- Comportamento de auth opcional: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth do armazenamento de perfis e ignorar substituições apenas por env ## Geração de música live - Teste: `extensions/music-generation-providers.live.test.ts` -- Ativar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` +- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Escopo: - - Exercita o caminho compartilhado de provedores empacotados de geração de música + - Exercita o caminho compartilhado do provedor de geração de música empacotado - Atualmente cobre Google e MiniMax - - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes da sondagem - - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste desatualizadas em `auth-profiles.json` não escondam credenciais reais do shell - - Ignora provedores sem autenticação/profile/modelo utilizável + - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes de sondar + - Usa por padrão chaves de API live/env antes dos perfis de auth armazenados, para que chaves de teste desatualizadas em `auth-profiles.json` não escondam credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável - Executa ambos os modos de runtime declarados quando disponíveis: - - `generate` com entrada apenas por prompt + - `generate` com entrada apenas de prompt - `edit` quando o provedor declara `capabilities.edit.enabled` - - Cobertura atual da faixa compartilhada: + - Cobertura atual da lane compartilhada: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: arquivo live Comfy separado, não esta varredura compartilhada + - `comfy`: arquivo live separado do Comfy, não esta varredura compartilhada - Restrição opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições somente por env +- Comportamento de auth opcional: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth do armazenamento de perfis e ignorar substituições apenas por env ## Geração de vídeo live - Teste: `extensions/video-generation-providers.live.test.ts` -- Ativar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` +- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Escopo: - - Exercita o caminho compartilhado de provedores empacotados de geração de vídeo - - Usa por padrão o caminho smoke seguro para release: provedores não FAL, uma solicitação text-to-video por provedor, prompt de lagosta de um segundo e um limite de operação por provedor vindo de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) - - Ignora FAL por padrão porque a latência de fila do lado do provedor pode dominar o tempo de release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente - - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes da sondagem - - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste desatualizadas em `auth-profiles.json` não escondam credenciais reais do shell - - Ignora provedores sem autenticação/profile/modelo utilizável + - Exercita o caminho compartilhado do provedor de geração de vídeo empacotado + - Usa por padrão o caminho de smoke seguro para release: provedores não-FAL, uma requisição text-to-video por provedor, prompt de lagosta de um segundo e um limite de operação por provedor de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) + - Ignora FAL por padrão porque a latência da fila no lado do provedor pode dominar o tempo de release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente + - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes de sondar + - Usa por padrão chaves de API live/env antes dos perfis de auth armazenados, para que chaves de teste desatualizadas em `auth-profiles.json` não escondam credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável - Executa apenas `generate` por padrão - Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de transformação declarados quando disponíveis: - - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de imagem respaldada por buffer na varredura compartilhada - - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de vídeo respaldada por buffer na varredura compartilhada - - Provedores `imageToVideo` atualmente declarados, mas ignorados na varredura compartilhada: - - `vydra` porque o `veo3` empacotado é somente texto e o `kling` empacotado exige uma URL remota de imagem - - Cobertura específica de Vydra por provedor: + - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de imagem com suporte a buffer na varredura compartilhada + - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de vídeo com suporte a buffer na varredura compartilhada + - Provedores atuais `imageToVideo` declarados, mas ignorados na varredura compartilhada: + - `vydra` porque o `veo3` empacotado é apenas de texto e o `kling` empacotado requer uma URL de imagem remota + - Cobertura Vydra específica por provedor: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - esse arquivo executa `veo3` text-to-video mais uma faixa `kling` que usa por padrão um fixture de URL remota de imagem - - Cobertura live atual de `videoToVideo`: - - `runway` somente quando o modelo selecionado é `runway/gen4_aleph` - - Provedores `videoToVideo` atualmente declarados, mas ignorados na varredura compartilhada: + - esse arquivo executa `veo3` text-to-video e uma lane `kling` que usa por padrão uma fixture de URL de imagem remota + - Cobertura atual live de `videoToVideo`: + - `runway` apenas quando o modelo selecionado é `runway/gen4_aleph` + - Provedores atuais `videoToVideo` declarados, mas ignorados na varredura compartilhada: - `alibaba`, `qwen`, `xai` porque esses caminhos atualmente exigem URLs de referência remotas `http(s)` / MP4 - - `google` porque a faixa compartilhada atual Gemini/Veo usa entrada local respaldada por buffer e esse caminho não é aceito na varredura compartilhada - - `openai` porque a faixa compartilhada atual não tem garantias de acesso específico por organização para inpaint/remix de vídeo + - `google` porque a lane compartilhada atual Gemini/Veo usa entrada local com suporte a buffer e esse caminho não é aceito na varredura compartilhada + - `openai` porque a lane compartilhada atual não garante acesso específico por organização a inpaint/remix de vídeo - Restrição opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos os provedores na varredura padrão, incluindo FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reduzir o limite de operação de cada provedor em uma execução smoke mais agressiva -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições somente por env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos os provedores na varredura padrão, inclusive FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reduzir o limite de operação de cada provedor em uma execução smoke agressiva +- Comportamento de auth opcional: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth do armazenamento de perfis e ignorar substituições apenas por env ## Harness live de mídia - Comando: `pnpm test:live:media` -- Objetivo: - - Executa as suítes live compartilhadas de imagem, música e vídeo por um único entrypoint nativo do repositório +- Finalidade: + - Executa as suítes live compartilhadas de imagem, música e vídeo por meio de um único entrypoint nativo do repositório - Carrega automaticamente variáveis de ambiente de provedor ausentes de `~/.profile` - - Restringe automaticamente por padrão cada suíte aos provedores que atualmente têm autenticação utilizável + - Restringe automaticamente por padrão cada suíte aos provedores que atualmente têm auth utilizável - Reutiliza `scripts/test-live.mjs`, para que o comportamento de Heartbeat e modo silencioso permaneça consistente - Exemplos: - `pnpm test:live:media` @@ -918,214 +921,214 @@ Se você quiser depender de chaves de env (por exemplo, exportadas no seu `~/.pr - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Runners Docker (verificações opcionais “funciona em Linux”) +## Runners Docker (verificações opcionais de "funciona em Linux") -Esses runners Docker são divididos em dois grupos: +Esses runners Docker se dividem em dois grupos: -- Runners live-model: `test:docker:live-models` e `test:docker:live-gateway` executam apenas seu arquivo live correspondente de chaves de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de configuração e workspace (e obtendo `~/.profile` se montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. -- Runners Docker live usam por padrão um limite smoke menor para que uma varredura Docker completa permaneça prática: - `test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12`, e +- Runners de modelos live: `test:docker:live-models` e `test:docker:live-gateway` executam apenas seu arquivo live correspondente com chaves de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de config e workspace (e carregando `~/.profile` se estiver montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. +- Os runners Docker live usam por padrão um limite smoke menor para que uma varredura Docker completa permaneça prática: + `test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12` e `test:docker:live-gateway` usa por padrão `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando - quiser explicitamente a varredura maior e exaustiva. -- `test:docker:all` constrói a imagem Docker live uma vez via `test:docker:live-build` e depois a reutiliza para as duas faixas live Docker. Também constrói uma imagem compartilhada `scripts/e2e/Dockerfile` via `test:docker:e2e-build` e a reutiliza para os runners smoke E2E em contêiner que exercitam o app compilado. -- Runners smoke de contêiner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` e `test:docker:config-reload` iniciam um ou mais contêineres reais e verificam caminhos de integração de nível superior. + quiser explicitamente a varredura exaustiva maior. +- `test:docker:all` cria a imagem Docker live uma vez via `test:docker:live-build`, depois a reutiliza para as duas lanes Docker live. Ele também cria uma imagem compartilhada `scripts/e2e/Dockerfile` via `test:docker:e2e-build` e a reutiliza para os runners smoke E2E em contêiner que exercitam o app construído. +- Runners smoke em contêiner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` e `test:docker:config-reload` iniciam um ou mais contêineres reais e verificam caminhos de integração de nível superior. -Os runners Docker live-model também fazem bind-mount apenas das homes de autenticação CLI necessárias (ou de todas as compatíveis quando a execução não está restrita) e então as copiam para a home do contêiner antes da execução, para que OAuth de CLI externa possa atualizar tokens sem modificar o armazenamento de autenticação do host: +Os runners Docker de modelos live também fazem bind-mount apenas dos homes de auth de CLI necessários (ou de todos os suportados quando a execução não está restrita) e depois os copiam para o home do contêiner antes da execução para que o OAuth de CLI externa possa atualizar tokens sem alterar o armazenamento de auth do host: - Modelos diretos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke de vinculação ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Smoke de bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) - Smoke de backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Smoke do harness de app-server Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) +- Smoke do harness app-server do Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + agent dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live do Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) -- Assistente de onboarding (TTY, estrutura completa): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Smoke de onboarding/canal/agente por tarball npm: `pnpm test:docker:npm-onboard-channel-agent` instala globalmente no Docker o tarball empacotado do OpenClaw, configura OpenAI por onboarding com referência de env e Telegram por padrão, verifica que ativar o plugin instala suas dependências de runtime sob demanda, executa doctor e executa um turno de agente OpenAI simulado. Reuse um tarball pré-compilado com `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignore a recompilação no host com `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` ou troque o canal com `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Rede do Gateway (dois contêineres, autenticação WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Regressão mínima de raciocínio OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) executa um servidor OpenAI simulado por meio do Gateway, verifica que `web_search` eleva `reasoning.effort` de `minimal` para `low`, depois força a rejeição do schema do provedor e verifica que o detalhe bruto aparece nos logs do Gateway. -- Bridge de canal MCP (Gateway semeado + bridge stdio + smoke bruto de frame de notificação Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Ferramentas MCP do bundle Pi (servidor MCP stdio real + smoke allow/deny do perfil Pi embutido): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Limpeza MCP de Cron/subagent (Gateway real + teardown de filho MCP stdio após execuções isoladas de cron e subagente one-shot): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Assistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) +- Smoke de onboarding/channel/agent com tarball npm: `pnpm test:docker:npm-onboard-channel-agent` instala globalmente no Docker o tarball empacotado do OpenClaw, configura OpenAI via onboarding por referência de env mais Telegram por padrão, verifica se habilitar o plugin instala suas dependências de runtime sob demanda, executa doctor e roda um turno de agent OpenAI mockado. Reutilize um tarball pré-construído com `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignore a rebuild no host com `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` ou troque o channel com `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Rede do Gateway (dois contêineres, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Regressão mínima de raciocínio `web_search` do OpenAI Responses: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) executa um servidor OpenAI mockado via Gateway, verifica se `web_search` eleva `reasoning.effort` de `minimal` para `low`, depois força a rejeição do schema do provedor e verifica se o detalhe bruto aparece nos logs do Gateway. +- Bridge de channel MCP (Gateway preparado + bridge stdio + smoke bruto de frame de notificação do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Ferramentas MCP do bundle Pi (servidor MCP stdio real + smoke de allow/deny do perfil Pi embutido): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Limpeza de MCP Cron/subagent (Gateway real + encerramento do processo filho MCP stdio após execuções isoladas de cron e subagent one-shot): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) - Plugins (smoke de instalação + alias `/plugin` + semântica de reinício do bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -- Smoke sem alterações de atualização de plugin: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke de metadados de recarga de configuração: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) -- Dependências de runtime de plugin empacotado: `pnpm test:docker:bundled-channel-deps` constrói por padrão uma pequena imagem Docker de runner, compila e empacota o OpenClaw uma vez no host e então monta esse tarball em cada cenário de instalação Linux. Reuse a imagem com `OPENCLAW_SKIP_DOCKER_BUILD=1`, ignore a recompilação no host após uma build local recente com `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` ou aponte para um tarball existente com `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Restrinja dependências de runtime de plugin empacotado durante a iteração desativando cenários não relacionados, por exemplo: +- Smoke de update de plugin sem alterações: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke de metadados de recarga de config: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) +- Dependências de runtime de plugins empacotados: `pnpm test:docker:bundled-channel-deps` cria por padrão uma imagem pequena de runner Docker, constrói e empacota o OpenClaw uma vez no host e então monta esse tarball em cada cenário de instalação Linux. Reutilize a imagem com `OPENCLAW_SKIP_DOCKER_BUILD=1`, ignore a rebuild no host após uma build local recente com `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` ou aponte para um tarball existente com `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Restrinja as dependências de runtime de plugins empacotados durante a iteração desabilitando cenários não relacionados, por exemplo: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Para pré-compilar e reutilizar manualmente a imagem compartilhada do app compilado: +Para pré-construir e reutilizar manualmente a imagem compartilhada do app construído: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Substituições de imagem específicas de suíte, como `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, ainda têm prioridade quando definidas. Quando `OPENCLAW_SKIP_DOCKER_BUILD=1` aponta para uma imagem remota compartilhada, os scripts fazem pull dela se ainda não estiver localmente. Os testes Docker de QR e instalador mantêm seus próprios Dockerfiles porque validam comportamento de pacote/instalação, não o runtime compartilhado do app compilado. +Substituições de imagem específicas da suíte, como `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, ainda têm precedência quando definidas. Quando `OPENCLAW_SKIP_DOCKER_BUILD=1` aponta para uma imagem compartilhada remota, os scripts fazem pull dela se ainda não estiver localmente. Os testes Docker de QR e instalador mantêm seus próprios Dockerfiles porque validam comportamento de pacote/instalação em vez do runtime compartilhado do app construído. -Os runners Docker live-model também fazem bind-mount do checkout atual em modo somente leitura e +Os runners Docker de modelos live também fazem bind-mount do checkout atual em modo somente leitura e o preparam em um workdir temporário dentro do contêiner. Isso mantém a imagem de runtime -enxuta e ainda assim executa Vitest exatamente contra sua origem/configuração local. -A etapa de preparação ignora caches locais grandes e saídas locais de build de app como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais de `.build` de app ou -saída do Gradle para que execuções live em Docker não passem minutos copiando +enxuta e, ao mesmo tempo, executa o Vitest contra sua origem/config local exata. +A etapa de preparação ignora caches locais grandes e saídas de build de apps, como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais de saída +`.build` ou Gradle, para que execuções live no Docker não gastem minutos copiando artefatos específicos da máquina. -Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que sondas live do gateway não iniciem -workers reais de canais Telegram/Discord/etc. dentro do contêiner. -`test:docker:live-models` ainda executa `pnpm test:live`, então passe também -`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir cobertura -live do gateway dessa faixa Docker. +Eles também definem `OPENCLAW_SKIP_CHANNELS=1`, para que as sondas live do Gateway não iniciem +workers reais de channels Telegram/Discord/etc. dentro do contêiner. +`test:docker:live-models` ainda executa `pnpm test:live`, então também passe +`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir cobertura live do Gateway +nessa lane Docker. `test:docker:openwebui` é um smoke de compatibilidade de nível superior: ele inicia um -contêiner de gateway do OpenClaw com os endpoints HTTP compatíveis com OpenAI ativados, +contêiner Gateway do OpenClaw com os endpoints HTTP compatíveis com OpenAI habilitados, inicia um contêiner Open WebUI fixado contra esse gateway, faz login pelo Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma -solicitação real de chat pelo proxy `/api/chat/completions` do Open WebUI. -A primeira execução pode ser visivelmente mais lenta porque o Docker talvez precise fazer pull da -imagem do Open WebUI e o Open WebUI talvez precise concluir sua própria configuração de cold start. -Essa faixa espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` por padrão) é a forma principal de fornecê-la em execuções Dockerizadas. -Execuções bem-sucedidas imprimem uma pequena carga JSON como `{ "ok": true, "model": +requisição real de chat pelo proxy `/api/chat/completions` do Open WebUI. +A primeira execução pode ser visivelmente mais lenta porque o Docker pode precisar fazer pull da +imagem do Open WebUI e o Open WebUI pode precisar concluir sua própria configuração de inicialização a frio. +Essa lane espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` +(`~/.profile` por padrão) é a principal forma de fornecê-la em execuções Dockerizadas. +Execuções bem-sucedidas imprimem um pequeno payload JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` é intencionalmente determinístico e não precisa de uma conta real de Telegram, Discord ou iMessage. Ele inicia um contêiner Gateway -pré-semeado, inicia um segundo contêiner que cria `openclaw mcp serve` e então -verifica descoberta de conversas roteadas, leituras de transcrição, metadados de anexos, -comportamento de fila de eventos live, roteamento de envio de saída e notificações -de estilo Claude sobre canal + permissão pela bridge MCP stdio real. A verificação -de notificação inspeciona diretamente os frames MCP stdio brutos, então o smoke valida o que a -bridge realmente emite, não apenas o que por acaso um SDK específico de cliente expõe. -`test:docker:pi-bundle-mcp-tools` é determinístico e não precisa de uma chave de modelo -live. Ele compila a imagem Docker do repositório, inicia um servidor de sonda MCP stdio real -dentro do contêiner, materializa esse servidor pelo runtime embutido MCP do bundle Pi, -executa a ferramenta e então verifica se `coding` e `messaging` mantêm -ferramentas `bundle-mcp` enquanto `minimal` e `tools.deny: ["bundle-mcp"]` as filtram. -`test:docker:cron-mcp-cleanup` é determinístico e não precisa de uma chave de modelo -live. Ele inicia um Gateway pré-semeado com um servidor de sonda MCP stdio real, executa um -turno isolado de Cron e um turno filho one-shot de `/subagents spawn`, e então verifica +preparado, inicia um segundo contêiner que executa `openclaw mcp serve` e então +verifica descoberta de conversa roteada, leituras de transcript, metadados de anexos, +comportamento da fila de eventos live, roteamento de envio de saída e notificações +de channel + permissão no estilo Claude pela bridge stdio MCP real. A verificação de notificações +inspeciona diretamente os frames MCP stdio brutos, para que o smoke valide o que a +bridge realmente emite, e não apenas o que um SDK cliente específico por acaso expõe. +`test:docker:pi-bundle-mcp-tools` é determinístico e não precisa de uma chave de modelo live. +Ele cria a imagem Docker do repositório, inicia um servidor de sonda MCP stdio real +dentro do contêiner, materializa esse servidor pelo runtime MCP do bundle Pi embutido, +executa a ferramenta e então verifica se `coding` e `messaging` mantêm ferramentas +`bundle-mcp`, enquanto `minimal` e `tools.deny: ["bundle-mcp"]` as filtram. +`test:docker:cron-mcp-cleanup` é determinístico e não precisa de uma chave de modelo live. +Ele inicia um Gateway preparado com um servidor de sonda MCP stdio real, executa um +turno isolado de cron e um turno filho one-shot de `/subagents spawn`, e então verifica se o processo filho MCP é encerrado após cada execução. -Smoke manual ACP de thread em linguagem natural (não CI): +Smoke manual de thread ACP em linguagem simples (não CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantenha este script para fluxos de trabalho de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua. +- Mantenha este script para fluxos de regressão/depuração. Ele pode voltar a ser necessário para validação de roteamento de threads ACP, então não o exclua. Variáveis de ambiente úteis: - `OPENCLAW_CONFIG_DIR=...` (padrão: `~/.openclaw`) montado em `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (padrão: `~/.openclaw/workspace`) montado em `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e obtido antes de executar os testes -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente obtidas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem mounts externos de autenticação de CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações CLI com cache dentro do Docker -- Diretórios/arquivos de autenticação de CLI externos em `$HOME` são montados em modo somente leitura sob `/host-auth...` e depois copiados para `/home/node/...` antes do início dos testes +- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e carregado antes de executar os testes +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem mounts de auth de CLI externa +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações de CLI com cache dentro do Docker +- Diretórios/arquivos de auth de CLI externa sob `$HOME` são montados em modo somente leitura sob `/host-auth...` e então copiados para `/home/node/...` antes do início dos testes - Diretórios padrão: `.minimax` - Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Execuções restritas por provedor montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Execuções com provedores restritos montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Substitua manualmente com `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` ou uma lista separada por vírgulas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para restringir a execução - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do contêiner -- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em novas execuções que não precisem de recompilação -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfil (não de env) +- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em reruns que não precisem de rebuild +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (não do env) - `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo gateway para o smoke do Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...` para substituir o prompt de verificação de nonce usado pelo smoke do Open WebUI -- `OPENWEBUI_IMAGE=...` para substituir a tag de imagem fixada do Open WebUI +- `OPENWEBUI_IMAGE=...` para substituir a tag fixada da imagem do Open WebUI ## Sanidade da documentação -Execute verificações da documentação após edições: `pnpm check:docs`. -Execute a validação completa de âncoras do Mintlify quando também precisar de verificações de títulos na página: `pnpm docs:check-links:anchors`. +Execute verificações da documentação após editar docs: `pnpm check:docs`. +Execute a validação completa de âncoras do Mintlify quando também precisar verificar headings na página: `pnpm docs:check-links:anchors`. ## Regressão offline (segura para CI) Estas são regressões de “pipeline real” sem provedores reais: -- Tool calling do Gateway (OpenAI simulado, gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistente do Gateway (WS `wizard.start`/`wizard.next`, grava config + auth imposto): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Chamada de ferramenta do Gateway (OpenAI mockado, gateway real + loop de agent): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Assistente do Gateway (WS `wizard.start`/`wizard.next`, gravação de config + auth aplicada): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Avaliações de confiabilidade de agente (skills) +## Avaliações de confiabilidade de agent (Skills) -Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade de agente”: +Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade de agent”: -- Tool-calling simulado pelo loop real de gateway + agente (`src/gateway/gateway.test.ts`). -- Fluxos end-to-end do assistente que validam encadeamento de sessão e efeitos de configuração (`src/gateway/gateway.test.ts`). +- Chamada de ferramenta mockada pelo gateway real + loop de agent (`src/gateway/gateway.test.ts`). +- Fluxos end-to-end do assistente que validam wiring de sessão e efeitos de config (`src/gateway/gateway.test.ts`). O que ainda falta para Skills (veja [Skills](/pt-BR/tools/skills)): -- **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a skill certa (ou evita as irrelevantes)? -- **Conformidade:** o agente lê `SKILL.md` antes de usar e segue as etapas/args obrigatórios? -- **Contratos de workflow:** cenários de vários turnos que afirmam ordem de ferramentas, continuidade do histórico da sessão e limites de sandbox. +- **Tomada de decisão:** quando Skills estão listadas no prompt, o agent escolhe a Skill correta (ou evita as irrelevantes)? +- **Conformidade:** o agent lê `SKILL.md` antes do uso e segue as etapas/args exigidos? +- **Contratos de fluxo de trabalho:** cenários de múltiplos turnos que validam ordem de ferramentas, continuidade do histórico da sessão e limites do sandbox. -Avaliações futuras devem permanecer determinísticas primeiro: +As futuras avaliações devem permanecer determinísticas primeiro: -- Um runner de cenários usando provedores simulados para afirmar chamadas de ferramenta + ordem, leituras de arquivo de skill e encadeamento de sessão. -- Um pequeno conjunto de cenários focados em skill (usar vs evitar, controle, prompt injection). +- Um runner de cenários usando provedores mockados para validar chamadas de ferramenta + ordem, leituras de arquivos de Skill e wiring de sessão. +- Uma pequena suíte de cenários focados em Skills (usar vs evitar, gating, prompt injection). - Avaliações live opcionais (opt-in, controladas por env) somente depois que a suíte segura para CI estiver pronta. -## Testes de contrato (formato de plugin e canal) +## Testes de contrato (formato de plugin e channel) -Testes de contrato verificam se todo plugin e canal registrado está em conformidade com seu -contrato de interface. Eles iteram sobre todos os plugins descobertos e executam uma suíte de -afirmações de formato e comportamento. A faixa unit padrão de `pnpm test` -ignora intencionalmente esses arquivos compartilhados de costura e smoke; execute os comandos de contrato explicitamente -quando tocar superfícies compartilhadas de canal ou provedor. +Os testes de contrato verificam se todo plugin e channel registrado está em conformidade com seu +contrato de interface. Eles iteram sobre todos os plugins descobertos e executam um conjunto de +asserções de formato e comportamento. A lane unit padrão de `pnpm test` intencionalmente +ignora esses arquivos compartilhados de interface e smoke; execute explicitamente +os comandos de contrato quando tocar em superfícies compartilhadas de channel ou provedor. ### Comandos - Todos os contratos: `pnpm test:contracts` -- Somente contratos de canal: `pnpm test:contracts:channels` -- Somente contratos de provedor: `pnpm test:contracts:plugins` +- Apenas contratos de channel: `pnpm test:contracts:channels` +- Apenas contratos de provedor: `pnpm test:contracts:plugins` -### Contratos de canal +### Contratos de channel Localizados em `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Formato básico do plugin (id, nome, capacidades) - **setup** - Contrato do assistente de configuração -- **session-binding** - Comportamento de vinculação de sessão -- **outbound-payload** - Estrutura da carga de mensagem -- **inbound** - Tratamento de mensagem de entrada -- **actions** - Handlers de ação do canal +- **session-binding** - Comportamento de vínculo de sessão +- **outbound-payload** - Estrutura do payload de mensagem +- **inbound** - Tratamento de mensagens de entrada +- **actions** - Manipuladores de ação do channel - **threading** - Tratamento de ID de thread -- **directory** - API de diretório/lista -- **group-policy** - Aplicação da política de grupo +- **directory** - API de diretório/lista de participantes +- **group-policy** - Aplicação de política de grupo ### Contratos de status do provedor Localizados em `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondas de status de canal +- **status** - Sondas de status do channel - **registry** - Formato do registro de plugins ### Contratos de provedor Localizados em `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato do fluxo de autenticação -- **auth-choice** - Escolha/seleção de autenticação -- **catalog** - API de catálogo de modelos -- **discovery** - Descoberta de plugin -- **loader** - Carregamento de plugin -- **runtime** - Runtime de provedor +- **auth** - Contrato de fluxo de auth +- **auth-choice** - Escolha/seleção de auth +- **catalog** - API do catálogo de modelos +- **discovery** - Descoberta de plugins +- **loader** - Carregamento de plugins +- **runtime** - Runtime do provedor - **shape** - Formato/interface do plugin - **wizard** - Assistente de configuração ### Quando executar -- Após alterar exports ou subpaths do plugin-sdk -- Após adicionar ou modificar um canal ou plugin de provedor -- Após refatorar registro ou descoberta de plugins +- Depois de alterar exports ou subpaths do plugin-sdk +- Depois de adicionar ou modificar um plugin de channel ou provedor +- Depois de refatorar registro ou descoberta de plugin -Os testes de contrato executam no CI e não exigem chaves de API reais. +Os testes de contrato executam no CI e não requerem chaves de API reais. -## Adicionando regressões (orientação) +## Adicionar regressões (orientação) -Quando você corrige um problema de provedor/modelo descoberto em live: +Ao corrigir um problema de provedor/modelo descoberto em live: -- Adicione uma regressão segura para CI, se possível (provedor simulado/stub ou capture a transformação exata do formato da solicitação) -- Se for inerentemente somente live (limites de taxa, políticas de autenticação), mantenha o teste live restrito e opt-in por meio de variáveis de ambiente -- Prefira mirar na menor camada que detecta o bug: - - bug de conversão/replay de solicitação do provedor → teste de modelos diretos - - bug no pipeline de sessão/histórico/ferramenta do gateway → smoke live do gateway ou teste mock do gateway seguro para CI +- Adicione uma regressão segura para CI, se possível (provedor mockado/stubado ou capture a transformação exata do formato da requisição) +- Se for inerentemente apenas live (limites de taxa, políticas de auth), mantenha o teste live restrito e opt-in por variáveis de ambiente +- Prefira direcionar a menor camada que detecta o bug: + - bug de conversão/replay de requisição do provedor → teste de modelos diretos + - bug no pipeline de sessão/histórico/ferramenta do Gateway → smoke live do Gateway ou teste mockado do Gateway seguro para CI - Proteção de travessia de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um destino amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`) e então afirma que ids exec de segmento de travessia são rejeitados. - - Se você adicionar uma nova família de destino SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de destino não classificados para que novas classes não possam ser ignoradas silenciosamente. + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo de amostra por classe de SecretRef dos metadados do registro (`listSecretTargetRegistryEntries()`), então valida que ids de execução de segmento de travessia são rejeitados. + - Se você adicionar uma nova família de alvo SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente.