diff --git a/docs/it/concepts/model-providers.md b/docs/it/concepts/model-providers.md index d7ef8f3bf..b83b7a1e0 100644 --- a/docs/it/concepts/model-providers.md +++ b/docs/it/concepts/model-providers.md @@ -1,21 +1,21 @@ --- read_when: - - Hai bisogno di un riferimento per la configurazione dei modelli, provider per provider + - Ti serve un riferimento per la configurazione dei modelli, provider per provider - Vuoi configurazioni di esempio o comandi di onboarding CLI per i provider di modelli -summary: Panoramica del provider di modelli con configurazioni di esempio + flussi CLI +summary: Panoramica dei provider di modelli con configurazioni di esempio + flussi CLI title: Provider di modelli x-i18n: - generated_at: "2026-04-11T02:44:28Z" + generated_at: "2026-04-13T08:27:13Z" model: gpt-5.4 provider: openai - source_hash: 910ea7895e74c03910757d9d3e02825754b779b204eca7275b28422647ed0151 + source_hash: 66ba688c4b4366eec07667571e835d4cfeee684896e2ffae11d601b5fa0a4b98 source_path: concepts/model-providers.md workflow: 15 --- # Provider di modelli -Questa pagina copre i **provider di LLM/modelli** (non i canali di chat come WhatsApp/Telegram). +Questa pagina copre i **provider LLM/modelli** (non i canali di chat come WhatsApp/Telegram). Per le regole di selezione del modello, vedi [/concepts/models](/it/concepts/models). ## Regole rapide @@ -25,17 +25,17 @@ Per le regole di selezione del modello, vedi [/concepts/models](/it/concepts/mod - Helper CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. - Le regole di runtime di fallback, le probe di cooldown e la persistenza delle override di sessione sono documentate in [/concepts/model-failover](/it/concepts/model-failover). -- `models.providers.*.models[].contextWindow` è metadato nativo del modello; - `models.providers.*.models[].contextTokens` è il limite effettivo del runtime. -- I plugin provider possono iniettare cataloghi di modelli tramite `registerProvider({ catalog })`; - OpenClaw unisce quell'output in `models.providers` prima di scrivere +- `models.providers.*.models[].contextWindow` sono metadati nativi del modello; + `models.providers.*.models[].contextTokens` è il limite effettivo di runtime. +- I Plugin provider possono iniettare cataloghi di modelli tramite `registerProvider({ catalog })`; + OpenClaw unisce questo output in `models.providers` prima di scrivere `models.json`. - I manifest dei provider possono dichiarare `providerAuthEnvVars` e - `providerAuthAliases` così le probe di autenticazione generiche basate su env e le varianti di provider - non devono caricare il runtime del plugin. La mappa rimanente delle variabili env nel core ora è - solo per i provider non plugin/core e per alcuni casi di precedenza generica come - l'onboarding Anthropic con priorità alla chiave API. -- I plugin provider possono anche gestire il comportamento di runtime del provider tramite + `providerAuthAliases` così le probe generiche di autenticazione basate su env e le varianti del provider + non devono caricare il runtime del plugin. La mappa rimanente delle variabili env del core ora è + solo per i provider non-plugin/core e per alcuni casi di precedenza generica, come + l'onboarding Anthropic con priorità alla API key. +- I Plugin provider possono anche gestire il comportamento di runtime del provider tramite `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -53,162 +53,204 @@ Per le regole di selezione del modello, vedi [/concepts/models](/it/concepts/mod `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, e `onModelSelected`. -- Nota: `capabilities` del runtime del provider è metadato condiviso del runner (famiglia del provider, - peculiarità di transcript/tooling, suggerimenti su transport/cache). Non è la - stessa cosa del [modello di capacità pubblico](/it/plugins/architecture#public-capability-model) - che descrive cosa registra un plugin (inferenza testuale, voce, ecc.). -- Il provider `codex` incluso è associato all'harness dell'agente Codex incluso. - Usa `codex/gpt-*` quando vuoi login gestito da Codex, rilevamento dei modelli, - ripresa nativa del thread ed esecuzione app-server. I riferimenti semplici `openai/gpt-*` continuano +- Nota: le `capabilities` di runtime del provider sono metadati condivisi del runner (famiglia del provider, + particolarità di trascrizione/tooling, hint di transport/cache). Non sono la + stessa cosa del [modello di capability pubblico](/it/plugins/architecture#public-capability-model) + che descrive cosa registra un plugin (inferenza testuale, speech, ecc.). +- Il provider `codex` incluso è abbinato all'harness agent Codex incluso. + Usa `codex/gpt-*` quando vuoi login gestito da Codex, discovery dei modelli, + ripresa nativa dei thread ed esecuzione app-server. I riferimenti semplici `openai/gpt-*` continuano a usare il provider OpenAI e il normale transport provider di OpenClaw. - Le distribuzioni solo Codex possono disabilitare il fallback automatico a PI con + I deployment solo-Codex possono disabilitare il fallback PI automatico con `agents.defaults.embeddedHarness.fallback: "none"`; vedi [Codex Harness](/it/plugins/codex-harness). ## Comportamento del provider gestito dal plugin -I plugin provider possono ora gestire la maggior parte della logica specifica del provider, mentre OpenClaw mantiene +I Plugin provider ora possono gestire la maggior parte della logica specifica del provider mentre OpenClaw mantiene il loop di inferenza generico. Suddivisione tipica: - `auth[].run` / `auth[].runNonInteractive`: il provider gestisce i flussi di onboarding/login per `openclaw onboard`, `openclaw models auth` e la configurazione headless -- `wizard.setup` / `wizard.modelPicker`: il provider gestisce etichette per le scelte di autenticazione, - alias legacy, suggerimenti di allowlist per l'onboarding e voci di configurazione nei selettori di onboarding/modello +- `wizard.setup` / `wizard.modelPicker`: il provider gestisce le etichette di scelta auth, + gli alias legacy, gli hint di allowlist per l'onboarding e le voci di configurazione nei selettori onboarding/modelli - `catalog`: il provider appare in `models.providers` -- `normalizeModelId`: il provider normalizza gli id dei modelli legacy/preview prima della - ricerca o canonizzazione +- `normalizeModelId`: il provider normalizza gli id dei modelli legacy/preview prima del + lookup o della canonicalizzazione - `normalizeTransport`: il provider normalizza `api` / `baseUrl` della famiglia di transport prima dell'assemblaggio generico del modello; OpenClaw controlla prima il provider corrispondente, - poi altri plugin provider con hook compatibili finché uno non modifica effettivamente il + poi gli altri Plugin provider con hook-capable finché uno non modifica davvero il transport - `normalizeConfig`: il provider normalizza la configurazione `models.providers.` prima che il - runtime la usi; OpenClaw controlla prima il provider corrispondente, poi altri - plugin provider con hook compatibili finché uno non modifica effettivamente la configurazione. Se nessun + runtime la usi; OpenClaw controlla prima il provider corrispondente, poi gli altri + Plugin provider con hook-capable finché uno non modifica davvero la configurazione. Se nessun hook del provider riscrive la configurazione, gli helper inclusi della famiglia Google continuano a normalizzare le voci supportate dei provider Google. -- `applyNativeStreamingUsageCompat`: il provider applica riscritture di compatibilità dell'uso dello streaming nativo guidate dall'endpoint per i provider di configurazione -- `resolveConfigApiKey`: il provider risolve l'autenticazione con marcatore env per i provider di configurazione - senza forzare il caricamento completo dell'autenticazione di runtime. `amazon-bedrock` ha anche un - resolver integrato per i marcatori env AWS qui, anche se l'autenticazione di runtime di Bedrock usa - la catena predefinita dell'SDK AWS. -- `resolveSyntheticAuth`: il provider può esporre la disponibilità dell'autenticazione +- `applyNativeStreamingUsageCompat`: il provider applica riscritture di compatibilità native di streaming-usage guidate dagli endpoint per i provider di configurazione +- `resolveConfigApiKey`: il provider risolve l'autenticazione con marker env per i provider di configurazione + senza forzare il caricamento completo dell'autenticazione runtime. `amazon-bedrock` ha anche un + resolver integrato di marker env AWS qui, anche se l'autenticazione runtime di Bedrock usa + la catena predefinita dell'AWS SDK. +- `resolveSyntheticAuth`: il provider può esporre la disponibilità di autenticazione locale/self-hosted o altra autenticazione basata su configurazione senza persistere segreti in chiaro -- `shouldDeferSyntheticProfileAuth`: il provider può contrassegnare i placeholder di profilo sintetico memorizzati +- `shouldDeferSyntheticProfileAuth`: il provider può contrassegnare i placeholder sintetici di profilo memorizzati come con precedenza inferiore rispetto all'autenticazione basata su env/config - `resolveDynamicModel`: il provider accetta id di modello non ancora presenti nel catalogo statico locale -- `prepareDynamicModel`: il provider necessita di un aggiornamento dei metadati prima di riprovare +- `prepareDynamicModel`: il provider richiede un refresh dei metadati prima di ritentare la risoluzione dinamica -- `normalizeResolvedModel`: il provider necessita di riscritture del transport o del base URL -- `contributeResolvedModelCompat`: il provider contribuisce flag di compatibilità per i propri - modelli del vendor anche quando arrivano tramite un altro transport compatibile -- `capabilities`: il provider pubblica peculiarità di transcript/tooling/famiglia del provider -- `normalizeToolSchemas`: il provider ripulisce gli schemi degli strumenti prima che il - runner incorporato li veda +- `normalizeResolvedModel`: il provider richiede riscritture di transport o base URL +- `contributeResolvedModelCompat`: il provider contribuisce flag di compatibilità per i suoi + modelli vendor anche quando arrivano tramite un altro transport compatibile +- `capabilities`: il provider pubblica particolarità di trascrizione/tooling/famiglia provider +- `normalizeToolSchemas`: il provider ripulisce gli schemi dei tool prima che il + runner integrato li veda - `inspectToolSchemas`: il provider espone avvisi sugli schemi specifici del transport dopo la normalizzazione -- `resolveReasoningOutputMode`: il provider sceglie contratti di output del ragionamento +- `resolveReasoningOutputMode`: il provider sceglie tra contratti di output del reasoning nativi o con tag -- `prepareExtraParams`: il provider imposta valori predefiniti o normalizza parametri di richiesta per modello +- `prepareExtraParams`: il provider imposta valori predefiniti o normalizza i parametri di richiesta per modello - `createStreamFn`: il provider sostituisce il normale percorso di stream con un transport completamente personalizzato -- `wrapStreamFn`: il provider applica wrapper di compatibilità per header/body/modello della richiesta +- `wrapStreamFn`: il provider applica wrapper di compatibilità a header/body/modello della richiesta - `resolveTransportTurnState`: il provider fornisce header o metadati nativi del transport per turno -- `resolveWebSocketSessionPolicy`: il provider fornisce header nativi di sessione WebSocket - o una policy di raffreddamento della sessione +- `resolveWebSocketSessionPolicy`: il provider fornisce header nativi della sessione WebSocket + o la policy di cool-down della sessione - `createEmbeddingProvider`: il provider gestisce il comportamento degli embedding della memoria quando - appartiene al plugin provider invece che allo switchboard core degli embedding -- `formatApiKey`: il provider formatta i profili di autenticazione memorizzati nella stringa - di `apiKey` del runtime attesa dal transport -- `refreshOAuth`: il provider gestisce l'aggiornamento OAuth quando i refresher condivisi `pi-ai` - non sono sufficienti -- `buildAuthDoctorHint`: il provider aggiunge indicazioni di riparazione quando l'aggiornamento OAuth + appartiene al Plugin provider invece che allo switchboard embedding del core +- `formatApiKey`: il provider formatta i profili auth memorizzati nella stringa + `apiKey` di runtime attesa dal transport +- `refreshOAuth`: il provider gestisce il refresh OAuth quando i refresher condivisi + `pi-ai` non sono sufficienti +- `buildAuthDoctorHint`: il provider aggiunge indicazioni di riparazione quando il refresh OAuth fallisce -- `matchesContextOverflowError`: il provider riconosce errori di overflow della finestra di contesto - specifici del provider che le euristiche generiche non rileverebbero -- `classifyFailoverReason`: il provider mappa errori raw di transport/API specifici del provider - in motivi di failover come rate limit o sovraccarico -- `isCacheTtlEligible`: il provider decide quali id di modello upstream supportano il TTL della cache dei prompt +- `matchesContextOverflowError`: il provider riconosce errori di overflow della + finestra di contesto specifici del provider che le euristiche generiche non rileverebbero +- `classifyFailoverReason`: il provider mappa errori grezzi specifici del provider del transport/API + in motivi di failover come rate limit o overload +- `isCacheTtlEligible`: il provider decide quali id di modello upstream supportano il TTL della prompt-cache - `buildMissingAuthMessage`: il provider sostituisce l'errore generico dell'auth-store - con un suggerimento di recupero specifico del provider + con un hint di recupero specifico del provider - `suppressBuiltInModel`: il provider nasconde righe upstream obsolete e può restituire un - errore gestito dal vendor per i fallimenti di risoluzione diretta + errore gestito dal vendor per errori di risoluzione diretta - `augmentModelCatalog`: il provider aggiunge righe sintetiche/finali al catalogo dopo - il rilevamento e il merge della configurazione + discovery e merge della configurazione - `isBinaryThinking`: il provider gestisce l'esperienza thinking binaria on/off -- `supportsXHighThinking`: il provider abilita `xhigh` per modelli selezionati -- `resolveDefaultThinkingLevel`: il provider gestisce la policy predefinita di `/think` per una +- `supportsXHighThinking`: il provider abilita `xhigh` per i modelli selezionati +- `resolveDefaultThinkingLevel`: il provider gestisce la policy `/think` predefinita per una famiglia di modelli -- `applyConfigDefaults`: il provider applica valori predefiniti globali specifici del provider - durante la materializzazione della configurazione in base alla modalità di autenticazione, all'env o alla famiglia di modelli -- `isModernModelRef`: il provider gestisce la corrispondenza del modello preferito live/smoke +- `applyConfigDefaults`: il provider applica valori globali predefiniti specifici del provider + durante la materializzazione della configurazione in base a modalità auth, env o famiglia di modelli +- `isModernModelRef`: il provider gestisce la corrispondenza del modello preferito per live/smoke - `prepareRuntimeAuth`: il provider trasforma una credenziale configurata in un token di runtime - di breve durata + a breve durata - `resolveUsageAuth`: il provider risolve le credenziali di utilizzo/quota per `/usage` e le relative superfici di stato/reporting - `fetchUsageSnapshot`: il provider gestisce il recupero/parsing dell'endpoint di utilizzo mentre - il core continua a gestire la shell di riepilogo e la formattazione + il core continua a gestire il wrapper di riepilogo e la formattazione - `onModelSelected`: il provider esegue effetti collaterali post-selezione come telemetria o bookkeeping della sessione gestito dal provider Esempi inclusi attuali: -- `anthropic`: fallback forward-compat per Claude 4.6, suggerimenti per la riparazione dell'autenticazione, recupero dell'endpoint di utilizzo, metadati cache-TTL/famiglia provider e valori predefiniti globali della configurazione sensibili all'autenticazione -- `amazon-bedrock`: riconoscimento dell'overflow del contesto gestito dal provider e classificazione dei motivi di failover per errori specifici di Bedrock come throttle/not-ready, oltre alla famiglia di replay condivisa `anthropic-by-model` per le protezioni della replay-policy solo Claude sul traffico Anthropic -- `anthropic-vertex`: protezioni della replay-policy solo Claude sul traffico `anthropic-message` -- `openrouter`: id modello pass-through, wrapper delle richieste, hint sulle capacità del provider, sanitizzazione della thought-signature Gemini sul traffico Gemini via proxy, iniezione del ragionamento via proxy tramite la famiglia di stream `openrouter-thinking`, inoltro dei metadati di routing e policy cache-TTL -- `github-copilot`: onboarding/login del dispositivo, fallback forward-compat dei modelli, hint del transcript Claude-thinking, scambio del token di runtime e recupero dell'endpoint di utilizzo -- `openai`: fallback forward-compat per GPT-5.4, normalizzazione diretta del transport OpenAI, hint per autenticazione mancante consapevoli di Codex, soppressione di Spark, righe sintetiche del catalogo OpenAI/Codex, policy thinking/live-model, normalizzazione degli alias dei token di utilizzo (`input` / `output` e famiglie `prompt` / `completion`), famiglia di stream condivisa `openai-responses-defaults` per wrapper nativi OpenAI/Codex, metadati della famiglia provider, registrazione del provider di generazione immagini incluso per `gpt-image-1` e registrazione del provider di generazione video incluso per `sora-2` -- `google` e `google-gemini-cli`: fallback forward-compat per Gemini 3.1, validazione replay nativa Gemini, sanitizzazione del replay bootstrap, modalità di output del ragionamento con tag, corrispondenza modern-model, registrazione del provider di generazione immagini incluso per i modelli Gemini image-preview e registrazione del provider di generazione video incluso per i modelli Veo; inoltre Gemini CLI OAuth gestisce la formattazione del token del profilo di autenticazione, il parsing del token di utilizzo e il recupero dell'endpoint quota per le superfici di utilizzo +- `anthropic`: fallback forward-compat per Claude 4.6, hint di riparazione auth, recupero dell'endpoint + di utilizzo, metadati cache-TTL/famiglia provider e valori globali predefiniti di configurazione + consapevoli dell'auth +- `amazon-bedrock`: riconoscimento dell'overflow del contesto gestito dal provider e classificazione dei + motivi di failover per errori specifici di Bedrock come throttle/not-ready, più + la famiglia di replay condivisa `anthropic-by-model` per guardrail della replay-policy solo-Claude + sul traffico Anthropic +- `anthropic-vertex`: guardrail della replay-policy solo-Claude sul traffico + Anthropic-message +- `openrouter`: id modello pass-through, wrapper delle richieste, hint di capability del provider, + sanitizzazione della thought-signature Gemini su traffico Gemini tramite proxy, iniezione del + reasoning tramite proxy attraverso la famiglia di stream `openrouter-thinking`, inoltro dei + metadati di routing e policy cache-TTL +- `github-copilot`: onboarding/login del dispositivo, fallback del modello forward-compat, + hint di trascrizione Claude-thinking, scambio di token di runtime e recupero dell'endpoint + di utilizzo +- `openai`: fallback forward-compat GPT-5.4, normalizzazione diretta del transport OpenAI, + hint di autenticazione mancante consapevoli di Codex, soppressione di Spark, righe sintetiche del + catalogo OpenAI/Codex, policy di thinking/modello live, normalizzazione degli alias dei token + di utilizzo (`input` / `output` e famiglie `prompt` / `completion`), la famiglia di stream condivisa + `openai-responses-defaults` per wrapper nativi OpenAI/Codex, metadati della famiglia provider, + registrazione inclusa del provider di generazione immagini per `gpt-image-1` e registrazione inclusa del provider + di generazione video per `sora-2` +- `google` e `google-gemini-cli`: fallback forward-compat Gemini 3.1, + validazione nativa del replay Gemini, sanitizzazione del replay bootstrap, modalità + di output reasoning con tag, corrispondenza dei modelli moderni, registrazione inclusa del provider + di generazione immagini per i modelli Gemini image-preview e registrazione inclusa del + provider di generazione video per i modelli Veo; Gemini CLI OAuth gestisce anche + la formattazione del token del profilo auth, il parsing del token di utilizzo e il recupero dell'endpoint + quota per le superfici di utilizzo - `moonshot`: transport condiviso, normalizzazione del payload thinking gestita dal plugin -- `kilocode`: transport condiviso, header delle richieste gestiti dal plugin, normalizzazione del payload di ragionamento, sanitizzazione della thought-signature Gemini via proxy e policy cache-TTL -- `zai`: fallback forward-compat per GLM-5, valori predefiniti `tool_stream`, policy cache-TTL, policy binary-thinking/live-model e autenticazione utilizzo + recupero quota; gli id sconosciuti `glm-5*` vengono sintetizzati dal template incluso `glm-4.7` -- `xai`: normalizzazione nativa del transport Responses, riscritture degli alias `/fast` per le varianti Grok fast, `tool_stream` predefinito, pulizia specifica xAI di schema strumenti / payload di ragionamento e registrazione del provider di generazione video incluso per `grok-imagine-video` -- `mistral`: metadati delle capacità gestiti dal plugin -- `opencode` e `opencode-go`: metadati delle capacità gestiti dal plugin più sanitizzazione della thought-signature Gemini via proxy -- `alibaba`: catalogo di generazione video gestito dal plugin per riferimenti diretti a modelli Wan come `alibaba/wan2.6-t2v` -- `byteplus`: cataloghi gestiti dal plugin più registrazione del provider di generazione video incluso per i modelli Seedance text-to-video/image-to-video -- `fal`: registrazione del provider di generazione video incluso per provider hosted di terze parti, registrazione del provider di generazione immagini per i modelli immagine FLUX, più registrazione del provider di generazione video incluso per modelli video hosted di terze parti +- `kilocode`: transport condiviso, header delle richieste gestiti dal plugin, normalizzazione del payload di reasoning, + sanitizzazione della thought-signature proxy-Gemini e policy cache-TTL +- `zai`: fallback forward-compat GLM-5, valori predefiniti `tool_stream`, policy cache-TTL, + policy binary-thinking/live-model e auth di utilizzo + recupero della quota; + gli id sconosciuti `glm-5*` vengono sintetizzati dal template incluso `glm-4.7` +- `xai`: normalizzazione nativa del transport Responses, riscritture dell'alias `/fast` per + le varianti veloci di Grok, valore predefinito `tool_stream`, pulizia specifica xAI di tool-schema / + reasoning-payload e registrazione inclusa del provider di generazione video + per `grok-imagine-video` +- `mistral`: metadati di capability gestiti dal plugin +- `opencode` e `opencode-go`: metadati di capability gestiti dal plugin più + sanitizzazione della thought-signature proxy-Gemini +- `alibaba`: catalogo di generazione video gestito dal plugin per riferimenti diretti ai modelli Wan + come `alibaba/wan2.6-t2v` +- `byteplus`: cataloghi gestiti dal plugin più registrazione inclusa del provider di generazione video + per i modelli Seedance text-to-video/image-to-video +- `fal`: registrazione inclusa del provider di generazione video per modelli video hosted di terze parti + registrazione del provider di generazione immagini per i modelli immagine FLUX più registrazione inclusa + del provider di generazione video per modelli video hosted di terze parti - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` e `volcengine`: solo cataloghi gestiti dal plugin -- `qwen`: cataloghi gestiti dal plugin per i modelli testuali più registrazioni condivise dei provider media-understanding e video-generation per le sue superfici multimodali; la generazione video Qwen usa gli endpoint video Standard DashScope con i modelli Wan inclusi come `wan2.6-t2v` e `wan2.7-r2v` -- `runway`: registrazione del provider di generazione video gestita dal plugin per modelli nativi Runway basati su task come `gen4.5` -- `minimax`: cataloghi gestiti dal plugin, registrazione del provider di generazione video incluso per i modelli video Hailuo, registrazione del provider di generazione immagini incluso per `image-01`, selezione ibrida della replay-policy Anthropic/OpenAI e logica di autenticazione/snapshot dell'utilizzo -- `together`: cataloghi gestiti dal plugin più registrazione del provider di generazione video incluso per i modelli video Wan -- `xiaomi`: cataloghi gestiti dal plugin più logica di autenticazione/snapshot dell'utilizzo +- `qwen`: cataloghi gestiti dal plugin per modelli testuali più registrazioni condivise + del provider media-understanding e del provider di generazione video per le sue + superfici multimodali; la generazione video Qwen usa gli endpoint video Standard DashScope + con modelli Wan inclusi come `wan2.6-t2v` e `wan2.7-r2v` +- `runway`: registrazione del provider di generazione video gestita dal plugin per modelli nativi + Runway basati su task come `gen4.5` +- `minimax`: cataloghi gestiti dal plugin, registrazione inclusa del provider di generazione video + per i modelli video Hailuo, registrazione inclusa del provider di generazione immagini + per `image-01`, selezione ibrida della replay-policy Anthropic/OpenAI e logica + auth/snapshot di utilizzo +- `together`: cataloghi gestiti dal plugin più registrazione inclusa del provider di generazione video + per i modelli video Wan +- `xiaomi`: cataloghi gestiti dal plugin più logica auth/snapshot di utilizzo Il plugin `openai` incluso ora gestisce entrambi gli id provider: `openai` e `openai-codex`. Questo copre i provider che rientrano ancora nei transport normali di OpenClaw. Un provider -che richiede un esecutore di richieste completamente personalizzato è una superficie di estensione +che richiede un esecutore di richieste totalmente personalizzato è una superficie di estensione separata e più profonda. -## Rotazione delle chiavi API +## Rotazione delle API key - Supporta la rotazione generica del provider per provider selezionati. - Configura più chiavi tramite: - `OPENCLAW_LIVE__KEY` (singolo override live, priorità massima) - - `_API_KEYS` (elenco separato da virgole o punto e virgola) + - `_API_KEYS` (lista separata da virgole o punto e virgola) - `_API_KEY` (chiave primaria) - - `_API_KEY_*` (elenco numerato, ad esempio `_API_KEY_1`) + - `_API_KEY_*` (lista numerata, ad esempio `_API_KEY_1`) - Per i provider Google, `GOOGLE_API_KEY` è incluso anche come fallback. - L'ordine di selezione delle chiavi preserva la priorità e rimuove i duplicati. - Le richieste vengono ritentate con la chiave successiva solo in caso di risposte con rate limit (per esempio `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` o messaggi periodici di limite d'uso). + `workers_ai ... quota limit exceeded` o messaggi periodici di limite di utilizzo). - I fallimenti non dovuti a rate limit falliscono immediatamente; non viene tentata alcuna rotazione delle chiavi. -- Quando tutte le chiavi candidate falliscono, viene restituito l'errore finale dell'ultimo tentativo. +- Quando tutte le chiavi candidate falliscono, l'errore finale viene restituito dall'ultimo tentativo. ## Provider integrati (catalogo pi-ai) OpenClaw include il catalogo pi‑ai. Questi provider non richiedono alcuna -configurazione `models.providers`; basta impostare l'autenticazione e scegliere un modello. +configurazione `models.providers`; basta impostare l'auth e scegliere un modello. ### OpenAI @@ -221,14 +263,14 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere - Override per modello tramite `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) - Il warm-up WebSocket di OpenAI Responses è abilitato per impostazione predefinita tramite `params.openaiWsWarmup` (`true`/`false`) - L'elaborazione prioritaria OpenAI può essere abilitata tramite `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` e `params.fastMode` mappano le richieste dirette Responses `openai/*` a `service_tier=priority` su `api.openai.com` -- Usa `params.serviceTier` quando vuoi un tier esplicito invece dell'interruttore condiviso `/fast` -- Gli header di attribuzione OpenClaw nascosti (`originator`, `version`, - `User-Agent`) si applicano solo al traffico nativo OpenAI verso `api.openai.com`, non ai - proxy generici compatibili con OpenAI -- I percorsi nativi OpenAI mantengono anche `store` di Responses, hint della cache dei prompt e - la modellazione del payload di compatibilità del ragionamento OpenAI; i percorsi proxy no -- `openai/gpt-5.3-codex-spark` è intenzionalmente soppresso in OpenClaw perché la OpenAI API live lo rifiuta; Spark è trattato come solo Codex +- `/fast` e `params.fastMode` mappano le richieste Responses dirette `openai/*` a `service_tier=priority` su `api.openai.com` +- Usa `params.serviceTier` quando vuoi un tier esplicito invece del toggle condiviso `/fast` +- Gli header di attribuzione nascosti di OpenClaw (`originator`, `version`, + `User-Agent`) si applicano solo al traffico OpenAI nativo verso `api.openai.com`, non + ai proxy generici compatibili con OpenAI +- I percorsi OpenAI nativi mantengono anche `store` di Responses, hint di prompt-cache e + modellazione del payload di compatibilità reasoning OpenAI; i percorsi proxy no +- `openai/gpt-5.3-codex-spark` è intenzionalmente soppresso in OpenClaw perché la OpenAI API live lo rifiuta; Spark è trattato solo come Codex ```json5 { @@ -243,8 +285,8 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere - Rotazione opzionale: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, più `OPENCLAW_LIVE_ANTHROPIC_KEY` (singolo override) - Modello di esempio: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Le richieste pubbliche dirette ad Anthropic supportano anche l'interruttore condiviso `/fast` e `params.fastMode`, incluso il traffico autenticato con chiave API e OAuth inviato a `api.anthropic.com`; OpenClaw lo mappa a Anthropic `service_tier` (`auto` vs `standard_only`) -- Nota Anthropic: lo staff Anthropic ci ha detto che l'uso di Claude CLI in stile OpenClaw è di nuovo 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. +- Le richieste Anthropic pubbliche dirette supportano anche il toggle condiviso `/fast` e `params.fastMode`, incluso il traffico autenticato con API key e OAuth inviato a `api.anthropic.com`; OpenClaw lo mappa a `service_tier` Anthropic (`auto` vs `standard_only`) +- Nota Anthropic: il personale Anthropic ci ha detto che l'uso in stile Claude CLI di OpenClaw è di nuovo consentito, quindi OpenClaw tratta 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. - Il setup-token Anthropic resta disponibile come percorso token OpenClaw supportato, ma OpenClaw ora preferisce il riutilizzo di Claude CLI e `claude -p` quando disponibili. ```json5 @@ -262,12 +304,12 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere - Il transport predefinito è `auto` (prima WebSocket, fallback SSE) - Override per modello tramite `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) - `params.serviceTier` viene inoltrato anche nelle richieste native Codex Responses (`chatgpt.com/backend-api`) -- Gli header di attribuzione OpenClaw nascosti (`originator`, `version`, - `User-Agent`) vengono allegati solo al traffico nativo Codex verso +- Gli header di attribuzione nascosti di OpenClaw (`originator`, `version`, + `User-Agent`) vengono allegati solo al traffico Codex nativo verso `chatgpt.com/backend-api`, non ai proxy generici compatibili con OpenAI -- Condivide lo stesso interruttore `/fast` e la stessa configurazione `params.fastMode` di `openai/*` diretto; OpenClaw lo mappa a `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` resta disponibile quando il catalogo OAuth Codex lo espone; dipende dai diritti disponibili -- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo e un valore predefinito di runtime `contextTokens = 272000`; sostituisci il limite di runtime con `models.providers.openai-codex.models[].contextTokens` +- Condivide lo stesso toggle `/fast` e la stessa configurazione `params.fastMode` di `openai/*` diretto; OpenClaw lo mappa a `service_tier=priority` +- `openai-codex/gpt-5.3-codex-spark` resta disponibile quando il catalogo OAuth Codex lo espone; dipende dai diritti +- `openai-codex/gpt-5.4` mantiene il valore nativo `contextWindow = 1050000` e un valore predefinito di runtime `contextTokens = 272000`; esegui l'override del limite di runtime con `models.providers.openai-codex.models[].contextTokens` - Nota sulla policy: OpenAI Codex OAuth è esplicitamente supportato per strumenti/workflow esterni come OpenClaw. ```json5 @@ -288,11 +330,11 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere } ``` -### Altre opzioni ospitate in stile abbonamento +### Altre opzioni hosted in stile abbonamento - [Qwen Cloud](/it/providers/qwen): superficie provider Qwen Cloud più mapping degli endpoint Alibaba DashScope e Coding Plan -- [MiniMax](/it/providers/minimax): accesso MiniMax Coding Plan OAuth o con chiave API -- [GLM Models](/it/providers/glm): endpoint Z.AI Coding Plan o API generiche +- [MiniMax](/it/providers/minimax): accesso MiniMax Coding Plan con OAuth o API key +- [GLM Models](/it/providers/glm): endpoint Z.AI Coding Plan o endpoint API generici ### OpenCode @@ -308,35 +350,35 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere } ``` -### Google Gemini (chiave API) +### Google Gemini (API key) - Provider: `google` - Auth: `GEMINI_API_KEY` - Rotazione opzionale: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (singolo override) - Modelli di esempio: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` -- Compatibilità: la configurazione OpenClaw legacy che usa `google/gemini-3.1-flash-preview` viene normalizzata in `google/gemini-3-flash-preview` +- Compatibilità: la configurazione legacy di OpenClaw che usa `google/gemini-3.1-flash-preview` viene normalizzata in `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Le esecuzioni Gemini dirette accettano anche `agents.defaults.models["google/"].params.cachedContent` (o il legacy `cached_content`) per inoltrare un handle nativo del provider - `cachedContents/...`; i cache hit Gemini vengono esposti come OpenClaw `cacheRead` + `cachedContents/...`; i cache hit Gemini emergono come `cacheRead` di OpenClaw ### Google Vertex e Gemini CLI - Provider: `google-vertex`, `google-gemini-cli` - Auth: Vertex usa gcloud ADC; Gemini CLI usa il proprio flusso OAuth - Attenzione: Gemini CLI OAuth in OpenClaw è un'integrazione non ufficiale. Alcuni utenti hanno segnalato restrizioni dell'account Google dopo l'uso di client di terze parti. Rivedi i termini di Google e usa un account non critico se scegli di procedere. -- Gemini CLI OAuth è distribuito come parte del plugin `google` incluso. +- Gemini CLI OAuth viene distribuito come parte del plugin `google` incluso. - Installa prima Gemini CLI: - `brew install gemini-cli` - oppure `npm install -g @google/gemini-cli` - Abilita: `openclaw plugins enable google` - Login: `openclaw models auth login --provider google-gemini-cli --set-default` - Modello predefinito: `google-gemini-cli/gemini-3-flash-preview` - - Nota: **non** incolli un client id o secret in `openclaw.json`. Il flusso di login della CLI memorizza - i token nei profili di autenticazione sull'host gateway. - - Se le richieste falliscono dopo il login, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host gateway. - - Le risposte JSON di Gemini CLI vengono analizzate da `response`; l'utilizzo usa come fallback - `stats`, con `stats.cached` normalizzato in OpenClaw `cacheRead`. + - Nota: **non** incolli un client id o un secret in `openclaw.json`. Il flusso di login CLI memorizza + i token nei profili auth sull'host Gateway. + - Se le richieste falliscono dopo il login, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host Gateway. + - Le risposte JSON di Gemini CLI vengono parsate da `response`; l'utilizzo usa come fallback + `stats`, con `stats.cached` normalizzato in `cacheRead` di OpenClaw. ### Z.AI (GLM) @@ -361,36 +403,36 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere - Modello di esempio: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - Base URL: `https://api.kilo.ai/api/gateway/` -- Il catalogo statico di fallback include `kilocode/kilo/auto`; il rilevamento live di +- Il catalogo statico di fallback include `kilocode/kilo/auto`; la discovery live su `https://api.kilo.ai/api/gateway/models` può espandere ulteriormente il catalogo di runtime. - Il routing upstream esatto dietro `kilocode/kilo/auto` è gestito da Kilo Gateway, - non codificato rigidamente in OpenClaw. + non hardcoded in OpenClaw. Vedi [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazione. -### Altri plugin provider inclusi +### Altri Plugin provider inclusi - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Modello di esempio: `openrouter/auto` -- OpenClaw applica gli header di attribuzione app documentati di OpenRouter solo quando - la richiesta punta effettivamente a `openrouter.ai` -- I marker `cache_control` specifici di Anthropic per OpenRouter sono allo stesso modo limitati +- OpenClaw applica gli header di attribuzione dell'app documentati da OpenRouter solo quando + la richiesta ha davvero come destinazione `openrouter.ai` +- I marker Anthropic `cache_control` specifici di OpenRouter sono analogamente limitati a route OpenRouter verificate, non a URL proxy arbitrari -- OpenRouter resta sul percorso in stile proxy compatibile con OpenAI, quindi la - modellazione della richiesta solo OpenAI nativa (`serviceTier`, `store` di Responses, - hint della cache dei prompt, payload di compatibilità del ragionamento OpenAI) non viene inoltrata +- OpenRouter resta sul percorso compatibile con OpenAI in stile proxy, quindi la + modellazione nativa delle richieste solo-OpenAI (`serviceTier`, `store` di Responses, + hint di prompt-cache, payload di compatibilità reasoning OpenAI) non viene inoltrata - I riferimenti OpenRouter basati su Gemini mantengono solo la sanitizzazione della thought-signature proxy-Gemini; - la validazione replay Gemini nativa e le riscritture bootstrap restano disattivate + la validazione nativa del replay Gemini e le riscritture bootstrap restano disattivate - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Modello di esempio: `kilocode/kilo/auto` -- I riferimenti Kilo basati su Gemini mantengono lo stesso percorso di sanitizzazione della thought-signature - proxy-Gemini; `kilocode/kilo/auto` e altri hint in cui il ragionamento proxy non è supportato - saltano l'iniezione del ragionamento proxy -- MiniMax: `minimax` (chiave API) e `minimax-portal` (OAuth) +- I riferimenti Kilo basati su Gemini mantengono lo stesso percorso di + sanitizzazione della thought-signature proxy-Gemini; `kilocode/kilo/auto` e altri hint proxy-reasoning-unsupported + saltano l'iniezione del reasoning via proxy +- MiniMax: `minimax` (API key) e `minimax-portal` (OAuth) - Auth: `MINIMAX_API_KEY` per `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` per `minimax-portal` - Modello di esempio: `minimax/MiniMax-M2.7` o `minimax-portal/MiniMax-M2.7` -- La configurazione onboarding/chiave API di MiniMax scrive definizioni esplicite del modello M2.7 con +- L'onboarding/configurazione API key MiniMax scrive definizioni esplicite del modello M2.7 con `input: ["text", "image"]`; il catalogo del provider incluso mantiene i riferimenti chat solo testo finché quella configurazione del provider non viene materializzata - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) @@ -422,8 +464,8 @@ Vedi [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazi - `/fast` o `params.fastMode: true` riscrivono `grok-3`, `grok-3-mini`, `grok-4` e `grok-4-0709` nelle rispettive varianti `*-fast` - `tool_stream` è attivo per impostazione predefinita; imposta - `agents.defaults.models["xai/"].params.tool_stream` su `false` per - disattivarlo + `agents.defaults.models["xai/"].params.tool_stream` a `false` per + disabilitarlo - Mistral: `mistral` (`MISTRAL_API_KEY`) - Modello di esempio: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` @@ -434,20 +476,20 @@ Vedi [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazi - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Modello di esempio Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Vedi [Hugging Face (Inference)](/it/providers/huggingface). -## Provider tramite `models.providers` (custom/base URL) +## Provider tramite `models.providers` (base URL personalizzato) Usa `models.providers` (o `models.json`) per aggiungere provider **personalizzati** o proxy compatibili con OpenAI/Anthropic. -Molti dei plugin provider inclusi qui sotto pubblicano già un catalogo predefinito. -Usa voci esplicite `models.providers.` solo quando vuoi sovrascrivere -base URL, header o elenco modelli predefiniti. +Molti dei Plugin provider inclusi qui sotto pubblicano già un catalogo predefinito. +Usa voci esplicite `models.providers.` solo quando vuoi sovrascrivere la +base URL, gli header o l'elenco modelli predefiniti. ### Moonshot AI (Kimi) -Moonshot è distribuito come plugin provider incluso. Usa il provider integrato per +Moonshot è distribuito come Plugin provider incluso. Usa il provider integrato per impostazione predefinita e aggiungi una voce esplicita `models.providers.moonshot` solo quando -devi sovrascrivere il base URL o i metadati del modello: +devi sovrascrivere la base URL o i metadati del modello: - Provider: `moonshot` - Auth: `MOONSHOT_API_KEY` @@ -501,7 +543,7 @@ Kimi Coding usa l'endpoint compatibile con Anthropic di Moonshot AI: } ``` -Il legacy `kimi/k2p5` continua a essere accettato come id modello di compatibilità. +Il legacy `kimi/k2p5` resta accettato come id modello di compatibilità. ### Volcano Engine (Doubao) @@ -520,13 +562,12 @@ Volcano Engine (火山引擎) fornisce accesso a Doubao e ad altri modelli in Ci } ``` -L'onboarding usa per impostazione predefinita la superficie coding, ma il catalogo generale `volcengine/*` -viene registrato contemporaneamente. +L'onboarding usa come predefinita la superficie coding, ma il catalogo generale `volcengine/*` +viene registrato nello stesso momento. -Nei selettori di onboarding/configurazione del modello, la scelta di autenticazione Volcengine preferisce entrambe -le righe `volcengine/*` e `volcengine-plan/*`. Se quei modelli non sono ancora caricati, -OpenClaw torna al catalogo non filtrato invece di mostrare un selettore -limitato al provider vuoto. +Nei selettori di onboarding/configurazione modello, la scelta auth Volcengine preferisce sia +le righe `volcengine/*` sia quelle `volcengine-plan/*`. Se questi modelli non sono ancora caricati, +OpenClaw torna al catalogo non filtrato invece di mostrare un selettore con ambito provider vuoto. Modelli disponibili: @@ -544,7 +585,7 @@ Modelli coding (`volcengine-plan`): - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (internazionale) +### BytePlus (Internazionale) BytePlus ARK fornisce accesso agli stessi modelli di Volcano Engine per gli utenti internazionali. @@ -561,13 +602,12 @@ BytePlus ARK fornisce accesso agli stessi modelli di Volcano Engine per gli uten } ``` -L'onboarding usa per impostazione predefinita la superficie coding, ma il catalogo generale `byteplus/*` -viene registrato contemporaneamente. +L'onboarding usa come predefinita la superficie coding, ma il catalogo generale `byteplus/*` +viene registrato nello stesso momento. -Nei selettori di onboarding/configurazione del modello, la scelta di autenticazione BytePlus preferisce entrambe -le righe `byteplus/*` e `byteplus-plan/*`. Se quei modelli non sono ancora caricati, -OpenClaw torna al catalogo non filtrato invece di mostrare un selettore -limitato al provider vuoto. +Nei selettori di onboarding/configurazione modello, la scelta auth BytePlus preferisce sia +le righe `byteplus/*` sia quelle `byteplus-plan/*`. Se questi modelli non sono ancora caricati, +OpenClaw torna al catalogo non filtrato invece di mostrare un selettore con ambito provider vuoto. Modelli disponibili: @@ -617,27 +657,49 @@ MiniMax viene configurato tramite `models.providers` perché usa endpoint person - MiniMax OAuth (globale): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- Chiave API MiniMax (globale): `--auth-choice minimax-global-api` -- Chiave API MiniMax (CN): `--auth-choice minimax-cn-api` +- API key MiniMax (globale): `--auth-choice minimax-global-api` +- API key MiniMax (CN): `--auth-choice minimax-cn-api` - Auth: `MINIMAX_API_KEY` per `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` per `minimax-portal` Vedi [/providers/minimax](/it/providers/minimax) per i dettagli di configurazione, le opzioni dei modelli e gli snippet di configurazione. -Sul percorso di streaming compatibile con Anthropic di MiniMax, OpenClaw disabilita thinking per +Sul percorso di streaming compatibile con Anthropic di MiniMax, OpenClaw disabilita il thinking per impostazione predefinita a meno che tu non lo imposti esplicitamente, e `/fast on` riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. -Suddivisione delle capacità gestite dal plugin: +Suddivisione delle capability gestita dal plugin: -- I valori predefiniti per testo/chat restano su `minimax/MiniMax-M2.7` -- La generazione di immagini è `minimax/image-01` o `minimax-portal/image-01` -- La comprensione delle immagini è `MiniMax-VL-01`, gestita dal plugin, su entrambi i percorsi di autenticazione MiniMax +- I valori predefiniti text/chat restano su `minimax/MiniMax-M2.7` +- La generazione immagini è `minimax/image-01` o `minimax-portal/image-01` +- L'understanding delle immagini è `MiniMax-VL-01` gestito dal plugin su entrambi i percorsi auth MiniMax - La ricerca web resta sull'id provider `minimax` +### LM Studio + +LM Studio è distribuito come Plugin provider incluso che usa l'API nativa: + +- Provider: `lmstudio` +- Auth: `LM_API_TOKEN` +- Base URL di inferenza predefinita: `http://localhost:1234/v1` + +Quindi imposta un modello (sostituiscilo con uno degli ID restituiti da `http://localhost:1234/api/v1/models`): + +```json5 +{ + agents: { + defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } }, + }, +} +``` + +OpenClaw usa i percorsi nativi di LM Studio `/api/v1/models` e `/api/v1/models/load` +per discovery + auto-load, con `/v1/chat/completions` per l'inferenza per impostazione predefinita. +Vedi [/providers/lmstudio](/it/providers/lmstudio) per configurazione e risoluzione dei problemi. + ### Ollama -Ollama è distribuito come plugin provider incluso e usa l'API nativa di Ollama: +Ollama è distribuito come Plugin provider incluso e usa l'API nativa di Ollama: - Provider: `ollama` - Auth: nessuna richiesta (server locale) @@ -657,27 +719,27 @@ ollama pull llama3.3 } ``` -Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando fai opt-in con -`OLLAMA_API_KEY`, e il plugin provider incluso aggiunge Ollama direttamente a +Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando abiliti +`OLLAMA_API_KEY`, e il Plugin provider incluso aggiunge Ollama direttamente a `openclaw onboard` e al selettore dei modelli. Vedi [/providers/ollama](/it/providers/ollama) per onboarding, modalità cloud/locale e configurazione personalizzata. ### vLLM -vLLM è distribuito come plugin provider incluso per server locali/self-hosted -compatibili con OpenAI: +vLLM è distribuito come Plugin provider incluso per server compatibili con OpenAI +locali/self-hosted: - Provider: `vllm` - Auth: opzionale (dipende dal tuo server) -- Base URL predefinito: `http://127.0.0.1:8000/v1` +- Base URL predefinita: `http://127.0.0.1:8000/v1` -Per fare opt-in al rilevamento automatico in locale (qualsiasi valore va bene se il tuo server non impone l'autenticazione): +Per abilitare l'auto-discovery in locale (qualsiasi valore va bene se il tuo server non impone auth): ```bash export VLLM_API_KEY="vllm-local" ``` -Poi imposta un modello (sostituiscilo con uno degli id restituiti da `/v1/models`): +Quindi imposta un modello (sostituiscilo con uno degli ID restituiti da `/v1/models`): ```json5 { @@ -691,21 +753,21 @@ Vedi [/providers/vllm](/it/providers/vllm) per i dettagli. ### SGLang -SGLang è distribuito come plugin provider incluso per server self-hosted veloci -compatibili con OpenAI: +SGLang è distribuito come Plugin provider incluso per server compatibili con OpenAI +self-hosted ad alte prestazioni: - Provider: `sglang` - Auth: opzionale (dipende dal tuo server) -- Base URL predefinito: `http://127.0.0.1:30000/v1` +- Base URL predefinita: `http://127.0.0.1:30000/v1` -Per fare opt-in al rilevamento automatico in locale (qualsiasi valore va bene se il tuo server non -impone l'autenticazione): +Per abilitare l'auto-discovery in locale (qualsiasi valore va bene se il tuo server non +impone auth): ```bash export SGLANG_API_KEY="sglang-local" ``` -Poi imposta un modello (sostituiscilo con uno degli id restituiti da `/v1/models`): +Quindi imposta un modello (sostituiscilo con uno degli ID restituiti da `/v1/models`): ```json5 { @@ -726,19 +788,19 @@ Esempio (compatibile con OpenAI): agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "Local" } }, + models: { "lmstudio/my-local-model": { alias: "Locale" } }, }, }, models: { providers: { lmstudio: { baseUrl: "http://localhost:1234/v1", - apiKey: "LMSTUDIO_KEY", + apiKey: "${LM_API_TOKEN}", api: "openai-completions", models: [ { id: "my-local-model", - name: "Local Model", + name: "Modello locale", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -754,20 +816,20 @@ Esempio (compatibile con OpenAI): Note: -- Per i provider personalizzati, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` sono opzionali. - Se omessi, OpenClaw usa questi valori predefiniti: +- Per i provider personalizzati, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` sono facoltativi. + Se omessi, OpenClaw usa come valori predefiniti: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` - Consigliato: imposta valori espliciti che corrispondano ai limiti del tuo proxy/modello. -- Per `api: "openai-completions"` su endpoint non nativi (qualsiasi `baseUrl` non vuoto il cui host non sia `api.openai.com`), OpenClaw forza `compat.supportsDeveloperRole: false` per evitare errori 400 del provider per ruoli `developer` non supportati. -- Le route in stile proxy compatibili con OpenAI saltano anche la - modellazione nativa della richiesta solo OpenAI: niente `service_tier`, niente `store` di Responses, niente hint della cache dei prompt, niente - modellazione del payload di compatibilità del ragionamento OpenAI e nessun header nascosto di attribuzione OpenClaw. -- Se `baseUrl` è vuoto/omesso, OpenClaw mantiene il comportamento OpenAI predefinito (che risolve a `api.openai.com`). -- Per sicurezza, un valore esplicito `compat.supportsDeveloperRole: true` viene comunque sovrascritto sugli endpoint non nativi `openai-completions`. +- Per `api: "openai-completions"` su endpoint non nativi (qualsiasi `baseUrl` non vuota il cui host non sia `api.openai.com`), OpenClaw forza `compat.supportsDeveloperRole: false` per evitare errori 400 del provider dovuti a ruoli `developer` non supportati. +- I percorsi compatibili con OpenAI in stile proxy saltano anche la + modellazione nativa delle richieste solo-OpenAI: niente `service_tier`, niente `store` di Responses, niente hint di prompt-cache, niente + modellazione del payload di compatibilità reasoning OpenAI e nessun header di attribuzione nascosto di OpenClaw. +- Se `baseUrl` è vuota/omessa, OpenClaw mantiene il comportamento OpenAI predefinito (che risolve in `api.openai.com`). +- Per sicurezza, un valore esplicito `compat.supportsDeveloperRole: true` viene comunque sovrascritto sugli endpoint `openai-completions` non nativi. ## Esempi CLI @@ -781,7 +843,7 @@ Vedi anche: [/gateway/configuration](/it/gateway/configuration) per esempi compl ## Correlati -- [Models](/it/concepts/models) — configurazione dei modelli e alias +- [Models](/it/concepts/models) — configurazione e alias dei modelli - [Model Failover](/it/concepts/model-failover) — catene di fallback e comportamento di retry - [Configuration Reference](/it/gateway/configuration-reference#agent-defaults) — chiavi di configurazione del modello - [Providers](/it/providers) — guide di configurazione per provider diff --git a/docs/it/concepts/qa-e2e-automation.md b/docs/it/concepts/qa-e2e-automation.md index 566a88c57..13b3f5fc3 100644 --- a/docs/it/concepts/qa-e2e-automation.md +++ b/docs/it/concepts/qa-e2e-automation.md @@ -6,25 +6,29 @@ read_when: summary: Forma dell'automazione QA privata per qa-lab, qa-channel, scenari con seed e report del protocollo title: Automazione QA end-to-end x-i18n: - generated_at: "2026-04-12T23:28:18Z" + generated_at: "2026-04-13T08:27:17Z" model: gpt-5.4 provider: openai - source_hash: b9fe27dc049823d5e3eb7ae1eac6aad21ed9e917425611fb1dbcb28ab9210d5e + source_hash: a4a4f5c765163565c95c2a071f201775fd9d8d60cad4ff25d71e4710559c1570 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automazione QA end-to-end -Lo stack QA privato serve a testare OpenClaw in modo più realistico e aderente ai canali rispetto a quanto possa fare un singolo test unitario. +Lo stack QA privato è pensato per esercitare OpenClaw in un modo più realistico, +modellato sui canali, rispetto a quanto possa fare un singolo unit test. Componenti attuali: -- `extensions/qa-channel`: canale di messaggistica sintetico con superfici per DM, canale, thread, reazione, modifica ed eliminazione. -- `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione, iniettare messaggi in ingresso ed esportare un report Markdown. -- `qa/`: asset seed supportati dal repository per l'attività iniziale e gli scenari QA di base. +- `extensions/qa-channel`: canale di messaggi sintetico con superfici per DM, canale, thread, + reazione, modifica ed eliminazione. +- `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione, + inserire messaggi in ingresso ed esportare un report Markdown. +- `qa/`: asset seed supportati dal repository per l'attività iniziale e gli scenari QA + di base. -L'attuale flusso operativo QA è un sito QA a due pannelli: +L'attuale flusso dell'operatore QA è un sito QA a due pannelli: - Sinistra: dashboard del Gateway (Control UI) con l'agente. - Destra: QA Lab, che mostra la trascrizione in stile Slack e il piano dello scenario. @@ -35,9 +39,13 @@ Eseguilo con: pnpm qa:lab:up ``` -Questo costruisce il sito QA, avvia la lane del Gateway basata su Docker ed espone la pagina QA Lab in cui un operatore o un ciclo di automazione può assegnare all'agente una missione QA, osservare il comportamento reale del canale e registrare cosa ha funzionato, cosa è fallito o cosa è rimasto bloccato. +Questo costruisce il sito QA, avvia la corsia Gateway supportata da Docker ed espone la +pagina di QA Lab dove un operatore o un ciclo di automazione può assegnare all'agente una missione QA, +osservare il comportamento reale del canale e registrare cosa ha funzionato, cosa è fallito o +cosa è rimasto bloccato. -Per iterare più velocemente sull'interfaccia utente di QA Lab senza ricostruire ogni volta l'immagine Docker, avvia lo stack con un bundle QA Lab montato tramite bind: +Per iterare più velocemente sull'interfaccia di QA Lab senza ricostruire ogni volta l'immagine Docker, +avvia lo stack con un bundle QA Lab montato tramite bind: ```bash pnpm openclaw qa docker-build-image @@ -46,45 +54,69 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind `extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch` ricostruisce quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash degli asset di QA Lab. +`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind +`extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch` +ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash +degli asset di QA Lab. -Per una lane smoke Matrix reale a livello di trasporto, esegui: +Per una corsia smoke Matrix con trasporto reale, esegui: ```bash pnpm openclaw qa matrix ``` -Questa lane predispone un homeserver Tuwunel usa e getta in Docker, registra utenti temporanei driver, SUT e observer, crea una stanza privata e poi esegue il vero plugin Matrix all'interno di un processo figlio QA del Gateway. La lane di trasporto live mantiene la configurazione figlia limitata al trasporto sotto test, quindi Matrix viene eseguito senza `qa-channel` nella configurazione figlia. +Questa corsia effettua il provisioning di un homeserver Tuwunel usa e getta in Docker, registra +utenti temporanei driver, SUT e observer, crea una stanza privata, quindi esegue +il vero Plugin Matrix all'interno di un processo figlio QA del Gateway. La corsia di trasporto live mantiene +la configurazione del processo figlio limitata al trasporto in prova, quindi Matrix viene eseguito senza +`qa-channel` nella configurazione del processo figlio. -Per una lane smoke Telegram reale a livello di trasporto, esegui: +Per una corsia smoke Telegram con trasporto reale, esegui: ```bash pnpm openclaw qa telegram ``` -Questa lane usa un vero gruppo privato Telegram invece di predisporre un server usa e getta. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, oltre a due bot distinti nello stesso gruppo privato. Il bot SUT deve avere un nome utente Telegram e l'osservazione bot-to-bot funziona al meglio quando entrambi i bot hanno la modalità Bot-to-Bot Communication Mode abilitata in `@BotFather`. +Questa corsia punta a un vero gruppo privato Telegram invece di effettuare il provisioning di +un server usa e getta. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, oltre a due bot distinti nello stesso +gruppo privato. Il bot SUT deve avere un username Telegram e l'osservazione bot-to-bot +funziona al meglio quando entrambi i bot hanno attivata la modalità Bot-to-Bot Communication +in `@BotFather`. -Le lane di trasporto live ora condividono un unico contratto più piccolo invece di definire ognuna una propria forma per l'elenco degli scenari. +Le corsie di trasporto live ora condividono un unico contratto più piccolo invece di +inventare ognuna una propria forma per l'elenco degli scenari. -`qa-channel` rimane la suite ampia di comportamento sintetico del prodotto e non fa parte della matrice di copertura del trasporto live. +`qa-channel` rimane la suite ampia di comportamento sintetico del prodotto e non fa parte +della matrice di copertura dei trasporti 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 | +| Corsia | Canary | Blocco 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 | -Questo mantiene `qa-channel` come suite ampia di comportamento del prodotto, mentre Matrix, Telegram e i futuri trasporti live condividono un'unica checklist esplicita del contratto di trasporto. +Questo mantiene `qa-channel` come suite ampia di comportamento del prodotto, mentre Matrix, +Telegram e i futuri trasporti live condividono una checklist esplicita del contratto di trasporto. -Per una lane VM Linux usa e getta senza introdurre Docker nel percorso QA, esegui: +Per una corsia VM Linux usa e getta senza introdurre Docker nel percorso QA, esegui: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Questo avvia una nuova istanza Multipass, installa le dipendenze, costruisce OpenClaw all'interno dell'istanza, esegue `qa suite`, quindi copia il normale report QA e il riepilogo in `.artifacts/qa-e2e/...` sull'host. +Questo avvia un guest Multipass pulito, installa le dipendenze, compila OpenClaw +all'interno del guest, esegue `qa suite`, quindi copia il normale report QA e il +riepilogo in `.artifacts/qa-e2e/...` sull'host. Riutilizza lo stesso comportamento di selezione degli scenari di `qa suite` sull'host. -Le esecuzioni della suite su host e Multipass eseguono per impostazione predefinita in parallelo più scenari selezionati con worker Gateway isolati, fino a 64 worker o al numero di scenari selezionati. Usa `--concurrency ` per regolare il numero di worker oppure `--concurrency 1` per l'esecuzione seriale. -Le esecuzioni live inoltrano gli input di autenticazione QA supportati e pratici per l'istanza: chiavi provider basate su env, il percorso di configurazione del provider live QA e `CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la radice del repository in modo che l'istanza possa scrivere indietro tramite il workspace montato. +Le esecuzioni della suite su host e Multipass eseguono in parallelo per impostazione predefinita +più scenari selezionati con worker Gateway isolati, fino a 64 worker o al numero di +scenari selezionati. Usa `--concurrency ` per regolare il numero di worker, oppure +`--concurrency 1` per l'esecuzione seriale. +Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il +guest: chiavi provider basate su env, il percorso della configurazione del provider live QA e +`CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la root del repository affinché il guest +possa scrivere indietro attraverso il workspace montato. ## Seed supportati dal repository @@ -93,41 +125,49 @@ Gli asset seed si trovano in `qa/`: - `qa/scenarios/index.md` - `qa/scenarios/*.md` -Questi sono intenzionalmente in git affinché il piano QA sia visibile sia agli esseri umani sia all'agente. +Questi sono intenzionalmente in git in modo che il piano QA sia visibile sia agli esseri umani sia all' +agente. -`qa-lab` deve rimanere un runner Markdown generico. Ogni file Markdown di scenario è la fonte di verità per una singola esecuzione di test e dovrebbe definire: +`qa-lab` dovrebbe rimanere un esecutore Markdown generico. Ogni file Markdown di scenario è +la fonte di verità per una singola esecuzione di test e dovrebbe definire: - metadati dello scenario - riferimenti a documentazione e codice -- requisiti opzionali dei plugin +- requisiti opzionali dei Plugin - patch opzionale della configurazione del Gateway - il `qa-flow` eseguibile -L'elenco di base deve rimanere abbastanza ampio da coprire: +La superficie di runtime riutilizzabile che supporta `qa-flow` può rimanere generica +e trasversale. Per esempio, gli scenari Markdown possono combinare helper lato trasporto +con helper lato browser che pilotano la Control UI incorporata tramite la seam +Gateway `browser.request` senza aggiungere un esecutore speciale. + +L'elenco di base dovrebbe rimanere abbastanza ampio da coprire: - chat DM e di canale - comportamento dei thread - ciclo di vita delle azioni sui messaggi - callback Cron - richiamo della memoria -- cambio di modello -- handoff del subagente +- cambio modello +- handoff a subagent - lettura del repository e della documentazione - una piccola attività di build come Lobster Invaders ## Adattatori di trasporto -`qa-lab` gestisce una seam di trasporto generica per scenari QA in Markdown. -`qa-channel` è il primo adattatore su questa seam, ma l'obiettivo di progettazione è più ampio: -i futuri canali reali o sintetici dovrebbero collegarsi allo stesso runner di suite invece di aggiungere un runner QA specifico per il trasporto. +`qa-lab` possiede una seam di trasporto generica per gli scenari QA Markdown. +`qa-channel` è il primo adattatore su quella seam, ma l'obiettivo progettuale è più ampio: +i futuri canali reali o sintetici dovrebbero collegarsi allo stesso esecutore della suite +invece di aggiungere un esecutore QA specifico per trasporto. A livello di architettura, la suddivisione è: -- `qa-lab` gestisce l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artifact e il reporting. -- l'adattatore di trasporto gestisce la configurazione del Gateway, la readiness, l'osservazione in ingresso e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato. -- i file di scenario Markdown sotto `qa/scenarios/` definiscono l'esecuzione del test; `qa-lab` fornisce la superficie runtime riutilizzabile che li esegue. +- `qa-lab` possiede l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artifact e il reporting. +- l'adattatore di trasporto possiede la configurazione del Gateway, la readiness, l'osservazione in ingresso e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato. +- i file di scenario Markdown in `qa/scenarios/` definiscono l'esecuzione del test; `qa-lab` fornisce la superficie di runtime riutilizzabile che li esegue. -Le linee guida di adozione rivolte ai maintainer per i nuovi adattatori di canale si trovano in +La guida all'adozione, rivolta ai maintainer, per i nuovi adattatori di canale si trova in [Testing](/it/help/testing#adding-a-channel-to-qa). ## Reporting @@ -140,7 +180,8 @@ Il report dovrebbe rispondere a: - Cosa è rimasto bloccato - Quali scenari di follow-up vale la pena aggiungere -Per controlli di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live e scrivi un report Markdown valutato: +Per i controlli su carattere e stile, esegui lo stesso scenario su più ref di modelli live +e scrivi un report Markdown valutato: ```bash pnpm openclaw qa character-eval \ @@ -159,16 +200,34 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Il comando esegue processi figli locali del Gateway QA, non Docker. Gli scenari di character eval dovrebbero impostare la persona tramite `SOUL.md`, quindi eseguire normali turni utente come chat, aiuto sul workspace e piccole attività sui file. Al modello candidato non dovrebbe essere detto che è in fase di valutazione. Il comando conserva ogni trascrizione completa, registra statistiche di base dell'esecuzione e poi chiede ai modelli giudice in modalità fast con ragionamento `xhigh` di classificare le esecuzioni per naturalezza, vibe e umorismo. -Usa `--blind-judge-models` quando confronti provider: il prompt del giudice riceve comunque ogni trascrizione e stato dell'esecuzione, ma i riferimenti dei candidati vengono sostituiti con etichette neutrali come `candidate-01`; il report rimappa le classifiche ai riferimenti reali dopo il parsing. -Le esecuzioni dei candidati usano per impostazione predefinita `high` thinking, con `xhigh` per i modelli OpenAI che lo supportano. Sostituisci un candidato specifico inline con `--model provider/model,thinking=`. `--thinking ` continua a impostare un fallback globale e la forma meno recente `--model-thinking ` viene mantenuta per compatibilità. -I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast, così viene utilizzata l'elaborazione prioritaria dove il provider la supporta. Aggiungi inline `,fast`, `,no-fast` o `,fast=false` quando un singolo candidato o giudice ha bisogno di un override. Passa `--fast` solo quando vuoi forzare la modalità fast per ogni modello candidato. Le durate dei candidati e dei giudici vengono registrate nel report per l'analisi comparativa, ma i prompt dei giudici indicano esplicitamente di non classificare in base alla velocità. -Le esecuzioni dei modelli candidati e giudici usano entrambe per impostazione predefinita una concorrenza di 16. Riduci `--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione sul Gateway locale rendono un'esecuzione troppo rumorosa. -Quando non viene passato alcun `--model` candidato, la character eval usa per impostazione predefinita +Il comando esegue processi figli locali del Gateway QA, non Docker. Gli scenari di valutazione del carattere +dovrebbero impostare la persona tramite `SOUL.md`, quindi eseguire normali turni utente +come chat, aiuto sul workspace e piccole attività sui file. Al modello candidato +non dovrebbe essere detto che sta venendo valutato. Il comando preserva ogni +trascrizione completa, registra statistiche di base dell'esecuzione, quindi chiede ai modelli giudice in modalità fast con +ragionamento `xhigh` di classificare le esecuzioni in base a naturalezza, vibe e umorismo. +Usa `--blind-judge-models` quando confronti provider: il prompt del giudice riceve comunque +ogni trascrizione e stato di esecuzione, ma i ref candidati vengono sostituiti con etichette neutre +come `candidate-01`; il report rimappa le classifiche ai ref reali dopo il parsing. +Le esecuzioni candidate usano per impostazione predefinita il thinking `high`, con `xhigh` per i modelli OpenAI che +lo supportano. Sostituisci un candidato specifico inline con +`--model provider/model,thinking=`. `--thinking ` imposta ancora un +fallback globale e la vecchia forma `--model-thinking ` è +mantenuta per compatibilità. +I ref candidati OpenAI usano per impostazione predefinita la modalità fast, così viene utilizzata l'elaborazione prioritaria dove +il provider la supporta. Aggiungi `,fast`, `,no-fast` o `,fast=false` inline quando +un singolo candidato o giudice necessita di una sostituzione. Passa `--fast` solo quando vuoi +forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici sono +registrate nel report per l'analisi comparativa, ma i prompt dei giudici dichiarano esplicitamente di +non classificare in base alla velocità. +Sia le esecuzioni dei modelli candidati sia quelle dei modelli giudice usano per impostazione predefinita +concorrenza 16. Riduci `--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione sul Gateway locale +rendono un'esecuzione troppo rumorosa. +Quando non viene passato alcun candidato `--model`, la valutazione del carattere usa per impostazione predefinita `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` e -`google/gemini-3.1-pro-preview`. +`google/gemini-3.1-pro-preview` quando non viene passato alcun `--model`. Quando non viene passato alcun `--judge-model`, i giudici usano per impostazione predefinita `openai/gpt-5.4,thinking=xhigh,fast` e `anthropic/claude-opus-4-6,thinking=high`. diff --git a/docs/it/gateway/local-models.md b/docs/it/gateway/local-models.md index b593b3957..e0ead6d35 100644 --- a/docs/it/gateway/local-models.md +++ b/docs/it/gateway/local-models.md @@ -6,23 +6,23 @@ read_when: summary: Esegui OpenClaw su LLM locali (LM Studio, vLLM, LiteLLM, endpoint OpenAI personalizzati) title: Modelli locali x-i18n: - generated_at: "2026-04-08T02:14:56Z" + generated_at: "2026-04-13T08:27:14Z" model: gpt-5.4 provider: openai - source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8 + source_hash: 3ecb61b3e6e34d3666f9b688cd694d92c5fb211cf8c420fa876f7ccf5789154a source_path: gateway/local-models.md workflow: 15 --- # Modelli locali -Il locale è fattibile, ma OpenClaw si aspetta un contesto ampio e forti difese contro il prompt injection. Le schede più piccole troncano il contesto e indeboliscono la sicurezza. Punta in alto: **≥2 Mac Studio al massimo della configurazione o una configurazione GPU equivalente (~$30k+)**. Una singola GPU da **24 GB** funziona solo con prompt più leggeri e con latenza più elevata. Usa la **variante di modello più grande / completa che riesci a eseguire**; checkpoint fortemente quantizzati o “small” aumentano il rischio di prompt injection (vedi [Sicurezza](/it/gateway/security)). +Il locale è fattibile, ma OpenClaw si aspetta un contesto ampio + forti difese contro il prompt injection. Le schede piccole troncano il contesto e indeboliscono la sicurezza. Punta in alto: **≥2 Mac Studio al massimo della configurazione o una macchina GPU equivalente (~30.000$+)**. Una singola GPU da **24 GB** funziona solo per prompt più leggeri con latenza più alta. Usa la **variante di modello più grande / a dimensione piena che puoi eseguire**; checkpoint fortemente quantizzati o “small” aumentano il rischio di prompt injection (vedi [Sicurezza](/it/gateway/security)). -Se vuoi la configurazione locale con meno attrito, inizia con [Ollama](/it/providers/ollama) e `openclaw onboard`. Questa pagina è la guida con indicazioni precise per stack locali di fascia più alta e server locali personalizzati compatibili con OpenAI. +Se vuoi la configurazione locale con meno attrito, inizia con [LM Studio](/it/providers/lmstudio) o [Ollama](/it/providers/ollama) e `openclaw onboard`. Questa pagina è la guida con opinioni precise per stack locali di fascia più alta e server locali personalizzati compatibili con OpenAI. -## Consigliato: LM Studio + modello locale grande (Responses API) +## Consigliato: LM Studio + grande modello locale (API Responses) -Il miglior stack locale attuale. Carica un modello grande in LM Studio (ad esempio, una build completa di Qwen, DeepSeek o Llama), abilita il server locale (predefinito `http://127.0.0.1:1234`) e usa Responses API per mantenere il ragionamento separato dal testo finale. +La migliore stack locale attuale. Carica un modello grande in LM Studio (per esempio, una build completa di Qwen, DeepSeek o Llama), abilita il server locale (predefinito `http://127.0.0.1:1234`), e usa l’API Responses per mantenere il ragionamento separato dal testo finale. ```json5 { @@ -45,7 +45,7 @@ Il miglior stack locale attuale. Carica un modello grande in LM Studio (ad esemp models: [ { id: “my-local-model”, - name: “Local Model”, + name: “Modello locale”, reasoning: false, input: [“text”], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -62,13 +62,13 @@ Il miglior stack locale attuale. Carica un modello grande in LM Studio (ad esemp **Checklist di configurazione** - Installa LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- In LM Studio, scarica la **build di modello più grande disponibile** (evita varianti “small”/fortemente quantizzate), avvia il server e conferma che `http://127.0.0.1:1234/v1/models` lo elenchi. -- Sostituisci `my-local-model` con l'ID effettivo del modello mostrato in LM Studio. -- Mantieni il modello caricato; il caricamento a freddo aggiunge latenza all'avvio. +- In LM Studio, scarica la **build del modello più grande disponibile** (evita varianti “small”/fortemente quantizzate), avvia il server, conferma che `http://127.0.0.1:1234/v1/models` lo elenchi. +- Sostituisci `my-local-model` con l’ID modello effettivo mostrato in LM Studio. +- Mantieni il modello caricato; il caricamento a freddo aggiunge latenza di avvio. - Regola `contextWindow`/`maxTokens` se la tua build di LM Studio è diversa. -- Per WhatsApp, usa Responses API in modo che venga inviato solo il testo finale. +- Per WhatsApp, mantieni l’API Responses così viene inviato solo il testo finale. -Mantieni configurati anche i modelli ospitati quando esegui in locale; usa `models.mode: "merge"` in modo che i fallback restino disponibili. +Mantieni configurati anche i modelli ospitati quando esegui in locale; usa `models.mode: "merge"` così i fallback restano disponibili. ### Configurazione ibrida: primario ospitato, fallback locale @@ -97,7 +97,7 @@ Mantieni configurati anche i modelli ospitati quando esegui in locale; usa `mode models: [ { id: "my-local-model", - name: "Local Model", + name: "Modello locale", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -111,18 +111,18 @@ Mantieni configurati anche i modelli ospitati quando esegui in locale; usa `mode } ``` -### Priorità al locale con rete di sicurezza ospitata +### Locale come prima scelta con rete di sicurezza ospitata -Inverti l'ordine tra primario e fallback; mantieni lo stesso blocco `providers` e `models.mode: "merge"` così puoi usare come fallback Sonnet o Opus quando la macchina locale non è disponibile. +Inverti l’ordine di primario e fallback; mantieni lo stesso blocco `providers` e `models.mode: "merge"` così puoi ripiegare su Sonnet o Opus quando la macchina locale non è disponibile. ### Hosting regionale / instradamento dei dati -- Esistono anche varianti MiniMax/Kimi/GLM ospitate su OpenRouter con endpoint vincolati a una regione (ad esempio, ospitati negli Stati Uniti). Scegli lì la variante regionale per mantenere il traffico nella giurisdizione che preferisci continuando a usare `models.mode: "merge"` per i fallback Anthropic/OpenAI. -- Solo locale resta il percorso più forte per la privacy; l'instradamento regionale ospitato è la via di mezzo quando hai bisogno di funzionalità del provider ma vuoi controllare il flusso dei dati. +- Varianti MiniMax/Kimi/GLM ospitate esistono anche su OpenRouter con endpoint vincolati alla regione (ad esempio ospitati negli Stati Uniti). Scegli lì la variante regionale per mantenere il traffico nella giurisdizione desiderata continuando a usare `models.mode: "merge"` per i fallback Anthropic/OpenAI. +- Solo locale resta il percorso più forte per la privacy; l’instradamento regionale ospitato è la via di mezzo quando ti servono funzionalità del provider ma vuoi controllare il flusso dei dati. ## Altri proxy locali compatibili con OpenAI -vLLM, LiteLLM, OAI-proxy o gateway personalizzati funzionano se espongono un endpoint `/v1` in stile OpenAI. Sostituisci il blocco provider sopra con il tuo endpoint e l'ID del modello: +vLLM, LiteLLM, OAI-proxy o gateway personalizzati funzionano se espongono un endpoint `/v1` in stile OpenAI. Sostituisci il blocco provider sopra con il tuo endpoint e il tuo ID modello: ```json5 { @@ -136,7 +136,7 @@ vLLM, LiteLLM, OAI-proxy o gateway personalizzati funzionano se espongono un end models: [ { id: "my-local-model", - name: "Local Model", + name: "Modello locale", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -150,40 +150,25 @@ vLLM, LiteLLM, OAI-proxy o gateway personalizzati funzionano se espongono un end } ``` -Mantieni `models.mode: "merge"` in modo che i modelli ospitati restino disponibili come fallback. +Mantieni `models.mode: "merge"` così i modelli ospitati restano disponibili come fallback. -Nota sul comportamento per backend `/v1` locali/con proxy: +Nota sul comportamento per backend locali/proxy `/v1`: -- OpenClaw li tratta come route compatibili con OpenAI in stile proxy, non come endpoint OpenAI nativi -- il model shaping delle richieste riservato al solo OpenAI nativo non si applica qui: niente - `service_tier`, niente `store` di Responses, niente model shaping del payload di compatibilità per il ragionamento OpenAI - e niente suggerimenti per la cache dei prompt -- le intestazioni di attribuzione nascoste di OpenClaw (`originator`, `version`, `User-Agent`) - non vengono iniettate su questi URL proxy personalizzati +- OpenClaw li tratta come route proxy compatibili con OpenAI, non come endpoint OpenAI nativi +- qui non si applica il modellamento delle richieste riservato a OpenAI nativo: niente `service_tier`, niente `store` di Responses, niente modellamento del payload di compatibilità del ragionamento OpenAI e niente suggerimenti per la cache dei prompt +- gli header di attribuzione nascosti di OpenClaw (`originator`, `version`, `User-Agent`) non vengono iniettati su questi URL proxy personalizzati -Note di compatibilità per backend compatibili con OpenAI più rigidi: +Note di compatibilità per backend compatibili con OpenAI più restrittivi: -- Alcuni server accettano solo `messages[].content` come stringa su Chat Completions, non - array strutturati di parti di contenuto. Imposta - `models.providers..models[].compat.requiresStringContent: true` per - questi endpoint. -- Alcuni backend locali più piccoli o più rigidi sono instabili con la forma completa dei prompt del runtime - agente di OpenClaw, soprattutto quando sono inclusi gli schemi degli strumenti. Se il - backend funziona per chiamate dirette minime a `/v1/chat/completions` ma fallisce nei normali - turni agente di OpenClaw, prova prima con - `models.providers..models[].compat.supportsTools: false`. -- Se il backend continua a fallire solo su esecuzioni OpenClaw più grandi, il problema residuo - di solito è la capacità del modello/server a monte o un bug del backend, non il layer di trasporto di OpenClaw. +- Alcuni server accettano solo `messages[].content` come stringa nelle Chat Completions, non array strutturati di content part. Imposta `models.providers..models[].compat.requiresStringContent: true` per quegli endpoint. +- Alcuni backend locali più piccoli o più restrittivi sono instabili con la forma completa del prompt del runtime agent di OpenClaw, soprattutto quando sono inclusi schemi di tool. Se il backend funziona per piccole chiamate dirette a `/v1/chat/completions` ma fallisce nei normali turni agente di OpenClaw, prova prima con `models.providers..models[].compat.supportsTools: false`. +- Se il backend continua a fallire solo su esecuzioni OpenClaw più grandi, il problema rimanente di solito è la capacità del modello/server a monte o un bug del backend, non il livello di trasporto di OpenClaw. ## Risoluzione dei problemi -- Il gateway riesce a raggiungere il proxy? `curl http://127.0.0.1:1234/v1/models`. -- Modello LM Studio scaricato dalla memoria? Ricaricalo; l'avvio a freddo è una causa comune di “blocco”. +- Il Gateway riesce a raggiungere il proxy? `curl http://127.0.0.1:1234/v1/models`. +- Modello LM Studio scaricato dalla memoria? Ricaricalo; l’avvio a freddo è una causa comune di “blocco”. - Errori di contesto? Riduci `contextWindow` o aumenta il limite del tuo server. -- Il server compatibile con OpenAI restituisce `messages[].content ... expected a string`? - Aggiungi `compat.requiresStringContent: true` a quella voce di modello. -- Le chiamate dirette minime a `/v1/chat/completions` funzionano, ma `openclaw infer model run` - fallisce su Gemma o su un altro modello locale? Disabilita prima gli schemi degli strumenti con - `compat.supportsTools: false`, poi riprova. Se il server continua a bloccarsi solo - su prompt OpenClaw più grandi, trattalo come una limitazione del server/modello a monte. -- Sicurezza: i modelli locali saltano i filtri lato provider; mantieni gli agenti limitati e la compattazione attiva per limitare l'impatto del prompt injection. +- Il server compatibile con OpenAI restituisce `messages[].content ... expected a string`? Aggiungi `compat.requiresStringContent: true` a quella voce del modello. +- Piccole chiamate dirette a `/v1/chat/completions` funzionano, ma `openclaw infer model run` fallisce su Gemma o un altro modello locale? Disabilita prima gli schemi di tool con `compat.supportsTools: false`, poi riprova. Se il server continua a bloccarsi solo su prompt OpenClaw più grandi, trattalo come un limite del server/modello a monte. +- Sicurezza: i modelli locali saltano i filtri lato provider; mantieni gli agenti limitati e Compaction attivo per ridurre il raggio d’impatto del prompt injection. diff --git a/docs/it/help/testing.md b/docs/it/help/testing.md index 82165140d..ba935c9af 100644 --- a/docs/it/help/testing.md +++ b/docs/it/help/testing.md @@ -1,134 +1,212 @@ --- read_when: - Eseguire i test in locale o in CI - - Aggiungere test di regressione per bug del modello/provider - - Eseguire il debug del comportamento di Gateway + agente + - Aggiungere test di regressione per bug di modello/provider + - Debuggare il comportamento di Gateway + agent summary: 'Kit di test: suite unit/e2e/live, runner Docker e cosa copre ciascun test' -title: Test +title: Testare x-i18n: - generated_at: "2026-04-12T23:28:34Z" + generated_at: "2026-04-13T08:27:15Z" model: gpt-5.4 provider: openai - source_hash: a66ea672c386094ab4a8035a082c8a85d508a14301ad44b628d2a10d9cec3a52 + source_hash: 3db91b4bc36f626cd014958ec66b08b9cecd9faaa20a5746cd3a49ad4b0b1c38 source_path: help/testing.md workflow: 15 --- # Test -OpenClaw ha tre suite Vitest (unit/integration, e2e, live) e un piccolo insieme di runner Docker. +OpenClaw ha tre suite Vitest (unità/integrazione, e2e, live) e un piccolo insieme di runner Docker. -Questo documento è una guida a “come testiamo”: +Questa documentazione è una guida a “come testiamo”: -- Cosa copre ciascuna suite (e cosa deliberatamente _non_ copre) -- Quali comandi eseguire per i flussi di lavoro comuni (locale, pre-push, debug) -- Come i test live rilevano le credenziali e selezionano modelli/provider -- Come aggiungere regressioni per problemi reali di modelli/provider +- Cosa copre ogni suite (e cosa deliberatamente _non_ copre) +- Quali comandi eseguire per i flussi di lavoro più comuni (locale, pre-push, debug) +- Come i test live individuano le credenziali e selezionano modelli/provider +- Come aggiungere regressioni per problemi reali di modello/provider ## Avvio rapido -Nella maggior parte dei giorni: +Nella maggior parte dei casi: - Gate completo (previsto prima del push): `pnpm build && pnpm check && pnpm test` -- Esecuzione locale più veloce dell’intera suite su una macchina capiente: `pnpm test:max` -- Ciclo di watch diretto di Vitest: `pnpm test:watch` -- Il targeting diretto dei file ora instrada anche i percorsi di estensioni/canali: `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` -- Corsia QA supportata da VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Esecuzione locale più rapida dell’intera suite su una macchina capiente: `pnpm test:max` +- Loop diretto di Vitest in watch: `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 esecuzioni mirate quando stai iterando su un singolo errore. +- Sito QA con backend Docker: `pnpm qa:lab:up` +- Corsia QA con backend Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando tocchi i test o vuoi maggiore sicurezza: +Quando modifichi i test o vuoi più sicurezza: - Gate di copertura: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` -Quando esegui il debug di provider/modelli reali (richiede credenziali reali): +Quando esegui debug di provider/modelli reali (richiede credenziali reali): -- Suite live (modelli + probe di strumenti/immagini del Gateway): `pnpm test:live` -- Punta in modo silenzioso a un singolo file live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (sonde per modelli + strumenti/immagini del gateway): `pnpm test:live` +- Esegui in modo silenzioso un singolo file live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Suggerimento: quando ti serve solo un singolo caso che fallisce, preferisci restringere i test live tramite le variabili d’ambiente allowlist descritte di seguito. +Suggerimento: quando ti serve solo un singolo caso in errore, preferisci restringere i test live tramite le variabili env di allowlist descritte sotto. ## Runner specifici per QA -Questi comandi si affiancano alle principali suite di test quando hai bisogno del realismo di QA-lab: +Questi comandi si affiancano alle suite di test principali quando ti serve il realismo di QA-lab: - `pnpm openclaw qa suite` - - Esegue direttamente sull’host gli scenari QA supportati dal repository. - - Per impostazione predefinita esegue in parallelo più scenari selezionati con worker Gateway isolati, fino a 64 worker o al numero di scenari selezionati. Usa `--concurrency ` per regolare il numero di worker, oppure `--concurrency 1` per la vecchia corsia seriale. + - Esegue direttamente sull’host gli scenari QA basati sul repository. + - Per impostazione predefinita esegue in parallelo più scenari selezionati con worker gateway isolati, fino a 64 worker o al numero di scenari selezionati. Usa `--concurrency ` per regolare il numero di worker, oppure `--concurrency 1` per la vecchia corsia seriale. - `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 la VM 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 repository affinché il guest possa scriverle tramite l’area di lavoro montata. + - Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il guest: + chiavi provider basate su env, il percorso della configurazione del provider live QA e `CODEX_HOME` quando presente. + - 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, oltre ai log Multipass, sotto `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Avvia il sito QA supportato da Docker per attività QA in stile operatore. + - Avvia il sito QA con backend Docker per il lavoro QA in stile operatore. - `pnpm openclaw qa matrix` - - Esegue la corsia QA live di Matrix contro un homeserver Tuwunel temporaneo supportato da Docker. - - Effettua il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una stanza privata, quindi avvia un processo figlio QA Gateway con il vero Plugin Matrix come trasporto SUT. - - Per impostazione predefinita usa l’immagine stabile Tuwunel bloccata `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sostituiscila con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando devi testare un’immagine diversa. - - Scrive un report QA Matrix, un riepilogo e un artefatto degli eventi osservati sotto `.artifacts/qa-e2e/...`. + - Esegue la corsia QA live Matrix contro un homeserver Tuwunel temporaneo con backend Docker. + - Effettua il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una stanza privata, poi avvia un processo figlio del gateway QA 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 al momento supporta solo `--credential-source env` perché la corsia esegue il provisioning locale di utenti temporanei. + - Scrive sotto `.artifacts/qa-e2e/...` un report QA Matrix, un riepilogo e un artifact degli eventi osservati. - `pnpm openclaw qa telegram` - - Esegue la corsia QA live di Telegram contro un gruppo privato reale usando i token del bot driver e del bot SUT dall’ambiente. + - Esegue la corsia QA live Telegram contro un gruppo privato reale usando i token bot driver e SUT da 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. - - Richiede due bot distinti nello stesso gruppo privato, con il bot SUT che espone un nome utente Telegram. - - Per un’osservazione stabile bot-to-bot, abilita la modalità Bot-to-Bot Communication 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 artefatto dei messaggi osservati sotto `.artifacts/qa-e2e/...`. + - 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. + - 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 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 sotto `.artifacts/qa-e2e/...` un report QA Telegram, un riepilogo e un artifact dei messaggi osservati. -Le corsie di trasporto live condividono un unico contratto standard, così i nuovi trasporti non divergono: +Le corsie 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 copertura del trasporto live. +`qa-channel` resta la suite QA sintetica ampia e non fa parte della matrice di copertura dei trasporti live. -| Corsia | Canary | Blocco menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up del thread | Isolamento del thread | Osservazione delle reazioni | Comando help | -| -------- | ------ | --------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Corsia | Canary | Gating per mention | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione reazioni | Comando help | +| -------- | ------ | ------------------ | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------- | ------------ | +| 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 basato su Convex, invia heartbeat +su quel lease mentre la corsia è in esecuzione e rilascia il lease allo spegnimento. + +Scaffold di riferimento del progetto Convex: + +- `qa/convex-credential-broker/` + +Variabili env obbligatorie: + +- `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 credenziale: + - CLI: `--credential-role maintainer|ci` + - Valore predefinito env: `OPENCLAW_QA_CREDENTIAL_ROLE` (predefinito `maintainer`) + +Variabili env facoltative: + +- `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 tracciamento facoltativo) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` consente URL Convex `http://` in loopback per sviluppo solo locale. + +`OPENCLAW_QA_CONVEX_SITE_URL` dovrebbe usare `https://` nel normale funzionamento. + +I comandi admin per maintainer (aggiunta/rimozione/elenco del pool) richiedono +specificamente `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. + +Helper CLI per i maintainer: + +```bash +pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json +pnpm openclaw qa credentials list --kind telegram +pnpm openclaw qa credentials remove --credential-id +``` + +Usa `--json` per output leggibile da macchina in script e utility CI. + +Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): + +- `POST /acquire` + - Richiesta: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` + - Successo: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` + - Esaurito/ritentabile: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` +- `POST /heartbeat` + - Richiesta: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` + - Successo: `{ status: "ok" }` (o `2xx` vuoto) +- `POST /release` + - Richiesta: `{ kind, ownerId, actorRole, credentialId, leaseToken }` + - Successo: `{ status: "ok" }` (o `2xx` vuoto) +- `POST /admin/add` (solo secret maintainer) + - Richiesta: `{ kind, actorId, payload, note?, status? }` + - Successo: `{ status: "ok", credential }` +- `POST /admin/remove` (solo secret maintainer) + - Richiesta: `{ credentialId, actorId }` + - Successo: `{ status: "ok", changed, credential }` + - Guardia 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: + +- `{ groupId: string, driverToken: string, sutToken: string }` +- `groupId` deve essere una stringa dell’id numerico della chat Telegram. +- `admin/add` convalida questa forma per `kind: "telegram"` e rifiuta payload malformati. ### Aggiungere un canale a QA Aggiungere un canale al sistema QA markdown richiede esattamente due cose: -1. Un adapter di trasporto per il canale. +1. Un adattatore di trasporto per il canale. 2. Un pacchetto di scenari che eserciti il contratto del canale. -Non aggiungere un runner QA specifico per canale quando il runner condiviso `qa-lab` può gestire il flusso. +Non aggiungere un runner QA specifico per canale quando il runner condiviso `qa-lab` può +gestire il flusso. -`qa-lab` possiede i meccanismi condivisi: +`qa-lab` gestisce le meccaniche condivise: - avvio e teardown della suite - concorrenza dei worker -- scrittura degli artefatti +- scrittura degli artifact - generazione dei report - esecuzione degli scenari -- alias di compatibilità per i vecchi scenari `qa-channel` +- alias di compatibilità per gli scenari `qa-channel` meno recenti -L’adapter del canale possiede il contratto di trasporto: +L’adattatore di canale gestisce il contratto di trasporto: - come viene configurato il gateway per quel trasporto -- come viene verificata la disponibilità -- come vengono iniettati gli eventi in ingresso -- come vengono osservati i messaggi in uscita -- come vengono esposte le trascrizioni e lo stato del trasporto normalizzato +- come viene verificata la readiness +- come vengono iniettati gli eventi inbound +- come vengono osservati i messaggi outbound +- come sono esposti trascrizioni e stato di trasporto normalizzato - come vengono eseguite le azioni supportate dal trasporto -- come vengono gestiti reset o cleanup specifici del trasporto +- come viene gestito il reset o la pulizia specifici del trasporto La soglia minima di adozione per un nuovo canale è: -1. Implementare l’adapter di trasporto sulla seam condivisa `qa-lab`. -2. Registrare l’adapter nel registro dei trasporti. -3. Mantenere i meccanismi specifici del trasporto all’interno dell’adapter o dell’harness del canale. -4. Scrivere o adattare scenari markdown sotto `qa/scenarios/`. +1. Implementare l’adattatore di trasporto sulla seam condivisa `qa-lab`. +2. Registrare l’adattatore nel registro dei trasporti. +3. Mantenere le meccaniche specifiche del trasporto dentro l’adattatore o nell’harness del canale. +4. Creare o adattare scenari markdown sotto `qa/scenarios/`. 5. Usare gli helper generici degli scenari per i nuovi scenari. 6. Mantenere funzionanti gli alias di compatibilità esistenti, a meno che il repository non stia eseguendo una migrazione intenzionale. -La regola decisionale è rigorosa: +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 singolo trasporto di canale, tienilo in quell’adapter o harness del Plugin. -- Se uno scenario ha bisogno di una nuova capacità utilizzabile da più di un canale, aggiungi un helper generico invece di un ramo specifico per canale 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. +- Se un comportamento dipende da un solo trasporto di canale, tienilo in quell’adattatore o harness del Plugin. +- Se uno scenario richiede una nuova capacità che può essere usata da più di un canale, aggiungi un helper generico invece di un branch specifico per canale in `suite.ts`. +- Se un comportamento ha senso solo per un trasporto, mantieni lo scenario specifico per quel trasporto e rendilo esplicito nel contratto dello scenario. I nomi preferiti degli helper generici per i nuovi scenari sono: @@ -145,7 +223,7 @@ I nomi preferiti degli helper generici per i nuovi scenari sono: - `formatTransportTranscript` - `resetTransport` -Gli alias di compatibilità rimangono disponibili per gli scenari esistenti, inclusi: +Gli alias di compatibilità restano disponibili per gli scenari esistenti, inclusi: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -153,100 +231,101 @@ Gli alias di compatibilità rimangono disponibili per gli scenari esistenti, inc - `formatConversationTranscript` - `resetBus` -Il nuovo lavoro sui canali dovrebbe usare i nomi generici degli helper. -Gli alias di compatibilità esistono per evitare una migrazione in un solo giorno, non come modello per la scrittura di nuovi scenari. +Il nuovo lavoro sui canali dovrebbe usare i nomi degli helper generici. +Gli alias di compatibilità esistono per evitare una migrazione in un solo giorno, non come modello per +la creazione di nuovi scenari. ## Suite di test (cosa viene eseguito dove) -Pensa alle suite come a “realismo crescente” (e crescente instabilità/costo): +Pensa alle suite come a “realismo crescente” (e costi/instabilità crescenti): -### Unit / integration (predefinita) +### Unità / integrazione (predefinita) - Comando: `pnpm test` -- Configurazione: dieci esecuzioni sequenziali di shard (`vitest.full-*.config.ts`) sui progetti Vitest con scope già esistenti -- File: inventari core/unit sotto `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e i test Node `ui` in allowlist coperti da `vitest.unit.config.ts` +- Configurazione: dieci esecuzioni sequenziali a shard (`vitest.full-*.config.ts`) sui progetti Vitest scoped esistenti +- File: inventari core/unit sotto `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 (autenticazione del gateway, routing, strumenti, parsing, configurazione) + - Test di integrazione in-process (auth del gateway, routing, tooling, parsing, config) - Regressioni deterministiche per bug noti - Aspettative: - Viene eseguito in CI - Non richiede chiavi reali - Deve essere veloce e stabile - Nota sui progetti: - - `pnpm test` senza target ora esegue undici configurazioni shard più piccole (`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 unico grande processo root-project nativo. Questo riduce il picco di RSS su macchine cariche ed evita che il lavoro di auto-reply/estensioni affami le suite non correlate. - - `pnpm test --watch` continua a usare il grafo dei progetti del 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 i target espliciti di file/directory attraverso corsie con scope, quindi `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo completo di avvio del root project. - - `pnpm test:changed` espande i percorsi git modificati nelle stesse corsie con scope quando il diff tocca solo file sorgente/test instradabili; le modifiche a config/setup tornano comunque alla riesecuzione ampia del root-project. - - I test unitari leggeri in termini di import da agents, commands, plugin, helper di auto-reply, `plugin-sdk` e aree simili di utility pure vengono instradati attraverso la corsia `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file con stato/runtime più pesanti restano sulle corsie esistenti. + - `pnpm test` senza target ora esegue undici configurazioni shard più piccole (`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 unico enorme processo native root-project. Questo riduce il picco RSS su macchine sotto carico ed evita che il lavoro di auto-reply/extension affami suite non correlate. + - `pnpm test --watch` usa ancora il grafo di progetti nativo root `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 file/directory attraverso corsie scoped, quindi `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 corsie scoped quando la diff tocca solo file sorgente/test instradabili; le modifiche a config/setup tornano comunque alla riesecuzione ampia del progetto root. + - I test unitari leggeri sulle importazioni da agenti, comandi, plugin, helper auto-reply, `plugin-sdk` e aree di utility pure simili vengono instradati tramite la corsia `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file stateful/runtime-heavy restano sulle corsie esistenti. - Alcuni file sorgente helper selezionati di `plugin-sdk` e `commands` mappano inoltre le esecuzioni in modalità changed a test sibling espliciti in quelle corsie 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 mantiene il lavoro più pesante dell’harness di reply fuori dai test economici di status/chunk/token. -- Nota sul runner embedded: + - `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 mantiene il lavoro dell’harness reply più pesante fuori dai test economici di status/chunk/token. +- Nota sull’embedded runner: - Quando modifichi gli input di discovery dei message-tool o il contesto runtime di Compaction, mantieni entrambi i livelli di copertura. - - Aggiungi regressioni helper focalizzate per boundary puri di routing/normalizzazione. - - Mantieni inoltre in salute le suite di integrazione del runner embedded: + - Aggiungi regressioni helper mirate per i boundary puri 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`. - - Queste suite verificano che gli id con scope e il comportamento di compattazione continuino a passare - attraverso i veri percorsi `run.ts` / `compact.ts`; i soli test helper non sono un + - Queste suite verificano che gli id scoped e il comportamento di Compaction continuino a passare + attraverso i veri percorsi `run.ts` / `compact.ts`; i test solo helper non sono un sostituto sufficiente di questi percorsi di integrazione. - Nota sul pool: - - La configurazione base di Vitest ora usa per default `threads`. - - La configurazione Vitest condivisa fissa inoltre `isolate: false` e usa il runner non isolato in root projects, configurazioni e2e e live. - - La corsia 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 default `threads` + `isolate: false` dalla configurazione Vitest condivisa. - - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per default ai processi child Node di Vitest per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontarlo con il comportamento V8 standard. + - La configurazione base di Vitest ora usa `threads` come predefinito. + - La configurazione Vitest condivisa imposta anche `isolate: false` e usa il runner non isolato per i progetti root, e2e e live. + - La corsia UI root mantiene la sua configurazione `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 configurazione 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 confrontarti con il comportamento V8 standard. - Nota sull’iterazione locale veloce: - - `pnpm test:changed` instrada attraverso corsie con scope quando i percorsi modificati mappano in modo pulito a una suite più piccola. + - `pnpm test:changed` instrada tramite corsie scoped 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 di worker più alto. - - L’auto-scaling locale dei worker ora è intenzionalmente conservativo e riduce anche il carico quando il load average dell’host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per default. - - La configurazione base di Vitest contrassegna i progetti/file di configurazione come `forceRerunTriggers` così le riesecuzioni in modalità changed 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 il profiling diretto. -- Nota sul debug delle prestazioni: - - `pnpm test:perf:imports` abilita il reporting della durata degli import di Vitest più l’output di scomposizione degli import. + - 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 configurazione 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 configurazione mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` abilitato sugli host supportati; imposta `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se vuoi un’unica posizione cache esplicita per il profiling diretto. +- Nota sul debug prestazionale: + - `pnpm test:perf:imports` abilita il reporting della durata di importazione di Vitest più l’output di breakdown delle importazioni. - `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 il `test:changed` instradato con il percorso root-project nativo per quel diff committed 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 l’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 dei file disabilitato. +- `pnpm test:perf:changed:bench -- --ref ` confronta `test:changed` instradato con il percorso nativo root-project per quella diff committed e stampa wall time più RSS massimo su macOS. +- `pnpm test:perf:changed:bench -- --worktree` esegue il benchmark dell’albero dirty corrente instradando l’elenco dei file modificati tramite `scripts/test-projects.mjs` e la configurazione root Vitest. + - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per l’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 file disabilitato. ### E2E (smoke del gateway) - Comando: `pnpm test:e2e` - Configurazione: `vitest.e2e.config.ts` - File: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Runtime predefinito: +- Predefiniti runtime: - Usa Vitest `threads` con `isolate: false`, in linea con il resto del repository. - - Usa worker adattivi (CI: fino a 2, locale: 1 per default). - - Per default viene eseguito in modalità silenziosa per ridurre l’overhead di I/O della console. + - Usa worker adattivi (CI: fino a 2, locale: 1 per impostazione predefinita). + - Per impostazione predefinita viene eseguito in modalità silenziosa per ridurre l’overhead I/O della console. - Override utili: - `OPENCLAW_E2E_WORKERS=` per forzare il numero di worker (massimo 16). - - `OPENCLAW_E2E_VERBOSE=1` per riabilitare l’output verboso della console. + - `OPENCLAW_E2E_VERBOSE=1` per riabilitare output console verboso. - Ambito: - Comportamento end-to-end del gateway multiistanza - Superfici WebSocket/HTTP, pairing dei Node e networking più pesante - Aspettative: - Viene eseguito in CI (quando abilitato nella pipeline) - Non richiede chiavi reali - - Ha più parti in movimento rispetto ai test unitari (può essere più lento) + - Ha più parti in movimento dei test unitari (può essere più lento) ### E2E: smoke del backend OpenShell - Comando: `pnpm test:e2e:openshell` - File: `test/openshell-sandbox.e2e.test.ts` - Ambito: - - Avvia sull’host un Gateway OpenShell isolato tramite Docker - - Crea una sandbox da un Dockerfile locale temporaneo + - 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` + exec SSH reali - Verifica il comportamento del filesystem canonico remoto tramite il bridge fs della sandbox - Aspettative: - Solo opt-in; non fa parte dell’esecuzione predefinita `pnpm test:e2e` - - Richiede una CLI `openshell` locale più un daemon Docker funzionante + - Richiede una CLI `openshell` locale e un daemon Docker funzionante - Usa `HOME` / `XDG_CONFIG_HOME` isolati, poi distrugge il gateway di test e la 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) @@ -257,29 +336,29 @@ Pensa alle suite come a “realismo crescente” (e crescente instabilità/costo - Predefinito: **abilitato** da `pnpm test:live` (imposta `OPENCLAW_LIVE_TEST=1`) - Ambito: - “Questo provider/modello funziona davvero _oggi_ con credenziali reali?” - - Catturare cambi di formato del provider, particolarità delle tool call, problemi di autenticazione e comportamento dei rate limit + - Intercetta cambiamenti di formato del provider, peculiarità delle chiamate agli strumenti, problemi di auth e comportamento dei rate limit - Aspettative: - - Per progetto non è stabile in CI (reti reali, policy reali dei provider, quote, outage) + - Per progettazione non è stabile in CI (reti reali, policy reali dei provider, quote, outage) - Costa denaro / usa rate limit - - È preferibile eseguire subset ristretti invece di “tutto” -- Le esecuzioni live fanno source di `~/.profile` per recuperare eventuali chiavi API mancanti. -- Per default, le esecuzioni live continuano a isolare `HOME` e copiano il materiale di configurazione/autenticazione in una home di test temporanea così i 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 home directory reale. -- `pnpm test:live` ora usa per default 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 rumore 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` con formato separato da virgole/punto e virgola o `*_API_KEY_1`, `*_API_KEY_2` (ad esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure override per-live tramite `OPENCLAW_LIVE_*_KEY`; i test ritentano in caso di risposte di rate limit. + - È preferibile eseguire sottoinsiemi ristretti invece di “tutto” +- Le esecuzioni live eseguono il source di `~/.profile` per recuperare API key mancanti. +- Per impostazione predefinita, le esecuzioni live isolano comunque `HOME` e copiano il materiale di config/auth in una home di test temporanea, così i 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 di nuovo i log completi di avvio. +- Rotazione delle API key (specifica per provider): imposta `*_API_KEYS` con formato virgola/punto e virgola oppure `*_API_KEY_1`, `*_API_KEY_2` (per esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure override per-live tramite `OPENCLAW_LIVE_*_KEY`; i test ritentano sulle risposte di rate limit. - Output di avanzamento/heartbeat: - - Le suite live ora emettono righe di avanzamento su stderr così le chiamate lunghe ai provider risultano visibilmente attive anche quando la cattura della console di Vitest è silenziosa. - - `vitest.live.config.ts` disabilita l’intercettazione della console di Vitest così le righe di avanzamento del provider/gateway vengono trasmesse immediatamente durante le esecuzioni live. - - Regola gli heartbeat del modello diretto con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Regola gli heartbeat del gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Le suite live ora emettono righe di avanzamento su stderr, così le chiamate lunghe ai provider risultano visibilmente attive anche quando la cattura console di Vitest è silenziosa. + - `vitest.live.config.ts` disabilita l’intercettazione 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`. ## Quale suite dovrei eseguire? Usa questa tabella decisionale: -- Modifica di logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai cambiato molto) +- Se modifichi logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai cambiato molto) - Se tocchi networking del gateway / protocollo WS / pairing: aggiungi `pnpm test:e2e` -- Se stai facendo debug di “il mio bot non funziona” / errori specifici del provider / tool calling: esegui un `pnpm test:live` ristretto +- Se stai facendo debug di “il mio bot è giù” / errori specifici del provider / chiamata agli strumenti: esegui un `pnpm test:live` ristretto ## Live: sweep delle capacità del Node Android @@ -287,49 +366,49 @@ Usa questa tabella decisionale: - 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 manuale/precondizionato (la suite non installa/esegue/accoppia l’app). - - Validazione `node.invoke` del Gateway comando per comando per il Node Android selezionato. -- Pre-setup richiesto: - - App Android già connessa e accoppiata al gateway. + - Setup manuale/precondizionato (la suite non installa/esegue/abbina l’app). + - Validazione `node.invoke` del gateway comando per comando per il Node Android selezionato. +- Pre-setup obbligatorio: + - App Android già connessa e paired al gateway. - App mantenuta in primo piano. - - Permessi/consenso all’acquisizione concessi per le capacità che ti aspetti passino. + - Permessi/consenso alla cattura concessi per le capacità che ti aspetti passino. - Override facoltativi 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) -## Live: smoke del modello (chiavi del profilo) +## Live: smoke dei modelli (chiavi profilo) I test live sono divisi in due livelli così possiamo isolare i guasti: -- “Modello diretto” ci dice se il provider/modello può rispondere del tutto con la chiave fornita. -- “Smoke del Gateway” ci dice se l’intera pipeline gateway+agente funziona per quel modello (sessioni, cronologia, strumenti, policy sandbox, ecc.). +- “Direct model” ci dice se il provider/modello riesce almeno a rispondere con la chiave fornita. +- “Gateway smoke” ci dice se l’intera pipeline gateway+agent funziona per quel modello (sessioni, cronologia, strumenti, policy sandbox, ecc.). -### Livello 1: completamento diretto del modello (senza gateway) +### Livello 1: completamento direct model (senza gateway) - Test: `src/agents/models.profiles.live.test.ts` - Obiettivo: - - Enumerare i modelli rilevati + - Enumerare i modelli individuati - Usare `getApiKeyForModel` per selezionare i modelli per cui hai credenziali - Eseguire un piccolo completamento per modello (e regressioni mirate dove necessario) - Come abilitarlo: - - `pnpm test:live` (o `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 sullo smoke del Gateway + - `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` concentrato sul gateway smoke - Come selezionare i modelli: - - `OPENCLAW_LIVE_MODELS=modern` per eseguire l’allowlist moderna (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 moderna + - `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 dell’allowlist modern - oppure `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separata da virgole) - - Gli sweep modern/all usano per default un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep moderno esaustivo o un numero positivo per un limite più piccolo. + - Gli sweep modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo. - Come selezionare i provider: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separata da virgole) - Da dove arrivano le chiavi: - - Per default: store del profilo e fallback env - - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** lo store del profilo + - Per impostazione predefinita: store profilo e fallback env + - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** lo store profilo - Perché esiste: - - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline gateway agente è rotta” - - Contiene regressioni piccole e isolate (esempio: replay del ragionamento di OpenAI Responses/Codex Responses + flussi di tool-call) + - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline dell’agent del gateway è rotta” + - Contiene regressioni piccole e isolate (esempio: flussi di replay del ragionamento e tool-call OpenAI Responses/Codex Responses) -### Livello 2: smoke Gateway + agente dev (quello che fa davvero "@openclaw") +### Livello 2: smoke Gateway + dev agent (quello che fa davvero "@openclaw") - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Obiettivo: @@ -337,34 +416,34 @@ I test live sono divisi in due livelli così possiamo isolare i guasti: - Creare/modificare una sessione `agent:dev:*` (override del modello per esecuzione) - Iterare sui modelli-con-chiavi e verificare: - risposta “significativa” (senza strumenti) - - il funzionamento di una vera invocazione di strumento (probe `read`) - - probe opzionali di strumenti extra (probe `exec+read`) - - il corretto funzionamento dei percorsi di regressione OpenAI (solo tool-call → follow-up) -- Dettagli delle probe (così puoi spiegare rapidamente i guasti): - - probe `read`: il test scrive un file nonce nell’area di lavoro e chiede all’agente di eseguire `read` su di esso e di restituire il nonce. - - probe `exec+read`: il test chiede all’agente di scrivere tramite `exec` un nonce in un file temporaneo e poi di leggerlo di nuovo tramite `read`. - - probe immagine: il test allega un PNG generato (gatto + codice casuale) 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`. + - che una vera invocazione di strumento funzioni (sonda `read`) + - sonde strumento extra facoltative (sonda `exec+read`) + - che i percorsi di regressione OpenAI (solo tool-call → follow-up) continuino a funzionare +- Dettagli delle sonde (così puoi spiegare rapidamente i guasti): + - sonda `read`: il test scrive un file nonce nel workspace e chiede all’agent di `read` leggerlo e restituire il nonce. + - sonda `exec+read`: il test chiede all’agent di scrivere tramite `exec` un nonce in un file temporaneo, poi di `read` leggerlo di nuovo. + - sonda immagine: il test allega un PNG generato (gatto + codice casuale) e si aspetta che il modello restituisca `cat `. + - Riferimento implementativo: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. - Come abilitarlo: - - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) + - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) - Come selezionare i modelli: - - Predefinito: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` è un alias per l’allowlist moderna - - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o elenco separato da virgole) per restringere - - Gli sweep gateway modern/all usano per default un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` per uno sweep moderno esaustivo o un numero positivo per un limite più piccolo. + - Predefinito: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` è un alias dell’allowlist modern + - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o un elenco separato da virgole) per restringere + - Gli sweep gateway modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo. - Come selezionare i provider (evita “tutto OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separata da virgole) -- Le probe di strumenti + immagine sono sempre attive in questo test live: - - probe `read` + probe `exec+read` (stress degli strumenti) - - la probe immagine viene eseguita quando il modello dichiara il supporto per input immagine +- Le sonde di strumenti + immagine sono sempre attive in questo test live: + - sonda `read` + sonda `exec+read` (stress degli strumenti) + - la sonda 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: "" }]` - - 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 + - Il gateway analizza gli allegati in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - L’embedded agent inoltra al modello un messaggio utente multimodale - Verifica: la risposta contiene `cat` + il codice (tolleranza OCR: sono ammessi piccoli errori) -Suggerimento: per vedere cosa puoi testare sulla tua macchina (e gli esatti id `provider/model`), esegui: +Suggerimento: per vedere cosa puoi testare sulla tua macchina (e gli id esatti `provider/model`), esegui: ```bash openclaw models list @@ -374,23 +453,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 configurazione predefinita. -- I default smoke specifici del backend si trovano nella definizione `cli-backend.ts` dell’estensione proprietaria. +- Obiettivo: validare la pipeline Gateway + agent usando un backend CLI locale, senza toccare la configurazione predefinita. +- I predefiniti smoke specifici del backend si trovano nella definizione `cli-backend.ts` dell’extension proprietaria. - Abilitazione: - - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) + - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Predefiniti: - Provider/modello predefinito: `claude-cli/claude-sonnet-4-6` - - Il comportamento di comando/argomenti/immagine proviene dai metadati del Plugin proprietario del backend CLI. + - Il comportamento di comando/argomenti/immagine proviene dai metadati del Plugin backend CLI proprietario. - Override (facoltativi): - `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 è impostato `IMAGE_ARG`. + - `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 ripresa. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la probe predefinita di continuità nella stessa sessione Claude Sonnet -> Opus (impostalo a `1` per forzarla quando il modello selezionato supporta un target di switch). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la sonda predefinita di continuità della stessa sessione Claude Sonnet -> Opus (impostala a `1` per forzarla quando il modello selezionato supporta una destinazione di switch). Esempio: @@ -418,27 +497,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 repository come utente non root `node`. -- Risolve i metadati smoke della CLI dall’estensione proprietaria, quindi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) in un prefisso scrivibile con 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 sottoscrizione 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 corsia subscription disabilita per default le probe Claude MCP/tool e immagine perché Claude attualmente instrada l’uso delle app di terze parti tramite fatturazione extra-usage invece che attraverso i normali limiti del piano di sottoscrizione. -- 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 tool call MCP `cron` verificata tramite la CLI del gateway. -- Lo smoke predefinito di Claude modifica inoltre la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. +- Esegue lo smoke live del backend CLI dentro l’immagine Docker del repository come utente `node` non root. +- Risolve i metadati smoke CLI dall’extension proprietaria, poi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` oppure `@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 per l’abbonamento Claude Code tramite `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` oppure `CLAUDE_CODE_OAUTH_TOKEN` da `claude setup-token`. Per prima cosa verifica `claude -p` diretto in Docker, poi esegue due turni Gateway CLI-backend senza preservare le variabili env della API key Anthropic. Questa corsia subscription disabilita per impostazione predefinita le sonde Claude MCP/tool e immagine perché Claude attualmente instrada l’uso di applicazioni di terze parti tramite 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 allo strumento 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. ## Live: smoke di bind ACP (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Obiettivo: validare il vero flusso di conversation-bind ACP con un agente ACP live: +- Obiettivo: validare il vero flusso di conversation-bind ACP con un agent ACP live: - inviare `/acp spawn --bind here` - - associare sul posto una conversazione sintetica su canale messaggi - - inviare un normale follow-up sulla stessa conversazione + - associare in-place una conversazione sintetica di message-channel + - inviare un normale follow-up su quella stessa conversazione - verificare che il follow-up arrivi nella trascrizione della sessione ACP associata - Abilitazione: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Predefiniti: - - Agenti ACP in Docker: `claude,codex,gemini` - - Agente ACP per `pnpm test:live ...` diretto: `claude` - - Canale sintetico: contesto di conversazione stile DM Slack + - Agent ACP in Docker: `claude,codex,gemini` + - Agent ACP per `pnpm test:live ...` diretto: `claude` + - Canale sintetico: contesto conversazione in stile DM Slack - Backend ACP: `acpx` - Override: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -447,8 +526,8 @@ Note: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Note: - - Questa corsia usa la superficie gateway `chat.send` con campi di originating-route sintetici solo-admin così i test possono collegare il contesto del canale messaggi 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’agente harness ACP selezionato. + - Questa corsia 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 `acpx` incorporato per l’agent harness ACP selezionato. Esempio: @@ -464,7 +543,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 @@ -475,30 +554,30 @@ pnpm test:docker:live-acp-bind:gemini Note Docker: - Il runner Docker si trova in `scripts/test-live-acp-bind-docker.sh`. -- Per default, esegue in sequenza lo smoke di bind ACP contro tutti gli agenti CLI live supportati: `claude`, `codex`, poi `gemini`. -- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` per restringere la matrice. -- Esegue il source di `~/.profile`, prepara nel container il materiale di autenticazione 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 dal profilo importato. +- Per impostazione predefinita esegue in sequenza lo smoke ACP bind contro tutti gli agent CLI live supportati: `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. +- Esegue il source di `~/.profile`, mette in staging 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` oppure `@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 dal profilo sorgente. ## Live: smoke dell’harness app-server Codex - Obiettivo: validare l’harness Codex di proprietà del Plugin tramite il normale - metodo gateway `agent`: - - caricare il Plugin `codex` incluso + metodo `agent` del gateway: + - caricare il Plugin `codex` incorporato - selezionare `OPENCLAW_AGENT_RUNTIME=codex` - - inviare un primo turno agent 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 - dell’app-server possa riprendere - - eseguire `/codex status` e `/codex models` tramite lo stesso percorso - del comando gateway + app-server possa riprendere + - eseguire `/codex status` e `/codex models` tramite lo stesso percorso di comando + del gateway - 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` +- Sonda immagine facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Sonda MCP/tool facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Lo smoke imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` così un harness Codex - rotto non può passare ricadendo silenziosamente su PI. -- Autenticazione: `OPENAI_API_KEY` dalla shell/profilo, più eventuali + rotto non può risultare verde ricadendo silenziosamente su PI. +- Auth: `OPENAI_API_KEY` dalla shell/profilo, più eventuali `~/.codex/auth.json` e `~/.codex/config.toml` copiati Ricetta locale: @@ -522,44 +601,44 @@ pnpm test:docker:live-codex-harness Note Docker: - Il runner Docker si trova in `scripts/test-live-codex-harness-docker.sh`. -- Esegue il source di `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file di - autenticazione della CLI Codex quando presenti, installa `@openai/codex` in un prefisso npm - montato e scrivibile, prepara il tree dei sorgenti, quindi esegue solo il test live dell’harness Codex. -- Docker abilita per default le probe immagine e MCP/tool. Imposta - `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` o - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando hai bisogno di un’esecuzione di debug più ristretta. -- Docker esporta inoltre `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, in linea con la - configurazione del test live così il fallback `openai-codex/*` o PI non può nascondere una regressione dell’harness Codex. +- Esegue il source del `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file auth + della CLI Codex quando presenti, installa `@openai/codex` in un prefisso npm + montato e scrivibile, mette in staging l’albero dei sorgenti, poi esegue solo il test live dell’harness Codex. +- Docker abilita per impostazione predefinita le sonde immagine e MCP/tool. Imposta + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oppure + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando ti serve un’esecuzione di debug più ristretta. +- Docker esporta anche `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, in linea con la + configurazione del test live, così `openai-codex/*` o il fallback PI non possono nascondere una regressione dell’harness Codex. ### Ricette live consigliate -Allowlist ristrette ed esplicite sono più veloci e meno instabili: +Le allowlist ristrette ed esplicite sono le più veloci e le meno soggette a instabilità: -- Modello singolo, diretto (senza gateway): +- Modello singolo, direct (senza gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modello singolo, smoke del Gateway: +- 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: - `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 (autenticazione 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à degli strumenti). - API Gemini vs CLI Gemini: - - API: OpenClaw chiama via HTTP l’API Gemini ospitata da Google (chiave API / autenticazione del 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 autenticazione e può comportarsi in modo diverso (streaming/supporto strumenti/disallineamento di versione). + - API: OpenClaw chiama via HTTP l’API Gemini ospitata da Google (API key / auth del profilo); è questo 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 strumenti/disallineamento di versione). ## Live: matrice dei modelli (cosa copriamo) -Non esiste un “elenco modelli CI” fisso (il live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. +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. ### Set smoke moderno (tool calling + immagine) @@ -568,17 +647,17 @@ Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo continui a f - OpenAI (non-Codex): `openai/gpt-5.4` (facoltativo: `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 modelli Gemini 2.x più vecchi) +- Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evita i vecchi modelli Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` e `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Esegui smoke del Gateway con strumenti + immagine: +Esegui il gateway smoke con strumenti + 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) -Scegline almeno uno per famiglia di provider: +Scegline almeno uno per ogni famiglia di provider: - OpenAI: `openai/gpt-5.4` (oppure `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) @@ -586,7 +665,7 @@ Scegline almeno uno per famiglia di provider: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Copertura aggiuntiva facoltativa (gradita): +Copertura aggiuntiva facoltativa (utile averla): - xAI: `xai/grok-4` (oppure l’ultima disponibile) - Mistral: `mistral/`… (scegli un modello con capacità “tools” che hai abilitato) @@ -595,35 +674,35 @@ Copertura aggiuntiva facoltativa (gradita): ### Vision: invio immagine (allegato → messaggio multimodale) -Includi almeno un modello con capacità immagine in `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/varianti 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 supporto vision, ecc.) per esercitare la sonda immagine. ### Aggregatori / gateway alternativi -Se hai chiavi abilitate, supportiamo anche i test tramite: +Se hai le chiavi abilitate, supportiamo anche i test tramite: - 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 (autenticazione tramite `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- 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/configurazione): +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ù qualsiasi proxy compatibile OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, ecc.) -Suggerimento: non cercare di codificare in modo rigido “tutti i modelli” nella documentazione. L’elenco autorevole è qualunque cosa restituisca `discoverModels(...)` sulla tua macchina + qualunque chiave sia disponibile. +Suggerimento: non provare a hardcodare “tutti i modelli” nella documentazione. L’elenco autorevole è qualunque cosa `discoverModels(...)` restituisca sulla tua macchina + qualunque chiave sia disponibile. -## Credenziali (non committare mai) +## Credenziali (non fare mai commit) -I test live rilevano le credenziali nello stesso modo in cui lo fa la CLI. Implicazioni pratiche: +I test live scoprono le credenziali nello stesso modo in cui lo fa la CLI. Implicazioni pratiche: - Se la CLI funziona, i test live dovrebbero trovare le stesse chiavi. -- Se un test live dice “nessuna credenziale”, esegui il debug nello stesso modo in cui faresti il debug di `openclaw models list` / selezione del modello. +- Se un test live dice “nessuna credenziale”, fai debug nello stesso modo in cui faresti per `openclaw models list` / selezione del modello. -- Profili di autenticazione per agente: `~/.openclaw/agents//agent/auth-profiles.json` (questo è ciò che “chiavi del profilo” significa nei test live) -- Configurazione: `~/.openclaw/openclaw.json` (o `OPENCLAW_CONFIG_PATH`) -- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live staged quando presente, ma non nello store principale delle chiavi del profilo) -- Le esecuzioni locali live copiano per default la configurazione attiva, i file `auth-profiles.json` per agente, `credentials/` legacy e le directory di autenticazione CLI esterne supportate in una home di test temporanea; le home live staged saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dalla tua vera area di lavoro host. +- Profili auth per agent: `~/.openclaw/agents//agent/auth-profiles.json` (questo è ciò che nei test live significa “chiavi profilo”) +- Config: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) +- Directory state legacy: `~/.openclaw/credentials/` (copiata nella home live staged 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 agent, la directory legacy `credentials/` e le directory auth CLI esterne supportate in una home di test temporanea; le home live staged saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le sonde restano fuori dal tuo workspace host reale. -Se vuoi affidarti alle chiavi env (ad esempio 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 sotto (possono montare `~/.profile` nel container). ## Live Deepgram (trascrizione audio) @@ -636,14 +715,14 @@ Se vuoi affidarti alle chiavi env (ad esempio esportate nel tuo `~/.profile`), e - Abilitazione: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Override facoltativo del modello: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live media di workflow ComfyUI +## 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 immagine, video e `music_generate` di comfy incluso + - Esercita i percorsi immagine, video e `music_generate` del comfy incorporato - Salta ogni capacità a meno che `models.providers.comfy.` non sia configurato - - Utile dopo modifiche all’invio del workflow comfy, al polling, ai download o alla registrazione del Plugin + - Utile dopo modifiche all’invio di workflow comfy, polling, download o registrazione del Plugin ## Live generazione di immagini @@ -652,15 +731,15 @@ Se vuoi affidarti alle chiavi env (ad esempio esportate nel tuo `~/.profile`), e - Harness: `pnpm test:live:media image` - Ambito: - Enumera ogni Plugin provider di generazione immagini registrato - - Carica le variabili env provider mancanti dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per default le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza autenticazione/profilo/modello utilizzabile + - Carica da `~/.profile` le variabili env mancanti del provider prima delle sonde + - Usa per impostazione predefinita API key live/env prima dei profili auth memorizzati, così chiavi di test stale in `auth-profiles.json` non mascherano le credenziali reali 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` - `openai:default-generate` -- Provider inclusi attualmente coperti: +- Provider incorporati attualmente coperti: - `openai` - `google` - Restrizione facoltativa: @@ -668,7 +747,7 @@ Se vuoi affidarti alle chiavi env (ad esempio esportate nel tuo `~/.profile`), e - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’autenticazione tramite store del profilo e ignorare gli override solo-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre auth da store profilo e ignorare override solo env ## Live generazione musicale @@ -676,23 +755,23 @@ Se vuoi affidarti alle chiavi env (ad esempio esportate nel tuo `~/.profile`), e - 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 dei provider inclusi di generazione musicale + - Esercita il percorso condiviso del provider di generazione musicale incorporato - Attualmente copre Google e MiniMax - - Carica le variabili env dei provider dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per default le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza autenticazione/profilo/modello utilizzabile + - Carica da `~/.profile` le variabili env del provider prima delle sonde + - Usa per impostazione predefinita API key live/env prima dei profili auth memorizzati, così chiavi di test stale in `auth-profiles.json` non mascherano le credenziali reali della shell + - Salta i provider senza auth/profilo/modello utilizzabili - Esegue entrambe le modalità runtime dichiarate quando disponibili: - `generate` con input solo prompt - `edit` quando il provider dichiara `capabilities.edit.enabled` - Copertura attuale della corsia condivisa: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: file live Comfy separato, non questo sweep condiviso + - `comfy`: file live Comfy separato, non questa sweep condivisa - Restrizione facoltativa: - `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’autenticazione tramite store del profilo e ignorare gli override solo-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre auth da store profilo e ignorare override solo env ## Live generazione video @@ -700,225 +779,225 @@ Se vuoi affidarti alle chiavi env (ad esempio esportate nel tuo `~/.profile`), e - 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 dei provider inclusi di generazione video - - Carica le variabili env dei provider dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per default le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza autenticazione/profilo/modello utilizzabile + - Esercita il percorso condiviso del provider di generazione video incorporato + - Carica da `~/.profile` le variabili env del provider prima delle sonde + - Usa per impostazione predefinita API key live/env prima dei profili auth memorizzati, così chiavi di test stale in `auth-profiles.json` non mascherano le credenziali reali della shell + - Salta i provider senza auth/profilo/modello utilizzabili - Esegue entrambe le modalità runtime dichiarate quando disponibili: - `generate` con input solo prompt - - `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 - - Provider `imageToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - - `vydra` perché `veo3` incluso è solo testo e `kling` incluso richiede un URL immagine remoto - - Copertura specifica del provider Vydra: + - `imageToVideo` quando il provider dichiara `capabilities.imageToVideo.enabled` e il provider/modello selezionato accetta input immagine locale basato su buffer nella sweep condivisa + - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale basato su buffer nella sweep condivisa + - Provider `imageToVideo` attualmente dichiarati ma saltati nella sweep condivisa: + - `vydra` perché il `veo3` incorporato è solo testo e il `kling` incorporato richiede un URL immagine remoto + - 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 corsia `kling` che usa per default un fixture di URL immagine remoto - - Copertura live attuale di `videoToVideo`: + - quel file esegue `veo3` text-to-video più una corsia `kling` che usa per impostazione predefinita un fixture con URL immagine remoto + - Copertura live `videoToVideo` attuale: - solo `runway` quando il modello selezionato è `runway/gen4_aleph` - - Provider `videoToVideo` attualmente dichiarati ma saltati nello sweep condiviso: + - Provider `videoToVideo` attualmente dichiarati ma saltati nella sweep condivisa: - `alibaba`, `qwen`, `xai` perché quei percorsi richiedono attualmente URL di riferimento remoti `http(s)` / MP4 - - `google` perché l’attuale corsia condivisa Gemini/Veo usa input locale basato su buffer e quel percorso non è accettato nello sweep condiviso - - `openai` perché l’attuale corsia condivisa non garantisce l’accesso specifico dell’organizzazione a video inpaint/remix + - `google` perché l’attuale corsia condivisa Gemini/Veo usa input locale basato su buffer e quel percorso non è accettato nella sweep condivisa + - `openai` perché l’attuale corsia condivisa non garantisce l’accesso specifico per organizzazione a video inpaint/remix - Restrizione facoltativa: - `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"` - Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’autenticazione tramite store del profilo e ignorare gli override solo-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre auth da store profilo e ignorare 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 repository - - Carica automaticamente le variabili env provider mancanti da `~/.profile` - - Restringe automaticamente per default ogni suite ai provider che al momento hanno autenticazione utilizzabile - - Riutilizza `scripts/test-live.mjs`, così heartbeat e comportamento della modalità silenziosa restano coerenti + - Carica automaticamente da `~/.profile` le variabili env mancanti del provider + - Restringe automaticamente per impostazione predefinita ogni suite ai provider che al momento hanno auth utilizzabile + - Riutilizza `scripts/test-live.mjs`, così il comportamento di heartbeat e modalità silenziosa resta coerente - Esempi: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `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 (verifiche facoltative “funziona su Linux”) -Questi runner Docker si dividono in due categorie: +Questi runner Docker si dividono in due gruppi: -- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il rispettivo file live con chiavi profilo dentro l’immagine Docker del repository (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la tua directory di configurazione locale e l’area di lavoro (ed eseguendo il source di `~/.profile` se montato). Gli entrypoint locali corrispondenti sono `test:live:models-profiles` e `test:live:gateway-profiles`. -- I runner live Docker usano per default un limite smoke più piccolo così uno sweep Docker completo resta praticabile: - `test:docker:live-models` usa per default `OPENCLAW_LIVE_MAX_MODELS=12`, e - `test:docker:live-gateway` usa per default `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il rispettivo file live con chiavi profilo dentro l’immagine Docker del repository (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la directory di configurazione locale e il workspace (ed eseguendo il source di `~/.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ì una sweep Docker completa resta pratica: + `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`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e `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 riutilizza per le due corsie Docker live. -- Runner smoke container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` avviano uno o più container reali e verificano percorsi di integrazione di livello superiore. +- `test:docker:all` costruisce una sola volta l’immagine Docker live tramite `test:docker:live-build`, poi la riutilizza per le due corsie Docker live. +- Runner smoke del container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` avviano uno o più container reali e verificano percorsi di integrazione di livello superiore. -I runner Docker live-model montano inoltre tramite bind solo le home di autenticazione 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 autenticazione dell’host: +I runner Docker live-model montano inoltre in bind solo le home auth CLI necessarie (oppure tutte quelle supportate quando l’esecuzione non è ristretta), poi le copiano nella home del container prima dell’esecuzione così OAuth della CLI esterna può aggiornare i token senza modificare lo store auth dell’host: -- Modelli diretti: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke di bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) -- Smoke del backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Smoke dell’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`) +- Modelli direct: `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 + dev agent: `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`) -- Networking del Gateway (due container, autenticazione WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Bridge di canale MCP (Gateway seedato + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Plugin (smoke di installazione + alias `/plugin` + semantica di riavvio del bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Networking del gateway (due container, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Bridge canale MCP (Gateway seeded + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Plugin (smoke install + alias `/plugin` + semantica di riavvio del bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -I runner Docker live-model montano inoltre tramite bind il checkout corrente in sola lettura e -lo preparano in una workdir temporanea dentro il container. Questo mantiene snella l’immagine runtime -pur eseguendo comunque Vitest contro i tuoi esatti sorgenti/configurazione locali. -Il passaggio di staging salta grandi cache solo-locali e output di build dell’app come -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory di output locali dell’app `.build` o -Gradle così le esecuzioni live Docker non passano minuti a copiare -artefatti specifici della macchina. -Impostano inoltre `OPENCLAW_SKIP_CHANNELS=1` così le probe live del gateway non avviano -veri worker di canale 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 copertura -live del gateway da quella corsia Docker. +I runner Docker live-model montano inoltre in bind il checkout corrente in sola lettura e +lo mettono in staging in una workdir temporanea dentro il container. Questo mantiene l’immagine runtime +snella pur eseguendo Vitest sul tuo esatto sorgente/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 dell’app, così le esecuzioni live Docker non spendono minuti a copiare +artifact specifici della macchina. +Impostano inoltre `OPENCLAW_SKIP_CHANNELS=1` così le sonde live del gateway non avviano +worker di canale reali Telegram/Discord/ecc. dentro il container. +`test:docker:live-models` esegue comunque `pnpm test:live`, quindi fai passare anche +`OPENCLAW_LIVE_GATEWAY_*` quando devi restringere o escludere la copertura live del gateway +da quella corsia Docker. `test:docker:openwebui` è uno smoke di compatibilità di livello superiore: avvia un -container Gateway OpenClaw con endpoint HTTP compatibili OpenAI abilitati, -avvia un container Open WebUI fissato contro quel gateway, effettua il login tramite -Open WebUI, verifica che `/api/models` esponga `openclaw/default`, quindi invia una +container gateway OpenClaw con gli endpoint HTTP compatibili OpenAI abilitati, +avvia un container Open WebUI fissato contro quel gateway, esegue il sign-in tramite +Open WebUI, verifica che `/api/models` esponga `openclaw/default`, poi 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. -Questa corsia si aspetta una chiave modello live utilizzabile, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` per default) è il modo principale per fornirla nelle esecuzioni Dockerizzate. +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 cold-start. +Questa corsia richiede una chiave di modello live utilizzabile e `OPENCLAW_PROFILE_FILE` +(`~/.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 deterministico e non ha bisogno di un -vero account Telegram, Discord o iMessage. Avvia un container Gateway -seedato, ne avvia un secondo che esegue `openclaw mcp serve`, quindi -verifica discovery della conversazione instradata, lettura delle trascrizioni, metadati degli allegati, -comportamento della coda eventi live, routing dell’invio in uscita e notifiche in stile Claude di canale + +`test:docker:mcp-channels` è intenzionalmente deterministico e non richiede un +account reale Telegram, Discord o iMessage. Avvia un container Gateway +seeded, avvia un secondo container che esegue `openclaw mcp serve`, poi +verifica discovery della conversazione instradata, letture della trascrizione, metadati degli allegati, +comportamento della coda eventi live, instradamento dell’invio outbound e notifiche in stile Claude di canale + permessi sul vero bridge MCP stdio. Il controllo delle notifiche ispeziona direttamente i frame MCP stdio raw così lo smoke valida ciò che il -bridge emette realmente, non solo ciò che un particolare SDK client capita di esporre. +bridge emette realmente, non solo ciò che un determinato SDK client espone in superficie. Smoke manuale ACP plain-language thread (non CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantieni questo script per flussi di lavoro di regressione/debug. Potrebbe essere nuovamente necessario per la validazione del routing dei thread ACP, quindi non eliminarlo. +- Mantieni questo script per flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la validazione del routing thread ACP, quindi non eliminarlo. Variabili env utili: -- `OPENCLAW_CONFIG_DIR=...` (predefinito: `~/.openclaw`) montata su `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (predefinito: `~/.openclaw/workspace`) montata su `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (predefinito: `~/.profile`) montata su `/home/node/.profile` ed eseguito il source prima di avviare i test -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinito: `~/.cache/openclaw/docker-cli-tools`) montata su `/home/node/.npm-global` per installazioni CLI in cache dentro Docker -- Directory/file di autenticazione CLI esterni sotto `$HOME` vengono montati in sola lettura sotto `/host-auth...`, poi copiati in `/home/node/...` prima dell’avvio dei test +- `OPENCLAW_CONFIG_DIR=...` (predefinito: `~/.openclaw`) montata in `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (predefinito: `~/.openclaw/workspace`) montata in `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (predefinito: `~/.profile`) montata in `/home/node/.profile` ed eseguito il source prima di avviare i test +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinito: `~/.cache/openclaw/docker-cli-tools`) montata in `/home/node/.npm-global` per installazioni CLI in cache dentro Docker +- Le directory/file auth CLI esterni 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 ristrette per provider montano solo le directory/file necessari dedotti da `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Le esecuzioni provider ristrette montano solo 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` - `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 riutilizzare un’immagine `openclaw:local-live` esistente per riesecuzioni che non richiedono una nuova build -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurare che le credenziali provengano dallo store del profilo (non dall’env) +- `OPENCLAW_SKIP_DOCKER_BUILD=1` per riutilizzare un’immagine `openclaw:local-live` esistente per riesecuzioni che non richiedono una ricostruzione +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurarsi che le credenziali provengano dallo store profilo (non da 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 immagine Open WebUI fissato -## Verifica della documentazione +## Integrità della documentazione Esegui i controlli della documentazione dopo modifiche ai documenti: `pnpm check:docs`. -Esegui la validazione completa degli anchor Mintlify quando ti servono anche i controlli delle intestazioni in pagina: `pnpm docs:check-links:anchors`. +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) Queste sono regressioni della “pipeline reale” senza provider reali: -- Tool calling del Gateway (OpenAI mock, vero gateway + agent loop): `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 applicata): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Tool calling del gateway (mock OpenAI, loop reale 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`, scrittura config + auth obbligata): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Valutazioni di affidabilità dell’agente (Skills) +## Valutazioni di affidabilità dell’agent (Skills) -Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità dell’agente”: +Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità dell’agent”: -- Tool-calling mock tramite il vero gateway + agent loop (`src/gateway/gateway.test.ts`). +- Mock del tool-calling tramite il vero loop gateway + agent (`src/gateway/gateway.test.ts`). - Flussi wizard end-to-end 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)): +Cosa manca ancora per Skills (vedi [Skills](/it/tools/skills)): -- **Decisione:** quando le Skills sono elencate nel prompt, l’agente sceglie la Skill giusta (o evita quelle irrilevanti)? -- **Conformità:** l’agente legge `SKILL.md` prima dell’uso e segue i passaggi/argomenti richiesti? -- **Contratti di workflow:** scenari multi-turno che verificano ordine degli strumenti, continuità della cronologia della sessione e boundary della sandbox. +- **Decisioning:** quando 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 i passaggi/argomenti richiesti? +- **Workflow contracts:** scenari multi-turno che verificano ordine degli strumenti, riporto della cronologia di sessione e boundary della sandbox. -Le valutazioni future dovrebbero restare prima di tutto deterministiche: +Le valutazioni future dovrebbero restare deterministiche prima di tutto: -- Un runner di scenari che usa provider mock per verificare tool call + ordine, letture di file Skill e wiring della sessione. -- Una piccola suite di scenari focalizzati sulle Skill (usare vs evitare, gating, prompt injection). -- Valutazioni live facoltative (opt-in, controllate da env) solo dopo che la suite sicura per CI è pronta. +- Un runner di scenari che usi provider mock per verificare chiamate agli strumenti + 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. -## Test di contratto (forma di Plugin e canale) +## Test di contratto (forma di Plugin e channel) -I test di contratto verificano che ogni Plugin e canale 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 corsia unitaria predefinita `pnpm test` -salta intenzionalmente questi file seam condivisi e smoke; esegui esplicitamente i comandi di contratto -quando tocchi superfici condivise di canali o provider. +I test di contratto verificano che ogni Plugin e channel registrato sia conforme al +proprio contratto di interfaccia. Iterano su tutti i plugin scoperti ed eseguono una suite di +verifiche su forma e comportamento. La corsia unitaria predefinita `pnpm test` +salta intenzionalmente questi file shared seam e smoke; esegui esplicitamente +i comandi di contratto 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, capacità) -- **setup** - Contratto della procedura guidata di setup -- **session-binding** - Comportamento del binding di sessione -- **outbound-payload** - Struttura del payload dei messaggi -- **inbound** - Gestione dei messaggi in ingresso -- **actions** - Handler delle azioni del canale -- **threading** - Gestione dell’ID del thread -- **directory** - API di directory/roster -- **group-policy** - Applicazione della group policy +- **setup** - Contratto del wizard di setup +- **session-binding** - Comportamento di binding della sessione +- **outbound-payload** - Struttura del payload del messaggio +- **inbound** - Gestione dei messaggi inbound +- **actions** - Handler delle azioni del channel +- **threading** - Gestione dell’id del thread +- **directory** - API directory/roster +- **group-policy** - Applicazione della policy di gruppo ### Contratti di stato del provider Si trovano in `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe di stato del canale +- **status** - Sonde 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 di autenticazione -- **auth-choice** - Scelta/selezione dell’autenticazione +- **auth** - Contratto del flusso auth +- **auth-choice** - Scelta/selezione auth - **catalog** - API del catalogo modelli -- **discovery** - Discovery dei Plugin -- **loader** - Caricamento dei Plugin +- **discovery** - Discovery del Plugin +- **loader** - Caricamento del Plugin - **runtime** - Runtime del provider - **shape** - Forma/interfaccia del Plugin -- **wizard** - Procedura guidata di setup +- **wizard** - Wizard di setup ### Quando eseguirli -- Dopo aver modificato export o sottopercorsi di `plugin-sdk` -- Dopo aver aggiunto o modificato un Plugin di canale o provider -- Dopo il refactoring della registrazione o della discovery dei Plugin +- Dopo aver modificato export o subpath di `plugin-sdk` +- Dopo aver aggiunto o modificato un Plugin channel o provider +- Dopo aver rifattorizzato registrazione o discovery 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. ## Aggiungere regressioni (linee guida) -Quando correggi un problema di provider/modello scoperto nel live: +Quando correggi un problema di provider/modello scoperto in live: -- Aggiungi una regressione sicura per CI se possibile (provider mock/stub, oppure acquisisci l’esatta trasformazione della forma della richiesta) -- Se è intrinsecamente solo-live (rate limit, policy di autenticazione), mantieni il test live ristretto e opt-in tramite variabili env -- Preferisci puntare al livello più piccolo che intercetta il bug: - - bug di conversione/replay della richiesta del provider → test diretto dei modelli - - bug della pipeline sessione/cronologia/strumenti del gateway → smoke live del gateway o test mock del gateway sicuro per CI +- Aggiungi, se possibile, una regressione sicura per CI (provider mock/stub, oppure cattura 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 del provider → test direct models + - bug della pipeline session/history/tool del gateway → gateway live smoke o test mock gateway sicuro per CI - Guardrail di attraversamento SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un target campionato per classe SecretRef dai metadati del registro (`listSecretTargetRegistryEntries()`), quindi 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 su id target non classificati così le nuove classi non possono essere saltate in silenzio. + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un target campione per 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 in silenzio. diff --git a/docs/it/providers/index.md b/docs/it/providers/index.md index f6b948db6..5b848cdb2 100644 --- a/docs/it/providers/index.md +++ b/docs/it/providers/index.md @@ -1,14 +1,14 @@ --- read_when: - Vuoi scegliere un provider di modelli - - Hai bisogno di una rapida panoramica dei backend LLM supportati + - Ti serve una rapida panoramica dei backend LLM supportati summary: Provider di modelli (LLM) supportati da OpenClaw title: Directory dei provider x-i18n: - generated_at: "2026-04-08T02:17:21Z" + generated_at: "2026-04-13T08:27:13Z" model: gpt-5.4 provider: openai - source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70 + source_hash: 3bc682d008119719826f71f74959ab32bedf14214459f5e6ac9cb70371d3c540 source_path: providers/index.md workflow: 15 --- @@ -18,9 +18,9 @@ x-i18n: OpenClaw può usare molti provider LLM. Scegli un provider, autenticati, quindi imposta il modello predefinito come `provider/model`. -Cerchi la documentazione dei canali chat (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/ecc.)? Vedi [Channels](/it/channels). +Cerchi la documentazione dei canali di chat (WhatsApp/Telegram/Discord/Slack/Mattermost (Plugin)/ecc.)? Vedi [Canali](/it/channels). -## Avvio rapido +## Guida rapida 1. Autenticati con il provider (di solito tramite `openclaw onboard`). 2. Imposta il modello predefinito: @@ -48,10 +48,11 @@ Cerchi la documentazione dei canali chat (WhatsApp/Telegram/Discord/Slack/Matter - [Modelli GLM](/it/providers/glm) - [Google (Gemini)](/it/providers/google) - [Groq (inferenza LPU)](/it/providers/groq) -- [Hugging Face (Inference)](/it/providers/huggingface) +- [Hugging Face (inferenza)](/it/providers/huggingface) - [inferrs (modelli locali)](/it/providers/inferrs) - [Kilocode](/it/providers/kilocode) -- [LiteLLM (gateway unificato)](/it/providers/litellm) +- [LiteLLM (Gateway unificato)](/it/providers/litellm) +- [LM Studio (modelli locali)](/it/providers/lmstudio) - [MiniMax](/it/providers/minimax) - [Mistral](/it/providers/mistral) - [Moonshot AI (Kimi + Kimi Coding)](/it/providers/moonshot) @@ -69,7 +70,7 @@ Cerchi la documentazione dei canali chat (WhatsApp/Telegram/Discord/Slack/Matter - [StepFun](/it/providers/stepfun) - [Synthetic](/it/providers/synthetic) - [Together AI](/it/providers/together) -- [Venice (Venice AI, focalizzato sulla privacy)](/it/providers/venice) +- [Venice (Venice AI, orientato alla privacy)](/it/providers/venice) - [Vercel AI Gateway](/it/providers/vercel-ai-gateway) - [Vydra](/it/providers/vydra) - [vLLM (modelli locali)](/it/providers/vllm) @@ -80,7 +81,7 @@ Cerchi la documentazione dei canali chat (WhatsApp/Telegram/Discord/Slack/Matter ## Pagine panoramiche condivise -- [Ulteriori varianti incluse](/it/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy e Gemini CLI OAuth +- [Varianti bundle aggiuntive](/it/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy e Gemini CLI OAuth - [Generazione di immagini](/it/tools/image-generation) - Strumento condiviso `image_generate`, selezione del provider e failover - [Generazione musicale](/it/tools/music-generation) - Strumento condiviso `music_generate`, selezione del provider e failover - [Generazione video](/it/tools/video-generation) - Strumento condiviso `video_generate`, selezione del provider e failover @@ -91,7 +92,7 @@ Cerchi la documentazione dei canali chat (WhatsApp/Telegram/Discord/Slack/Matter ## Strumenti della community -- [Claude Max API Proxy](/it/providers/claude-max-api-proxy) - Proxy della community per credenziali di abbonamento Claude (verifica policy/termini di Anthropic prima dell'uso) +- [Claude Max API Proxy](/it/providers/claude-max-api-proxy) - Proxy della community per le credenziali di abbonamento Claude (verifica la policy/i termini di Anthropic prima dell'uso) Per il catalogo completo dei provider (xAI, Groq, Mistral, ecc.) e la configurazione avanzata, -vedi [Model providers](/it/concepts/model-providers). +vedi [Provider di modelli](/it/concepts/model-providers). diff --git a/docs/it/providers/lmstudio.md b/docs/it/providers/lmstudio.md new file mode 100644 index 000000000..cb4da0c93 --- /dev/null +++ b/docs/it/providers/lmstudio.md @@ -0,0 +1,163 @@ +--- +read_when: + - Vuoi eseguire OpenClaw con modelli open source tramite LM Studio + - Vuoi configurare e impostare LM Studio +summary: Esegui OpenClaw con LM Studio +title: LM Studio +x-i18n: + generated_at: "2026-04-13T08:27:15Z" + model: gpt-5.4 + provider: openai + source_hash: 11264584e8277260d4215feb7c751329ce04f59e9228da1c58e147c21cd9ac2c + source_path: providers/lmstudio.md + workflow: 15 +--- + +# LM Studio + +LM Studio è un'app intuitiva ma potente per eseguire modelli open-weight sul tuo hardware. Ti consente di eseguire modelli llama.cpp (GGUF) o MLX (Apple Silicon). È disponibile come pacchetto GUI o come demone headless (`llmster`). Per la documentazione del prodotto e della configurazione, vedi [lmstudio.ai](https://lmstudio.ai/). + +## Guida rapida + +1. Installa LM Studio (desktop) oppure `llmster` (headless), quindi avvia il server locale: + +```bash +curl -fsSL https://lmstudio.ai/install.sh | bash +``` + +2. Avvia il server + +Assicurati di avviare l'app desktop oppure di eseguire il demone con il seguente comando: + +```bash +lms daemon up +``` + +```bash +lms server start --port 1234 +``` + +Se stai usando l'app, assicurati di avere JIT abilitato per un'esperienza fluida. Scopri di più nella [guida JIT e TTL di LM Studio](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict). + +3. OpenClaw richiede un valore di token LM Studio. Imposta `LM_API_TOKEN`: + +```bash +export LM_API_TOKEN="your-lm-studio-api-token" +``` + +Se l'autenticazione di LM Studio è disabilitata, usa qualsiasi valore di token non vuoto: + +```bash +export LM_API_TOKEN="placeholder-key" +``` + +Per i dettagli sulla configurazione dell'autenticazione di LM Studio, vedi [Autenticazione di LM Studio](https://lmstudio.ai/docs/developer/core/authentication). + +4. Esegui l'onboarding e scegli `LM Studio`: + +```bash +openclaw onboard +``` + +5. Durante l'onboarding, usa il prompt `Default model` per scegliere il tuo modello LM Studio. + +Puoi anche impostarlo o modificarlo in seguito: + +```bash +openclaw models set lmstudio/qwen/qwen3.5-9b +``` + +Le chiavi dei modelli LM Studio seguono il formato `author/model-name` (ad esempio `qwen/qwen3.5-9b`). I riferimenti ai modelli di OpenClaw antepongono il nome del provider: `lmstudio/qwen/qwen3.5-9b`. Puoi trovare la chiave esatta di un modello eseguendo `curl http://localhost:1234/api/v1/models` e cercando il campo `key`. + +## Onboarding non interattivo + +Usa l'onboarding non interattivo quando vuoi automatizzare la configurazione (CI, provisioning, bootstrap remoto): + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio +``` + +Oppure specifica URL di base o modello con chiave API: + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio \ + --custom-base-url http://localhost:1234/v1 \ + --lmstudio-api-key "$LM_API_TOKEN" \ + --custom-model-id qwen/qwen3.5-9b +``` + +`--custom-model-id` accetta la chiave del modello restituita da LM Studio (ad esempio `qwen/qwen3.5-9b`), senza il prefisso provider `lmstudio/`. + +L'onboarding non interattivo richiede `--lmstudio-api-key` (oppure `LM_API_TOKEN` nell'ambiente). +Per i server LM Studio senza autenticazione, va bene qualsiasi valore di token non vuoto. + +`--custom-api-key` rimane supportato per compatibilità, ma per LM Studio è preferibile `--lmstudio-api-key`. + +Questo scrive `models.providers.lmstudio`, imposta il modello predefinito su +`lmstudio/` e scrive il profilo di autenticazione `lmstudio:default`. + +La configurazione interattiva può richiedere una lunghezza di contesto di caricamento preferita facoltativa e la applica ai modelli LM Studio rilevati che salva nella configurazione. + +## Configurazione + +### Configurazione esplicita + +```json5 +{ + models: { + providers: { + lmstudio: { + baseUrl: "http://localhost:1234/v1", + apiKey: "${LM_API_TOKEN}", + api: "openai-completions", + models: [ + { + id: "qwen/qwen3-coder-next", + name: "Qwen 3 Coder Next", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 128000, + maxTokens: 8192, + }, + ], + }, + }, + }, +} +``` + +## Risoluzione dei problemi + +### LM Studio non rilevato + +Assicurati che LM Studio sia in esecuzione e di avere impostato `LM_API_TOKEN` (per i server senza autenticazione, va bene qualsiasi valore di token non vuoto): + +```bash +# Avvia tramite l'app desktop oppure in modalità headless: +lms server start --port 1234 +``` + +Verifica che l'API sia accessibile: + +```bash +curl http://localhost:1234/api/v1/models +``` + +### Errori di autenticazione (HTTP 401) + +Se la configurazione segnala HTTP 401, verifica la tua chiave API: + +- Controlla che `LM_API_TOKEN` corrisponda alla chiave configurata in LM Studio. +- Per i dettagli sulla configurazione dell'autenticazione di LM Studio, vedi [Autenticazione di LM Studio](https://lmstudio.ai/docs/developer/core/authentication). +- Se il tuo server non richiede autenticazione, usa qualsiasi valore di token non vuoto per `LM_API_TOKEN`. + +### Caricamento del modello just-in-time + +LM Studio supporta il caricamento dei modelli just-in-time (JIT), in cui i modelli vengono caricati alla prima richiesta. Assicurati di averlo abilitato per evitare errori di tipo "Model not loaded". diff --git a/docs/it/reference/api-usage-costs.md b/docs/it/reference/api-usage-costs.md index 68021ba28..e91e3e11c 100644 --- a/docs/it/reference/api-usage-costs.md +++ b/docs/it/reference/api-usage-costs.md @@ -1,114 +1,114 @@ --- read_when: - Vuoi capire quali funzionalità possono chiamare API a pagamento - - Devi verificare chiavi, costi e visibilità dell'utilizzo - - Stai spiegando la reportistica dei costi di /status o /usage -summary: Verifica cosa può comportare spese, quali chiavi vengono usate e come visualizzare l'utilizzo -title: Utilizzo API e costi + - Devi verificare chiavi, costi e visibilità dell’utilizzo + - Stai spiegando la reportistica dei costi in `/status` o `/usage` +summary: Verifica cosa può comportare costi, quali chiavi vengono utilizzate e come visualizzare l’utilizzo +title: Utilizzo e costi delle API x-i18n: - generated_at: "2026-04-07T08:17:26Z" + generated_at: "2026-04-13T08:27:13Z" model: gpt-5.4 provider: openai - source_hash: ab6eefcde9ac014df6cdda7aaa77ef48f16936ab12eaa883d9fe69425a31a2dd + source_hash: f5077e74d38ef781ac7a72603e9f9e3829a628b95c5a9967915ab0f321565429 source_path: reference/api-usage-costs.md workflow: 15 --- -# Utilizzo API e costi +# Utilizzo e costi delle API -Questa documentazione elenca le **funzionalità che possono invocare chiavi API** e dove compaiono i relativi costi. Si concentra sulle +Questo documento elenca le **funzionalità che possono invocare chiavi API** e dove compaiono i relativi costi. Si concentra sulle funzionalità di OpenClaw che possono generare utilizzo del provider o chiamate API a pagamento. ## Dove compaiono i costi (chat + CLI) **Snapshot dei costi per sessione** -- `/status` mostra il modello corrente della sessione, l'utilizzo del contesto e i token dell'ultima risposta. -- Se il modello usa **autenticazione con chiave API**, `/status` mostra anche il **costo stimato** dell'ultima risposta. -- Se i metadati live della sessione sono scarsi, `/status` può recuperare i contatori di - token/cache e l'etichetta del modello runtime attivo dall'ultima voce di utilizzo - della trascrizione. I valori live non nulli esistenti hanno comunque la precedenza, e i totali - della trascrizione dimensionati sul prompt possono prevalere quando i totali memorizzati mancano o sono inferiori. +- `/status` mostra il modello della sessione corrente, l’utilizzo del contesto e i token dell’ultima risposta. +- Se il modello usa **autenticazione con chiave API**, `/status` mostra anche il **costo stimato** dell’ultima risposta. +- Se i metadati della sessione live sono scarsi, `/status` può recuperare i contatori + di token/cache e l’etichetta del modello runtime attivo dalla voce di utilizzo + più recente della trascrizione. I valori live esistenti diversi da zero hanno comunque la precedenza, e i totali della trascrizione dimensionati sul prompt possono prevalere quando i totali memorizzati mancano o sono inferiori. -**Footer dei costi per messaggio** +**Piè di pagina dei costi per messaggio** -- `/usage full` aggiunge un footer di utilizzo a ogni risposta, incluso il **costo stimato** (solo con chiave API). -- `/usage tokens` mostra solo i token; i flussi CLI e i flussi OAuth/token in stile abbonamento nascondono il costo in dollari. -- Nota su Gemini CLI: quando la CLI restituisce output JSON, OpenClaw legge l'utilizzo da - `stats`, normalizza `stats.cached` in `cacheRead` e ricava i token di input da - `stats.input_tokens - stats.cached` quando necessario. +- `/usage full` aggiunge un piè di pagina di utilizzo a ogni risposta, incluso il **costo stimato** (solo con chiave API). +- `/usage tokens` mostra solo i token; i flussi OAuth/token in stile abbonamento e CLI nascondono il costo in dollari. +- Nota su Gemini CLI: quando la CLI restituisce output JSON, OpenClaw legge l’utilizzo da + `stats`, normalizza `stats.cached` in `cacheRead` e ricava i token di input + da `stats.input_tokens - stats.cached` quando necessario. -Nota su Anthropic: il personale Anthropic ci ha detto che l'uso di Claude CLI in stile OpenClaw è -di nuovo 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. +Nota su Anthropic: il personale Anthropic ci ha detto che l’utilizzo di Claude CLI in stile OpenClaw è +di nuovo 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. Anthropic continua comunque a non esporre una stima in dollari per messaggio che OpenClaw possa mostrare in `/usage full`. -**Finestre di utilizzo CLI (quote provider)** +**Finestre di utilizzo della CLI (quote provider)** -- `openclaw status --usage` e `openclaw channels list` mostrano le **finestre di utilizzo** del provider - (snapshot delle quote, non costi per messaggio). -- L'output leggibile è normalizzato in `X% left` per tutti i provider. -- Provider attuali con finestre di utilizzo: Anthropic, GitHub Copilot, Gemini CLI, +- `openclaw status --usage` e `openclaw channels list` mostrano le **finestre di utilizzo** + del provider (snapshot delle quote, non costi per messaggio). +- L’output leggibile è normalizzato in `X% left` per tutti i provider. +- Provider attuali con finestra di utilizzo: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi e z.ai. - Nota su MiniMax: i suoi campi grezzi `usage_percent` / `usagePercent` indicano la - quota residua, quindi OpenClaw li inverte prima della visualizzazione. I campi basati sul conteggio - hanno comunque la precedenza quando presenti. Se il provider restituisce `model_remains`, OpenClaw preferisce la voce del modello chat, ricava l'etichetta della finestra dai timestamp quando necessario e - include il nome del modello nell'etichetta del piano. -- L'autenticazione di utilizzo per quelle finestre di quota proviene da hook specifici del provider quando - disponibili; altrimenti OpenClaw usa come fallback le credenziali OAuth/chiave API corrispondenti da profili auth, env o configurazione. + quota rimanente, quindi OpenClaw li inverte prima della visualizzazione. I campi basati sul conteggio hanno comunque la precedenza + quando presenti. Se il provider restituisce `model_remains`, OpenClaw preferisce la voce del modello di chat, ricava l’etichetta della finestra dai timestamp quando necessario e + include il nome del modello nell’etichetta del piano. +- L’autenticazione di utilizzo per queste finestre di quota proviene da hook specifici del provider quando + disponibili; in caso contrario, OpenClaw usa come fallback la corrispondenza delle + credenziali OAuth/chiave API dai profili di autenticazione, dall’ambiente o dalla configurazione. -Vedi [Token use & costs](/it/reference/token-use) per dettagli ed esempi. +Consulta [Uso dei token e costi](/it/reference/token-use) per dettagli ed esempi. -## Come vengono rilevate le chiavi +## Come vengono individuate le chiavi OpenClaw può rilevare le credenziali da: -- **Profili auth** (per agente, memorizzati in `auth-profiles.json`). -- **Variabili d'ambiente** (ad esempio `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`). +- **Profili di autenticazione** (per agente, memorizzati in `auth-profiles.json`). +- **Variabili d’ambiente** (ad es. `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`). - **Configurazione** (`models.providers.*.apiKey`, `plugins.entries.*.config.webSearch.apiKey`, `plugins.entries.firecrawl.config.webFetch.apiKey`, `memorySearch.*`, `talk.providers.*.apiKey`). -- **Skills** (`skills.entries..apiKey`) che possono esportare chiavi nell'env del processo della skill. +- **Skills** (`skills.entries..apiKey`) che possono esportare chiavi nell’ambiente del processo della skill. ## Funzionalità che possono consumare chiavi ### 1) Risposte del modello core (chat + strumenti) -Ogni risposta o chiamata a uno strumento usa il **provider del modello corrente** (OpenAI, Anthropic, ecc.). Questa è la -fonte principale di utilizzo e costo. +Ogni risposta o chiamata di strumento usa il **provider del modello corrente** (OpenAI, Anthropic, ecc.). Questa è la +fonte primaria di utilizzo e costo. -Questo include anche provider ospitati in stile abbonamento che continuano comunque a fatturare al di fuori della -UI locale di OpenClaw, come **OpenAI Codex**, **Alibaba Cloud Model Studio +Questo include anche i provider ospitati in stile abbonamento che continuano a fatturare al di fuori +dell’interfaccia locale di OpenClaw, come **OpenAI Codex**, **Alibaba Cloud Model Studio Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** e -il percorso Claude-login di Anthropic in OpenClaw con **Extra Usage** abilitato. +il percorso di login Claude di OpenClaw di Anthropic con **Extra Usage** abilitato. -Vedi [Models](/it/providers/models) per la configurazione dei prezzi e [Token use & costs](/it/reference/token-use) per la visualizzazione. +Consulta [Modelli](/it/providers/models) per la configurazione dei prezzi e [Uso dei token e costi](/it/reference/token-use) per la visualizzazione. -### 2) Comprensione dei media (audio/immagine/video) +### 2) Comprensione dei contenuti multimediali (audio/immagine/video) -I media in ingresso possono essere riepilogati/trascritti prima dell'esecuzione della risposta. Questo usa API di modelli/provider. +I contenuti multimediali in ingresso possono essere riassunti/trascritti prima che venga eseguita la risposta. Questo usa API di modelli/provider. - Audio: OpenAI / Groq / Deepgram / Google / Mistral. - Immagine: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI. - Video: Google / Qwen / Moonshot. -Vedi [Media understanding](/it/nodes/media-understanding). +Consulta [Comprensione dei contenuti multimediali](/it/nodes/media-understanding). ### 3) Generazione di immagini e video -Anche le capacità condivise di generazione possono consumare chiavi dei provider: +Le funzionalità di generazione condivise possono anch’esse consumare chiavi provider: - Generazione di immagini: OpenAI / Google / fal / MiniMax -- Generazione video: Qwen +- Generazione di video: Qwen La generazione di immagini può dedurre un provider predefinito supportato da autenticazione quando -`agents.defaults.imageGenerationModel` non è impostato. La generazione video al momento -richiede un `agents.defaults.videoGenerationModel` esplicito come +`agents.defaults.imageGenerationModel` non è impostato. La generazione di video attualmente +richiede un valore esplicito per `agents.defaults.videoGenerationModel`, ad esempio `qwen/wan2.6-t2v`. -Vedi [Image generation](/it/tools/image-generation), [Qwen Cloud](/it/providers/qwen), -e [Models](/it/concepts/models). +Consulta [Generazione di immagini](/it/tools/image-generation), [Qwen Cloud](/it/providers/qwen) +e [Modelli](/it/concepts/models). ### 4) Embedding della memoria + ricerca semantica @@ -118,84 +118,85 @@ La ricerca semantica nella memoria usa **API di embedding** quando è configurat - `memorySearch.provider = "gemini"` → embedding Gemini - `memorySearch.provider = "voyage"` → embedding Voyage - `memorySearch.provider = "mistral"` → embedding Mistral +- `memorySearch.provider = "lmstudio"` → embedding LM Studio (locale/self-hosted) - `memorySearch.provider = "ollama"` → embedding Ollama (locale/self-hosted; in genere senza fatturazione API ospitata) -- Fallback facoltativo a un provider remoto se gli embedding locali falliscono +- Fallback opzionale a un provider remoto se gli embedding locali falliscono -Puoi mantenerla locale con `memorySearch.provider = "local"` (nessun utilizzo API). +Puoi mantenerlo locale con `memorySearch.provider = "local"` (nessun utilizzo API). -Vedi [Memory](/it/concepts/memory). +Consulta [Memoria](/it/concepts/memory). ### 5) Strumento di ricerca web `web_search` può comportare costi di utilizzo a seconda del provider: -- **Brave Search API**: `BRAVE_API_KEY` oppure `plugins.entries.brave.config.webSearch.apiKey` -- **Exa**: `EXA_API_KEY` oppure `plugins.entries.exa.config.webSearch.apiKey` -- **Firecrawl**: `FIRECRAWL_API_KEY` oppure `plugins.entries.firecrawl.config.webSearch.apiKey` -- **Gemini (Google Search)**: `GEMINI_API_KEY` oppure `plugins.entries.google.config.webSearch.apiKey` -- **Grok (xAI)**: `XAI_API_KEY` oppure `plugins.entries.xai.config.webSearch.apiKey` -- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY` oppure `plugins.entries.moonshot.config.webSearch.apiKey` -- **MiniMax Search**: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_API_KEY` oppure `plugins.entries.minimax.config.webSearch.apiKey` -- **Ollama Web Search**: senza chiave per impostazione predefinita, ma richiede un host Ollama raggiungibile più `ollama signin`; può anche riutilizzare la normale autenticazione bearer del provider Ollama quando l'host la richiede -- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY` oppure `plugins.entries.perplexity.config.webSearch.apiKey` -- **Tavily**: `TAVILY_API_KEY` oppure `plugins.entries.tavily.config.webSearch.apiKey` +- **Brave Search API**: `BRAVE_API_KEY` o `plugins.entries.brave.config.webSearch.apiKey` +- **Exa**: `EXA_API_KEY` o `plugins.entries.exa.config.webSearch.apiKey` +- **Firecrawl**: `FIRECRAWL_API_KEY` o `plugins.entries.firecrawl.config.webSearch.apiKey` +- **Gemini (Google Search)**: `GEMINI_API_KEY` o `plugins.entries.google.config.webSearch.apiKey` +- **Grok (xAI)**: `XAI_API_KEY` o `plugins.entries.xai.config.webSearch.apiKey` +- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY` o `plugins.entries.moonshot.config.webSearch.apiKey` +- **MiniMax Search**: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_API_KEY` o `plugins.entries.minimax.config.webSearch.apiKey` +- **Ollama Web Search**: senza chiave per impostazione predefinita, ma richiede un host Ollama raggiungibile più `ollama signin`; può anche riutilizzare la normale autenticazione bearer del provider Ollama quando l’host la richiede +- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY` o `plugins.entries.perplexity.config.webSearch.apiKey` +- **Tavily**: `TAVILY_API_KEY` o `plugins.entries.tavily.config.webSearch.apiKey` - **DuckDuckGo**: fallback senza chiave (nessuna fatturazione API, ma non ufficiale e basato su HTML) -- **SearXNG**: `SEARXNG_BASE_URL` oppure `plugins.entries.searxng.config.webSearch.baseUrl` (senza chiave/self-hosted; nessuna fatturazione API ospitata) +- **SearXNG**: `SEARXNG_BASE_URL` o `plugins.entries.searxng.config.webSearch.baseUrl` (senza chiave/self-hosted; nessuna fatturazione API ospitata) -I percorsi legacy del provider `tools.web.search.*` vengono ancora caricati tramite lo shim temporaneo di compatibilità, ma non sono più la superficie di configurazione consigliata. +I percorsi provider legacy `tools.web.search.*` vengono ancora caricati tramite lo shim di compatibilità temporaneo, ma non sono più la superficie di configurazione consigliata. -**Credito gratuito Brave Search:** ogni piano Brave include \$5/mese di credito -gratuito rinnovabile. Il piano Search costa \$5 ogni 1.000 richieste, quindi il credito copre -1.000 richieste/mese senza costi. Imposta il tuo limite di utilizzo nella dashboard Brave +**Credito gratuito Brave Search:** ogni piano Brave include 5 $/mese di credito gratuito +rinnovabile. Il piano Search costa 5 $ ogni 1.000 richieste, quindi il credito copre +1.000 richieste/mese senza addebito. Imposta il tuo limite di utilizzo nella dashboard Brave per evitare addebiti imprevisti. -Vedi [Web tools](/it/tools/web). +Consulta [Strumenti web](/it/tools/web). -### 5) Strumento di web fetch (Firecrawl) +### 5) Strumento di recupero web (Firecrawl) `web_fetch` può chiamare **Firecrawl** quando è presente una chiave API: -- `FIRECRAWL_API_KEY` oppure `plugins.entries.firecrawl.config.webFetch.apiKey` +- `FIRECRAWL_API_KEY` o `plugins.entries.firecrawl.config.webFetch.apiKey` -Se Firecrawl non è configurato, lo strumento usa come fallback fetch diretto + readability (nessuna API a pagamento). +Se Firecrawl non è configurato, lo strumento usa come fallback il recupero diretto + readability (nessuna API a pagamento). -Vedi [Web tools](/it/tools/web). +Consulta [Strumenti web](/it/tools/web). -### 6) Snapshot di utilizzo del provider (status/health) +### 6) Snapshot di utilizzo del provider (stato/salute) -Alcuni comandi di stato chiamano **endpoint di utilizzo del provider** per mostrare finestre di quota o stato auth. -Di solito sono chiamate a basso volume, ma colpiscono comunque le API del provider: +Alcuni comandi di stato chiamano gli **endpoint di utilizzo del provider** per visualizzare finestre di quota o stato di salute dell’autenticazione. +Si tratta in genere di chiamate a basso volume, ma colpiscono comunque le API del provider: - `openclaw status --usage` - `openclaw models status --json` -Vedi [Models CLI](/cli/models). +Consulta [CLI dei modelli](/cli/models). -### 7) Riepilogo di salvaguardia della compattazione +### 7) Riassunto di salvaguardia della Compaction -La salvaguardia della compattazione può riepilogare la cronologia della sessione usando il **modello corrente**, il che +La salvaguardia della Compaction può riassumere la cronologia della sessione usando il **modello corrente**, che invoca API del provider quando viene eseguita. -Vedi [Session management + compaction](/it/reference/session-management-compaction). +Consulta [Gestione della sessione + compaction](/it/reference/session-management-compaction). ### 8) Scansione / probe dei modelli -`openclaw models scan` può eseguire probe sui modelli OpenRouter e usa `OPENROUTER_API_KEY` quando +`openclaw models scan` può sondare i modelli OpenRouter e usa `OPENROUTER_API_KEY` quando il probing è abilitato. -Vedi [Models CLI](/cli/models). +Consulta [CLI dei modelli](/cli/models). ### 9) Talk (voce) La modalità Talk può invocare **ElevenLabs** quando configurata: -- `ELEVENLABS_API_KEY` oppure `talk.providers.elevenlabs.apiKey` +- `ELEVENLABS_API_KEY` o `talk.providers.elevenlabs.apiKey` -Vedi [Talk mode](/it/nodes/talk). +Consulta [Modalità Talk](/it/nodes/talk). ### 10) Skills (API di terze parti) -Le Skills possono memorizzare `apiKey` in `skills.entries..apiKey`. Se una skill usa quella chiave per API esterne, -può generare costi secondo il provider della skill. +Le Skills possono memorizzare `apiKey` in `skills.entries..apiKey`. Se una skill usa tale chiave per API esterne, +può comportare costi in base al provider della skill. -Vedi [Skills](/it/tools/skills). +Consulta [Skills](/it/tools/skills).