diff --git a/docs/it/ci.md b/docs/it/ci.md index 8cacc92a3..303c658ac 100644 --- a/docs/it/ci.md +++ b/docs/it/ci.md @@ -1,14 +1,14 @@ --- read_when: - - Devi capire perché un job CI è stato eseguito o non è stato eseguito. - - Stai eseguendo il debug di controlli GitHub Actions non riusciti. -summary: Grafico dei job CI, gate di ambito e comandi locali equivalenti + - Devi capire perché un job CI è stato eseguito oppure no + - Stai eseguendo il debug di controlli GitHub Actions non riusciti +summary: Grafo dei job CI, gate di ambito ed equivalenti dei comandi locali title: Pipeline CI x-i18n: - generated_at: "2026-04-23T13:57:58Z" + generated_at: "2026-04-23T14:55:06Z" model: gpt-5.4 provider: openai - source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f + source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d source_path: ci.md workflow: 15 --- @@ -17,84 +17,84 @@ x-i18n: La CI viene eseguita a ogni push su `main` e a ogni pull request. Usa uno scoping intelligente per saltare i job costosi quando sono cambiate solo aree non correlate. -QA Lab ha lane CI dedicate al di fuori del workflow principale con smart scope. Il -workflow `Parity gate` viene eseguito su modifiche PR corrispondenti e tramite invio manuale; esso -compila il runtime QA privato e confronta i pacchetti agentici mock GPT-5.4 e Opus 4.6. +QA Lab ha corsie CI dedicate al di fuori del workflow principale con scoping intelligente. Il +workflow `Parity gate` viene eseguito sulle modifiche PR corrispondenti e tramite dispatch manuale; esso +compila il runtime QA privato e confronta i pack agentici mock GPT-5.4 e Opus 4.6. Il workflow `QA-Lab - All Lanes` viene eseguito ogni notte su `main` e tramite -invio manuale; distribuisce in parallelo il mock parity gate, la lane live Matrix e la lane live -Telegram come job paralleli. I job live usano l'ambiente `qa-live-shared`, -e la lane Telegram usa lease Convex. Anche `OpenClaw Release -Checks` esegue le stesse lane QA Lab prima dell'approvazione della release. +dispatch manuale; distribuisce in parallelo il mock parity gate, la corsia Matrix live e la corsia +Telegram live come job paralleli. I job live usano l'ambiente `qa-live-shared`, +e la corsia Telegram usa lease Convex. Anche `OpenClaw Release +Checks` esegue le stesse corsie QA Lab prima dell'approvazione della release. ## Panoramica dei job | Job | Scopo | Quando viene eseguito | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | Rileva modifiche solo-docs, scope modificati, extension modificate e costruisce il manifest CI | Sempre su push e PR non draft | -| `security-scm-fast` | Rilevamento di chiavi private e audit del workflow tramite `zizmor` | Sempre su push e PR non draft | +| `preflight` | Rileva modifiche solo alla documentazione, scope cambiati, estensioni cambiate e compila il manifest CI | Sempre su push e PR non draft | +| `security-scm-fast` | Rilevamento di chiavi private e audit dei workflow tramite `zizmor` | Sempre su push e PR non draft | | `security-dependency-audit` | Audit del lockfile di produzione senza dipendenze rispetto agli advisory npm | Sempre su push e PR non draft | | `security-fast` | Aggregato richiesto per i job di sicurezza rapidi | Sempre su push e PR non draft | | `build-artifacts` | Compila `dist/`, Control UI, controlli degli artifact compilati e artifact riutilizzabili downstream | Modifiche rilevanti per Node | -| `checks-fast-core` | Lane rapide di correttezza Linux come controlli bundled/plugin-contract/protocol | Modifiche rilevanti per Node | -| `checks-fast-contracts-channels` | Controlli sharded dei contratti dei canali con un risultato di check aggregato stabile | Modifiche rilevanti per Node | -| `checks-node-extensions` | Shard completi di test dei bundled plugin sull'intera suite extension | Modifiche rilevanti per Node | -| `checks-node-core-test` | Shard di test core Node, escluse le lane di canale, bundled, contratti ed extension | Modifiche rilevanti per Node | -| `extension-fast` | Test mirati solo per i bundled plugin modificati | Pull request con modifiche alle extension | -| `check` | Equivalente locale principale sharded del gate: tipi prod, lint, guard, tipi di test e smoke rigoroso | Modifiche rilevanti per Node | -| `check-additional` | Guard di architettura, boundary, superficie extension, package-boundary e shard gateway-watch | Modifiche rilevanti per Node | -| `build-smoke` | Smoke test della CLI compilata e smoke sulla memoria di avvio | Modifiche rilevanti per Node | -| `checks` | Verificatore per test dei canali sugli artifact compilati più compatibilità Node 22 solo push | Modifiche rilevanti per Node | -| `check-docs` | Controlli di formattazione docs, lint e link non validi | Docs modificate | -| `skills-python` | Ruff + pytest per Skills basate su Python | Modifiche rilevanti per Skills Python | -| `checks-windows` | Lane di test specifiche per Windows | Modifiche rilevanti per Windows | -| `macos-node` | Lane di test TypeScript macOS che usa gli artifact compilati condivisi | Modifiche rilevanti per macOS | +| `checks-fast-core` | Corsie rapide di correttezza Linux, come controlli bundled/plugin-contract/protocol | Modifiche rilevanti per Node | +| `checks-fast-contracts-channels` | Controlli shardizzati dei contratti dei canali con un risultato di controllo aggregato stabile | Modifiche rilevanti per Node | +| `checks-node-extensions` | Shard completi dei test dei plugin bundled nell'intera suite delle estensioni | Modifiche rilevanti per Node | +| `checks-node-core-test` | Shard dei test core Node, escluse le corsie per canali, bundled, contratti ed estensioni | Modifiche rilevanti per Node | +| `extension-fast` | Test mirati solo per i plugin bundled modificati | Pull request con modifiche alle estensioni | +| `check` | Equivalente locale principale shardizzato: tipi prod, lint, guard, tipi di test e smoke rigoroso | Modifiche rilevanti per Node | +| `check-additional` | Guard di architettura, boundary, surface delle estensioni, boundary dei package e shard gateway-watch | Modifiche rilevanti per Node | +| `build-smoke` | Test smoke della CLI compilata e smoke sulla memoria all'avvio | Modifiche rilevanti per Node | +| `checks` | Verificatore per i test dei canali sugli artifact compilati più compatibilità Node 22 solo su push | Modifiche rilevanti per Node | +| `check-docs` | Controlli di formattazione docs, lint e link interrotti | Documentazione modificata | +| `skills-python` | Ruff + pytest per Skills basate su Python | Modifiche rilevanti per skill Python | +| `checks-windows` | Corsie di test specifiche per Windows | Modifiche rilevanti per Windows | +| `macos-node` | Corsia di test TypeScript su macOS usando gli artifact compilati condivisi | Modifiche rilevanti per macOS | | `macos-swift` | Lint, build e test Swift per l'app macOS | Modifiche rilevanti per macOS | | `android` | Test unitari Android per entrambe le varianti più una build APK debug | Modifiche rilevanti per Android | ## Ordine fail-fast -I job sono ordinati in modo che i controlli economici falliscano prima che vengano eseguiti quelli costosi: +I job sono ordinati in modo che i controlli economici falliscano prima che partano quelli costosi: -1. `preflight` decide quali lane esistono effettivamente. La logica `docs-scope` e `changed-scope` è composta da step interni a questo job, non da job autonomi. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falliscono rapidamente senza attendere i job più pesanti della matrice artifact e piattaforme. -3. `build-artifacts` si sovrappone alle lane Linux rapide così i consumer downstream possono iniziare non appena la build condivisa è pronta. -4. Successivamente si distribuiscono le lane più pesanti di piattaforma e runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` solo PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. +1. `preflight` decide quali corsie esistono del tutto. La logica `docs-scope` e `changed-scope` è composta da step all'interno di questo job, non da job separati. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falliscono rapidamente senza aspettare i job più pesanti della matrice artifact e piattaforme. +3. `build-artifacts` si sovrappone alle corsie Linux rapide così i consumer downstream possono iniziare non appena la build condivisa è pronta. +4. Successivamente si distribuiscono le corsie più pesanti di piattaforma e runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` solo PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. La logica di scope si trova in `scripts/ci-changed-scope.mjs` ed è coperta da unit test in `src/scripts/ci-changed-scope.test.ts`. -Le modifiche ai workflow CI convalidano il grafo CI Node più il lint dei workflow, ma non forzano da sole build native Windows, Android o macOS; quelle lane di piattaforma restano limitate alle modifiche del codice sorgente della piattaforma. -I controlli Node Windows sono limitati a wrapper specifici di processo/percorso Windows, helper npm/pnpm/UI runner, configurazione del package manager e superfici del workflow CI che eseguono quella lane; modifiche non correlate a sorgente, plugin, install-smoke e solo test restano sulle lane Linux Node, così non riservano un worker Windows da 16 vCPU per copertura già esercitata dai normali shard di test. -Il workflow separato `install-smoke` riusa lo stesso script di scope tramite il proprio job `preflight`. Calcola `run_install_smoke` a partire dal segnale changed-smoke più ristretto, quindi lo smoke Docker/install viene eseguito per modifiche rilevanti a installazione, packaging, container, produzione delle bundled extension e alle superfici core plugin/channel/gateway/Plugin SDK che i job Docker smoke esercitano. Le modifiche solo test e solo docs non riservano worker Docker. Il suo QR package smoke forza il layer Docker `pnpm install` a essere rieseguito preservando la cache BuildKit dello store pnpm, così esercita comunque l'installazione senza riscaricare le dipendenze a ogni esecuzione. Il suo gateway-network e2e riusa l'immagine runtime compilata in precedenza nel job, quindi aggiunge copertura WebSocket reale da container a container senza aggiungere un'altra build Docker. L'aggregato locale `test:docker:all` precompila un'unica immagine live-test condivisa e un'unica immagine built-app condivisa `scripts/e2e/Dockerfile`, poi esegue in parallelo le lane smoke live/E2E con `OPENCLAW_SKIP_DOCKER_BUILD=1`; regola la concorrenza predefinita di 4 con `OPENCLAW_DOCKER_ALL_PARALLELISM`. L'aggregato locale, per impostazione predefinita, smette di pianificare nuove lane nel pool dopo il primo errore e ogni lane ha un timeout di 120 minuti, modificabile con `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Le lane sensibili all'avvio o al provider vengono eseguite in esclusiva dopo il pool parallelo. Il workflow live/E2E riutilizzabile rispecchia il pattern a immagine condivisa compilando e pubblicando una singola immagine Docker E2E GHCR con tag SHA prima della matrice Docker, quindi eseguendo la matrice con `OPENCLAW_SKIP_DOCKER_BUILD=1`. Il workflow live/E2E pianificato esegue quotidianamente l'intera suite Docker del percorso di release. I test Docker di QR e installer mantengono i propri Dockerfile focalizzati sull'installazione. Un job separato `docker-e2e-fast` esegue il profilo Docker bounded bundled-plugin con un timeout del comando di 120 secondi: riparazione delle dipendenze setup-entry più isolamento sintetico dei guasti del bundled-loader. La matrice completa bundled update/channel resta manuale/full-suite perché esegue ripetuti passaggi reali di npm update e doctor repair. +Le modifiche ai workflow CI validano il grafo CI Node più il lint dei workflow, ma non impongono da sole build native Windows, Android o macOS; quelle corsie di piattaforma restano limitate alle modifiche del codice sorgente della relativa piattaforma. +I controlli Node per Windows sono limitati a wrapper specifici di processo/path di Windows, helper runner npm/pnpm/UI, configurazione del package manager e surface dei workflow CI che eseguono quella corsia; modifiche non correlate a sorgente, plugin, install-smoke e solo test restano sulle corsie Linux Node, così non riservano un worker Windows da 16 vCPU per una copertura già esercitata dagli shard di test normali. +Il workflow separato `install-smoke` riusa lo stesso script di scope tramite il proprio job `preflight`. Calcola `run_install_smoke` dal segnale changed-smoke più ristretto, quindi Docker/install smoke viene eseguito per modifiche rilevanti per installazione, packaging, container, modifiche di produzione alle estensioni bundled e le surface core plugin/channel/gateway/Plugin SDK esercitate dai job Docker smoke. Le modifiche solo test e solo documentazione non riservano worker Docker. Il suo smoke del pacchetto QR forza il layer Docker `pnpm install` a essere rieseguito preservando però la cache BuildKit del pnpm store, quindi esercita comunque l'installazione senza riscaricare le dipendenze a ogni esecuzione. Il suo gateway-network e2e riusa l'immagine runtime compilata in precedenza nel job, quindi aggiunge copertura WebSocket reale container-to-container senza aggiungere un'altra build Docker. In locale, `test:docker:all` precompila un'unica immagine live-test condivisa e un'unica immagine built-app condivisa da `scripts/e2e/Dockerfile`, poi esegue in parallelo le corsie smoke live/E2E con `OPENCLAW_SKIP_DOCKER_BUILD=1`; regola il parallelismo predefinito di 4 con `OPENCLAW_DOCKER_ALL_PARALLELISM`. L'aggregato locale smette per impostazione predefinita di pianificare nuove corsie in pool dopo il primo errore, e ogni corsia ha un timeout di 120 minuti sovrascrivibile con `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Le corsie sensibili all'avvio o al provider vengono eseguite in esclusiva dopo il pool parallelo. Il workflow live/E2E riutilizzabile rispecchia il pattern dell'immagine condivisa compilando e pubblicando un'unica immagine Docker E2E GHCR con tag SHA prima della matrice Docker, quindi eseguendo la matrice con `OPENCLAW_SKIP_DOCKER_BUILD=1`. Il workflow live/E2E schedulato esegue quotidianamente l'intera suite Docker del percorso di release. I test Docker QR e installer mantengono i propri Dockerfile focalizzati sull'installazione. Un job separato `docker-e2e-fast` esegue il profilo Docker bounded bundled-plugin con un timeout di 120 secondi per comando: riparazione delle dipendenze setup-entry più isolamento sintetico dei guasti del bundled-loader. La matrice completa bundled update/channel resta manuale/full-suite perché esegue passaggi ripetuti reali di npm update e doctor repair. -La logica locale delle lane modificate si trova in `scripts/changed-lanes.mjs` ed è eseguita da `scripts/check-changed.mjs`. Quel gate locale è più rigoroso sui boundary architetturali rispetto all'ampio scope CI di piattaforma: le modifiche di produzione core eseguono typecheck prod core più test core, le modifiche solo test core eseguono solo typecheck/test core di test, le modifiche di produzione extension eseguono typecheck prod extension più test extension, e le modifiche solo test extension eseguono solo typecheck/test extension di test. Le modifiche al Plugin SDK pubblico o al plugin-contract estendono la validazione alle extension perché le extension dipendono da quei contratti core. I version bump solo metadata di release eseguono controlli mirati di versione/config/dipendenze root. Le modifiche root/config sconosciute fanno fail safe su tutte le lane. +La logica locale delle corsie modificate si trova in `scripts/changed-lanes.mjs` ed è eseguita da `scripts/check-changed.mjs`. Questo gate locale è più rigoroso sui boundary architetturali rispetto all'ampio scope CI di piattaforma: le modifiche di produzione core eseguono typecheck prod core più test core, le modifiche solo ai test core eseguono solo typecheck/test core di test, le modifiche di produzione alle estensioni eseguono typecheck prod delle estensioni più test delle estensioni, e le modifiche solo ai test delle estensioni eseguono solo typecheck/test delle estensioni di test. Le modifiche al Plugin SDK pubblico o al plugin-contract estendono la validazione alle estensioni perché le estensioni dipendono da quei contratti core. Gli incrementi di versione limitati ai soli metadati di release eseguono controlli mirati di versione/config/dipendenze root. Le modifiche sconosciute a root/config falliscono in modo sicuro su tutte le corsie. -Sui push, la matrice `checks` aggiunge la lane `compat-node22` solo push. Sulle pull request, quella lane viene saltata e la matrice resta focalizzata sulle normali lane di test/canale. +Sui push, la matrice `checks` aggiunge la corsia `compat-node22` solo push. Sulle pull request, quella corsia viene saltata e la matrice resta focalizzata sulle normali corsie di test/canali. -Le famiglie di test Node più lente sono divise o bilanciate in modo che ogni job resti piccolo: i contratti dei canali dividono la copertura registry e core in sei shard pesati totali, i test dei bundled plugin sono bilanciati su sei worker extension, auto-reply viene eseguito come tre worker bilanciati invece di sei piccoli worker, e le configurazioni agentic gateway/plugin sono distribuite sui job Node agentic esistenti solo-sorgente invece di attendere gli artifact compilati. I test ampi browser, QA, media e plugin vari usano le loro configurazioni Vitest dedicate invece del catch-all condiviso per i plugin. La lane agents ampia usa lo scheduler condiviso di parallelismo per file di Vitest perché è dominata da import/scheduling piuttosto che da un singolo file di test lento. `runtime-config` viene eseguito con lo shard infra core-runtime per evitare che lo shard runtime condiviso possieda la coda finale. `check-additional` tiene insieme il lavoro compile/canary di package-boundary e separa l'architettura della topologia runtime dalla copertura gateway watch; lo shard boundary guard esegue i suoi piccoli guard indipendenti in parallelo all'interno di un unico job. Gateway watch, test dei canali e lo shard core support-boundary vengono eseguiti in parallelo all'interno di `build-artifacts` dopo che `dist/` e `dist-runtime/` sono già stati compilati, mantenendo i loro vecchi nomi di check come job verificatori leggeri ed evitando due worker Blacksmith aggiuntivi e una seconda coda di consumer degli artifact. -La CI Android esegue sia `testPlayDebugUnitTest` sia `testThirdPartyDebugUnitTest`, quindi compila l'APK debug Play. La variante third-party non ha un source set o manifest separato; la sua lane di unit test compila comunque quella variante con i flag BuildConfig SMS/call-log, evitando però un job duplicato di packaging APK debug a ogni push rilevante per Android. -`extension-fast` è solo PR perché le esecuzioni push eseguono già gli shard completi dei bundled plugin. Questo mantiene il feedback sui plugin modificati per le review senza riservare un worker Blacksmith aggiuntivo su `main` per una copertura già presente in `checks-node-extensions`. +Le famiglie di test Node più lente sono suddivise o bilanciate in modo che ogni job resti piccolo senza riservare runner in eccesso: i contratti dei canali vengono eseguiti come tre shard pesati, i test dei plugin bundled vengono bilanciati su sei worker di estensione, le piccole corsie unitarie core sono abbinate, auto-reply viene eseguito su tre worker bilanciati invece di sei worker minuscoli, e le configurazioni agentiche gateway/plugin sono distribuite sui job Node agentici solo-sorgente esistenti invece di aspettare gli artifact compilati. I test estesi di browser, QA, media e plugin vari usano le loro configurazioni Vitest dedicate invece del catch-all condiviso dei plugin. L'ampia corsia agents usa lo scheduler shared Vitest file-parallel perché è dominata da import/scheduling piuttosto che da un singolo file di test lento. `runtime-config` viene eseguito con lo shard infra core-runtime per evitare che lo shard runtime condiviso possieda la coda finale. `check-additional` mantiene insieme il lavoro compile/canary dei package-boundary e separa l'architettura della topologia runtime dalla copertura gateway watch; lo shard boundary guard esegue in concorrenza i suoi piccoli guard indipendenti all'interno di un unico job. Gateway watch, test dei canali e lo shard core support-boundary vengono eseguiti in concorrenza all'interno di `build-artifacts` dopo che `dist/` e `dist-runtime/` sono già stati compilati, mantenendo i loro vecchi nomi di check come job verificatori leggeri, evitando però due worker Blacksmith aggiuntivi e una seconda coda di consumer degli artifact. +La CI Android esegue sia `testPlayDebugUnitTest` sia `testThirdPartyDebugUnitTest`, poi compila l'APK debug Play. La variante third-party non ha un source set o manifest separato; la sua corsia di test unitari compila comunque quella variante con i flag SMS/call-log di BuildConfig, evitando però un job duplicato di packaging dell'APK debug a ogni push rilevante per Android. +`extension-fast` è solo PR perché le esecuzioni su push eseguono già gli shard completi dei plugin bundled. Questo mantiene un feedback rapido sui plugin modificati per le review senza riservare un worker Blacksmith aggiuntivo su `main` per una copertura già presente in `checks-node-extensions`. -GitHub può contrassegnare come `cancelled` i job superati quando arriva un push più recente sullo stesso ref PR o `main`. Consideralo rumore della CI, a meno che anche l'esecuzione più recente per lo stesso ref non stia fallendo. I check shard aggregati usano `!cancelled() && always()` così riportano comunque i normali errori degli shard, ma non si mettono in coda dopo che l'intero workflow è già stato superato. -La chiave di concorrenza CI è versionata (`CI-v7-*`) così uno zombie lato GitHub in un vecchio gruppo di coda non può bloccare indefinitamente le esecuzioni più recenti su main. +GitHub può contrassegnare i job sostituiti come `cancelled` quando arriva un push più recente sullo stesso ref PR o `main`. Consideralo rumore della CI a meno che anche l'esecuzione più recente per lo stesso ref non stia fallendo. I check shard aggregati usano `!cancelled() && always()` così riportano comunque i normali errori degli shard ma non si mettono in coda dopo che l'intero workflow è già stato sostituito. +La chiave di concorrenza CI è versionata (`CI-v7-*`) così uno zombie lato GitHub in un vecchio gruppo di coda non può bloccare indefinitamente le nuove esecuzioni su main. ## Runner -| Runner | Job | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ubuntu-24.04` | `preflight`, job e aggregati di sicurezza rapidi (`security-scm-fast`, `security-dependency-audit`, `security-fast`), controlli rapidi protocol/contract/bundled, controlli sharded dei contratti dei canali, shard `check` tranne lint, shard e aggregati `check-additional`, verificatori aggregati dei test Node, controlli docs, Skills Python, workflow-sanity, labeler, auto-response; anche il preflight install-smoke usa Ubuntu ospitato da GitHub così la matrice Blacksmith può mettersi in coda prima | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard di test Linux Node, shard di test dei bundled plugin, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, che resta abbastanza sensibile alla CPU da far costare di più 8 vCPU rispetto a quanto facesse risparmiare; build Docker install-smoke, dove il tempo di coda a 32 vCPU costava più di quanto facesse risparmiare | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` su `openclaw/openclaw`; i fork fanno fallback a `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` su `openclaw/openclaw`; i fork fanno fallback a `macos-latest` | +| Runner | Job | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, job di sicurezza rapidi e aggregati (`security-scm-fast`, `security-dependency-audit`, `security-fast`), controlli rapidi protocol/contract/bundled, controlli shardizzati dei contratti dei canali, shard `check` tranne lint, shard e aggregati `check-additional`, verificatori aggregati dei test Node, controlli della documentazione, Skills Python, workflow-sanity, labeler, auto-response; anche il preflight di install-smoke usa Ubuntu ospitato da GitHub così la matrice Blacksmith può mettersi in coda prima | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard dei test Linux Node, shard dei test dei plugin bundled, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, che resta abbastanza sensibile alla CPU da far costare di più 8 vCPU rispetto a quanto facevano risparmiare; build Docker di install-smoke, dove il tempo di coda di 32 vCPU costava più di quanto faceva risparmiare | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` su `openclaw/openclaw`; i fork ricadono su `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` su `openclaw/openclaw`; i fork ricadono su `macos-latest` | ## Equivalenti locali ```bash -pnpm changed:lanes # ispeziona il classificatore locale delle lane modificate per origin/main...HEAD -pnpm check:changed # gate locale intelligente: typecheck/lint/test modificati per lane di boundary -pnpm check # gate locale rapido: tsgo di produzione + lint sharded + guard rapidi in parallelo +pnpm changed:lanes # ispeziona il classificatore locale delle corsie modificate per origin/main...HEAD +pnpm check:changed # gate locale intelligente: typecheck/lint/test modificati per corsia di boundary +pnpm check # gate locale rapido: tsgo di produzione + lint shardizzato + guard rapidi in parallelo pnpm check:test-types -pnpm check:timed # stesso gate con tempistiche per fase +pnpm check:timed # stesso gate con temporizzazioni per fase pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression @@ -102,6 +102,7 @@ pnpm test # test vitest pnpm test:channels pnpm test:contracts:channels pnpm check:docs # formato docs + lint + link interrotti -pnpm build # compila dist quando le lane CI artifact/build-smoke sono rilevanti -node scripts/ci-run-timings.mjs # riassume il tempo totale, il tempo di coda e i job più lenti +pnpm build # compila dist quando contano le corsie CI artifact/build-smoke +node scripts/ci-run-timings.mjs # riepiloga wall time, tempo di coda e job più lenti +node scripts/ci-run-timings.mjs --recent 10 # confronta le recenti esecuzioni CI riuscite su main ``` diff --git a/docs/it/gateway/authentication.md b/docs/it/gateway/authentication.md index f7239a14c..2f1be6a2c 100644 --- a/docs/it/gateway/authentication.md +++ b/docs/it/gateway/authentication.md @@ -1,45 +1,45 @@ --- read_when: - Debug dell'autenticazione del modello o della scadenza di OAuth - - Documentazione dell'autenticazione o dell'archiviazione delle credenziali -summary: 'Autenticazione dei modelli: OAuth, chiavi API, riutilizzo di Claude CLI e setup-token di Anthropic' + - Documentare l'autenticazione o l'archiviazione delle credenziali +summary: 'Autenticazione del modello: OAuth, chiavi API, riutilizzo della CLI di Claude e token di configurazione di Anthropic' title: Autenticazione x-i18n: - generated_at: "2026-04-07T08:12:42Z" + generated_at: "2026-04-23T14:55:08Z" model: gpt-5.4 provider: openai - source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231 + source_hash: 37a7c20872b915d1d079f0578c933e43cbdb97eca1c60d8c4e6e5137ca83f8b2 source_path: gateway/authentication.md workflow: 15 --- -# Autenticazione (provider di modelli) +# Autenticazione (Provider di modelli) -Questa pagina copre l'autenticazione dei **provider di modelli** (chiavi API, OAuth, riutilizzo di Claude CLI e setup-token di Anthropic). Per l'autenticazione della **connessione gateway** (token, password, trusted-proxy), vedi [Configurazione](/it/gateway/configuration) e [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth). +Questa pagina copre l'autenticazione dei **provider di modelli** (chiavi API, OAuth, riutilizzo della CLI di Claude e token di configurazione di Anthropic). Per l'autenticazione della **connessione Gateway** (token, password, trusted-proxy), vedi [Configurazione](/it/gateway/configuration) e [Autenticazione Trusted Proxy](/it/gateway/trusted-proxy-auth). -OpenClaw supporta OAuth e chiavi API per i provider di modelli. Per host gateway sempre attivi, le chiavi API sono in genere l'opzione più prevedibile. Sono supportati anche i flussi di sottoscrizione/OAuth quando corrispondono al modello di account del provider. +OpenClaw supporta OAuth e le chiavi API per i provider di modelli. Per host Gateway sempre attivi, le chiavi API sono di solito l'opzione più prevedibile. Anche i flussi subscription/OAuth sono supportati quando corrispondono al modello di account del tuo provider. Vedi [/concepts/oauth](/it/concepts/oauth) per il flusso OAuth completo e il layout di archiviazione. Per l'autenticazione basata su SecretRef (provider `env`/`file`/`exec`), vedi [Gestione dei segreti](/it/gateway/secrets). -Per le regole di idoneità delle credenziali e dei codici motivo usate da `models status --probe`, vedi [Semantica delle credenziali di autenticazione](/it/auth-credential-semantics). +Per le regole di idoneità delle credenziali/codici motivo usate da `models status --probe`, vedi [Semantica delle credenziali di autenticazione](/it/auth-credential-semantics). ## Configurazione consigliata (chiave API, qualsiasi provider) -Se stai eseguendo un gateway di lunga durata, inizia con una chiave API per il provider scelto. -Per Anthropic in particolare, l'autenticazione con chiave API resta la configurazione server più prevedibile, ma OpenClaw supporta anche il riutilizzo di un accesso locale a Claude CLI. +Se stai eseguendo un Gateway di lunga durata, inizia con una chiave API per il provider scelto. +Per Anthropic in particolare, l'autenticazione con chiave API rimane la configurazione server più prevedibile, ma OpenClaw supporta anche il riutilizzo di un accesso locale alla CLI di Claude. 1. Crea una chiave API nella console del tuo provider. -2. Inseriscila sull'**host gateway** (la macchina che esegue `openclaw gateway`). +2. Inseriscila sull'**host Gateway** (la macchina che esegue `openclaw gateway`). ```bash export _API_KEY="..." openclaw models status ``` -3. Se il Gateway viene eseguito sotto systemd/launchd, è preferibile inserire la chiave in - `~/.openclaw/.env` in modo che il demone possa leggerla: +3. Se il Gateway viene eseguito sotto systemd/launchd, preferisci inserire la chiave in + `~/.openclaw/.env` così il demone può leggerla: ```bash cat >> ~/.openclaw/.env <<'EOF' @@ -47,39 +47,56 @@ cat >> ~/.openclaw/.env <<'EOF' EOF ``` -Poi riavvia il demone (oppure riavvia il tuo processo Gateway) e ricontrolla: +Poi riavvia il demone (o riavvia il processo Gateway) e ricontrolla: ```bash openclaw models status openclaw doctor ``` -Se preferisci non gestire tu stesso le variabili d'ambiente, l'onboarding può archiviare -le chiavi API per l'uso da parte del demone: `openclaw onboard`. +Se preferisci non gestire tu stesso le variabili env, l'onboarding può archiviare +le chiavi API per l'uso del demone: `openclaw onboard`. -Vedi [Guida](/it/help) per i dettagli sull'ereditarietà dell'ambiente (`env.shellEnv`, +Vedi [Aiuto](/it/help) per i dettagli sull'ereditarietà env (`env.shellEnv`, `~/.openclaw/.env`, systemd/launchd). -## Anthropic: compatibilità tra Claude CLI e token +## Anthropic: compatibilità tra CLI di Claude e token -L'autenticazione Anthropic setup-token è ancora disponibile in OpenClaw come percorso token supportato. Da allora, il personale Anthropic ci ha comunicato che l'uso di Claude CLI in stile OpenClaw è nuovamente consentito, quindi OpenClaw considera il riutilizzo di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. Quando il riutilizzo di Claude CLI è disponibile sull'host, questo è ora il percorso preferito. +L'autenticazione con token di configurazione Anthropic è ancora disponibile in OpenClaw come percorso token supportato. Da allora, lo staff di Anthropic ci ha detto che l'uso della CLI di Claude nello stile di OpenClaw è di nuovo consentito, quindi OpenClaw considera il riutilizzo della CLI di Claude e l'uso di `claude -p` come autorizzati per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. Quando il riutilizzo della CLI di Claude è disponibile sull'host, questo è ora il percorso preferito. -Per host gateway di lunga durata, una chiave API Anthropic resta comunque la configurazione più prevedibile. -Se vuoi riutilizzare un accesso Claude esistente sullo stesso host, usa il percorso Anthropic Claude CLI in onboarding/configure. +Per host Gateway di lunga durata, una chiave API Anthropic rimane comunque la configurazione più prevedibile. Se vuoi riutilizzare un login Claude esistente sullo stesso host, usa il percorso Anthropic Claude CLI in onboarding/configure. -Inserimento manuale del token (qualsiasi provider; scrive `auth-profiles.json` e aggiorna la configurazione): +Configurazione host consigliata per il riutilizzo della CLI di Claude: + +```bash +# Esegui sull'host Gateway +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Questa è una configurazione in due passaggi: + +1. Fai accedere Claude Code stesso ad Anthropic sull'host Gateway. +2. Indica a OpenClaw di passare la selezione del modello Anthropic al backend locale `claude-cli` + e di archiviare il profilo di autenticazione OpenClaw corrispondente. + +Se `claude` non è in `PATH`, installa prima Claude Code oppure imposta +`agents.defaults.cliBackends.claude-cli.command` sul percorso reale del binario. + +Inserimento manuale del token (qualsiasi provider; scrive `auth-profiles.json` + aggiorna la configurazione): ```bash openclaw models auth paste-token --provider openrouter ``` -Sono supportati anche riferimenti a profili auth per credenziali statiche: +Sono supportati anche i riferimenti ai profili di autenticazione per credenziali statiche: - le credenziali `api_key` possono usare `keyRef: { source, provider, id }` - le credenziali `token` possono usare `tokenRef: { source, provider, id }` -- i profili in modalità OAuth non supportano credenziali SecretRef; se `auth.profiles..mode` è impostato su `"oauth"`, l'input `keyRef`/`tokenRef` supportato da SecretRef per quel profilo viene rifiutato. +- i profili in modalità OAuth non supportano credenziali SecretRef; se `auth.profiles..mode` è impostato su `"oauth"`, l'input `keyRef`/`tokenRef` basato su SecretRef per quel profilo viene rifiutato. -Controllo adatto all'automazione (uscita `1` se scaduto/mancante, `2` se in scadenza): +Controllo adatto all'automazione (uscita `1` quando mancante/scaduto, `2` quando in scadenza): ```bash openclaw models status --check @@ -93,38 +110,38 @@ openclaw models status --probe Note: -- Le righe della probe possono provenire da profili auth, credenziali env o `models.json`. -- Se `auth.order.` esplicito omette un profilo archiviato, la probe riporta +- Le righe di probe possono provenire da profili di autenticazione, credenziali env o `models.json`. +- Se `auth.order.` esplicito omette un profilo archiviato, probe riporta `excluded_by_auth_order` per quel profilo invece di provarlo. -- Se l'autenticazione esiste ma OpenClaw non riesce a risolvere un candidato di modello sondabile per - quel provider, la probe riporta `status: no_model`. -- I cooldown del rate limit possono essere limitati al modello. Un profilo in cooldown per un - modello può comunque essere utilizzabile per un modello correlato dello stesso provider. +- Se l'autenticazione esiste ma OpenClaw non riesce a risolvere un candidato di modello interrogabile per + quel provider, probe riporta `status: no_model`. +- I cooldown del rate limit possono essere specifici per modello. Un profilo in cooldown per un + modello può essere ancora utilizzabile per un modello fratello sullo stesso provider. -Gli script operativi facoltativi (systemd/Termux) sono documentati qui: +Gli script operativi opzionali (systemd/Termux) sono documentati qui: [Script di monitoraggio dell'autenticazione](/it/help/scripts#auth-monitoring-scripts) ## Nota su Anthropic Il backend Anthropic `claude-cli` è di nuovo supportato. -- Il personale Anthropic ci ha comunicato che questo percorso di integrazione OpenClaw è nuovamente consentito. -- OpenClaw quindi considera il riutilizzo di Claude CLI e l'uso di `claude -p` come autorizzati - per esecuzioni basate su Anthropic, a meno che Anthropic non pubblichi una nuova policy. -- Le chiavi API Anthropic restano la scelta più prevedibile per host gateway +- Lo staff di Anthropic ci ha detto che questo percorso di integrazione di OpenClaw è di nuovo consentito. +- OpenClaw quindi considera il riutilizzo della CLI di Claude e l'uso di `claude -p` come autorizzati + per esecuzioni supportate da Anthropic, a meno che Anthropic non pubblichi una nuova policy. +- Le chiavi API Anthropic restano la scelta più prevedibile per host Gateway di lunga durata e per un controllo esplicito della fatturazione lato server. -## Verifica dello stato di autenticazione del modello +## Verifica dello stato dell'autenticazione del modello ```bash openclaw models status openclaw doctor ``` -## Comportamento di rotazione delle chiavi API (gateway) +## Comportamento della rotazione delle chiavi API (Gateway) Alcuni provider supportano il nuovo tentativo di una richiesta con chiavi alternative quando una chiamata API -incontra un limite di frequenza del provider. +raggiunge un rate limit del provider. - Ordine di priorità: - `OPENCLAW_LIVE__KEY` (singolo override) @@ -133,24 +150,24 @@ incontra un limite di frequenza del provider. - `_API_KEY_*` - I provider Google includono anche `GOOGLE_API_KEY` come fallback aggiuntivo. - Lo stesso elenco di chiavi viene deduplicato prima dell'uso. -- OpenClaw riprova con la chiave successiva solo per errori di rate limit (per esempio +- OpenClaw ritenta con la chiave successiva solo per errori di rate limit (per esempio `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, o `workers_ai ... quota limit exceeded`). -- Gli errori non legati al rate limit non vengono ritentati con chiavi alternative. +- Gli errori non dovuti a rate limit non vengono ritentati con chiavi alternative. - Se tutte le chiavi falliscono, viene restituito l'errore finale dell'ultimo tentativo. ## Controllare quale credenziale viene usata ### Per sessione (comando chat) -Usa `/model @` per fissare una credenziale provider specifica per la sessione corrente (esempi di ID profilo: `anthropic:default`, `anthropic:work`). +Usa `/model @` per fissare una credenziale provider specifica per la sessione corrente (esempio di id profilo: `anthropic:default`, `anthropic:work`). -Usa `/model` (o `/model list`) per un selettore compatto; usa `/model status` per la vista completa (candidati + profilo auth successivo, più dettagli dell'endpoint provider quando configurati). +Usa `/model` (o `/model list`) per un selettore compatto; usa `/model status` per la vista completa (candidati + profilo di autenticazione successivo, oltre ai dettagli dell'endpoint provider quando configurati). ### Per agente (override CLI) -Imposta un override esplicito dell'ordine dei profili auth per un agente (archiviato nell'`auth-state.json` di quell'agente): +Imposta un override esplicito dell'ordine dei profili di autenticazione per un agente (archiviato nel `auth-state.json` di quell'agente): ```bash openclaw models auth order get --provider anthropic @@ -159,16 +176,17 @@ openclaw models auth order clear --provider anthropic ``` Usa `--agent ` per indirizzare un agente specifico; omettilo per usare l'agente predefinito configurato. -Quando esegui il debug di problemi di ordine, `openclaw models status --probe` mostra i profili -archiviati omessi come `excluded_by_auth_order` invece di saltarli silenziosamente. -Quando esegui il debug di problemi di cooldown, ricorda che i cooldown del rate limit possono essere associati -a un ID modello invece che all'intero profilo provider. +Quando esegui il debug di problemi di ordine, `openclaw models status --probe` mostra i +profili archiviati omessi come `excluded_by_auth_order` invece di saltarli in silenzio. +Quando esegui il debug di problemi di cooldown, ricorda che i cooldown del rate limit possono essere legati +a un id modello anziché all'intero profilo provider. ## Risoluzione dei problemi ### "No credentials found" -Se il profilo Anthropic manca, configura una chiave API Anthropic sull'**host gateway** oppure imposta il percorso setup-token di Anthropic, poi ricontrolla: +Se il profilo Anthropic manca, configura una chiave API Anthropic sull'**host Gateway** +oppure imposta il percorso del token di configurazione Anthropic, poi ricontrolla: ```bash openclaw models status @@ -177,5 +195,5 @@ openclaw models status ### Token in scadenza/scaduto Esegui `openclaw models status` per confermare quale profilo è in scadenza. Se un -profilo token Anthropic manca o è scaduto, aggiorna tale configurazione tramite -setup-token oppure passa a una chiave API Anthropic. +profilo token Anthropic manca o è scaduto, aggiorna quella configurazione tramite +token di configurazione oppure migra a una chiave API Anthropic. diff --git a/docs/it/gateway/cli-backends.md b/docs/it/gateway/cli-backends.md index db8ddb9c8..ec67fca57 100644 --- a/docs/it/gateway/cli-backends.md +++ b/docs/it/gateway/cli-backends.md @@ -1,15 +1,15 @@ --- read_when: - - Vuoi un fallback affidabile quando i provider API falliscono + - Vuoi un fallback affidabile quando i provider API non funzionano - Stai eseguendo Codex CLI o altre CLI AI locali e vuoi riutilizzarle - - Vuoi capire il bridge MCP loopback per l'accesso agli strumenti del backend CLI -summary: 'Backend CLI: fallback CLI AI locale con bridge degli strumenti MCP facoltativo' + - Vuoi capire il bridge MCP local loopback per l'accesso agli strumenti del backend CLI +summary: 'Backend CLI: fallback della CLI AI locale con bridge strumenti MCP opzionale' title: Backend CLI x-i18n: - generated_at: "2026-04-23T08:28:23Z" + generated_at: "2026-04-23T14:55:08Z" model: gpt-5.4 provider: openai - source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e + source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316 source_path: gateway/cli-backends.md workflow: 15 --- @@ -17,31 +17,31 @@ x-i18n: # Backend CLI (runtime di fallback) OpenClaw può eseguire **CLI AI locali** come **fallback solo testo** quando i provider API non sono disponibili, -sono soggetti a rate limit o si comportano male temporaneamente. Si tratta intenzionalmente di una soluzione conservativa: +sono soggetti a limitazioni di frequenza o si comportano temporaneamente in modo anomalo. Si tratta intenzionalmente di una soluzione conservativa: -- **Gli strumenti OpenClaw non vengono iniettati direttamente**, ma i backend con `bundleMcp: true` - possono ricevere strumenti gateway tramite un bridge MCP loopback. +- **Gli strumenti di OpenClaw non vengono iniettati direttamente**, ma i backend con `bundleMcp: true` + possono ricevere gli strumenti del gateway tramite un bridge MCP local loopback. - **Streaming JSONL** per le CLI che lo supportano. -- **Le sessioni sono supportate** (così i turni di follow-up restano coerenti). -- **Le immagini possono essere inoltrate** se la CLI accetta percorsi immagine. +- **Le sessioni sono supportate** (quindi i turni successivi restano coerenti). +- **Le immagini possono essere inoltrate** se la CLI accetta percorsi di immagini. -Questo è progettato come **rete di sicurezza** piuttosto che come percorso primario. Usalo quando -vuoi risposte testuali “sempre funzionanti” senza dipendere da API esterne. +Questo è progettato come **rete di sicurezza** piuttosto che come percorso principale. Usalo quando +vuoi risposte testuali che “funzionano sempre” senza fare affidamento su API esterne. Se vuoi un runtime harness completo con controlli di sessione ACP, attività in background, -associazione di thread/conversazioni e sessioni di coding esterne persistenti, usa invece +associazione thread/conversazione e sessioni di coding esterne persistenti, usa [ACP Agents](/it/tools/acp-agents). I backend CLI non sono ACP. -## Avvio rapido per principianti +## Guida rapida per principianti -Puoi usare Codex CLI **senza alcuna config** (il Plugin OpenAI incluso +Puoi usare Codex CLI **senza alcuna configurazione** (il Plugin OpenAI incluso registra un backend predefinito): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Se il tuo gateway viene eseguito sotto launchd/systemd e il PATH è minimo, aggiungi solo il +Se il tuo gateway viene eseguito sotto launchd/systemd e PATH è minimale, aggiungi solo il percorso del comando: ```json5 @@ -58,16 +58,16 @@ percorso del comando: } ``` -Questo è tutto. Nessuna chiave, nessuna config di autenticazione extra oltre a quella della CLI stessa. +Questo è tutto. Non sono necessarie chiavi né configurazioni di autenticazione aggiuntive oltre a quelle della CLI stessa. -Se usi un backend CLI incluso come **provider di messaggi primario** su un -host gateway, OpenClaw ora carica automaticamente il Plugin incluso proprietario quando la tua config -fa riferimento esplicito a quel backend in un riferimento modello o sotto +Se usi un backend CLI incluso come **provider di messaggi principale** su un +host gateway, OpenClaw ora carica automaticamente il Plugin incluso proprietario quando la tua configurazione +fa esplicito riferimento a quel backend in un model ref o sotto `agents.defaults.cliBackends`. -## Usarlo come fallback +## Utilizzarlo come fallback -Aggiungi un backend CLI al tuo elenco di fallback in modo che venga eseguito solo quando i modelli primari falliscono: +Aggiungi un backend CLI al tuo elenco di fallback in modo che venga eseguito solo quando i modelli primari non riescono: ```json5 { @@ -89,8 +89,8 @@ Aggiungi un backend CLI al tuo elenco di fallback in modo che venga eseguito sol Note: - Se usi `agents.defaults.models` (allowlist), devi includere anche lì i modelli del tuo backend CLI. -- Se il provider primario fallisce (autenticazione, rate limit, timeout), OpenClaw - proverà successivamente il backend CLI. +- Se il provider primario non funziona (autenticazione, limiti di frequenza, timeout), OpenClaw + proverà poi il backend CLI. ## Panoramica della configurazione @@ -101,7 +101,7 @@ agents.defaults.cliBackends ``` Ogni voce è indicizzata da un **id provider** (ad esempio `codex-cli`, `my-cli`). -L'id provider diventa la parte sinistra del tuo riferimento modello: +L'id provider diventa il lato sinistro del tuo model ref: ``` / @@ -148,87 +148,100 @@ L'id provider diventa la parte sinistra del tuo riferimento modello: ## Come funziona 1. **Seleziona un backend** in base al prefisso del provider (`codex-cli/...`). -2. **Costruisce un prompt di sistema** usando lo stesso prompt + contesto workspace di OpenClaw. -3. **Esegue la CLI** con un ID sessione (se supportato) così la cronologia resta coerente. - Il backend incluso `claude-cli` mantiene vivo un processo Claude stdio per - sessione OpenClaw e invia i turni di follow-up tramite stdin stream-json. +2. **Costruisce un system prompt** usando lo stesso prompt OpenClaw + il contesto del workspace. +3. **Esegue la CLI** con un id sessione (se supportato) in modo che la cronologia resti coerente. + Il backend `claude-cli` incluso mantiene attivo un processo Claude stdio per ogni + sessione OpenClaw e invia i turni successivi tramite stream-json su stdin. 4. **Analizza l'output** (JSON o testo semplice) e restituisce il testo finale. -5. **Rende persistenti gli ID sessione** per backend, così i follow-up riutilizzano la stessa sessione CLI. +5. **Mantiene gli id sessione** per backend, in modo che i turni successivi riutilizzino la stessa sessione CLI. -Il backend incluso Anthropic `claude-cli` è di nuovo supportato. Lo staff Anthropic -ci ha detto che l'uso di Claude CLI in stile OpenClaw è di nuovo consentito, quindi OpenClaw tratta -l'uso di `claude -p` come autorizzato per questa integrazione, salvo che Anthropic pubblichi +Il backend Anthropic `claude-cli` incluso è di nuovo supportato. Il personale Anthropic +ci ha detto che l'uso di Claude CLI in stile OpenClaw è di nuovo consentito, quindi OpenClaw considera +l'uso di `claude -p` come autorizzato per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. -Il backend incluso OpenAI `codex-cli` passa il prompt di sistema di OpenClaw tramite -l'override di config `model_instructions_file` di Codex (`-c +Il backend OpenAI `codex-cli` incluso passa il system prompt di OpenClaw tramite +l'override della configurazione `model_instructions_file` di Codex (`-c model_instructions_file="..."`). Codex non espone un flag in stile Claude `--append-system-prompt`, quindi OpenClaw scrive il prompt assemblato in un file temporaneo per ogni nuova sessione Codex CLI. -Il backend incluso Anthropic `claude-cli` riceve lo snapshot delle Skills OpenClaw -in due modi: il catalogo compatto delle Skills OpenClaw nel prompt di sistema aggiunto, e +Il backend Anthropic `claude-cli` incluso riceve lo snapshot delle Skills di OpenClaw +in due modi: il catalogo compatto delle Skills di OpenClaw nel system prompt aggiunto, e un Plugin Claude Code temporaneo passato con `--plugin-dir`. Il Plugin contiene -solo le skill idonee per quell'agente/sessione, quindi il resolver di skill nativo di Claude Code -vede lo stesso insieme filtrato che OpenClaw altrimenti pubblicizzerebbe nel prompt. -Gli override di env/API key delle skill vengono comunque applicati da OpenClaw all'ambiente del processo figlio per l'esecuzione. +solo le Skills idonee per quell'agente/sessione, quindi il resolver nativo delle skill di Claude Code +vede lo stesso insieme filtrato che altrimenti OpenClaw pubblicizzerebbe nel +prompt. Le sostituzioni di env/chiavi API delle skill vengono comunque applicate da OpenClaw all'ambiente +del processo figlio per l'esecuzione. + +Prima che OpenClaw possa usare il backend `claude-cli` incluso, Claude Code stesso +deve già aver effettuato l'accesso sullo stesso host: + +```bash +claude auth login +claude auth status --text +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Usa `agents.defaults.cliBackends.claude-cli.command` solo quando il binario `claude` +non è già in `PATH`. ## Sessioni -- Se la CLI supporta le sessioni, imposta `sessionArg` (ad esempio `--session-id`) oppure +- Se la CLI supporta le sessioni, imposta `sessionArg` (ad esempio `--session-id`) o `sessionArgs` (segnaposto `{sessionId}`) quando l'ID deve essere inserito in più flag. -- Se la CLI usa un **sottocomando di ripresa** con flag diversi, imposta - `resumeArgs` (sostituisce `args` durante la ripresa) e facoltativamente `resumeOutput` +- Se la CLI usa un **sottocomando resume** con flag diversi, imposta + `resumeArgs` (sostituisce `args` alla ripresa) e facoltativamente `resumeOutput` (per riprese non JSON). - `sessionMode`: - - `always`: invia sempre un ID sessione (nuovo UUID se non ne è stato salvato nessuno). - - `existing`: invia un ID sessione solo se ne era già stato salvato uno. - - `none`: non invia mai un ID sessione. -- `claude-cli` usa come valori predefiniti `liveSession: "claude-stdio"`, `output: "jsonl"`, - e `input: "stdin"` così i turni di follow-up riutilizzano il processo Claude attivo - mentre è attivo. Lo stdio caldo è ora il valore predefinito, anche per config personalizzate + - `always`: invia sempre un id sessione (nuovo UUID se non ne è memorizzato nessuno). + - `existing`: invia un id sessione solo se ne era già stato memorizzato uno. + - `none`: non invia mai un id sessione. +- `claude-cli` usa per impostazione predefinita `liveSession: "claude-stdio"`, `output: "jsonl"`, + e `input: "stdin"` in modo che i turni successivi riutilizzino il processo Claude attivo mentre + è attivo. Lo stdio warm è ora il comportamento predefinito, anche per configurazioni personalizzate che omettono i campi di trasporto. Se il Gateway si riavvia o il processo inattivo termina, - OpenClaw riprende dall'ID sessione Claude memorizzato. Gli ID sessione memorizzati vengono verificati - rispetto a una trascrizione di progetto esistente e leggibile prima della ripresa, così - le associazioni fantasma vengono cancellate con `reason=transcript-missing` + OpenClaw riprende dall'id sessione Claude memorizzato. Gli id sessione memorizzati vengono verificati + rispetto a una trascrizione di progetto esistente e leggibile prima della ripresa, così i binding fantasma + vengono eliminati con `reason=transcript-missing` invece di avviare silenziosamente una nuova sessione Claude CLI con `--resume`. -- Le sessioni CLI memorizzate sono continuità gestita dal provider. Il reset giornaliero implicito +- Le sessioni CLI memorizzate sono continuità di proprietà del provider. Il reset giornaliero implicito non le interrompe; `/reset` e le policy esplicite `session.reset` sì. Note sulla serializzazione: -- `serialize: true` mantiene ordinate le esecuzioni sulla stessa corsia. -- La maggior parte delle CLI serializza su una corsia provider. -- OpenClaw interrompe il riutilizzo delle sessioni CLI memorizzate quando cambia l'identità di autenticazione selezionata, - inclusi un ID profilo auth cambiato, una API key statica, un token statico o l'identità - dell'account OAuth quando la CLI ne espone una. La rotazione dei token OAuth di accesso e refresh - non interrompe la sessione CLI memorizzata. Se una CLI non espone un ID account OAuth stabile, - OpenClaw lascia che sia quella CLI a far rispettare i permessi di ripresa. +- `serialize: true` mantiene ordinate le esecuzioni sulla stessa lane. +- La maggior parte delle CLI serializza su una lane provider. +- OpenClaw interrompe il riutilizzo della sessione CLI memorizzata quando cambia l'identità di autenticazione selezionata, + incluso un id profilo di autenticazione cambiato, una chiave API statica, un token statico o + l'identità dell'account OAuth quando la CLI la espone. La rotazione del token di accesso e refresh OAuth + non interrompe la sessione CLI memorizzata. Se una CLI non espone un id account OAuth stabile, + OpenClaw lascia che sia quella CLI a imporre i permessi di ripresa. -## Immagini (pass-through) +## Immagini (inoltro diretto) -Se la tua CLI accetta percorsi immagine, imposta `imageArg`: +Se la tua CLI accetta percorsi di immagini, imposta `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw scriverà le immagini base64 in file temporanei. Se `imageArg` è impostato, quei +OpenClaw scriverà le immagini base64 in file temporanei. Se `imageArg` è impostato, tali percorsi vengono passati come argomenti CLI. Se `imageArg` manca, OpenClaw aggiunge i -percorsi file al prompt (path injection), che è sufficiente per le CLI che caricano automaticamente -file locali da percorsi semplici. +percorsi dei file al prompt (path injection), il che è sufficiente per le CLI che caricano automaticamente +i file locali da semplici percorsi. ## Input / output -- `output: "json"` (predefinito) prova ad analizzare JSON e a estrarre testo + ID sessione. +- `output: "json"` (predefinito) prova ad analizzare JSON ed estrarre testo + id sessione. - Per l'output JSON di Gemini CLI, OpenClaw legge il testo della risposta da `response` e l'uso da `stats` quando `usage` manca o è vuoto. -- `output: "jsonl"` analizza stream JSONL (ad esempio Codex CLI `--json`) ed estrae il messaggio finale dell'agente più gli identificatori di sessione - quando presenti. +- `output: "jsonl"` analizza flussi JSONL (ad esempio Codex CLI `--json`) ed estrae il messaggio finale dell'agente più gli identificatori + di sessione quando presenti. - `output: "text"` tratta stdout come risposta finale. Modalità di input: @@ -237,7 +250,7 @@ Modalità di input: - `input: "stdin"` invia il prompt tramite stdin. - Se il prompt è molto lungo e `maxPromptArgChars` è impostato, viene usato stdin. -## Valori predefiniti (gestiti dal Plugin) +## Valori predefiniti (di proprietà del Plugin) Il Plugin OpenAI incluso registra anche un valore predefinito per `codex-cli`: @@ -262,31 +275,31 @@ Il Plugin Google incluso registra anche un valore predefinito per `google-gemini - `sessionIdFields: ["session_id", "sessionId"]` Prerequisito: la Gemini CLI locale deve essere installata e disponibile come -`gemini` nel `PATH` (`brew install gemini-cli` o +`gemini` in `PATH` (`brew install gemini-cli` oppure `npm install -g @google/gemini-cli`). -Note JSON di Gemini CLI: +Note JSON per Gemini CLI: - Il testo della risposta viene letto dal campo JSON `response`. -- L'uso ricade su `stats` quando `usage` è assente o vuoto. +- L'uso usa `stats` come fallback quando `usage` è assente o vuoto. - `stats.cached` viene normalizzato in `cacheRead` di OpenClaw. - Se `stats.input` manca, OpenClaw ricava i token di input da `stats.input_tokens - stats.cached`. Esegui override solo se necessario (caso comune: percorso `command` assoluto). -## Valori predefiniti gestiti dal Plugin +## Valori predefiniti di proprietà del Plugin -I valori predefiniti del backend CLI fanno ora parte della surface del Plugin: +I valori predefiniti del backend CLI ora fanno parte della superficie del Plugin: -- I plugin li registrano con `api.registerCliBackend(...)`. -- Il `id` del backend diventa il prefisso provider nei riferimenti modello. -- La config utente in `agents.defaults.cliBackends.` continua a sovrascrivere il valore predefinito del Plugin. -- La pulizia della config specifica del backend resta gestita dal Plugin tramite l'hook facoltativo - `normalizeConfig`. +- I Plugin li registrano con `api.registerCliBackend(...)`. +- L'`id` del backend diventa il prefisso provider nei model ref. +- La configurazione utente in `agents.defaults.cliBackends.` continua a sovrascrivere il valore predefinito del Plugin. +- La pulizia della configurazione specifica del backend resta di proprietà del Plugin tramite + l'hook facoltativo `normalizeConfig`. -I plugin che hanno bisogno di piccoli shim di compatibilità prompt/messaggio possono dichiarare -trasformazioni testuali bidirezionali senza sostituire un provider o un backend CLI: +I Plugin che hanno bisogno di piccoli shim di compatibilità per prompt/messaggi possono dichiarare +trasformazioni bidirezionali del testo senza sostituire un provider o un backend CLI: ```typescript api.registerTextTransforms({ @@ -303,42 +316,42 @@ api.registerTextTransforms({ }); ``` -`input` riscrive il prompt di sistema e il prompt utente passati alla CLI. `output` -riscrive i delta dell'assistente in streaming e il testo finale analizzato prima che OpenClaw gestisca +`input` riscrive il system prompt e il prompt utente passati alla CLI. `output` +riscrive i delta assistant in streaming e il testo finale analizzato prima che OpenClaw gestisca i propri marker di controllo e la consegna sul canale. -Per le CLI che emettono JSONL compatibile con lo stream-json di Claude Code, imposta -`jsonlDialect: "claude-stream-json"` nella config di quel backend. +Per le CLI che emettono JSONL compatibile con stream-json di Claude Code, imposta +`jsonlDialect: "claude-stream-json"` nella configurazione di quel backend. ## Overlay MCP bundle -I backend CLI **non** ricevono direttamente chiamate agli strumenti OpenClaw, ma un backend può -abilitare una overlay di config MCP generata con `bundleMcp: true`. +I backend CLI **non** ricevono direttamente le chiamate agli strumenti di OpenClaw, ma un backend può +abilitare una overlay di configurazione MCP generata con `bundleMcp: true`. -Comportamento attualmente incluso: +Comportamento incluso attuale: -- `claude-cli`: file di config MCP strict generato -- `codex-cli`: override di config inline per `mcp_servers` +- `claude-cli`: file di configurazione MCP strict generato +- `codex-cli`: override di configurazione inline per `mcp_servers` - `google-gemini-cli`: file di impostazioni di sistema Gemini generato Quando bundle MCP è abilitato, OpenClaw: -- avvia un server MCP HTTP loopback che espone strumenti gateway al processo CLI +- avvia un server MCP HTTP local loopback che espone gli strumenti del gateway al processo CLI - autentica il bridge con un token per sessione (`OPENCLAW_MCP_TOKEN`) - limita l'accesso agli strumenti alla sessione, all'account e al contesto del canale correnti - carica i server bundle-MCP abilitati per il workspace corrente -- li unisce con qualsiasi forma di config/impostazioni MCP backend esistente -- riscrive la config di avvio usando la modalità di integrazione gestita dal backend dell'estensione proprietaria +- li unisce con qualunque configurazione/forma di impostazioni MCP del backend già esistente +- riscrive la configurazione di avvio usando la modalità di integrazione di proprietà del backend dall'estensione proprietaria -Se non è abilitato alcun server MCP, OpenClaw inietta comunque una config strict quando un -backend abilita bundle MCP così che le esecuzioni in background restino isolate. +Se non sono abilitati server MCP, OpenClaw inietta comunque una configurazione strict quando un +backend abilita bundle MCP, così le esecuzioni in background restano isolate. ## Limitazioni -- **Nessuna chiamata diretta agli strumenti OpenClaw.** OpenClaw non inietta chiamate agli strumenti nel - protocollo del backend CLI. I backend vedono gli strumenti gateway solo quando abilitano +- **Nessuna chiamata diretta agli strumenti di OpenClaw.** OpenClaw non inietta chiamate agli strumenti nel + protocollo del backend CLI. I backend vedono gli strumenti del gateway solo quando abilitano `bundleMcp: true`. -- **Lo streaming è specifico del backend.** Alcuni backend trasmettono JSONL; altri fanno buffering +- **Lo streaming è specifico del backend.** Alcuni backend trasmettono JSONL in streaming; altri accumulano fino all'uscita. - **Gli output strutturati** dipendono dal formato JSON della CLI. - **Le sessioni Codex CLI** riprendono tramite output testuale (senza JSONL), che è meno @@ -348,7 +361,7 @@ backend abilita bundle MCP così che le esecuzioni in background restino isolate ## Risoluzione dei problemi - **CLI non trovata**: imposta `command` su un percorso completo. -- **Nome modello errato**: usa `modelAliases` per mappare `provider/model` → modello CLI. +- **Nome del modello errato**: usa `modelAliases` per mappare `provider/model` → modello CLI. - **Nessuna continuità di sessione**: assicurati che `sessionArg` sia impostato e che `sessionMode` non sia - `none` (Codex CLI attualmente non può riprendere con output JSON). -- **Immagini ignorate**: imposta `imageArg` (e verifica che la CLI supporti i percorsi file). + `none` (al momento Codex CLI non può riprendere con output JSON). +- **Immagini ignorate**: imposta `imageArg` (e verifica che la CLI supporti i percorsi dei file). diff --git a/docs/it/help/testing.md b/docs/it/help/testing.md index a9c3b166f..c70f8c559 100644 --- a/docs/it/help/testing.md +++ b/docs/it/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - - Esecuzione dei test in locale o in CI - - Aggiunta di test di regressione per bug di modelli/provider - - Debug del comportamento di Gateway + agenti -summary: 'Kit di test: suite unit/e2e/live, runner Docker e cosa copre ogni test' -title: Test + - Eseguire i test in locale o in CI + - Aggiunta di regressioni per bug di modello/provider + - Debugging del comportamento di Gateway + agent +summary: 'Kit di test: suite unit/e2e/live, runner Docker e cosa copre ciascun test' +title: Test in corso x-i18n: - generated_at: "2026-04-23T13:58:01Z" + generated_at: "2026-04-23T14:55:07Z" model: gpt-5.4 provider: openai - source_hash: fe0e9bdea78cba7e512358d2e4d428da04a2071188e74af2d5419d2c85eafe15 + source_hash: fbec4996699577321116c94f60c01d205d7594ed41aca27c821f1c3d65a7dca3 source_path: help/testing.md workflow: 15 --- @@ -18,170 +18,167 @@ x-i18n: OpenClaw ha tre suite Vitest (unit/integration, e2e, live) e un piccolo insieme di runner Docker. -Questa doc è una guida al “come testiamo”: +Questa documentazione è una guida al “come testiamo”: -- Cosa copre ogni suite (e cosa deliberatamente _non_ copre) -- Quali comandi eseguire per i flussi di lavoro più comuni (locale, pre-push, debug) +- Cosa copre ciascuna suite (e cosa deliberatamente _non_ copre) +- Quali comandi eseguire per i flussi di lavoro comuni (locale, pre-push, debugging) - Come i test live individuano le credenziali e selezionano modelli/provider - Come aggiungere regressioni per problemi reali di modelli/provider ## Avvio rapido -La maggior parte dei giorni: +Nella maggior parte dei giorni: -- Gate completo (atteso prima del push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Esecuzione locale più rapida dell’intera suite su una macchina capiente: `pnpm test:max` -- Loop di watch diretto di Vitest: `pnpm test:watch` -- Il targeting diretto dei file ora instrada anche i percorsi di extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Preferisci prima le esecuzioni mirate quando stai iterando su un singolo errore. +- Gate completo (previsto prima del push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Esecuzione locale più rapida della suite completa su una macchina capiente: `pnpm test:max` +- Ciclo watch diretto di Vitest: `pnpm test:watch` +- Il targeting diretto dei file ora instrada anche i percorsi extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Quando stai iterando su un singolo errore, preferisci prima esecuzioni mirate. - Sito QA supportato da Docker: `pnpm qa:lab:up` - Lane QA supportata da VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando tocchi i test o vuoi maggiore confidenza: +Quando tocchi i test o vuoi maggiore sicurezza: -- Gate di coverage: `pnpm test:coverage` +- Gate di copertura: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` -Quando fai debug di provider/modelli reali (richiede credenziali reali): +Quando fai debugging di provider/modelli reali (richiede credenziali reali): -- Suite live (modelli + probe tool/immagini di Gateway): `pnpm test:live` -- Esegui un singolo file live in modalità silenziosa: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Sweep live dei modelli Docker: `pnpm test:docker:live-models` - - Coverage CI: il job giornaliero `OpenClaw Scheduled Live And E2E Checks` e il job manuale +- Suite live (probe di modelli + tool/immagini di Gateway): `pnpm test:live` +- Seleziona un singolo file live in modalità silenziosa: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Sweep Docker dei modelli live: `pnpm test:docker:live-models` + - Ogni modello selezionato ora esegue un turno di testo più una piccola probe in stile lettura file. + I modelli i cui metadati dichiarano input `image` eseguono anche un piccolo turno immagine. + Disabilita le probe aggiuntive con `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` o + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` quando stai isolando errori del provider. + - Copertura CI: il job giornaliero `OpenClaw Scheduled Live And E2E Checks` e il job manuale `OpenClaw Release Checks` chiamano entrambi il workflow riutilizzabile live/E2E con - `include_live_suites: true`, che include job matrix separati per i modelli live Docker + `include_live_suites: true`, che include job separati di matrice Docker live model suddivisi per provider. - Per riesecuzioni CI mirate, avvia `OpenClaw Live And E2E Checks (Reusable)` con `include_live_suites: true` e `live_models_only: true`. - - Aggiungi nuove credenziali di provider ad alto segnale a `scripts/ci-hydrate-live-auth.sh` - più `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` e i relativi chiamanti - scheduled/release. -- Smoke di costo Moonshot/Kimi: con `MOONSHOT_API_KEY` impostata, esegui - `openclaw models list --provider moonshot --json`, poi esegui un comando isolato + - Aggiungi nuovi secret provider ad alto segnale a `scripts/ci-hydrate-live-auth.sh` + più `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` e i relativi + chiamanti pianificati/di release. +- Smoke del costo Moonshot/Kimi: con `MOONSHOT_API_KEY` impostato, esegui + `openclaw models list --provider moonshot --json`, poi esegui un test isolato `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - su `moonshot/kimi-k2.6`. Verifica che il JSON riporti Moonshot/K2.6 e che il - transcript dell’assistente memorizzi `usage.cost` normalizzato. + su `moonshot/kimi-k2.6`. Verifica che il JSON riporti Moonshot/K2.6 e che la + trascrizione dell’assistente memorizzi `usage.cost` normalizzato. -Suggerimento: quando ti serve solo un caso fallito, preferisci restringere i test live tramite le variabili d’ambiente di allowlist descritte sotto. +Suggerimento: quando ti serve solo un caso fallito, preferisci restringere i test live tramite le variabili env di allowlist descritte sotto. ## Runner specifici per QA -Questi comandi affiancano le suite di test principali quando ti serve il realismo di qa-lab: +Questi comandi si affiancano alle suite di test principali quando ti serve il realismo di qa-lab: -La CI esegue QA Lab in workflow dedicati. `Parity gate` gira sulle PR corrispondenti e -da esecuzione manuale con provider mock. `QA-Lab - All Lanes` gira ogni notte su -`main` e da esecuzione manuale con il gate di parità mock, la lane Matrix live e la -lane Telegram live gestita da Convex come job paralleli. `OpenClaw Release Checks` -esegue le stesse lane prima dell’approvazione del rilascio. +La CI esegue QA Lab in workflow dedicati. `Parity gate` viene eseguito su PR corrispondenti e +da avvio manuale con provider mock. `QA-Lab - All Lanes` viene eseguito ogni notte su +`main` e da avvio manuale con il parity gate mock, la lane live Matrix e la lane live Telegram +gestita da Convex come job paralleli. `OpenClaw Release Checks` +esegue le stesse lane prima dell’approvazione della release. - `pnpm openclaw qa suite` - - Esegue direttamente sull’host gli scenari QA supportati dal repo. - - Esegue più scenari selezionati in parallelo per impostazione predefinita con worker - Gateway isolati. `qa-channel` usa come valore predefinito una concorrenza di 4 - (limitata dal numero di scenari selezionati). Usa `--concurrency ` per regolare - il numero di worker, oppure `--concurrency 1` per la vecchia lane seriale. - - Termina con codice diverso da zero se uno qualunque degli scenari fallisce. Usa `--allow-failures` quando + - Esegue direttamente sull’host gli scenari QA supportati dal repository. + - Esegue per impostazione predefinita più scenari selezionati in parallelo con worker Gateway isolati. `qa-channel` usa per impostazione predefinita concorrenza 4 (limitata dal numero di scenari selezionati). Usa `--concurrency ` per regolare il numero di worker, oppure `--concurrency 1` per la vecchia lane seriale. + - Esce con codice non zero quando uno scenario fallisce. Usa `--allow-failures` quando vuoi ottenere gli artifact senza un codice di uscita di errore. - Supporta le modalità provider `live-frontier`, `mock-openai` e `aimock`. - `aimock` avvia un server provider locale supportato da AIMock per una copertura - sperimentale di fixture e mock di protocollo senza sostituire la lane - `mock-openai` orientata agli scenari. + `aimock` avvia un server provider locale basato su AIMock per copertura sperimentale + di fixture e protocol mock senza sostituire la lane `mock-openai` + orientata agli scenari. - `pnpm openclaw qa suite --runner multipass` - - Esegue la stessa suite QA all’interno di una VM Linux Multipass usa e getta. + - Esegue la stessa suite QA dentro una VM Linux Multipass usa e getta. - Mantiene lo stesso comportamento di selezione degli scenari di `qa suite` sull’host. - Riutilizza gli stessi flag di selezione provider/modello di `qa suite`. - Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il guest: chiavi provider basate su env, il percorso di configurazione del provider live QA e `CODEX_HOME` quando presente. - - Le directory di output devono rimanere sotto la root del repo così il guest può scrivere indietro - tramite il workspace montato. + - Le directory di output devono restare sotto la root del repository così il guest può scrivere indietro tramite + il workspace montato. - Scrive il normale report + riepilogo QA più i log Multipass sotto `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Avvia il sito QA supportato da Docker per lavoro QA in stile operatore. - `pnpm test:docker:npm-onboard-channel-agent` - - Costruisce un tarball npm a partire dal checkout corrente, lo installa globalmente in - Docker, esegue onboarding non interattivo con chiave API OpenAI, configura Telegram - per impostazione predefinita, verifica che l’abilitazione del plugin installi le dipendenze runtime - on demand, esegue doctor e lancia un turno di agente locale contro un endpoint - OpenAI mockato. - - Usa `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` per eseguire la stessa - lane di installazione pacchettizzata con Discord. + - Crea un tarball npm dal checkout corrente, lo installa globalmente in + Docker, esegue onboarding non interattivo con API key OpenAI, configura Telegram + per impostazione predefinita, verifica che l’abilitazione del plugin installi le dipendenze runtime su richiesta, + esegue doctor ed esegue un turno locale dell’agent contro un endpoint OpenAI simulato. + - Usa `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` per eseguire la stessa lane + di installazione pacchettizzata con Discord. - `pnpm test:docker:bundled-channel-deps` - - Impacchetta e installa la build OpenClaw corrente in Docker, avvia il Gateway - con OpenAI configurato, quindi abilita channel/plugin bundled tramite modifiche di config. - - Verifica che il rilevamento del setup lasci assenti le dipendenze runtime dei plugin non configurati, - che la prima esecuzione configurata di Gateway o doctor installi on demand le dipendenze runtime - di ogni plugin bundled e che un secondo riavvio non reinstalli dipendenze - già attivate. - - Installa anche una baseline npm precedente nota, abilita Telegram prima di eseguire - `openclaw update --tag `, e verifica che il doctor post-aggiornamento del - candidato ripari le dipendenze runtime dei channel bundled senza una riparazione postinstall - dal lato harness. + - Impacchetta e installa la build corrente di OpenClaw in Docker, avvia il Gateway + con OpenAI configurato, poi abilita channel/plugin bundled tramite + modifiche alla configurazione. + - Verifica che il rilevamento di setup lasci assenti le dipendenze runtime dei plugin non configurati, che la prima esecuzione configurata di Gateway o doctor installi su richiesta le dipendenze runtime di ciascun plugin bundled e che un secondo riavvio non reinstalli le dipendenze già attivate. + - Installa anche una baseline npm nota più vecchia, abilita Telegram prima di eseguire + `openclaw update --tag ` e verifica che il doctor post-aggiornamento + della candidate ripari le dipendenze runtime dei channel bundled senza una + riparazione postinstall lato harness. - `pnpm openclaw qa aimock` - - Avvia solo il server provider locale AIMock per test smoke diretti del protocollo. + - Avvia solo il server provider locale AIMock per smoke test diretti del protocollo. - `pnpm openclaw qa matrix` - - Esegue la lane QA live Matrix contro un homeserver Tuwunel temporaneo supportato da Docker. - - Questo host QA oggi è solo per repo/dev. Le installazioni OpenClaw pacchettizzate non distribuiscono + - Esegue la lane QA live Matrix contro un homeserver Tuwunel usa e getta supportato da Docker. + - Questo host QA oggi è solo per repository/sviluppo. Le installazioni OpenClaw pacchettizzate non distribuiscono `qa-lab`, quindi non espongono `openclaw qa`. - - I checkout del repo caricano direttamente il runner bundled; non serve alcun passaggio separato - di installazione del plugin. - - Esegue il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una room privata, quindi avvia un processo figlio QA gateway con il plugin Matrix reale come trasporto SUT. - - Usa per impostazione predefinita l’immagine Tuwunel stable fissata `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sovrascrivila con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando devi testare un’immagine diversa. - - Matrix non espone flag condivisi per la sorgente delle credenziali perché la lane esegue localmente il provisioning di utenti temporanei. - - Scrive un report QA Matrix, un riepilogo, un artifact degli eventi osservati e un log combinato stdout/stderr sotto `.artifacts/qa-e2e/...`. + - I checkout del repository caricano direttamente il runner bundled; non è necessario un passaggio separato di installazione del plugin. + - Esegue il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una stanza privata, poi avvia un processo figlio QA gateway con il vero plugin Matrix come trasporto SUT. + - Usa per impostazione predefinita l’immagine Tuwunel stable fissata `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sostituiscila con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando devi testare un’immagine diversa. + - Matrix non espone flag condivisi di origine credenziali perché la lane esegue localmente il provisioning di utenti usa e getta. + - Scrive un report QA Matrix, un riepilogo, un artifact di eventi osservati e un log combinato stdout/stderr sotto `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Esegue la lane QA live Telegram contro un gruppo privato reale usando i token bot driver e SUT da env. + - Esegue la lane QA live Telegram contro un gruppo privato reale usando i token bot driver e SUT dall’env. - Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’id del gruppo deve essere l’id numerico della chat Telegram. - - Supporta `--credential-source convex` per credenziali condivise in pool. Usa la modalità env per impostazione predefinita, oppure imposta `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` per usare lease condivisi. - - Termina con codice diverso da zero se uno qualunque degli scenari fallisce. Usa `--allow-failures` quando + - Supporta `--credential-source convex` per credenziali condivise in pool. Usa la modalità env per impostazione predefinita, oppure imposta `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` per scegliere lease condivisi. + - Esce con codice non zero quando uno scenario fallisce. Usa `--allow-failures` quando vuoi ottenere gli artifact senza un codice di uscita di errore. - Richiede due bot distinti nello stesso gruppo privato, con il bot SUT che espone uno username Telegram. - - Per un’osservazione stabile bot-to-bot, abilita la modalità Bot-to-Bot Communication Mode in `@BotFather` per entrambi i bot e assicurati che il bot driver possa osservare il traffico dei bot nel gruppo. + - Per un’osservazione stabile bot-to-bot, abilita Bot-to-Bot Communication Mode in `@BotFather` per entrambi i bot e assicurati che il bot driver possa osservare il traffico dei bot nel gruppo. - Scrive un report QA Telegram, un riepilogo e un artifact dei messaggi osservati sotto `.artifacts/qa-e2e/...`. Gli scenari di risposta includono l’RTT dalla richiesta di invio del driver alla risposta SUT osservata. -Le lane di trasporto live condividono un unico contratto standard così i nuovi trasporti non divergono: +Le lane di trasporto live condividono un contratto standard così i nuovi trasporti non divergono: -`qa-channel` rimane l’ampia suite QA sintetica e non fa parte della matrice di coverage dei trasporti live. +`qa-channel` resta l’ampia suite QA sintetica e non fa parte della matrice di copertura del trasporto live. | Lane | Canary | Gating delle menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione delle reazioni | Comando help | -| -------- | ------ | --------------------- | ---------------- | ------------------------- | -------------------- | ------------------- | -------------------- | --------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| -------- | ------ | --------------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenziali Telegram condivise tramite Convex (v1) Quando `--credential-source convex` (o `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) è abilitato per `openclaw qa telegram`, QA lab acquisisce un lease esclusivo da un pool supportato da Convex, invia heartbeat -per quel lease mentre la lane è in esecuzione e rilascia il lease allo spegnimento. +di quel lease mentre la lane è in esecuzione e rilascia il lease all’arresto. Scaffold di riferimento del progetto Convex: - `qa/convex-credential-broker/` -Variabili d’ambiente richieste: +Variabili env richieste: - `OPENCLAW_QA_CONVEX_SITE_URL` (per esempio `https://your-deployment.convex.site`) - Un secret per il ruolo selezionato: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` per `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` per `ci` -- Selezione del ruolo delle credenziali: +- Selezione del ruolo credenziale: - CLI: `--credential-role maintainer|ci` - - Valore predefinito env: `OPENCLAW_QA_CREDENTIAL_ROLE` (usa come default `ci` in CI, altrimenti `maintainer`) + - Valore env predefinito: `OPENCLAW_QA_CREDENTIAL_ROLE` (predefinito `ci` in CI, `maintainer` altrimenti) -Variabili d’ambiente facoltative: +Variabili env opzionali: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (predefinito `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (predefinito `30000`) - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (predefinito `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (predefinito `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (predefinito `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id di trace facoltativo) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` consente URL Convex `http://` in loopback solo per sviluppo locale. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id di tracciamento opzionale) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` consente URL Convex `http://` di loopback locale solo per sviluppo locale. `OPENCLAW_QA_CONVEX_SITE_URL` dovrebbe usare `https://` nel normale funzionamento. -I comandi admin per maintainer (aggiunta/rimozione/elenco pool) richiedono +I comandi amministrativi del maintainer (aggiunta/rimozione/elenco del pool) richiedono specificamente `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. Helper CLI per i maintainer: @@ -192,9 +189,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Usa `--json` per output leggibile da macchina in script e utilità CI. +Usa `--json` per output leggibile da macchina in script e utility CI. -Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Contratto dell’endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Richiesta: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -212,68 +209,68 @@ Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials - `POST /admin/remove` (solo secret maintainer) - Richiesta: `{ credentialId, actorId }` - Successo: `{ status: "ok", changed, credential }` - - Guardia lease attivo: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Protezione lease attivo: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (solo secret maintainer) - Richiesta: `{ kind?, status?, includePayload?, limit? }` - Successo: `{ status: "ok", credentials, count }` -Forma del payload per il tipo Telegram: +Forma del payload per il kind Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` deve essere una stringa con l’id numerico della chat Telegram. +- `groupId` deve essere una stringa numerica che rappresenta l’id della chat Telegram. - `admin/add` valida questa forma per `kind: "telegram"` e rifiuta payload malformati. -### Aggiunta di un canale a QA +### Aggiungere un channel a QA -Aggiungere un canale al sistema QA Markdown richiede esattamente due cose: +Aggiungere un channel al sistema QA markdown richiede esattamente due cose: -1. Un adapter di trasporto per il canale. -2. Un pacchetto di scenari che eserciti il contratto del canale. +1. Un adapter di trasporto per il channel. +2. Un pacchetto di scenari che eserciti il contratto del channel. Non aggiungere una nuova root di comando QA di primo livello quando l’host condiviso `qa-lab` può gestire il flusso. -`qa-lab` possiede la meccanica condivisa dell’host: +`qa-lab` gestisce le meccaniche host condivise: - la root di comando `openclaw qa` -- avvio e arresto della suite +- avvio e teardown della suite - concorrenza dei worker - scrittura degli artifact - generazione dei report - esecuzione degli scenari - alias di compatibilità per i vecchi scenari `qa-channel` -I plugin runner possiedono il contratto di trasporto: +I plugin runner gestiscono il contratto di trasporto: - come `openclaw qa ` viene montato sotto la root condivisa `qa` -- come il gateway viene configurato per quel trasporto +- come il Gateway viene configurato per quel trasporto - come viene verificata la readiness - come vengono iniettati gli eventi in ingresso - come vengono osservati i messaggi in uscita -- come vengono esposti transcript e stato di trasporto normalizzato +- come vengono esposte le trascrizioni e lo stato di trasporto normalizzato - come vengono eseguite le azioni supportate dal trasporto -- come viene gestito il reset o cleanup specifico del trasporto +- come viene gestito il reset o la pulizia specifici del trasporto -La soglia minima di adozione per un nuovo canale è: +La soglia minima di adozione per un nuovo channel è: 1. Mantenere `qa-lab` come proprietario della root condivisa `qa`. 2. Implementare il runner di trasporto sulla seam host condivisa `qa-lab`. -3. Mantenere la meccanica specifica del trasporto all’interno del plugin runner o harness del canale. +3. Mantenere le meccaniche specifiche del trasporto all’interno del plugin runner o dell’harness del channel. 4. Montare il runner come `openclaw qa ` invece di registrare una root di comando concorrente. - I plugin runner dovrebbero dichiarare `qaRunners` in `openclaw.plugin.json` ed esportare un array `qaRunnerCliRegistrations` corrispondente da `runtime-api.ts`. - Mantieni `runtime-api.ts` leggero; la CLI lazy e l’esecuzione del runner dovrebbero restare dietro entrypoint separati. -5. Scrivere o adattare scenari Markdown sotto le directory tematiche `qa/scenarios/`. + I plugin runner devono dichiarare `qaRunners` in `openclaw.plugin.json` ed esportare un array `qaRunnerCliRegistrations` corrispondente da `runtime-api.ts`. + Mantieni `runtime-api.ts` leggero; la CLI lazy e l’esecuzione del runner devono restare dietro entrypoint separati. +5. Creare o adattare scenari markdown nelle directory tematiche `qa/scenarios/`. 6. Usare gli helper di scenario generici per i nuovi scenari. -7. Mantenere funzionanti gli alias di compatibilità esistenti, a meno che il repo non stia facendo una migrazione intenzionale. +7. Mantenere funzionanti gli alias di compatibilità esistenti, a meno che il repository non stia effettuando una migrazione intenzionale. La regola decisionale è rigida: - Se un comportamento può essere espresso una sola volta in `qa-lab`, mettilo in `qa-lab`. -- Se un comportamento dipende da un solo trasporto di canale, tienilo in quel plugin runner o harness del plugin. -- Se uno scenario richiede una nuova capability che può essere usata da più di un canale, aggiungi un helper generico invece di un branch specifico di canale in `suite.ts`. +- Se un comportamento dipende da un trasporto di un solo channel, mantienilo in quel plugin runner o harness del plugin. +- Se uno scenario richiede una nuova capacità che può essere usata da più di un channel, aggiungi un helper generico invece di un branch specifico del channel in `suite.ts`. - Se un comportamento ha senso solo per un trasporto, mantieni lo scenario specifico del trasporto e rendilo esplicito nel contratto dello scenario. -I nomi preferiti per i nuovi helper generici di scenario sono: +I nomi preferiti degli helper generici per i nuovi scenari sono: - `waitForTransportReady` - `waitForChannelReady` @@ -296,187 +293,187 @@ Gli alias di compatibilità restano disponibili per gli scenari esistenti, inclu - `formatConversationTranscript` - `resetBus` -Il nuovo lavoro sui canali dovrebbe usare i nomi helper generici. -Gli alias di compatibilità esistono per evitare una migrazione in un solo giorno, non come modello per +Il nuovo lavoro sui channel deve usare i nomi degli helper generici. +Gli alias di compatibilità esistono per evitare una migrazione “flag day”, non come modello per la scrittura di nuovi scenari. ## Suite di test (cosa viene eseguito dove) -Pensa alle suite come a un “realismo crescente” (e crescente fragilità/costo): +Pensa alle suite come a “realismo crescente” (e flakiness/costo crescenti): ### Unit / integration (predefinita) - Comando: `pnpm test` -- Config: le esecuzioni non mirate usano il set di shard `vitest.full-*.config.ts` e possono espandere shard multi-project in config per singolo progetto per la pianificazione parallela -- File: inventari core/unit sotto `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e i test node di `ui` in allowlist coperti da `vitest.unit.config.ts` +- Configurazione: le esecuzioni non mirate usano il set di shard `vitest.full-*.config.ts` e possono espandere shard multi-project in configurazioni per progetto per la pianificazione parallela +- File: inventari core/unit in `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e i test node `ui` in allowlist coperti da `vitest.unit.config.ts` - Ambito: - Test unitari puri - - Test di integrazione in-process (auth del gateway, routing, tooling, parsing, config) + - Test di integrazione in-process (auth di gateway, routing, tooling, parsing, config) - Regressioni deterministiche per bug noti - Aspettative: - Viene eseguita in CI - Non richiede chiavi reali - Deve essere veloce e stabile -- Nota sui project: - - `pnpm test` non mirato ora esegue dodici config shard più piccole (`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`) invece di un singolo gigantesco processo root-project nativo. Questo riduce l’RSS di picco su macchine sotto carico ed evita che il lavoro di auto-reply/extension affami suite non correlate. - - `pnpm test --watch` usa ancora il grafo dei project della root nativa `vitest.config.ts`, perché un loop watch multi-shard non è pratico. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` instradano prima i target espliciti di file/directory attraverso lane con ambito ristretto, così `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo di avvio completo del progetto root. - - `pnpm test:changed` espande i percorsi git modificati nelle stesse lane con ambito ristretto quando il diff tocca solo file sorgente/test instradabili; le modifiche a config/setup ricadono ancora nella riesecuzione ampia del root-project. - - `pnpm check:changed` è il normale smart gate locale per lavoro ristretto. Classifica il diff in core, test core, extensions, test extension, app, docs, metadata di rilascio e tooling, quindi esegue le lane corrispondenti di typecheck/lint/test. Le modifiche a Plugin SDK pubblica e contratti plugin includono la validazione delle extension perché le extension dipendono da quei contratti core. I soli version bump nei metadata di rilascio eseguono controlli mirati su versione/config/dipendenze root invece della suite completa, con una guardia che rifiuta modifiche al package fuori dal campo versione di primo livello. - - I test unitari leggeri rispetto agli import da agenti, comandi, plugin, helper di auto-reply, `plugin-sdk` e aree utilitarie pure simili passano per la lane `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file stateful/runtime-heavy restano sulle lane esistenti. - - Alcuni file sorgente helper selezionati di `plugin-sdk` e `commands` mappano inoltre le esecuzioni in modalità changed a test sibling espliciti in quelle lane leggere, così le modifiche agli helper evitano di rieseguire l’intera suite pesante per quella directory. - - `auto-reply` ora ha tre bucket dedicati: helper core di primo livello, test di integrazione `reply.*` di primo livello e il sottoalbero `src/auto-reply/reply/**`. Questo tiene il lavoro più pesante dell’harness reply lontano dai test economici di status/chunk/token. +- Nota sui progetti: + - `pnpm test` non mirato ora esegue dodici configurazioni shard più piccole (`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`) invece di un singolo enorme processo root-project nativo. Questo riduce il picco RSS su macchine cariche ed evita che il lavoro auto-reply/extension affami suite non correlate. + - `pnpm test --watch` usa ancora il grafo dei progetti root nativo `vitest.config.ts`, perché un ciclo watch multi-shard non è pratico. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` instradano prima target espliciti di file/directory attraverso lane con scope, così `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo completo di avvio del progetto root. + - `pnpm test:changed` espande i percorsi git modificati nelle stesse lane con scope quando la diff tocca solo file sorgente/test instradabili; le modifiche a config/setup continuano invece a ricadere sulla riesecuzione ampia del progetto root. + - `pnpm check:changed` è il normale smart local gate per lavoro circoscritto. Classifica la diff in core, test core, extensions, test extension, app, documentazione, metadati di release e tooling, poi esegue le lane corrispondenti di typecheck/lint/test. Le modifiche a Plugin SDK pubblico e contratto plugin includono validazione delle extension perché le extension dipendono da quei contratti core. I version bump che toccano solo metadati di release eseguono controlli mirati di versione/config/dipendenze root invece della suite completa, con una guardia che rifiuta modifiche ai package fuori dal solo campo versione di primo livello. + - I test unitari leggeri in termini di import da agent, command, plugin, helper auto-reply, `plugin-sdk` e aree di utility pure simili passano attraverso la lane `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file stateful/runtime-heavy restano sulle lane esistenti. + - Alcuni file helper sorgente di `plugin-sdk` e `commands` mappano anche le esecuzioni in changed-mode a test sibling espliciti in quelle lane leggere, così le modifiche agli helper evitano di rieseguire l’intera suite pesante per quella directory. + - `auto-reply` ora ha tre bucket dedicati: helper core di primo livello, test di integrazione `reply.*` di primo livello e il sottoalbero `src/auto-reply/reply/**`. Questo tiene il lavoro più pesante dell’harness reply fuori dai test economici di stato/chunk/token. - Nota sull’embedded runner: - - Quando cambi gli input di discovery dei message-tool o il contesto runtime di Compaction, - mantieni entrambi i livelli di coverage. - - Aggiungi regressioni helper mirate per confini puri di routing/normalizzazione. + - Quando modifichi input di discovery dei message-tool o il contesto runtime di Compaction, + mantieni entrambi i livelli di copertura. + - Aggiungi regressioni helper mirate per boundary pure di routing/normalizzazione. - Mantieni sane anche le suite di integrazione dell’embedded runner: `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`. - - Quelle suite verificano che gli id con ambito e il comportamento di Compaction continuino a passare - attraverso i percorsi reali `run.ts` / `compact.ts`; i soli test helper non sono un - sostituto sufficiente per quei percorsi di integrazione. + - Queste suite verificano che gli id con scope e il comportamento di Compaction continuino a fluire + attraverso i veri percorsi `run.ts` / `compact.ts`; i soli test helper non sono un + sostituto sufficiente per questi percorsi di integrazione. - Nota sul pool: - - La config base di Vitest ora usa `threads` come predefinito. - - La config Vitest condivisa fissa anche `isolate: false` e usa il runner non isolato in root project, config e2e e live. - - La lane UI root mantiene il proprio setup `jsdom` e optimizer, ma ora gira anch’essa sul runner condiviso non isolato. - - Ogni shard di `pnpm test` eredita gli stessi valori predefiniti `threads` + `isolate: false` dalla config Vitest condivisa. - - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per impostazione predefinita ai processi Node figli di Vitest per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontare con il comportamento stock di V8. + - La configurazione base di Vitest ora usa `threads` per impostazione predefinita. + - La configurazione Vitest condivisa fissa anche `isolate: false` e usa il runner non isolato nei progetti root, nelle configurazioni e2e e live. + - La lane UI root mantiene la sua configurazione e l’optimizer `jsdom`, ma ora usa anch’essa il runner condiviso non isolato. + - Ogni shard di `pnpm test` eredita gli stessi valori predefiniti `threads` + `isolate: false` dalla configurazione Vitest condivisa. + - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per i processi child Node di Vitest per impostazione predefinita, per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontare il comportamento V8 standard. - Nota sull’iterazione locale rapida: - - `pnpm changed:lanes` mostra quali lane architetturali attiva un diff. - - Il pre-commit hook esegue `pnpm check:changed --staged` dopo formatting/linting dello staged, così i commit solo core non pagano il costo dei test extension a meno che non tocchino contratti pubblici rivolti alle extension. I commit di soli metadata di rilascio restano sulla lane mirata di versione/config/dipendenze root. - - Se l’esatto insieme di modifiche staged è già stato validato con gate equivalenti o più forti, usa `scripts/committer --fast "" ` per saltare solo la riesecuzione del hook changed-scope. Formatting/linting dello staged vengono comunque eseguiti. Cita i gate completati nel tuo handoff. Questo è accettabile anche dopo che un errore flaky isolato dell’hook è stato rieseguito e passa con prova circoscritta. - - `pnpm test:changed` passa attraverso lane con ambito ristretto quando i percorsi modificati si mappano chiaramente a una suite più piccola. - - `pnpm test:max` e `pnpm test:changed:max` mantengono lo stesso comportamento di instradamento, solo con un limite di worker più alto. + - `pnpm changed:lanes` mostra quali lane architetturali attiva una diff. + - L’hook pre-commit esegue `pnpm check:changed --staged` dopo formatting/linting dei file in stage, quindi i commit solo-core non pagano il costo dei test extension a meno che non tocchino contratti pubblici rivolti alle extension. I commit che toccano solo metadati di release restano sulla lane mirata versione/config/dipendenze root. + - Se l’esatto insieme di modifiche in stage è già stato validato con gate equivalenti o più forti, usa `scripts/committer --fast "" ` per saltare solo la riesecuzione dell’hook changed-scope. Formatting/linting dei file in stage vengono comunque eseguiti. Indica i gate completati nel tuo handoff. Questo è accettabile anche dopo la riesecuzione di un errore flaky isolato dell’hook che poi passa con prova circoscritta. + - `pnpm test:changed` passa attraverso lane con scope quando i percorsi modificati mappano chiaramente a una suite più piccola. + - `pnpm test:max` e `pnpm test:changed:max` mantengono lo stesso comportamento di instradamento, solo con un limite più alto di worker. - L’auto-scaling locale dei worker ora è intenzionalmente conservativo e riduce anche quando il load average dell’host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per impostazione predefinita. - - La config base di Vitest marca i file project/config come `forceRerunTriggers` così le riesecuzioni in modalità changed restano corrette quando cambia il wiring dei test. - - La config mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` abilitato sugli host supportati; imposta `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se vuoi una posizione cache esplicita per profiling diretto. -- Nota sul debug delle performance: - - `pnpm test:perf:imports` abilita il reporting della durata degli import di Vitest più l’output di breakdown degli import. - - `pnpm test:perf:imports:changed` applica la stessa vista di profiling ai file modificati da `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` confronta `test:changed` instradato con il percorso nativo root-project per quel diff commitatto e stampa wall time più max RSS su macOS. -- `pnpm test:perf:changed:bench -- --worktree` misura l’albero dirty corrente instradando l’elenco dei file modificati attraverso `scripts/test-projects.mjs` e la config root Vitest. - - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per overhead di avvio e transform di Vitest/Vite. - - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con parallelismo file disabilitato. + - La configurazione base di Vitest contrassegna i progetti/file di configurazione come `forceRerunTriggers` così le riesecuzioni in changed-mode restano corrette quando cambia il wiring dei test. + - La configurazione mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` abilitato sugli host supportati; imposta `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se vuoi una posizione cache esplicita per profiling diretto. +- Nota sul debugging delle performance: + - `pnpm test:perf:imports` abilita il report della durata degli import di Vitest più l’output di dettaglio degli import. + - `pnpm test:perf:imports:changed` limita la stessa vista di profiling ai file modificati rispetto a `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` confronta `test:changed` instradato con il percorso nativo root-project per quella diff già committata e stampa wall time più max RSS macOS. +- `pnpm test:perf:changed:bench -- --worktree` esegue benchmark del worktree sporco corrente instradando la lista dei file modificati attraverso `scripts/test-projects.mjs` e la configurazione root Vitest. + - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per overhead di startup e transform di Vitest/Vite. + - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con parallelismo dei file disabilitato. -### Stability (gateway) +### Stabilità (gateway) - Comando: `pnpm test:stability:gateway` -- Config: `vitest.gateway.config.ts`, forzata a un solo worker +- Configurazione: `vitest.gateway.config.ts`, forzata a un worker - Ambito: - - Avvia un Gateway loopback reale con diagnostica abilitata per impostazione predefinita - - Fa passare churn sintetico di messaggi gateway, memoria e payload grandi attraverso il percorso di eventi diagnostici - - Interroga `diagnostics.stability` tramite Gateway WS RPC + - Avvia un vero Gateway loopback con diagnostica abilitata per impostazione predefinita + - Pilota churn sintetico di messaggi gateway, memoria e payload grandi attraverso il percorso degli eventi diagnostici + - Interroga `diagnostics.stability` tramite la WS RPC del Gateway - Copre gli helper di persistenza del bundle di stabilità diagnostica - - Verifica che il recorder resti bounded, che i campioni RSS sintetici rimangano sotto il budget di pressione e che le profondità delle code per sessione tornino a zero + - Verifica che il recorder resti bounded, che i campioni RSS sintetici restino sotto il budget di pressione e che la profondità delle code per sessione torni a zero - Aspettative: - Sicura per CI e senza chiavi - - Lane ristretta per follow-up di regressioni di stabilità, non un sostituto della suite Gateway completa + - Lane ristretta per follow-up di regressioni di stabilità, non un sostituto della suite completa del Gateway ### E2E (smoke del gateway) - Comando: `pnpm test:e2e` -- Config: `vitest.e2e.config.ts` +- Configurazione: `vitest.e2e.config.ts` - File: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` e test E2E dei plugin bundled sotto `extensions/` -- Valori predefiniti runtime: - - Usa `threads` di Vitest con `isolate: false`, in linea con il resto del repo. +- Valori predefiniti di runtime: + - Usa Vitest `threads` con `isolate: false`, allineandosi al resto del repository. - Usa worker adattivi (CI: fino a 2, locale: 1 per impostazione predefinita). - - Gira in modalità silenziosa per impostazione predefinita per ridurre l’overhead di I/O su console. + - Viene eseguita in modalità silenziosa per impostazione predefinita per ridurre l’overhead di I/O su console. - Override utili: - `OPENCLAW_E2E_WORKERS=` per forzare il numero di worker (massimo 16). - - `OPENCLAW_E2E_VERBOSE=1` per riabilitare l’output verbose su console. + - `OPENCLAW_E2E_VERBOSE=1` per riattivare output console verboso. - Ambito: - - Comportamento end-to-end del gateway multiistanza + - Comportamento end-to-end del Gateway multiistanza - Superfici WebSocket/HTTP, pairing dei Node e networking più pesante - Aspettative: - Viene eseguita in CI (quando abilitata nella pipeline) - Non richiede chiavi reali - - Ha più parti in movimento rispetto ai test unitari (può essere più lenta) + - Ha più parti mobili rispetto ai test unitari (può essere più lenta) ### E2E: smoke del backend OpenShell - Comando: `pnpm test:e2e:openshell` - File: `extensions/openshell/src/backend.e2e.test.ts` - Ambito: - - Avvia un gateway OpenShell isolato sull’host tramite Docker - - Crea una sandbox a partire da un Dockerfile locale temporaneo - - Esercita il backend OpenShell di OpenClaw tramite `sandbox ssh-config` + esecuzione SSH reali - - Verifica il comportamento canonico del filesystem remoto tramite il bridge fs della sandbox + - Avvia un Gateway OpenShell isolato sull’host tramite Docker + - Crea un sandbox a partire da un Dockerfile locale temporaneo + - Esercita il backend OpenShell di OpenClaw tramite veri `sandbox ssh-config` + esecuzione SSH + - Verifica il comportamento del filesystem canonical remoto tramite il bridge fs del sandbox - Aspettative: - Solo opt-in; non fa parte dell’esecuzione predefinita `pnpm test:e2e` - - Richiede una CLI `openshell` locale più un demone Docker funzionante - - Usa `HOME` / `XDG_CONFIG_HOME` isolati, poi distrugge il gateway di test e la sandbox + - Richiede una CLI `openshell` locale più un daemon Docker funzionante + - Usa `HOME` / `XDG_CONFIG_HOME` isolati, poi distrugge il Gateway di test e il sandbox - Override utili: - - `OPENCLAW_E2E_OPENSHELL=1` per abilitare il test quando si esegue manualmente la suite e2e più ampia + - `OPENCLAW_E2E_OPENSHELL=1` per abilitare il test quando esegui manualmente la suite e2e più ampia - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` per puntare a un binario CLI non predefinito o a uno script wrapper ### Live (provider reali + modelli reali) - Comando: `pnpm test:live` -- Config: `vitest.live.config.ts` +- Configurazione: `vitest.live.config.ts` - File: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` e test live dei plugin bundled sotto `extensions/` - Predefinito: **abilitata** da `pnpm test:live` (imposta `OPENCLAW_LIVE_TEST=1`) - Ambito: - “Questo provider/modello funziona davvero _oggi_ con credenziali reali?” - - Intercetta cambi di formato del provider, particolarità del tool-calling, problemi di auth e comportamento dei rate limit + - Intercetta cambiamenti di formato del provider, particolarità della tool calling, problemi di auth e comportamento dei rate limit - Aspettative: - Per progettazione non è stabile in CI (reti reali, policy reali dei provider, quote, outage) - - Costa denaro / usa i rate limit - - È preferibile eseguire sottoinsiemi ristretti invece di “tutto” -- Le esecuzioni live leggono `~/.profile` per recuperare eventuali chiavi API mancanti. -- Per impostazione predefinita, le esecuzioni live isolano ancora `HOME` e copiano materiale di config/auth in una home di test temporanea così le fixture unit non possono modificare il tuo `~/.openclaw` reale. -- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando hai intenzionalmente bisogno che i test live usino la tua home directory reale. -- `pnpm test:live` ora usa per impostazione predefinita una modalità più silenziosa: mantiene l’output di avanzamento `[live] ...`, ma sopprime l’avviso extra su `~/.profile` e silenzia i log di bootstrap del gateway e il chatter Bonjour. Imposta `OPENCLAW_LIVE_TEST_QUIET=0` se vuoi riavere i log completi di avvio. -- Rotazione delle chiavi API (specifica per provider): imposta `*_API_KEYS` in formato con virgole/punto e virgola oppure `*_API_KEY_1`, `*_API_KEY_2` (per esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure l’override per-live `OPENCLAW_LIVE_*_KEY`; i test ritentano in risposta a rate limit. -- Output di avanzamento/heartbeat: - - Le suite live ora emettono righe di avanzamento su stderr così le chiamate provider lunghe risultano visibilmente attive anche quando la cattura console di Vitest è silenziosa. + - Costa denaro / usa rate limit + - Preferisci eseguire sottoinsiemi ristretti invece di “tutto” +- Le esecuzioni live leggono `~/.profile` per recuperare eventuali API key mancanti. +- Per impostazione predefinita, le esecuzioni live isolano comunque `HOME` e copiano materiale config/auth in una home temporanea di test così le fixture unit non possono modificare il tuo vero `~/.openclaw`. +- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando vuoi intenzionalmente che i test live usino la tua vera home directory. +- `pnpm test:live` ora usa per impostazione predefinita una modalità più silenziosa: mantiene l’output di avanzamento `[live] ...`, ma sopprime l’avviso extra su `~/.profile` e silenzia i log di bootstrap del Gateway/il chatter Bonjour. Imposta `OPENCLAW_LIVE_TEST_QUIET=0` se vuoi di nuovo i log completi di avvio. +- Rotazione delle API key (specifica per provider): imposta `*_API_KEYS` in formato con virgole/punto e virgola oppure `*_API_KEY_1`, `*_API_KEY_2` (per esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure l’override per-live `OPENCLAW_LIVE_*_KEY`; i test riprovano in caso di risposte rate limit. +- Output di progresso/heartbeat: + - Le suite live ora emettono righe di avanzamento su stderr così le chiamate lunghe al provider risultano visibilmente attive anche quando la cattura console di Vitest è silenziosa. - `vitest.live.config.ts` disabilita l’intercettazione della console di Vitest così le righe di avanzamento provider/gateway vengono trasmesse immediatamente durante le esecuzioni live. - - Regola gli heartbeat direct-model con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Regola gli heartbeat gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Regola gli heartbeat del modello diretto con `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Regola gli heartbeat del gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Quale suite dovrei eseguire? Usa questa tabella decisionale: -- Modifica di logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai cambiato molto) -- Interventi su networking del gateway / protocollo WS / pairing: aggiungi `pnpm test:e2e` -- Debug di “il mio bot è giù” / errori specifici del provider / tool calling: esegui un `pnpm test:live` ristretto +- Se modifichi logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai modificato molto) +- Se tocchi networking del Gateway / protocollo WS / pairing: aggiungi `pnpm test:e2e` +- Se fai debugging di “il mio bot è fuori uso” / errori specifici del provider / tool calling: esegui un `pnpm test:live` ristretto -## Live: sweep delle capability del Node Android +## Live: sweep delle capacità del Node Android - Test: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` - Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un Node Android connesso e verificare il comportamento del contratto del comando. - Ambito: - - Setup precondizionato/manuale (la suite non installa/esegue/abbina l’app). - - Validazione `node.invoke` del gateway comando per comando per il Node Android selezionato. + - Setup manuale/precondizionato (la suite non installa/esegue/associa l’app). + - Validazione `node.invoke` del Gateway comando per comando per il Node Android selezionato. - Pre-setup richiesto: - - App Android già connessa + abbinata al gateway. + - App Android già connessa + associata al Gateway. - App mantenuta in foreground. - - Permessi/consenso alla cattura concessi per le capability che ti aspetti passino. -- Override facoltativi del target: + - Permessi/consenso di acquisizione concessi per le capacità che ti aspetti superino il test. +- Override opzionali del target: - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Dettagli completi del setup Android: [App Android](/it/platforms/android) +- Dettagli completi di setup Android: [App Android](/it/platforms/android) -## Live: smoke dei modelli (chiavi profilo) +## Live: smoke del modello (chiavi del profilo) -I test live sono divisi in due livelli così possiamo isolare gli errori: +I test live sono divisi in due livelli così possiamo isolare i guasti: -- “Direct model” ci dice se il provider/modello può rispondere in assoluto con la chiave data. -- “Gateway smoke” ci dice se l’intera pipeline gateway+agente funziona per quel modello (sessioni, history, tool, policy sandbox, ecc.). +- “Modello diretto” ci dice se il provider/modello riesce almeno a rispondere con la chiave data. +- “Smoke del Gateway” ci dice se la pipeline completa gateway+agent funziona per quel modello (sessioni, cronologia, tool, policy sandbox, ecc.). -### Livello 1: completamento direct model (senza gateway) +### Livello 1: completamento diretto del modello (senza Gateway) - Test: `src/agents/models.profiles.live.test.ts` - Obiettivo: - Enumerare i modelli rilevati - Usare `getApiKeyForModel` per selezionare i modelli per cui hai credenziali - Eseguire un piccolo completamento per modello (e regressioni mirate dove necessario) -- Come abilitare: +- Come abilitarlo: - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) -- Imposta `OPENCLAW_LIVE_MODELS=modern` (oppure `all`, alias di modern) per eseguire davvero questa suite; altrimenti viene saltata per mantenere `pnpm test:live` focalizzato sul gateway smoke +- Imposta `OPENCLAW_LIVE_MODELS=modern` (oppure `all`, alias di modern) per eseguire davvero questa suite; altrimenti viene saltata per mantenere `pnpm test:live` focalizzato sul Gateway smoke - Come selezionare i modelli: - `OPENCLAW_LIVE_MODELS=modern` per eseguire l’allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` è un alias per l’allowlist modern @@ -485,29 +482,29 @@ I test live sono divisi in due livelli così possiamo isolare gli errori: - Come selezionare i provider: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separata da virgole) - Da dove arrivano le chiavi: - - Per impostazione predefinita: store dei profili e fallback env - - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** lo store dei profili + - Per impostazione predefinita: store del profilo e fallback env + - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** lo store del profilo - Perché esiste: - - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline agente del gateway è rotta” - - Contiene piccole regressioni isolate (esempio: replay reasoning OpenAI Responses/Codex Responses + flussi tool-call) + - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline agent del Gateway è rotta” + - Contiene regressioni piccole e isolate (esempio: flussi di replay del reasoning OpenAI Responses/Codex Responses + tool-call) -### Livello 2: Gateway + smoke dell’agente dev (quello che fa davvero "@openclaw") +### Livello 2: smoke del Gateway + agent dev (quello che fa davvero "@openclaw") - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Obiettivo: - - Avviare un gateway in-process + - Avviare un Gateway in-process - Creare/modificare una sessione `agent:dev:*` (override del modello per esecuzione) - Iterare sui modelli-con-chiavi e verificare: - risposta “significativa” (senza tool) - una vera invocazione di tool funziona (probe di lettura) - - probe di tool extra facoltative (probe exec+read) + - probe opzionali di tool extra (probe exec+read) - i percorsi di regressione OpenAI (solo tool-call → follow-up) continuano a funzionare -- Dettagli delle probe (così puoi spiegare rapidamente gli errori): - - probe `read`: il test scrive un file nonce nel workspace e chiede all’agente di `read`arlo e riecheggiare il nonce. - - probe `exec+read`: il test chiede all’agente di scrivere via `exec` un nonce in un file temporaneo, poi di `read`arlo. +- Dettagli delle probe (così puoi spiegare rapidamente i guasti): + - probe `read`: il test scrive un file nonce nel workspace e chiede all’agent di `read` il file e restituire il nonce. + - probe `exec+read`: il test chiede all’agent di scrivere tramite `exec` un nonce in un file temporaneo, poi di `read` per rileggerlo. - probe immagine: il test allega un PNG generato (gatto + codice randomizzato) e si aspetta che il modello restituisca `cat `. - - Riferimento di implementazione: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. -- Come abilitare: + - Riferimento implementativo: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. +- Come abilitarlo: - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) - Come selezionare i modelli: - Predefinito: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) @@ -518,13 +515,13 @@ I test live sono divisi in due livelli così possiamo isolare gli errori: - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separata da virgole) - Le probe tool + immagine sono sempre attive in questo test live: - probe `read` + probe `exec+read` (stress dei tool) - - la probe immagine gira quando il modello dichiara supporto all’input immagine + - la probe immagine viene eseguita quando il modello dichiara supporto per input immagine - Flusso (alto livello): - Il test genera un piccolo PNG con “CAT” + codice casuale (`src/gateway/live-image-probe.ts`) - Lo invia tramite `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Il Gateway analizza gli allegati in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - L’agente embedded inoltra al modello un messaggio utente multimodale - - Verifica: la risposta contiene `cat` + il codice (tolleranza OCR: sono ammessi piccoli errori) + - Gateway analizza gli allegati in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - L’agent embedded inoltra al modello un messaggio utente multimodale + - Verifica: la risposta contiene `cat` + il codice (tolleranza OCR: piccoli errori consentiti) Suggerimento: per vedere cosa puoi testare sulla tua macchina (e gli id esatti `provider/model`), esegui: @@ -536,23 +533,23 @@ openclaw models list --json ## Live: smoke del backend CLI (Claude, Codex, Gemini o altre CLI locali) - Test: `src/gateway/gateway-cli-backend.live.test.ts` -- Obiettivo: validare la pipeline Gateway + agente usando un backend CLI locale, senza toccare la tua config predefinita. +- Obiettivo: validare la pipeline Gateway + agent usando un backend CLI locale, senza toccare la tua configurazione predefinita. - Gli smoke predefiniti specifici del backend si trovano nella definizione `cli-backend.ts` dell’extension proprietaria. - Abilitazione: - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Valori predefiniti: - Provider/modello predefinito: `claude-cli/claude-sonnet-4-6` - - Il comportamento di comando/argomenti/immagine proviene dai metadati del plugin backend CLI proprietario. -- Override (facoltativi): + - Il comportamento di command/args/immagine proviene dai metadati del plugin proprietario del backend CLI. +- Override (opzionali): - `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` per inviare un vero allegato immagine (i percorsi vengono iniettati nel prompt). - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` per passare i percorsi dei file immagine come argomenti CLI invece che tramite iniezione nel prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oppure `"list"`) per controllare come vengono passati gli argomenti immagine quando `IMAGE_ARG` è impostato. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` per inviare un secondo turno e validare il flusso di resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la probe predefinita di continuità stessa-sessione Claude Sonnet -> Opus (impostalo a `1` per forzarla quando il modello selezionato supporta un target di switch). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) per controllare come vengono passati gli argomenti immagine quando `IMAGE_ARG` è impostato. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` per inviare un secondo turno e validare il flusso di ripresa. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la probe predefinita di continuità nella stessa sessione Claude Sonnet -> Opus (impostalo su `1` per forzarla quando il modello selezionato supporta un target di switch). Esempio: @@ -580,27 +577,27 @@ pnpm test:docker:live-cli-backend:gemini Note: - Il runner Docker si trova in `scripts/test-live-cli-backend-docker.sh`. -- Esegue lo smoke live del backend CLI dentro l’immagine Docker del repo come utente `node` non root. -- Risolve i metadati smoke della CLI dall’extension proprietaria, poi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) in un prefisso scrivibile in cache in `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predefinito: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` richiede OAuth portabile di abbonamento Claude Code tramite `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` oppure `CLAUDE_CODE_OAUTH_TOKEN` da `claude setup-token`. Prima dimostra `claude -p` diretto in Docker, poi esegue due turni Gateway CLI-backend senza preservare le variabili env della chiave API Anthropic. Questa lane subscription disabilita per impostazione predefinita le probe Claude MCP/tool e immagine perché Claude al momento instrada l’uso di app di terze parti tramite fatturazione di uso extra invece che tramite i normali limiti del piano di abbonamento. -- Lo smoke live del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno di testo, turno di classificazione immagine, poi chiamata tool MCP `cron` verificata tramite la CLI del gateway. -- Lo smoke predefinito di Claude inoltre modifica la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. +- Esegue lo smoke live del backend CLI all’interno dell’immagine Docker del repository come utente non root `node`. +- Risolve i metadati smoke della CLI dall’extension proprietaria, quindi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) in un prefisso scrivibile in cache in `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predefinito: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` richiede OAuth portabile dell’abbonamento Claude Code tramite `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` oppure `CLAUDE_CODE_OAUTH_TOKEN` da `claude setup-token`. Prima dimostra direttamente `claude -p` in Docker, poi esegue due turni Gateway CLI-backend senza preservare le variabili env delle API key Anthropic. Questa lane subscription disabilita per impostazione predefinita le probe Claude MCP/tool e immagine perché Claude attualmente instrada l’uso di app di terze parti attraverso fatturazione extra-usage invece che tramite i normali limiti del piano subscription. +- Lo smoke live del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno testuale, turno di classificazione immagine, poi chiamata tool MCP `cron` verificata tramite la CLI del gateway. +- Lo smoke predefinito di Claude modifica anche la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. ## Live: smoke del bind ACP (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Obiettivo: validare il flusso reale di conversation-bind ACP con un agente ACP live: +- Obiettivo: validare il vero flusso ACP conversation-bind con un agent ACP live: - inviare `/acp spawn --bind here` - - collegare in-place una conversazione sintetica di message-channel + - collegare sul posto una conversazione sintetica di message-channel - inviare un normale follow-up sulla stessa conversazione - - verificare che il follow-up arrivi nel transcript della sessione ACP collegata + - verificare che il follow-up arrivi nella trascrizione della sessione ACP collegata - Abilitazione: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Valori predefiniti: - - Agenti ACP in Docker: `claude,codex,gemini` - - Agente ACP per `pnpm test:live ...` diretto: `claude` - - Canale sintetico: contesto conversazione in stile DM Slack + - Agent ACP in Docker: `claude,codex,gemini` + - Agent ACP per `pnpm test:live ...` diretto: `claude` + - Channel sintetico: contesto di conversazione in stile DM Slack - Backend ACP: `acpx` - Override: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -610,8 +607,8 @@ Note: - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` - Note: - - Questa lane usa la superficie gateway `chat.send` con campi sintetici di originating-route riservati agli admin così i test possono allegare contesto di message-channel senza fingere una consegna esterna. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agenti integrato del plugin `acpx` embedded per l’agente harness ACP selezionato. + - Questa lane usa la superficie `chat.send` del Gateway con campi sintetici di originating-route solo admin così i test possono collegare il contesto del message-channel senza fingere una consegna esterna. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agent integrato del plugin embedded `acpx` per l’agent harness ACP selezionato. Esempio: @@ -627,7 +624,7 @@ Ricetta Docker: pnpm test:docker:live-acp-bind ``` -Ricette Docker per singolo agente: +Ricette Docker per singolo agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -638,34 +635,34 @@ pnpm test:docker:live-acp-bind:gemini Note Docker: - Il runner Docker si trova in `scripts/test-live-acp-bind-docker.sh`. -- Per impostazione predefinita, esegue in sequenza lo smoke ACP bind contro tutti gli agenti CLI live supportati: `claude`, `codex`, poi `gemini`. +- Per impostazione predefinita, esegue lo smoke ACP bind contro tutti gli agent CLI live supportati in sequenza: `claude`, `codex`, poi `gemini`. - Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oppure `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` per restringere la matrice. -- Legge `~/.profile`, prepara nel container il materiale di auth CLI corrispondente, installa `acpx` in un prefisso npm scrivibile, quindi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) se manca. -- Dentro Docker, il runner imposta `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` così acpx mantiene disponibili alla CLI harness figlia le variabili env del provider provenienti dal profilo letto. +- Legge `~/.profile`, prepara nel container il materiale di auth CLI corrispondente, installa `acpx` in un prefisso npm scrivibile, poi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) se manca. +- All’interno di Docker, il runner imposta `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` così acpx mantiene disponibili alla CLI harness figlia le variabili env del provider provenienti dal profilo caricato. ## Live: smoke dell’harness app-server Codex - Obiettivo: validare l’harness Codex posseduto dal plugin tramite il normale - metodo `agent` del gateway: + metodo Gateway `agent`: - caricare il plugin bundled `codex` - selezionare `OPENCLAW_AGENT_RUNTIME=codex` - - inviare un primo turno agente del gateway a `codex/gpt-5.4` + - inviare un primo turno Gateway agent a `codex/gpt-5.4` - inviare un secondo turno alla stessa sessione OpenClaw e verificare che il thread app-server possa riprendere - eseguire `/codex status` e `/codex models` tramite lo stesso percorso di comando - del gateway + del Gateway - facoltativamente eseguire due probe shell escalate revisionate da Guardian: un - comando benigno che dovrebbe essere approvato e un finto upload di secret che dovrebbe essere - negato così l’agente chiede conferma + comando benigno che dovrebbe essere approvato e un falso upload di secret che dovrebbe essere + negato così l’agent richiede conferma - Test: `src/gateway/gateway-codex-harness.live.test.ts` - Abilitazione: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modello predefinito: `codex/gpt-5.4` -- Probe immagine facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Probe MCP/tool facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Probe Guardian facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Lo smoke imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` così un harness Codex - rotto non può passare tornando silenziosamente a Pi. -- Auth: `OPENAI_API_KEY` dalla shell/profilo, più facoltativi +- Probe immagine opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Probe MCP/tool opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Probe Guardian opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Lo smoke imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` così un harness Codex rotto + non può passare ripiegando silenziosamente su Pi. +- Auth: `OPENAI_API_KEY` dalla shell/profilo, più eventuali `~/.codex/auth.json` e `~/.codex/config.toml` copiati Ricetta locale: @@ -690,53 +687,53 @@ pnpm test:docker:live-codex-harness Note Docker: - Il runner Docker si trova in `scripts/test-live-codex-harness-docker.sh`. -- Legge il `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file auth della CLI Codex +- Legge il `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file di auth della CLI Codex quando presenti, installa `@openai/codex` in un prefisso npm montato e scrivibile, - prepara il source tree, quindi esegue solo il test live dell’harness Codex. + prepara il source tree, poi esegue solo il test live Codex-harness. - Docker abilita per impostazione predefinita le probe immagine, MCP/tool e Guardian. Imposta `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oppure `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` oppure `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` quando ti serve un’esecuzione di debug più ristretta. -- Docker esporta anche `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, in linea con la config del +- Docker esporta anche `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, allineandosi alla configurazione del test live così il fallback `openai-codex/*` o Pi non può nascondere una regressione dell’harness Codex. ### Ricette live consigliate -Le allowlist ristrette ed esplicite sono le più veloci e le meno flaky: +Allowlist ristrette ed esplicite sono più rapide e meno flaky: -- Singolo modello, direct (senza gateway): +- Modello singolo, diretto (senza Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Singolo modello, gateway smoke: +- Modello singolo, Gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling su più provider: +- Tool calling su diversi provider: - `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` -- Focus Google (chiave API Gemini + Antigravity): - - Gemini (chiave API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Focus Google (API key Gemini + Antigravity): + - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Note: -- `google/...` usa l’API Gemini (chiave API). -- `google-antigravity/...` usa il bridge OAuth Antigravity (endpoint agente in stile Cloud Code Assist). -- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (auth separata + particolarità degli strumenti). +- `google/...` usa l’API Gemini (API key). +- `google-antigravity/...` usa il bridge OAuth Antigravity (endpoint agent in stile Cloud Code Assist). +- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (auth separata + particolarità dei tool). - API Gemini vs CLI Gemini: - - API: OpenClaw chiama l’API Gemini ospitata da Google via HTTP (auth con chiave API / profilo); questo è ciò che la maggior parte degli utenti intende con “Gemini”. - - CLI: OpenClaw esegue una shell verso un binario `gemini` locale; ha una propria auth e può comportarsi in modo diverso (streaming/supporto tool/version skew). + - API: OpenClaw chiama via HTTP l’API Gemini ospitata da Google (auth tramite API key / profilo); è ciò che la maggior parte degli utenti intende con “Gemini”. + - CLI: OpenClaw esegue una shell verso un binario locale `gemini`; ha una propria auth e può comportarsi diversamente (streaming/supporto tool/version skew). -## Live: matrice modelli (cosa copriamo) +## Live: matrice dei modelli (cosa copriamo) -Non esiste un “elenco modelli CI” fisso (live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. +Non esiste una “lista modelli CI” fissa (il live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. -### Set smoke modern (tool calling + immagine) +### Set smoke moderno (tool calling + immagine) -Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo di mantenere funzionante: +Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo continui a funzionare: -- OpenAI (non-Codex): `openai/gpt-5.4` (facoltativo: `openai/gpt-5.4-mini`) +- OpenAI (non-Codex): `openai/gpt-5.4` (opzionale: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) - Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evita i vecchi modelli Gemini 2.x) @@ -744,10 +741,10 @@ Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo di mantenere - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Esegui gateway smoke con tool + immagine: +Esegui Gateway smoke con tool + immagine: `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 facoltativo) +### Baseline: tool calling (Read + Exec opzionale) Scegline almeno uno per famiglia di provider: @@ -757,22 +754,22 @@ Scegline almeno uno per famiglia di provider: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Coverage aggiuntiva facoltativa (utile averla): +Copertura aggiuntiva opzionale (utile ma non necessaria): - xAI: `xai/grok-4` (oppure l’ultima disponibile) -- Mistral: `mistral/`… (scegli un modello con supporto `tools` che hai abilitato) +- Mistral: `mistral/`… (scegli un modello con capacità “tools” che hai abilitato) - Cerebras: `cerebras/`… (se hai accesso) -- LM Studio: `lmstudio/`… (locale; il tool calling dipende dalla modalità API) +- LM Studio: `lmstudio/`… (locale; la tool calling dipende dalla modalità API) -### Vision: invio immagini (allegato → messaggio multimodale) +### Vision: invio immagine (allegato → messaggio multimodale) -Includi almeno un modello capace di gestire immagini in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI con supporto vision, ecc.) per esercitare la probe immagine. +Includi almeno un modello con capacità immagine in `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/varianti OpenAI con capacità vision, ecc.) per esercitare la probe immagine. -### Aggregatori / gateway alternativi +### Aggregatori / Gateway alternativi -Se hai chiavi abilitate, supportiamo anche i test tramite: +Se hai chiavi abilitate, supportiamo anche test tramite: -- OpenRouter: `openrouter/...` (centinaia di modelli; usa `openclaw models scan` per trovare candidati con supporto tool+immagine) +- OpenRouter: `openrouter/...` (centinaia di modelli; usa `openclaw models scan` per trovare candidati con capacità tool+image) - OpenCode: `opencode/...` per Zen e `opencode-go/...` per Go (auth tramite `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) Altri provider che puoi includere nella matrice live (se hai credenziali/config): @@ -780,40 +777,40 @@ Altri provider che puoi includere nella matrice live (se hai credenziali/config) - Integrati: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` - Tramite `models.providers` (endpoint personalizzati): `minimax` (cloud/API), più qualunque proxy compatibile OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, ecc.) -Suggerimento: non provare a codificare rigidamente “tutti i modelli” nella doc. L’elenco autorevole è qualunque cosa restituisca `discoverModels(...)` sulla tua macchina + qualunque chiave sia disponibile. +Suggerimento: non provare a codificare in modo rigido “tutti i modelli” nella documentazione. L’elenco autorevole è quello che `discoverModels(...)` restituisce sulla tua macchina + le chiavi disponibili. -## Credenziali (non fare mai commit) +## Credenziali (non committare mai) -I test live scoprono le credenziali nello stesso modo in cui lo fa la CLI. Implicazioni pratiche: +I test live scoprono le credenziali nello stesso modo della CLI. Implicazioni pratiche: - Se la CLI funziona, i test live dovrebbero trovare le stesse chiavi. -- Se un test live dice “nessuna credenziale”, fai debug nello stesso modo in cui faresti debug di `openclaw models list` / selezione del modello. +- Se un test live dice “nessuna credenziale”, fai debugging come faresti per `openclaw models list` / selezione del modello. -- Profili auth per agente: `~/.openclaw/agents//agent/auth-profiles.json` (questo è il significato di “profile keys” nei test live) -- Config: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) -- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live preparata quando presente, ma non è lo store principale delle chiavi profilo) -- Le esecuzioni live locali copiano per impostazione predefinita la config attiva, i file `auth-profiles.json` per agente, la directory legacy `credentials/` e le directory auth supportate delle CLI esterne in una home di test temporanea; le home live preparate saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dal tuo workspace host reale. +- Profili di auth per-agent: `~/.openclaw/agents//agent/auth-profiles.json` (questo è ciò che “chiavi del profilo” significa nei test live) +- Configurazione: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) +- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live preparata quando presente, ma non è lo store principale delle chiavi del profilo) +- Le esecuzioni live locali copiano per impostazione predefinita la configurazione attiva, i file `auth-profiles.json` per-agent, la directory legacy `credentials/` e le directory di auth CLI esterne supportate in una home temporanea di test; le home live preparate saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dal tuo vero workspace host. -Se vuoi fare affidamento sulle chiavi env (ad es. esportate nel tuo `~/.profile`), esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker qui sotto (possono montare `~/.profile` nel container). +Se vuoi affidarti alle chiavi env (per esempio esportate nel tuo `~/.profile`), esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker qui sotto (possono montare `~/.profile` nel container). ## Live Deepgram (trascrizione audio) - Test: `extensions/deepgram/audio.live.test.ts` - Abilitazione: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Live piano di coding BytePlus +## Live BytePlus coding plan - Test: `extensions/byteplus/live.test.ts` - Abilitazione: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` -- Override facoltativo del modello: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Override opzionale del modello: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## Live media workflow ComfyUI - Test: `extensions/comfy/comfy.live.test.ts` - Abilitazione: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Ambito: - - Esercita i percorsi bundled comfy per immagini, video e `music_generate` - - Salta ogni capability a meno che `models.providers.comfy.` non sia configurato + - Esercita i percorsi bundled comfy di immagine, video e `music_generate` + - Salta ogni capacità a meno che `models.providers.comfy.` non sia configurato - Utile dopo modifiche a invio workflow comfy, polling, download o registrazione del plugin ## Live generazione immagini @@ -823,10 +820,10 @@ Se vuoi fare affidamento sulle chiavi env (ad es. esportate nel tuo `~/.profile` - Harness: `pnpm test:live:media image` - Ambito: - Enumera ogni plugin provider di generazione immagini registrato - - Carica le variabili env del provider mancanti dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell - - Salta i provider senza auth/profilo/modello utilizzabile - - Esegue le varianti stock di generazione immagini tramite la capability runtime condivisa: + - Carica le variabili env provider mancanti dalla tua shell di login (`~/.profile`) prima di eseguire le probe + - Usa per impostazione predefinita API key live/env prima dei profili di auth salvati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell + - Salta i provider senza auth/profilo/modello utilizzabili + - Esegue le varianti standard di generazione immagini tramite la capacità runtime condivisa: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -838,12 +835,12 @@ Se vuoi fare affidamento sulle chiavi env (ad es. esportate nel tuo `~/.profile` - `openai` - `vydra` - `xai` -- Restrizione facoltativa: +- Restrizione opzionale: - `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 auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth dallo store dei profili e ignorare gli override solo-env +- Comportamento auth opzionale: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth dallo store del profilo e ignorare gli override solo env ## Live generazione musica @@ -851,23 +848,23 @@ Se vuoi fare affidamento sulle chiavi env (ad es. esportate nel tuo `~/.profile` - Abilitazione: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Ambito: - - Esercita il percorso condiviso bundled dei provider di generazione musica + - Esercita il percorso condiviso bundled del provider di generazione musica - Attualmente copre Google e MiniMax - - Carica le variabili env del provider dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell - - Salta i provider senza auth/profilo/modello utilizzabile + - Carica le variabili env provider dalla tua shell di login (`~/.profile`) prima di eseguire le probe + - Usa per impostazione predefinita API key live/env prima dei profili di auth salvati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell + - Salta i provider senza auth/profilo/modello utilizzabili - Esegue entrambe le modalità runtime dichiarate quando disponibili: - - `generate` con input solo prompt + - `generate` con input basato solo su prompt - `edit` quando il provider dichiara `capabilities.edit.enabled` - - Coverage attuale della lane condivisa: + - Copertura attuale della lane condivisa: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: file live Comfy separato, non questo sweep condiviso -- Restrizione facoltativa: +- Restrizione opzionale: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth dallo store dei profili e ignorare gli override solo-env +- Comportamento auth opzionale: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth dallo store del profilo e ignorare gli override solo env ## Live generazione video @@ -875,42 +872,42 @@ Se vuoi fare affidamento sulle chiavi env (ad es. esportate nel tuo `~/.profile` - Abilitazione: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Ambito: - - Esercita il percorso condiviso bundled dei provider di generazione video - - Usa per impostazione predefinita il percorso smoke sicuro per il rilascio: provider non-FAL, una richiesta text-to-video per provider, prompt lobster di un secondo e un limite di operazione per provider da `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` per impostazione predefinita) - - Salta FAL per impostazione predefinita perché la latenza della coda lato provider può dominare il tempo di rilascio; passa `--video-providers fal` oppure `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente - - Carica le variabili env del provider dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell - - Salta i provider senza auth/profilo/modello utilizzabile + - Esercita il percorso condiviso bundled del provider di generazione video + - Per impostazione predefinita usa il percorso smoke sicuro per la release: provider non-FAL, una richiesta text-to-video per provider, prompt “lobster” di un secondo e un limite di operazione per provider da `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` per impostazione predefinita) + - Salta FAL per impostazione predefinita perché la latenza della coda lato provider può dominare i tempi di release; passa `--video-providers fal` oppure `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente + - Carica le variabili env provider dalla tua shell di login (`~/.profile`) prima di eseguire le probe + - Usa per impostazione predefinita API key live/env prima dei profili di auth salvati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell + - Salta i provider senza auth/profilo/modello utilizzabili - Esegue solo `generate` per impostazione predefinita - Imposta `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` per eseguire anche le modalità transform dichiarate quando disponibili: - - `imageToVideo` quando il provider dichiara `capabilities.imageToVideo.enabled` e il provider/modello selezionato accetta input immagine locale basato su buffer nello sweep condiviso - - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale basato su buffer nello sweep condiviso + - `imageToVideo` quando il provider dichiara `capabilities.imageToVideo.enabled` e il provider/modello selezionato accetta input immagine locale buffer-backed nello sweep condiviso + - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale buffer-backed nello sweep condiviso - Provider `imageToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - `vydra` perché `veo3` bundled è solo testo e `kling` bundled richiede un URL immagine remoto - - Coverage Vydra specifica del provider: + - Copertura Vydra specifica del provider: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - quel file esegue `veo3` text-to-video più una lane `kling` che usa per impostazione predefinita una fixture con URL immagine remoto - - Coverage live `videoToVideo` attuale: + - quel file esegue `veo3` text-to-video più una lane `kling` che per impostazione predefinita usa una fixture con URL immagine remoto + - Copertura live attuale `videoToVideo`: - solo `runway` quando il modello selezionato è `runway/gen4_aleph` - Provider `videoToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - - `alibaba`, `qwen`, `xai` perché quei percorsi attualmente richiedono URL di riferimento remoti `http(s)` / MP4 - - `google` perché l’attuale lane condivisa Gemini/Veo usa input locali basati su buffer e quel percorso non è accettato nello sweep condiviso - - `openai` perché l’attuale lane condivisa non garantisce l’accesso specifico per organizzazione a video inpaint/remix -- Restrizione facoltativa: + - `alibaba`, `qwen`, `xai` perché quei percorsi richiedono attualmente URL di riferimento remoti `http(s)` / MP4 + - `google` perché l’attuale lane condivisa Gemini/Veo usa input locali buffer-backed e quel percorso non è accettato nello sweep condiviso + - `openai` perché l’attuale lane condivisa non garantisce l’accesso specifico dell’organizzazione a inpaint/remix video +- Restrizione opzionale: - `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=""` per includere ogni provider nello sweep predefinito, incluso FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` per ridurre il limite di operazione di ogni provider in un’esecuzione smoke aggressiva -- Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth dallo store dei profili e ignorare gli override solo-env + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` per ridurre il limite di operazione di ciascun provider in uno smoke run aggressivo +- Comportamento auth opzionale: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth dallo store del profilo e ignorare gli override solo env ## Harness live media - Comando: `pnpm test:live:media` - Scopo: - - Esegue le suite live condivise di immagini, musica e video tramite un unico entrypoint nativo del repo - - Carica automaticamente le variabili env del provider mancanti da `~/.profile` - - Restringe automaticamente ogni suite ai provider che al momento hanno auth utilizzabile per impostazione predefinita + - Esegue le suite live condivise di immagini, musica e video tramite un unico entrypoint nativo del repository + - Carica automaticamente le variabili env provider mancanti da `~/.profile` + - Restringe automaticamente ciascuna suite ai provider che attualmente hanno auth utilizzabile per impostazione predefinita - Riutilizza `scripts/test-live.mjs`, così il comportamento di heartbeat e modalità silenziosa resta coerente - Esempi: - `pnpm test:live:media` @@ -918,192 +915,192 @@ Se vuoi fare affidamento sulle chiavi env (ad es. esportate nel tuo `~/.profile` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Runner Docker (controlli facoltativi “funziona su Linux”) +## Runner Docker (controlli opzionali “funziona su Linux”) -Questi runner Docker sono divisi in due gruppi: +Questi runner Docker si dividono in due gruppi: -- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il file live con chiavi profilo corrispondente dentro l’immagine Docker del repo (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la tua directory config locale e workspace (e leggendo `~/.profile` se montato). Gli entrypoint locali corrispondenti sono `test:live:models-profiles` e `test:live:gateway-profiles`. +- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il file live con chiavi del profilo corrispondente all’interno dell’immagine Docker del repository (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la tua directory config locale e il workspace (e leggendo `~/.profile` se montato). Gli entrypoint locali corrispondenti sono `test:live:models-profiles` e `test:live:gateway-profiles`. - I runner live Docker usano per impostazione predefinita un limite smoke più piccolo così uno sweep Docker completo resta praticabile: - `test:docker:live-models` usa per impostazione predefinita `OPENCLAW_LIVE_MAX_MODELS=12`, e - `test:docker:live-gateway` usa per impostazione predefinita `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, + `test:docker:live-models` usa come predefinito `OPENCLAW_LIVE_MAX_MODELS=12`, e + `test:docker:live-gateway` usa come predefiniti `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`. Sovrascrivi quelle variabili env quando + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sostituisci queste variabili env quando vuoi esplicitamente la scansione esaustiva più ampia. -- `test:docker:all` costruisce una volta l’immagine Docker live tramite `test:docker:live-build`, poi la riusa per le due lane Docker live. Costruisce anche un’unica immagine condivisa `scripts/e2e/Dockerfile` tramite `test:docker:e2e-build` e la riusa per i runner smoke E2E in container che esercitano l’app buildata. -- I runner smoke in container: `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` avviano uno o più container reali e verificano percorsi di integrazione di livello superiore. +- `test:docker:all` costruisce una volta l’immagine Docker live tramite `test:docker:live-build`, poi la riutilizza per le due lane Docker live. Costruisce anche una singola immagine condivisa `scripts/e2e/Dockerfile` tramite `test:docker:e2e-build` e la riutilizza per i runner smoke E2E in container che esercitano l’app buildata. +- Runner smoke in container: `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` avviano uno o più container reali e verificano percorsi di integrazione di livello superiore. -I runner Docker live-model montano inoltre solo le home auth CLI necessarie (o tutte quelle supportate quando l’esecuzione non è ristretta), poi le copiano nella home del container prima dell’esecuzione così l’OAuth della CLI esterna può aggiornare i token senza modificare lo store auth dell’host: +I runner Docker live-model montano inoltre solo le home di auth CLI necessarie (o tutte quelle supportate quando l’esecuzione non è ristretta), poi le copiano nella home del container prima dell’esecuzione così l’OAuth delle CLI esterne può aggiornare i token senza modificare lo store di auth dell’host: - Modelli diretti: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) - Smoke ACP bind: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) - Smoke backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) - Smoke harness 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`) +- Gateway + agent dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Wizard di onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Smoke onboarding/canale/agente da tarball npm: `pnpm test:docker:npm-onboard-channel-agent` installa globalmente in Docker il tarball OpenClaw pacchettizzato, configura OpenAI tramite onboarding env-ref più Telegram per impostazione predefinita, verifica che l’abilitazione del plugin installi on demand le sue dipendenze runtime, esegue doctor e lancia un turno agente OpenAI mockato. Riusa un tarball prebuildato con `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, salta la rebuild host con `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, oppure cambia canale con `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Networking Gateway (due container, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Regressione minimale reasoning OpenAI Responses `web_search`: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) esegue un server OpenAI mockato tramite Gateway, verifica che `web_search` alzi `reasoning.effort` da `minimal` a `low`, poi forza il rifiuto dello schema provider e controlla che il dettaglio raw compaia nei log di Gateway. -- Bridge canale MCP (Gateway seedato + bridge stdio + smoke raw del frame di notifica Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Tool MCP del bundle Pi (server MCP stdio reale + smoke allow/deny del profilo Pi embedded): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Cleanup MCP Cron/subagent (Gateway reale + teardown del processo figlio MCP stdio dopo esecuzioni isolate di Cron e subagent one-shot): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugin (smoke di installazione + alias `/plugin` + semantica di riavvio del bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -- Smoke invariato di aggiornamento plugin: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke dei metadata di reload config: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) -- Dipendenze runtime dei plugin bundled: `pnpm test:docker:bundled-channel-deps` costruisce per impostazione predefinita una piccola immagine runner Docker, builda e pacchettizza OpenClaw una volta sull’host, poi monta quel tarball in ogni scenario di installazione Linux. Riusa l’immagine con `OPENCLAW_SKIP_DOCKER_BUILD=1`, salta la rebuild host dopo una build locale fresca con `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, oppure punta a un tarball esistente con `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Restringi le dipendenze runtime dei plugin bundled durante l’iterazione disabilitando gli scenari non correlati, per esempio: +- Smoke onboarding/channel/agent da tarball npm: `pnpm test:docker:npm-onboard-channel-agent` installa globalmente in Docker il tarball OpenClaw impacchettato, configura OpenAI tramite onboarding env-ref più Telegram per impostazione predefinita, verifica che l’abilitazione del plugin installi le sue dipendenze runtime su richiesta, esegue doctor ed esegue un turno agent OpenAI simulato. Riusa un tarball prebuildato con `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, salta la rebuild host con `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, oppure cambia channel con `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Networking del Gateway (due container, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Regressione minimale del reasoning `web_search` OpenAI Responses: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) esegue un server OpenAI simulato tramite Gateway, verifica che `web_search` alzi `reasoning.effort` da `minimal` a `low`, poi forza il rifiuto dello schema provider e controlla che il dettaglio raw compaia nei log del Gateway. +- Bridge MCP channel (Gateway seeded + bridge stdio + smoke raw dei notification-frame Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Tool MCP bundle Pi (vero server MCP stdio + smoke allow/deny del profilo Pi embedded): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Cleanup MCP Cron/subagent (vero Gateway + teardown del child MCP stdio dopo esecuzioni isolate di Cron e subagent one-shot): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugin (smoke installazione + alias `/plugin` + semantica di riavvio Claude-bundle): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Smoke invariato dell’aggiornamento Plugin: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke dei metadati di reload della configurazione: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) +- Dipendenze runtime dei plugin bundled: `pnpm test:docker:bundled-channel-deps` costruisce per impostazione predefinita una piccola immagine runner Docker, builda e impacchetta OpenClaw una sola volta sull’host, poi monta quel tarball in ogni scenario di installazione Linux. Riusa l’immagine con `OPENCLAW_SKIP_DOCKER_BUILD=1`, salta la rebuild host dopo una build locale fresca con `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, oppure punta a un tarball esistente con `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Restringi le dipendenze runtime dei plugin bundled mentre iteri disabilitando gli scenari non correlati, per esempio: `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`. -Per prebuildare e riusare manualmente l’immagine condivisa built-app: +Per prebuildare e riutilizzare manualmente l’immagine condivisa dell’app buildata: ```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 ``` -Gli override di immagine specifici della suite, come `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, hanno comunque la precedenza quando sono impostati. Quando `OPENCLAW_SKIP_DOCKER_BUILD=1` punta a un’immagine condivisa remota, gli script la scaricano se non è già presente in locale. I test Docker di QR e installer mantengono i propri Dockerfile perché validano il comportamento di package/installazione piuttosto che il runtime condiviso built-app. +Gli override dell’immagine specifici della suite, come `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, hanno comunque la priorità quando impostati. Quando `OPENCLAW_SKIP_DOCKER_BUILD=1` punta a un’immagine condivisa remota, gli script la scaricano se non è già locale. I test Docker QR e installer mantengono i propri Dockerfile perché validano il comportamento di pacchetto/installazione invece del runtime condiviso dell’app buildata. -I runner Docker live-model montano anche il checkout corrente in sola lettura e -lo preparano in una workdir temporanea dentro il container. Questo mantiene snella l’immagine -runtime pur eseguendo Vitest sul tuo esatto source/config locale. -Il passaggio di staging salta grandi cache solo-locali e output di build delle app come -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory di output `.build` o -Gradle locali all’app, così le esecuzioni live Docker non passano minuti a copiare +I runner Docker live-model montano inoltre il checkout corrente in sola lettura e +lo preparano in una workdir temporanea dentro il container. Questo mantiene il runtime +image leggero pur eseguendo Vitest contro il tuo esatto source/config locale. +Il passaggio di staging salta grandi cache solo locali e output di build delle app come +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory `.build` locali dell’app o +directory di output Gradle, così le esecuzioni live Docker non passano minuti a copiare artifact specifici della macchina. -Impostano anche `OPENCLAW_SKIP_CHANNELS=1` così le probe gateway live non avviano -worker di canale reali Telegram/Discord/ecc. dentro il container. -`test:docker:live-models` esegue comunque `pnpm test:live`, quindi inoltra anche -`OPENCLAW_LIVE_GATEWAY_*` quando hai bisogno di restringere o escludere la coverage live -gateway da quella lane Docker. +Impostano anche `OPENCLAW_SKIP_CHANNELS=1` così le probe live del Gateway non avviano +veri worker di channel Telegram/Discord/ecc. dentro il container. +`test:docker:live-models` esegue comunque `pnpm test:live`, quindi passa anche +`OPENCLAW_LIVE_GATEWAY_*` quando hai bisogno di restringere o escludere la copertura live +Gateway da quella lane Docker. `test:docker:openwebui` è uno smoke di compatibilità di livello superiore: avvia un -container gateway OpenClaw con endpoint HTTP compatibili con OpenAI abilitati, -avvia un container Open WebUI fissato contro quel gateway, effettua il sign-in tramite -Open WebUI, verifica che `/api/models` esponga `openclaw/default`, quindi invia una -vera richiesta chat tramite il proxy `/api/chat/completions` di Open WebUI. -La prima esecuzione può essere sensibilmente più lenta perché Docker potrebbe dover scaricare l’immagine -Open WebUI e Open WebUI potrebbe dover completare il proprio setup a freddo. +container Gateway OpenClaw con gli endpoint HTTP compatibili con OpenAI abilitati, +avvia un container Open WebUI fissato contro quel Gateway, effettua l’accesso tramite +Open WebUI, verifica che `/api/models` esponga `openclaw/default`, poi invia una +vera richiesta di chat tramite il proxy `/api/chat/completions` di Open WebUI. +La prima esecuzione può essere sensibilmente più lenta perché Docker potrebbe dover scaricare +l’immagine Open WebUI e Open WebUI potrebbe dover completare il proprio setup di cold-start. Questa lane si aspetta una chiave di modello live utilizzabile, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` per impostazione predefinita) è il modo principale per fornirla nelle esecuzioni Docker. +(`~/.profile` per impostazione predefinita) è il modo principale per fornirla nelle esecuzioni Dockerizzate. Le esecuzioni riuscite stampano un piccolo payload JSON come `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` è intenzionalmente deterministica e non richiede un -account reale Telegram, Discord o iMessage. Avvia un container Gateway -seedato, avvia un secondo container che lancia `openclaw mcp serve`, poi -verifica discovery di conversazioni instradate, letture del transcript, metadati degli allegati, -comportamento della coda di eventi live, instradamento dell’invio in uscita e notifiche di canale + -permessi in stile Claude sul vero bridge stdio MCP. Il controllo delle notifiche +`test:docker:mcp-channels` è intenzionalmente deterministico e non richiede un +vero account Telegram, Discord o iMessage. Avvia un container Gateway seeded, +avvia un secondo container che esegue `openclaw mcp serve`, poi +verifica rilevamento della conversazione instradata, letture delle trascrizioni, metadati degli allegati, +comportamento della coda eventi live, instradamento dell’invio in uscita e notifiche di channel + +permessi in stile Claude tramite il vero bridge stdio MCP. Il controllo delle notifiche ispeziona direttamente i frame raw stdio MCP così lo smoke valida ciò che il -bridge emette realmente, non solo ciò che una specifica SDK client decide di esporre. -`test:docker:pi-bundle-mcp-tools` è deterministico e non richiede una chiave di modello live. -Costruisce l’immagine Docker del repo, avvia un vero server probe stdio MCP -dentro il container, materializza quel server tramite il runtime MCP del bundle Pi embedded, -esegue il tool, poi verifica che `coding` e `messaging` mantengano -i tool `bundle-mcp` mentre `minimal` e `tools.deny: ["bundle-mcp"]` li filtrano. -`test:docker:cron-mcp-cleanup` è deterministico e non richiede una chiave di modello live. -Avvia un Gateway seedato con un vero server probe stdio MCP, esegue un +bridge emette davvero, non solo ciò che capita di esporre un particolare SDK client. +`test:docker:pi-bundle-mcp-tools` è deterministico e non richiede una chiave di modello +live. Costruisce l’immagine Docker del repository, avvia un vero server probe MCP stdio +dentro il container, materializza quel server tramite il runtime MCP bundle Pi embedded, +esegue il tool, poi verifica che `coding` e `messaging` mantengano i +tool `bundle-mcp` mentre `minimal` e `tools.deny: ["bundle-mcp"]` li filtrano. +`test:docker:cron-mcp-cleanup` è deterministico e non richiede una chiave di modello +live. Avvia un Gateway seeded con un vero server probe MCP stdio, esegue un turno Cron isolato e un turno figlio one-shot `/subagents spawn`, poi verifica che il processo figlio MCP termini dopo ogni esecuzione. -Smoke manuale ACP thread in linguaggio naturale (non CI): +Smoke manuale del thread ACP in linguaggio naturale (non CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Conserva questo script per i flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la validazione dell’instradamento dei thread ACP, quindi non eliminarlo. +- Mantieni questo script per flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la validazione dell’instradamento dei thread ACP, quindi non eliminarlo. Variabili env utili: -- `OPENCLAW_CONFIG_DIR=...` (predefinita: `~/.openclaw`) montata in `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (predefinita: `~/.openclaw/workspace`) montata in `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (predefinita: `~/.profile`) montata in `/home/node/.profile` e letta prima di eseguire i test -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` per verificare solo le variabili env lette da `OPENCLAW_PROFILE_FILE`, usando directory config/workspace temporanee e senza mount auth di CLI esterne -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinita: `~/.cache/openclaw/docker-cli-tools`) montata in `/home/node/.npm-global` per installazioni CLI in cache dentro Docker -- Le directory/file auth di CLI esterne sotto `$HOME` vengono montati in sola lettura sotto `/host-auth...`, poi copiati in `/home/node/...` prima che i test inizino +- `OPENCLAW_CONFIG_DIR=...` (predefinita: `~/.openclaw`) montata su `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (predefinita: `~/.openclaw/workspace`) montata su `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (predefinita: `~/.profile`) montata su `/home/node/.profile` e letta prima di eseguire i test +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` per verificare solo le variabili env lette da `OPENCLAW_PROFILE_FILE`, usando directory config/workspace temporanee e nessun mount di auth CLI esterna +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinita: `~/.cache/openclaw/docker-cli-tools`) montata su `/home/node/.npm-global` per installazioni CLI in cache dentro Docker +- Le directory/file di auth CLI esterna sotto `$HOME` sono montati in sola lettura sotto `/host-auth...`, poi copiati in `/home/node/...` prima dell’avvio dei test - Directory predefinite: `.minimax` - File predefiniti: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Le esecuzioni con provider ristretto montano solo le directory/file necessari dedotti da `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Override manuale con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o un elenco separato da virgole come `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Le esecuzioni con provider ristretti montano solo le directory/file necessari dedotti da `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Override manuale con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oppure un elenco separato da virgole come `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` per restringere l’esecuzione - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` per filtrare i provider nel container -- `OPENCLAW_SKIP_DOCKER_BUILD=1` per riusare un’immagine `openclaw:local-live` esistente per riesecuzioni che non richiedono una rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurarsi che le credenziali provengano dallo store dei profili (non da env) -- `OPENCLAW_OPENWEBUI_MODEL=...` per scegliere il modello esposto dal gateway per lo smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` per sovrascrivere il prompt di controllo nonce usato dallo smoke Open WebUI -- `OPENWEBUI_IMAGE=...` per sovrascrivere il tag immagine Open WebUI fissato +- `OPENCLAW_SKIP_DOCKER_BUILD=1` per riutilizzare un’immagine `openclaw:local-live` esistente per riesecuzioni che non richiedono una rebuild +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurarsi che le credenziali provengano dallo store del profilo (non dall’env) +- `OPENCLAW_OPENWEBUI_MODEL=...` per scegliere il modello esposto dal Gateway per lo smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` per sostituire il prompt di controllo nonce usato dallo smoke Open WebUI +- `OPENWEBUI_IMAGE=...` per sostituire il tag dell’immagine Open WebUI fissata -## Controllo della documentazione +## Sanity check della documentazione -Esegui i controlli doc dopo modifiche alla documentazione: `pnpm check:docs`. -Esegui la validazione completa degli anchor Mintlify quando ti servono anche i controlli degli heading nella pagina: `pnpm docs:check-links:anchors`. +Esegui i controlli della documentazione dopo modifiche alla documentazione: `pnpm check:docs`. +Esegui la validazione completa degli anchor Mintlify quando ti servono anche i controlli delle intestazioni nella pagina: `pnpm docs:check-links:anchors`. -## Regressione offline (sicura per CI) +## Regressione offline (CI-safe) -Queste sono regressioni di “pipeline reale” senza provider reali: +Si tratta di regressioni di “pipeline reale” senza provider reali: -- Tool calling del Gateway (OpenAI mockato, gateway reale + loop dell’agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Tool calling del Gateway (OpenAI simulato, vero loop gateway + agent): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") - Wizard del Gateway (WS `wizard.start`/`wizard.next`, scrive config + auth enforced): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Valutazioni di affidabilità degli agenti (Skills) +## Valutazioni di affidabilità degli agent (Skills) -Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità degli agenti”: +Abbiamo già alcuni test CI-safe che si comportano come “valutazioni di affidabilità degli agent”: -- Tool-calling mockato tramite il gateway reale + loop dell’agente (`src/gateway/gateway.test.ts`). -- Flussi wizard end-to-end che validano wiring della sessione ed effetti della config (`src/gateway/gateway.test.ts`). +- Tool-calling simulata tramite il vero loop gateway + agent (`src/gateway/gateway.test.ts`). +- Flussi end-to-end del wizard che validano il wiring della sessione e gli effetti della configurazione (`src/gateway/gateway.test.ts`). Cosa manca ancora per le Skills (vedi [Skills](/it/tools/skills)): -- **Decisioning:** quando le Skills sono elencate nel prompt, l’agente sceglie la skill giusta (o evita quelle irrilevanti)? -- **Compliance:** l’agente legge `SKILL.md` prima dell’uso e segue i passaggi/argomenti richiesti? -- **Workflow contracts:** scenari multi-turn che verificano ordine dei tool, mantenimento della cronologia di sessione e confini della sandbox. +- **Decisioning:** quando le Skills sono elencate nel prompt, l’agent sceglie la Skill giusta (o evita quelle irrilevanti)? +- **Compliance:** l’agent legge `SKILL.md` prima dell’uso e segue passaggi/argomenti richiesti? +- **Workflow contracts:** scenari multi-turno che verificano ordine dei tool, persistenza della cronologia di sessione e boundary del sandbox. -Le future valutazioni dovrebbero restare prima di tutto deterministiche: +Le valutazioni future dovrebbero prima di tutto restare deterministiche: -- Un runner di scenari che usa provider mock per verificare chiamate ai tool + ordine, letture dei file skill e wiring della sessione. -- Una piccola suite di scenari focalizzati sulle skill (usa vs evita, gating, prompt injection). -- Valutazioni live facoltative (opt-in, protette da env) solo dopo che la suite sicura per CI è disponibile. +- Un runner di scenari che usa provider simulati per verificare chiamate ai tool + ordine, letture del file Skill e wiring della sessione. +- Una piccola suite di scenari focalizzati sulle Skill (usa vs evita, gating, prompt injection). +- Valutazioni live opzionali (opt-in, controllate da env) solo dopo che la suite CI-safe è pronta. -## Test di contratto (forma di plugin e canali) +## Test di contratto (forma di plugin e channel) -I test di contratto verificano che ogni plugin e canale registrato sia conforme al +I test di contratto verificano che ogni plugin e channel registrato sia conforme al proprio contratto di interfaccia. Iterano su tutti i plugin rilevati ed eseguono una suite di -verifiche di forma e comportamento. La lane unit predefinita `pnpm test` -salta intenzionalmente questi file condivisi di seam e smoke; esegui esplicitamente -i comandi dei contratti quando tocchi superfici condivise di canali o provider. +asserzioni di forma e comportamento. La lane unitaria predefinita `pnpm test` +salta intenzionalmente questi file shared seam e smoke; esegui i comandi di contratto esplicitamente +quando tocchi superfici condivise di channel o provider. ### Comandi - Tutti i contratti: `pnpm test:contracts` -- Solo contratti dei canali: `pnpm test:contracts:channels` -- Solo contratti dei provider: `pnpm test:contracts:plugins` +- Solo contratti channel: `pnpm test:contracts:channels` +- Solo contratti provider: `pnpm test:contracts:plugins` -### Contratti dei canali +### Contratti channel Si trovano in `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Forma base del plugin (id, nome, capability) +- **plugin** - Forma base del plugin (id, nome, capacità) - **setup** - Contratto del wizard di setup -- **session-binding** - Comportamento del binding di sessione +- **session-binding** - Comportamento del binding della sessione - **outbound-payload** - Struttura del payload del messaggio - **inbound** - Gestione dei messaggi in ingresso -- **actions** - Handler delle azioni del canale -- **threading** - Gestione degli id thread -- **directory** - API directory/roster -- **group-policy** - Applicazione della group policy +- **actions** - Handler delle azioni del channel +- **threading** - Gestione dell’id del thread +- **directory** - API di directory/roster +- **group-policy** - Enforcement della group policy -### Contratti di stato dei provider +### Contratti di stato del provider Si trovano in `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe di stato del canale +- **status** - Probe di stato del channel - **registry** - Forma del registro dei plugin -### Contratti dei provider +### Contratti provider Si trovano in `src/plugins/contracts/*.contract.test.ts`: - **auth** - Contratto del flusso auth - **auth-choice** - Scelta/selezione auth - **catalog** - API del catalogo modelli -- **discovery** - Discovery del plugin +- **discovery** - Rilevamento dei plugin - **loader** - Caricamento del plugin - **runtime** - Runtime del provider - **shape** - Forma/interfaccia del plugin @@ -1111,21 +1108,21 @@ Si trovano in `src/plugins/contracts/*.contract.test.ts`: ### Quando eseguirli -- Dopo aver modificato export o subpath di plugin-sdk -- Dopo aver aggiunto o modificato un plugin di canale o provider -- Dopo il refactor della registrazione o discovery dei plugin +- Dopo aver modificato export o sottopercorsi del plugin-sdk +- Dopo aver aggiunto o modificato un plugin channel o provider +- Dopo aver refattorizzato registrazione o rilevamento dei plugin -I test di contratto vengono eseguiti in CI e non richiedono chiavi API reali. +I test di contratto vengono eseguiti in CI e non richiedono API key reali. -## Aggiunta di regressioni (linee guida) +## Aggiungere regressioni (linee guida) -Quando correggi un problema di provider/modello scoperto in live: +Quando correggi un problema provider/modello scoperto in live: -- Aggiungi una regressione sicura per CI se possibile (provider mock/stub, oppure cattura dell’esatta trasformazione della forma della richiesta) +- Aggiungi se possibile una regressione CI-safe (provider simulato/finto, oppure acquisisci l’esatta trasformazione della forma della richiesta) - Se è intrinsecamente solo live (rate limit, policy auth), mantieni il test live ristretto e opt-in tramite variabili env -- Preferisci puntare al layer più piccolo che intercetta il bug: - - bug di conversione/replay della richiesta provider → test dei modelli diretti - - bug nella pipeline session/history/tool del gateway → gateway live smoke o test mock del gateway sicuro per CI -- Guardrail di attraversamento SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un target campionato per ogni classe SecretRef dai metadati del registro (`listSecretTargetRegistryEntries()`), poi verifica che gli id exec dei segmenti di attraversamento vengano rifiutati. - - Se aggiungi una nuova famiglia di target SecretRef `includeInPlan` in `src/secrets/target-registry-data.ts`, aggiorna `classifyTargetClass` in quel test. Il test fallisce intenzionalmente sugli id target non classificati così le nuove classi non possono essere saltate silenziosamente. +- Preferisci puntare al livello più piccolo che intercetta il bug: + - bug di conversione/replay della richiesta del provider → test dei modelli diretti + - bug della pipeline sessione/cronologia/tool del Gateway → Gateway live smoke o test mock del Gateway CI-safe +- Guardrail SecretRef traversal: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un target campionato per classe SecretRef dai metadati del registro (`listSecretTargetRegistryEntries()`), poi verifica che gli id exec dei segmenti traversal vengano rifiutati. + - Se aggiungi una nuova famiglia di target SecretRef `includeInPlan` in `src/secrets/target-registry-data.ts`, aggiorna `classifyTargetClass` in quel test. Il test fallisce intenzionalmente sugli id target non classificati così le nuove classi non possono essere saltate in silenzio.