From ec28b59a53b6c446ea60b7ab1a54ab708b336de8 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 08:28:31 +0000 Subject: [PATCH] chore(i18n): refresh it translations --- docs/it/ci.md | 93 +- docs/it/concepts/typing-indicators.md | 30 +- docs/it/gateway/cli-backends.md | 148 +- docs/it/gateway/configuration-reference.md | 1500 ++++++++++---------- docs/it/gateway/heartbeat.md | 271 ++-- docs/it/plugins/building-plugins.md | 160 ++- docs/it/plugins/codex-harness.md | 202 +-- docs/it/plugins/manifest.md | 608 ++++---- docs/it/plugins/sdk-agent-harness.md | 174 ++- docs/it/plugins/sdk-channel-plugins.md | 387 ++--- docs/it/plugins/sdk-overview.md | 607 ++++---- docs/it/providers/ollama.md | 136 +- docs/it/providers/tencent.md | 64 + docs/it/tools/index.md | 153 +- docs/it/tools/tokenjuice.md | 79 ++ 15 files changed, 2425 insertions(+), 2187 deletions(-) create mode 100644 docs/it/providers/tencent.md create mode 100644 docs/it/tools/tokenjuice.md diff --git a/docs/it/ci.md b/docs/it/ci.md index 75ba348d4..d4e5dc7e0 100644 --- a/docs/it/ci.md +++ b/docs/it/ci.md @@ -1,81 +1,82 @@ --- read_when: - - Hai bisogno di capire perché un job CI è stato o non è stato eseguito + - Devi capire perché un job CI è stato eseguito oppure no - Stai eseguendo il debug di controlli GitHub Actions non riusciti -summary: Grafo dei job CI, controlli di ambito ed equivalenti dei comandi locali +summary: Grafico dei job CI, gate di ambito e comandi locali equivalenti title: Pipeline CI x-i18n: - generated_at: "2026-04-22T04:21:29Z" + generated_at: "2026-04-22T08:20:01Z" model: gpt-5.4 provider: openai - source_hash: ae08bad6cbd0f2eced6c88a792a11bc1c2b1a2bfb003a56f70ff328a2739d3fc + source_hash: fc7ec59123aee65634736320dbf1cf5cdfb08786a78cca82ce9596fedc68b3cc source_path: ci.md workflow: 15 --- # Pipeline CI -La CI viene eseguita a ogni push su `main` e a ogni pull request. Usa uno scoping intelligente per saltare i job costosi quando sono cambiate solo aree non correlate. +La CI viene eseguita a ogni push su `main` e per ogni pull request. Usa uno scoping intelligente per saltare i job costosi quando sono cambiate solo aree non correlate. ## Panoramica dei job -| Job | Scopo | Quando viene eseguito | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Rilevare modifiche solo docs, ambiti cambiati, estensioni cambiate e costruire il manifest CI | Sempre su push e PR non draft | -| `security-scm-fast` | Rilevamento di chiavi private e audit dei workflow tramite `zizmor` | Sempre su push e PR non draft | -| `security-dependency-audit` | Audit del lockfile di produzione senza dipendenze rispetto agli advisory npm | Sempre su push e PR non draft | -| `security-fast` | Aggregato richiesto per i job di sicurezza rapidi | Sempre su push e PR non draft | -| `build-artifacts` | Costruire `dist/` e la Control UI una volta, caricare artifact riutilizzabili per i job downstream | Modifiche rilevanti per Node | -| `checks-fast-core` | Lane rapidi di correttezza Linux come controlli bundled/plugin-contract/protocol | Modifiche rilevanti per Node | -| `checks-fast-contracts-channels` | Controlli sharded dei contratti dei canali con un risultato di controllo aggregato stabile | Modifiche rilevanti per Node | -| `checks-node-extensions` | Shard completi di test dei Plugin inclusi nell'intera suite delle estensioni | Modifiche rilevanti per Node | -| `checks-node-core-test` | Shard dei test core Node, esclusi canali, bundle, contratti e lane delle estensioni | Modifiche rilevanti per Node | -| `extension-fast` | Test mirati solo per i Plugin inclusi modificati | Quando vengono rilevate modifiche alle estensioni | -| `check` | Equivalente principale locale sharded: tipi prod, lint, guardie, tipi test e smoke rigoroso | Modifiche rilevanti per Node | -| `check-additional` | Shard di architettura, confini, guardie della superficie delle estensioni, confini di pacchetto e gateway-watch | Modifiche rilevanti per Node | -| `build-smoke` | Smoke test della CLI buildata e smoke della memoria all'avvio | Modifiche rilevanti per Node | -| `checks` | Restanti lane Linux Node: test dei canali e compatibilità Node 22 solo per push | Modifiche rilevanti per Node | -| `check-docs` | Formattazione docs, lint e controlli dei link rotti | Docs modificate | -| `skills-python` | Ruff + pytest per Skills supportate da Python | Modifiche rilevanti per Skills Python | -| `checks-windows` | Lane di test specifici per Windows | Modifiche rilevanti per Windows | -| `macos-node` | Lane di test TypeScript su macOS usando gli artifact buildati condivisi | Modifiche rilevanti per macOS | -| `macos-swift` | Lint, build e test Swift per l'app macOS | Modifiche rilevanti per macOS | -| `android` | Matrice di build e test Android | Modifiche rilevanti per Android | +| Job | Scopo | Quando viene eseguito | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | +| `preflight` | Rilevare modifiche solo alla documentazione, ambiti modificati, estensioni modificate e costruire il manifest CI | Sempre su push e PR non draft | +| `security-scm-fast` | Rilevamento di chiavi private e audit dei workflow tramite `zizmor` | Sempre su push e PR non draft | +| `security-dependency-audit` | Audit del lockfile di produzione senza dipendenze rispetto agli avvisi npm | Sempre su push e PR non draft | +| `security-fast` | Aggregato richiesto per i job di sicurezza rapidi | Sempre su push e PR non draft | +| `build-artifacts` | Costruire `dist/` e la Control UI una volta, caricare artifact riutilizzabili per i job downstream | Modifiche rilevanti per Node | +| `checks-fast-core` | Lane di correttezza Linux rapide come controlli bundled/plugin-contract/protocol | Modifiche rilevanti per Node | +| `checks-fast-contracts-channels` | Controlli shardati dei contratti dei canali con un risultato di controllo aggregato stabile | Modifiche rilevanti per Node | +| `checks-node-extensions` | Shard completi dei test dei plugin bundled sull'intera suite delle estensioni | Modifiche rilevanti per Node | +| `checks-node-core-test` | Shard dei test core Node, esclusi canali, bundled, contratti e lane delle estensioni | Modifiche rilevanti per Node | +| `extension-fast` | Test mirati solo per i plugin bundled modificati | Quando vengono rilevate modifiche alle estensioni | +| `check` | Equivalente locale principale shardato: tipi prod, lint, guard, tipi di test e smoke rigoroso | Modifiche rilevanti per Node | +| `check-additional` | Guard di architettura, boundary, superficie delle estensioni, boundary dei package e shard gateway-watch | Modifiche rilevanti per Node | +| `build-smoke` | Smoke test della CLI buildata e smoke sulla memoria all'avvio | Modifiche rilevanti per Node | +| `checks` | Lane Linux Node rimanenti: test dei canali e compatibilità Node 22 solo su push | Modifiche rilevanti per Node | +| `check-docs` | Formattazione docs, lint e controlli dei link rotti | Documentazione modificata | +| `skills-python` | Ruff + pytest per le Skills supportate da Python | Modifiche rilevanti per Skills Python | +| `checks-windows` | Lane di test specifiche per Windows | Modifiche rilevanti per Windows | +| `macos-node` | Lane di test TypeScript su macOS che usa gli artifact buildati condivisi | Modifiche rilevanti per macOS | +| `macos-swift` | Lint, build e test Swift per l'app macOS | Modifiche rilevanti per macOS | +| `android` | Matrice di build e test Android | Modifiche rilevanti per Android | ## Ordine fail-fast -I job sono ordinati in modo che i controlli economici falliscano prima che partano quelli costosi: +I job sono ordinati in modo che i controlli economici falliscano prima che vengano eseguiti quelli costosi: -1. `preflight` decide quali lane esistono davvero. La logica `docs-scope` e `changed-scope` è composta da step interni a questo job, non da job autonomi. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falliscono rapidamente senza attendere i job più pesanti della matrice artifact e piattaforme. -3. `build-artifacts` si sovrappone ai lane Linux rapidi così i consumer downstream possono partire non appena la build condivisa è pronta. -4. Dopo si diramano i lane più pesanti di piattaforma e runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. +1. `preflight` decide quali lane esistono del tutto. La logica `docs-scope` e `changed-scope` sono step all'interno di questo job, non job separati. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falliscono rapidamente senza aspettare i job più pesanti della matrice artifact e piattaforme. +3. `build-artifacts` si sovrappone alle lane Linux rapide così i consumer downstream possono iniziare non appena la build condivisa è pronta. +4. Dopo si aprono a ventaglio le lane più pesanti di piattaforma e runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. La logica di ambito si trova in `scripts/ci-changed-scope.mjs` ed è coperta da unit test in `src/scripts/ci-changed-scope.test.ts`. -Il workflow separato `install-smoke` riusa lo stesso script di ambito tramite il proprio job `preflight`. Calcola `run_install_smoke` a partire dal segnale changed-smoke più ristretto, quindi lo smoke Docker/install viene eseguito solo per modifiche rilevanti per installazione, packaging e container. +Il workflow separato `install-smoke` riusa lo stesso script di ambito tramite il proprio job `preflight`. Calcola `run_install_smoke` dal segnale changed-smoke più ristretto, quindi lo smoke Docker/install viene eseguito solo per modifiche rilevanti per installazione, packaging e container. -La logica locale dei lane modificati si trova in `scripts/changed-lanes.mjs` ed è eseguita da `scripts/check-changed.mjs`. Questo gate locale è più rigoroso sui confini architetturali rispetto all'ampio ambito di piattaforma della CI: le modifiche di produzione al core eseguono typecheck prod del core più test del core, le modifiche solo ai test del core eseguono solo typecheck/test del core, le modifiche di produzione alle estensioni eseguono typecheck prod delle estensioni più test delle estensioni, e le modifiche solo ai test delle estensioni eseguono solo typecheck/test delle estensioni. Le modifiche al Plugin SDK pubblico o ai contratti dei Plugin estendono la validazione alle estensioni perché queste dipendono da quei contratti core. Gli incrementi di versione che toccano solo metadati di release eseguono controlli mirati su versione/configurazione/dipendenze root. Le modifiche sconosciute a root/configurazione vanno in fail-safe su tutti i lane. +La logica locale delle lane modificate si trova in `scripts/changed-lanes.mjs` ed è eseguita da `scripts/check-changed.mjs`. Questo gate locale è più rigoroso sui boundary architetturali rispetto all'ampio ambito di piattaforma della CI: le modifiche di produzione core eseguono typecheck core prod più test core, le modifiche solo ai test core eseguono solo typecheck/test core, le modifiche di produzione delle estensioni eseguono typecheck prod delle estensioni più test delle estensioni, e le modifiche solo ai test delle estensioni eseguono solo typecheck/test delle estensioni. Le modifiche al Plugin SDK pubblico o al plugin-contract estendono la validazione alle estensioni perché le estensioni dipendono da questi contratti core. I version bump solo nei metadati di release eseguono controlli mirati su versione/config/dipendenze root. Modifiche sconosciute a root/config fanno fail-safe verso tutte le lane. -Sui push, la matrice `checks` aggiunge il lane `compat-node22`, eseguito solo sui push. Sulle pull request, quel lane viene saltato e la matrice resta concentrata sui normali lane di test/canali. +Sui push, la matrice `checks` aggiunge la lane `compat-node22` solo per push. Sulle pull request, quella lane viene saltata e la matrice resta focalizzata sulle normali lane di test/canali. -Le famiglie di test Node più lente sono divise in shard per file inclusi così ogni job resta piccolo: i contratti dei canali dividono la copertura registry e core in otto shard pesati ciascuno, i test del comando di risposta auto-reply si dividono in quattro shard per pattern di inclusione, e gli altri grandi gruppi di prefissi di risposta auto-reply si dividono in due shard ciascuno. Anche `check-additional` separa il lavoro di compilazione/canary dei confini di pacchetto dal lavoro di topologia runtime su gateway/architettura. +Le famiglie di test Node più lente sono suddivise in shard per file inclusi così ogni job resta piccolo: i contratti dei canali dividono la copertura registry e core in otto shard pesati ciascuno, i test del comando reply di auto-reply si dividono in quattro shard per pattern inclusi, e gli altri grandi gruppi di prefissi reply di auto-reply si dividono in due shard ciascuno. Anche `check-additional` separa il lavoro di compile/canary dei boundary dei package dal lavoro di topologia runtime gateway/architettura. -GitHub può contrassegnare i job superati da esecuzioni più recenti come `cancelled` quando arriva un nuovo push sulla stessa PR o sullo stesso ref `main`. Trattalo come rumore CI a meno che anche l'esecuzione più recente per lo stesso ref non stia fallendo. I controlli aggregati degli shard evidenziano esplicitamente questo caso di cancellazione, così è più facile distinguerlo da un errore di test. +GitHub può contrassegnare i job sostituiti come `cancelled` quando arriva un push più recente sulla stessa PR o ref `main`. Consideralo rumore della CI a meno che anche l'esecuzione più recente per la stessa ref non stia fallendo. I controlli shard aggregati richiamano esplicitamente questo caso di cancellazione così è più facile distinguerlo da un fallimento di test. ## Runner -| Runner | Job | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, controlli Linux, controlli docs, Skills Python, `android` | -| `blacksmith-32vcpu-windows-2025` | `checks-windows` | -| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` su `openclaw/openclaw`; i fork tornano a `macos-latest` | +| Runner | Job | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`; anche il preflight di install-smoke usa Ubuntu ospitato da GitHub così la matrice Blacksmith può mettersi in coda prima | +| `blacksmith-16vcpu-ubuntu-2404` | `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, controlli Linux, controlli docs, Skills Python, `android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` su `openclaw/openclaw`; i fork ripiegano su `macos-latest` | ## Equivalenti locali ```bash -pnpm changed:lanes # ispeziona il classificatore locale dei lane modificati per origin/main...HEAD -pnpm check:changed # gate locale intelligente: typecheck/lint/test modificati per lane di confine -pnpm check # gate locale rapido: tsgo di produzione + lint sharded + guardie rapide in parallelo +pnpm changed:lanes # ispeziona il classificatore locale delle lane modificate per origin/main...HEAD +pnpm check:changed # gate locale intelligente: typecheck/lint/test modificati per lane di boundary +pnpm check # gate locale rapido: tsgo di produzione + lint shardato + guard rapidi in parallelo pnpm check:test-types pnpm check:timed # stesso gate con tempi per fase pnpm build:strict-smoke @@ -85,5 +86,5 @@ pnpm test # test vitest pnpm test:channels pnpm test:contracts:channels pnpm check:docs # formato docs + lint + link rotti -pnpm build # build di dist quando contano i lane CI artifact/build-smoke +pnpm build # build di dist quando sono rilevanti le lane CI artifact/build-smoke ``` diff --git a/docs/it/concepts/typing-indicators.md b/docs/it/concepts/typing-indicators.md index 376d4d9c3..4dc1d4d77 100644 --- a/docs/it/concepts/typing-indicators.md +++ b/docs/it/concepts/typing-indicators.md @@ -1,22 +1,22 @@ --- read_when: - - Modifica del comportamento o dei valori predefiniti degli indicatori di digitazione + - Modifica del comportamento o dei valori predefiniti dell’indicatore di digitazione summary: Quando OpenClaw mostra gli indicatori di digitazione e come configurarli title: Indicatori di digitazione x-i18n: - generated_at: "2026-04-05T13:50:54Z" + generated_at: "2026-04-22T08:19:59Z" model: gpt-5.4 provider: openai - source_hash: 28c8c395a135fc0745181aab66a93582177e6acd0b3496debcbb98159a4f11dc + source_hash: 2e7e8ca448b6706b6f53fcb6a582be6d4a84715c82dfde3d53abe4268af3ae0d source_path: concepts/typing-indicators.md workflow: 15 --- # Indicatori di digitazione -Gli indicatori di digitazione vengono inviati al canale della chat mentre un'esecuzione è attiva. Usa +Gli indicatori di digitazione vengono inviati al canale di chat mentre un’esecuzione è attiva. Usa `agents.defaults.typingMode` per controllare **quando** inizia la digitazione e `typingIntervalSeconds` -per controllare **quanto spesso** viene aggiornata. +per controllare **con quale frequenza** viene aggiornata. ## Valori predefiniti @@ -25,17 +25,17 @@ Quando `agents.defaults.typingMode` è **non impostato**, OpenClaw mantiene il c - **Chat dirette**: la digitazione inizia immediatamente non appena comincia il loop del modello. - **Chat di gruppo con una menzione**: la digitazione inizia immediatamente. - **Chat di gruppo senza una menzione**: la digitazione inizia solo quando il testo del messaggio comincia a essere trasmesso in streaming. -- **Esecuzioni heartbeat**: la digitazione è disabilitata. +- **Esecuzioni Heartbeat**: la digitazione inizia quando l’esecuzione Heartbeat comincia se la destinazione Heartbeat risolta è una chat che supporta la digitazione e la digitazione non è disabilitata. ## Modalità -Imposta `agents.defaults.typingMode` su uno dei seguenti valori: +Imposta `agents.defaults.typingMode` su uno di questi valori: - `never` — nessun indicatore di digitazione, mai. -- `instant` — avvia la digitazione **non appena inizia il loop del modello**, anche se l'esecuzione +- `instant` — avvia la digitazione **non appena inizia il loop del modello**, anche se l’esecuzione in seguito restituisce solo il token di risposta silenziosa. - `thinking` — avvia la digitazione al **primo delta di ragionamento** (richiede - `reasoningLevel: "stream"` per l'esecuzione). + `reasoningLevel: "stream"` per l’esecuzione). - `message` — avvia la digitazione al **primo delta di testo non silenzioso** (ignora il token silenzioso `NO_REPLY`). @@ -66,11 +66,15 @@ Puoi sovrascrivere modalità o frequenza per sessione: ## Note -- La modalità `message` non mostrerà la digitazione per risposte solo silenziose quando l'intero - payload corrisponde esattamente al token silenzioso (ad esempio `NO_REPLY` / `no_reply`, +- La modalità `message` non mostrerà la digitazione per risposte solo silenziose quando l’intero + payload è esattamente il token silenzioso (per esempio `NO_REPLY` / `no_reply`, con corrispondenza case-insensitive). -- `thinking` si attiva solo se l'esecuzione trasmette in streaming il ragionamento (`reasoningLevel: "stream"`). +- `thinking` si attiva solo se l’esecuzione trasmette in streaming il ragionamento (`reasoningLevel: "stream"`). Se il modello non emette delta di ragionamento, la digitazione non inizierà. -- Gli heartbeat non mostrano mai la digitazione, indipendentemente dalla modalità. +- La digitazione Heartbeat è un segnale di attività per la destinazione di consegna risolta. Si + avvia all’inizio dell’esecuzione Heartbeat invece di seguire la tempistica di streaming di `message` o `thinking`. Imposta `typingMode: "never"` per disabilitarla. +- Gli Heartbeat non mostrano la digitazione quando `target: "none"`, quando la destinazione non può + essere risolta, quando la consegna in chat è disabilitata per l’Heartbeat o quando il + canale non supporta la digitazione. - `typingIntervalSeconds` controlla la **frequenza di aggiornamento**, non il momento di avvio. Il valore predefinito è 6 secondi. diff --git a/docs/it/gateway/cli-backends.md b/docs/it/gateway/cli-backends.md index 9bf0a1b41..a52460101 100644 --- a/docs/it/gateway/cli-backends.md +++ b/docs/it/gateway/cli-backends.md @@ -3,13 +3,13 @@ read_when: - Vuoi un fallback affidabile quando i provider API falliscono - Stai eseguendo Codex CLI o altre CLI AI locali e vuoi riutilizzarle - Vuoi comprendere il bridge local loopback MCP per l'accesso agli strumenti del backend CLI -summary: 'Backend CLI: fallback CLI AI locale con bridge di strumenti MCP opzionale' +summary: 'Backend CLI: fallback CLI AI locale con bridge opzionale per strumenti MCP' title: Backend CLI x-i18n: - generated_at: "2026-04-16T19:30:59Z" + generated_at: "2026-04-22T08:20:02Z" model: gpt-5.4 provider: openai - source_hash: 381273532a8622bc4628000a6fb999712b12af08faade2b5f2b7ac4cc7d23efe + source_hash: 3566d4f2b7a841473a4ed6379c1abd8dbd06c392dbff15ca37c4f8ea1e1ead51 source_path: gateway/cli-backends.md workflow: 15 --- @@ -17,20 +17,20 @@ x-i18n: # Backend CLI (runtime di fallback) OpenClaw può eseguire **CLI AI locali** come **fallback solo testo** quando i provider API non sono disponibili, -soggetti a limitazioni di frequenza o temporaneamente malfunzionanti. Si tratta intenzionalmente di un approccio conservativo: +sono soggetti a rate limit o si comportano temporaneamente in modo anomalo. Si tratta intenzionalmente di un approccio conservativo: -- **Gli strumenti di OpenClaw non vengono iniettati direttamente**, ma i backend con `bundleMcp: true` +- **Gli strumenti OpenClaw non vengono iniettati direttamente**, ma i backend con `bundleMcp: true` possono ricevere gli strumenti del gateway tramite un bridge MCP loopback. - **Streaming JSONL** per le CLI che lo supportano. - **Le sessioni sono supportate** (così i turni successivi restano coerenti). -- **Le immagini possono essere passate** se la CLI accetta percorsi di immagini. +- **Le immagini possono essere inoltrate** se la CLI accetta percorsi di immagini. -Questo è progettato come una **rete di sicurezza** piuttosto che come percorso principale. Usalo quando +Questo è progettato come **rete di sicurezza** piuttosto che come percorso principale. Usalo quando vuoi risposte testuali “sempre funzionanti” senza dipendere da API esterne. Se vuoi un runtime harness completo con controlli di sessione ACP, attività in background, -binding thread/conversazione e sessioni di coding esterne persistenti, usa -[Agenti ACP](/it/tools/acp-agents) invece. I backend CLI non sono ACP. +associazione thread/conversazione e sessioni di coding esterne persistenti, usa invece +[ACP Agents](/it/tools/acp-agents). I backend CLI non sono ACP. ## Guida rapida per principianti @@ -41,7 +41,7 @@ registra un backend predefinito): openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Se il tuo gateway viene eseguito sotto launchd/systemd e PATH è minimale, aggiungi solo il +Se il tuo gateway è eseguito tramite launchd/systemd e PATH è minimale, aggiungi solo il percorso del comando: ```json5 @@ -58,14 +58,14 @@ percorso del comando: } ``` -Questo è tutto. Nessuna chiave, nessuna configurazione di autenticazione aggiuntiva oltre alla CLI stessa. +È tutto. Nessuna chiave, nessuna configurazione di autenticazione aggiuntiva necessaria oltre alla CLI stessa. Se usi un backend CLI incluso come **provider di messaggi principale** su un host gateway, OpenClaw ora carica automaticamente il Plugin incluso proprietario quando la tua configurazione -fa riferimento esplicito a quel backend in un model ref o sotto +fa riferimento esplicito a quel backend in un riferimento modello oppure in `agents.defaults.cliBackends`. -## Utilizzo come fallback +## Usarlo come fallback Aggiungi un backend CLI al tuo elenco di fallback in modo che venga eseguito solo quando i modelli primari falliscono: @@ -89,19 +89,19 @@ Aggiungi un backend CLI al tuo elenco di fallback in modo che venga eseguito sol Note: - Se usi `agents.defaults.models` (allowlist), devi includere anche lì i modelli del tuo backend CLI. -- Se il provider primario fallisce (autenticazione, limiti di frequenza, timeout), OpenClaw - proverà quindi il backend CLI. +- Se il provider primario fallisce (autenticazione, rate limit, timeout), OpenClaw proverà + il backend CLI come passo successivo. ## Panoramica della configurazione -Tutti i backend CLI si trovano sotto: +Tutti i backend CLI si trovano in: ``` agents.defaults.cliBackends ``` Ogni voce è indicizzata da un **id provider** (ad esempio `codex-cli`, `my-cli`). -L'id provider diventa la parte sinistra del tuo model ref: +L'id provider diventa il lato sinistro del tuo riferimento modello: ``` / @@ -131,7 +131,7 @@ L'id provider diventa la parte sinistra del tuo model ref: sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // Le CLI in stile Codex possono invece puntare a un file di prompt: + // Le CLI in stile Codex possono invece puntare a un file prompt: // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -149,50 +149,54 @@ L'id provider diventa la parte sinistra del tuo model ref: 1. **Seleziona un backend** in base al prefisso del provider (`codex-cli/...`). 2. **Costruisce un prompt di sistema** usando lo stesso prompt OpenClaw + contesto workspace. -3. **Esegue la CLI** con un id sessione (se supportato) in modo che la cronologia resti coerente. +3. **Esegue la CLI** con un id sessione (se supportato) così la cronologia resta coerente. + Il backend `claude-cli` incluso mantiene attivo un processo Claude stdio per ogni + sessione OpenClaw e invia i turni successivi tramite stdin stream-json. 4. **Analizza l'output** (JSON o testo semplice) e restituisce il testo finale. 5. **Rende persistenti gli id sessione** per backend, così i follow-up riutilizzano la stessa sessione CLI. -Il backend Anthropic `claude-cli` incluso è di nuovo supportato. Lo staff Anthropic +Il backend `claude-cli` Anthropic incluso è di nuovo supportato. Lo staff Anthropic ci ha detto che l'uso di Claude CLI in stile OpenClaw è di nuovo consentito, quindi OpenClaw considera l'uso di `claude -p` approvato per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. -Il backend OpenAI `codex-cli` incluso passa il prompt di sistema di OpenClaw tramite +Il backend `codex-cli` OpenAI incluso passa il prompt di sistema di OpenClaw tramite l'override di configurazione `model_instructions_file` di Codex (`-c model_instructions_file="..."`). Codex non espone un flag in stile Claude `--append-system-prompt`, quindi OpenClaw scrive il prompt assemblato in un file temporaneo per ogni nuova sessione Codex CLI. -Il backend Anthropic `claude-cli` incluso riceve lo snapshot delle Skills di OpenClaw -in due modi: il catalogo compatto delle Skills di OpenClaw nel prompt di sistema aggiunto, e -un Plugin temporaneo di Claude Code passato con `--plugin-dir`. Il Plugin contiene -solo le Skills idonee per quell'agente/sessione, così il resolver nativo delle skill di Claude Code -vede lo stesso insieme filtrato che OpenClaw altrimenti pubblicizzerebbe nel -prompt. Le sostituzioni delle variabili d'ambiente/API key delle skill vengono comunque applicate da OpenClaw all'ambiente del processo figlio per l'esecuzione. +Il backend `claude-cli` Anthropic incluso riceve lo snapshot delle Skills OpenClaw +in due modi: il catalogo compatto delle Skills OpenClaw nel prompt di sistema aggiunto, e +un Plugin Claude Code temporaneo passato con `--plugin-dir`. Il Plugin contiene +solo le Skills idonee per quell'agente/sessione, quindi il resolver di Skills nativo di Claude Code vede +lo stesso insieme filtrato che OpenClaw altrimenti pubblicizzerebbe nel prompt. Gli override di env/chiavi API delle Skill vengono comunque applicati da OpenClaw all'ambiente del processo figlio per l'esecuzione. ## Sessioni - Se la CLI supporta le sessioni, imposta `sessionArg` (ad esempio `--session-id`) oppure - `sessionArgs` (segnaposto `{sessionId}`) quando l'ID deve essere inserito + `sessionArgs` (placeholder `{sessionId}`) quando l'ID deve essere inserito in più flag. - Se la CLI usa un **sottocomando di ripresa** con flag diversi, imposta - `resumeArgs` (sostituisce `args` quando si riprende) e facoltativamente `resumeOutput` + `resumeArgs` (sostituisce `args` durante la ripresa) e facoltativamente `resumeOutput` (per riprese non JSON). - `sessionMode`: - - `always`: invia sempre un id sessione (nuovo UUID se non ne è stato memorizzato nessuno). - - `existing`: invia un id sessione solo se era già stato memorizzato in precedenza. + - `always`: invia sempre un id sessione (nuovo UUID se non ne è memorizzato nessuno). + - `existing`: invia un id sessione solo se ne era già stato memorizzato uno. - `none`: non inviare mai un id sessione. +- Il backend `claude-cli` incluso usa `liveSession: "claude-stdio"` così + i turni successivi riutilizzano il processo Claude attivo finché è disponibile. Se il + Gateway si riavvia o il processo inattivo termina, OpenClaw riprende dall'id sessione Claude memorizzato. Note sulla serializzazione: -- `serialize: true` mantiene ordinate le esecuzioni nella stessa corsia. -- La maggior parte delle CLI serializza su una corsia provider. -- OpenClaw scarta il riutilizzo della sessione CLI memorizzata quando cambia lo stato di autenticazione del backend, incluso un nuovo login, la rotazione del token o una credenziale del profilo di autenticazione modificata. +- `serialize: true` mantiene ordinate le esecuzioni sulla stessa lane. +- La maggior parte delle CLI serializza su una lane provider. +- OpenClaw interrompe il riuso della sessione CLI memorizzata quando cambia lo stato di autenticazione del backend, inclusi nuovo login, rotazione del token o modifica delle credenziali del profilo di autenticazione. -## Immagini (pass-through) +## Immagini (inoltro) Se la tua CLI accetta percorsi di immagini, imposta `imageArg`: @@ -201,27 +205,27 @@ imageArg: "--image", imageMode: "repeat" ``` -OpenClaw scriverà le immagini base64 in file temporanei. Se `imageArg` è impostato, questi -percorsi vengono passati come argomenti CLI. Se `imageArg` manca, OpenClaw aggiunge -i percorsi dei file al prompt (iniezione di percorso), il che è sufficiente per le CLI che caricano automaticamente -file locali da semplici percorsi. +OpenClaw scriverà le immagini base64 in file temporanei. Se `imageArg` è impostato, tali +percorsi vengono passati come argomenti CLI. Se `imageArg` manca, OpenClaw aggiunge i +percorsi dei file al prompt (path injection), che è sufficiente per le CLI che caricano automaticamente +i file locali da percorsi semplici. ## Input / output - `output: "json"` (predefinito) prova ad analizzare JSON ed estrarre testo + id sessione. - Per l'output JSON di Gemini CLI, OpenClaw legge il testo della risposta da `response` e - l'uso da `stats` quando `usage` è mancante o vuoto. -- `output: "jsonl"` analizza stream JSONL (ad esempio Codex CLI `--json`) ed estrae il messaggio finale dell'agente più gli identificatori - di sessione quando presenti. + l'utilizzo da `stats` quando `usage` manca o è vuoto. +- `output: "jsonl"` analizza stream JSONL (per esempio Codex CLI `--json`) ed estrae il messaggio finale dell'agente più gli identificatori di sessione + quando presenti. - `output: "text"` tratta stdout come risposta finale. Modalità di input: - `input: "arg"` (predefinito) passa il prompt come ultimo argomento CLI. - `input: "stdin"` invia il prompt tramite stdin. -- Se il prompt è molto lungo e `maxPromptArgChars` è impostato, viene usato stdin. +- Se il prompt è molto lungo ed è impostato `maxPromptArgChars`, viene usato stdin. -## Valori predefiniti (posseduti dal Plugin) +## Valori predefiniti (gestiti dal Plugin) Il Plugin OpenAI incluso registra anche un valore predefinito per `codex-cli`: @@ -245,32 +249,32 @@ Il Plugin Google incluso registra anche un valore predefinito per `google-gemini - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -Prerequisito: Gemini CLI locale deve essere installata e disponibile come +Prerequisito: la Gemini CLI locale deve essere installata e disponibile come `gemini` su `PATH` (`brew install gemini-cli` oppure `npm install -g @google/gemini-cli`). Note sul JSON di Gemini CLI: - Il testo della risposta viene letto dal campo JSON `response`. -- L'uso ricade su `stats` quando `usage` è assente o vuoto. +- L'utilizzo usa `stats` come fallback quando `usage` è assente o vuoto. - `stats.cached` viene normalizzato in OpenClaw `cacheRead`. -- Se `stats.input` è mancante, OpenClaw ricava i token di input da +- Se `stats.input` manca, OpenClaw ricava i token di input da `stats.input_tokens - stats.cached`. -Sovrascrivi solo se necessario (caso comune: percorso `command` assoluto). +Esegui override solo se necessario (caso comune: percorso `command` assoluto). -## Valori predefiniti posseduti dal Plugin +## Valori predefiniti gestiti dal Plugin -I valori predefiniti del backend CLI fanno ora parte della superficie del Plugin: +I valori predefiniti del backend CLI fanno ora parte della surface del Plugin: - I Plugin li registrano con `api.registerCliBackend(...)`. -- L'`id` del backend diventa il prefisso provider nei model ref. +- L'`id` del backend diventa il prefisso provider nei riferimenti modello. - La configurazione utente in `agents.defaults.cliBackends.` continua a sovrascrivere il valore predefinito del Plugin. -- La pulizia della configurazione specifica del backend resta posseduta dal Plugin tramite l'hook - facoltativo `normalizeConfig`. +- La pulizia della configurazione specifica del backend resta gestita dal Plugin tramite l'hook facoltativo + `normalizeConfig`. -I Plugin che hanno bisogno di piccoli shim di compatibilità per prompt/messaggi possono dichiarare -trasformazioni di testo bidirezionali senza sostituire un provider o backend CLI: +I Plugin che necessitano di piccoli shim di compatibilità di prompt/messaggio possono dichiarare +trasformazioni di testo bidirezionali senza sostituire un provider o un backend CLI: ```typescript api.registerTextTransforms({ @@ -288,51 +292,51 @@ api.registerTextTransforms({ ``` `input` riscrive il prompt di sistema e il prompt utente passati alla CLI. `output` -riscrive i delta dell'assistente in streaming e il testo finale analizzato prima che OpenClaw gestisca -i propri marker di controllo e la consegna al canale. +riscrive i delta in streaming dell'assistente e il testo finale analizzato prima che OpenClaw gestisca +i propri marker di controllo e la consegna sul canale. Per le CLI che emettono JSONL compatibile con Claude Code stream-json, imposta `jsonlDialect: "claude-stream-json"` nella configurazione di quel backend. -## Overlay bundle MCP +## Overlay MCP del bundle -I backend CLI **non** ricevono direttamente chiamate agli strumenti di OpenClaw, ma un backend può +I backend CLI **non** ricevono direttamente chiamate agli strumenti OpenClaw, ma un backend può scegliere di usare un overlay di configurazione MCP generato con `bundleMcp: true`. Comportamento incluso attuale: - `claude-cli`: file di configurazione MCP strict generato - `codex-cli`: override di configurazione inline per `mcp_servers` -- `google-gemini-cli`: file di impostazioni di sistema Gemini generato +- `google-gemini-cli`: file impostazioni di sistema Gemini generato -Quando bundle MCP è abilitato, OpenClaw: +Quando il bundle MCP è abilitato, OpenClaw: -- avvia un server HTTP MCP loopback che espone gli strumenti del gateway al processo CLI +- avvia un server MCP HTTP loopback che espone gli strumenti del gateway al processo CLI - autentica il bridge con un token per sessione (`OPENCLAW_MCP_TOKEN`) -- limita l'accesso agli strumenti al contesto corrente di sessione, account e canale +- limita l'accesso agli strumenti al contesto di sessione, account e canale corrente - carica i server bundle-MCP abilitati per il workspace corrente -- li unisce con qualsiasi forma esistente di configurazione/impostazioni MCP del backend -- riscrive la configurazione di avvio usando la modalità di integrazione posseduta dal backend dall'estensione proprietaria +- li unisce con qualsiasi forma di configurazione/impostazioni MCP del backend già esistente +- riscrive la configurazione di avvio usando la modalità di integrazione gestita dal backend dell'estensione proprietaria Se non è abilitato alcun server MCP, OpenClaw inietta comunque una configurazione strict quando un -backend sceglie di usare bundle MCP, così le esecuzioni in background restano isolate. +backend sceglie di usare bundle MCP così le esecuzioni in background restano isolate. ## Limitazioni -- **Nessuna chiamata diretta agli strumenti di OpenClaw.** OpenClaw non inietta chiamate agli strumenti nel - protocollo del backend CLI. I backend vedono gli strumenti del gateway solo quando scelgono +- **Nessuna chiamata diretta agli strumenti OpenClaw.** OpenClaw non inietta chiamate agli strumenti nel + protocollo del backend CLI. I backend vedono gli strumenti del gateway solo quando scelgono di usare `bundleMcp: true`. -- **Lo streaming è specifico del backend.** Alcuni backend trasmettono JSONL in streaming; altri accumulano +- **Lo streaming è specifico del backend.** Alcuni backend eseguono streaming JSONL; altri effettuano buffering fino all'uscita. - **Gli output strutturati** dipendono dal formato JSON della CLI. -- **Le sessioni Codex CLI** riprendono tramite output testuale (nessun JSONL), che è meno - strutturato dell'esecuzione iniziale `--json`. Le sessioni OpenClaw continuano comunque a funzionare +- **Le sessioni Codex CLI** riprendono tramite output di testo (senza JSONL), che è meno + strutturato rispetto all'esecuzione iniziale con `--json`. Le sessioni OpenClaw continuano comunque a funzionare normalmente. ## Risoluzione dei problemi - **CLI non trovata**: imposta `command` su un percorso completo. -- **Nome del modello errato**: usa `modelAliases` per mappare `provider/model` → modello CLI. +- **Nome modello errato**: usa `modelAliases` per mappare `provider/model` → modello CLI. - **Nessuna continuità di sessione**: assicurati che `sessionArg` sia impostato e che `sessionMode` non sia `none` (attualmente Codex CLI non può riprendere con output JSON). - **Immagini ignorate**: imposta `imageArg` (e verifica che la CLI supporti i percorsi di file). diff --git a/docs/it/gateway/configuration-reference.md b/docs/it/gateway/configuration-reference.md index 3236b798c..2fc264d0c 100644 --- a/docs/it/gateway/configuration-reference.md +++ b/docs/it/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - Ti servono la semantica esatta a livello di campo o i valori predefiniti - - Stai convalidando blocchi di configurazione di canale, modello, Gateway o strumento -summary: Riferimento della configurazione del Gateway per le chiavi principali di OpenClaw, i valori predefiniti e i link ai riferimenti dedicati dei sottosistemi -title: Riferimento configurazione + - Hai bisogno di una semantica esatta della configurazione a livello di campo o dei valori predefiniti + - Stai convalidando blocchi di configurazione di canali, modelli, Gateway o strumenti +summary: Riferimento della configurazione del Gateway per le chiavi principali di OpenClaw, i valori predefiniti e i collegamenti ai riferimenti dedicati dei sottosistemi +title: Riferimento della configurazione x-i18n: - generated_at: "2026-04-22T04:22:26Z" + generated_at: "2026-04-22T08:20:03Z" model: gpt-5.4 provider: openai - source_hash: 0313f47079536b93385b4e9c7680a896098ac05dce4e368d389a33e31b4649ac + source_hash: f0d6fc076f54e84bef5beefbcc42d8f172cc79792c716f76103894303e3042ac source_path: gateway/configuration-reference.md workflow: 15 --- -# Riferimento configurazione +# Riferimento della configurazione -Riferimento della configurazione principale per `~/.openclaw/openclaw.json`. Per una panoramica orientata alle attività, vedi [Configurazione](/it/gateway/configuration). +Riferimento della configurazione principale per `~/.openclaw/openclaw.json`. Per una panoramica orientata alle attività, vedi [Configuration](/it/gateway/configuration). -Questa pagina copre le principali superfici di configurazione di OpenClaw e rimanda ad altri riferimenti quando un sottosistema ha una documentazione più approfondita dedicata. **Non** cerca di includere inline ogni catalogo di comandi posseduto da canali/plugin o ogni impostazione profonda di memory/QMD in un'unica pagina. +Questa pagina copre le principali superfici di configurazione di OpenClaw e rimanda altrove quando un sottosistema ha un proprio riferimento più approfondito. **Non** cerca di includere in linea ogni catalogo di comandi posseduto da canali/plugin né ogni impostazione approfondita di memoria/QMD in un'unica pagina. Fonte autorevole del codice: -- `openclaw config schema` stampa lo Schema JSON live usato per la convalida e l'interfaccia di controllo, con i metadati di plugin/canali inclusi uniti quando disponibili -- `config.schema.lookup` restituisce un singolo nodo di schema con ambito sul percorso per strumenti di drill-down -- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash baseline della documentazione di configurazione rispetto alla superficie dello schema corrente +- `openclaw config schema` stampa lo JSON Schema live usato per la convalida e l'interfaccia di controllo, con i metadati dei bundled/plugin/channel uniti quando disponibili +- `config.schema.lookup` restituisce un singolo nodo dello schema con ambito di percorso per strumenti di approfondimento +- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash di baseline della documentazione di configurazione rispetto alla superficie attuale dello schema -Riferimenti approfonditi dedicati: +Riferimenti dedicati approfonditi: -- [Riferimento configurazione Memory](/it/reference/memory-config) per `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e la configurazione Dreaming sotto `plugins.entries.memory-core.config.dreaming` -- [Comandi slash](/it/tools/slash-commands) per il catalogo corrente di comandi integrati + inclusi -- le pagine del canale/plugin proprietario per le superfici di comando specifiche del canale +- [Memory configuration reference](/it/reference/memory-config) per `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e la configurazione di Dreaming sotto `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/it/tools/slash-commands) per il catalogo corrente dei comandi integrati + bundled +- pagine del canale/plugin proprietario per le superfici di comando specifiche del canale -Il formato di configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi: OpenClaw usa valori predefiniti sicuri quando vengono omessi. +Il formato della configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi: OpenClaw usa valori predefiniti sicuri quando vengono omessi. --- ## Canali -Ogni canale si avvia automaticamente quando esiste la sua sezione di configurazione (a meno che `enabled: false`). +Ogni canale si avvia automaticamente quando la sua sezione di configurazione esiste (a meno che `enabled: false`). ### Accesso DM e gruppi -Tutti i canali supportano criteri per DM e criteri per gruppi: +Tutti i canali supportano criteri DM e criteri di gruppo: -| Criterio DM | Comportamento | -| ------------------- | -------------------------------------------------------------- | -| `pairing` (predefinito) | I mittenti sconosciuti ricevono un codice di associazione monouso; il proprietario deve approvare | -| `allowlist` | Solo i mittenti in `allowFrom` (o archivio allow associato) | -| `open` | Consente tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | -| `disabled` | Ignora tutti i DM in ingresso | +| Criterio DM | Comportamento | +| ------------------- | --------------------------------------------------------------- | +| `pairing` (default) | I mittenti sconosciuti ricevono un codice di associazione monouso; il proprietario deve approvare | +| `allowlist` | Solo i mittenti in `allowFrom` (o nell'archivio consentiti associati) | +| `open` | Consente tutti i DM in entrata (richiede `allowFrom: ["*"]`) | +| `disabled` | Ignora tutti i DM in entrata | -| Criterio di gruppo | Comportamento | -| --------------------- | ------------------------------------------------------ | -| `allowlist` (predefinito) | Solo i gruppi che corrispondono all'allowlist configurata | -| `open` | Bypassa le allowlist di gruppo (il controllo delle menzioni continua ad applicarsi) | -| `disabled` | Blocca tutti i messaggi di gruppo/stanza | +| Criterio di gruppo | Comportamento | +| --------------------- | ----------------------------------------------------- | +| `allowlist` (default) | Solo i gruppi che corrispondono alla allowlist configurata | +| `open` | Bypassa le allowlist di gruppo (il gating per menzione continua ad applicarsi) | +| `disabled` | Blocca tutti i messaggi di gruppo/stanza | `channels.defaults.groupPolicy` imposta il valore predefinito quando `groupPolicy` di un provider non è impostato. I codici di associazione scadono dopo 1 ora. Le richieste DM di associazione in sospeso sono limitate a **3 per canale**. -Se un blocco provider manca del tutto (`channels.` assente), il criterio di gruppo a runtime usa come fallback `allowlist` (fail-closed) con un avviso all'avvio. +Se un blocco provider manca del tutto (`channels.` assente), il criterio di gruppo a runtime torna a `allowlist` (fail-closed) con un avviso all'avvio. ### Override del modello per canale -Usa `channels.modelByChannel` per fissare specifici ID canale a un modello. I valori accettano `provider/model` o alias di modello configurati. La mappatura del canale si applica quando una sessione non ha già un override del modello (ad esempio impostato tramite `/model`). +Usa `channels.modelByChannel` per fissare specifici ID canale a un modello. I valori accettano `provider/model` o alias di modello configurati. La mappatura del canale si applica quando una sessione non ha già un override del modello (per esempio, impostato tramite `/model`). ```json5 { @@ -106,10 +106,10 @@ Usa `channels.defaults` per il comportamento condiviso di criterio di gruppo e H ``` - `channels.defaults.groupPolicy`: criterio di gruppo di fallback quando `groupPolicy` a livello provider non è impostato. -- `channels.defaults.contextVisibility`: modalità predefinita di visibilità del contesto supplementare per tutti i canali. Valori: `all` (predefinito, include tutto il contesto citato/thread/storico), `allowlist` (include solo contesto da mittenti in allowlist), `allowlist_quote` (uguale ad allowlist ma mantiene il contesto esplicito di citazione/risposta). Override per canale: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: include gli stati di canale integri nell'output Heartbeat. -- `channels.defaults.heartbeat.showAlerts`: include stati degradati/di errore nell'output Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: visualizza un output Heartbeat compatto in stile indicatore. +- `channels.defaults.contextVisibility`: modalità predefinita di visibilità del contesto supplementare per tutti i canali. Valori: `all` (predefinito, include tutto il contesto citato/thread/cronologia), `allowlist` (include solo il contesto dai mittenti nella allowlist), `allowlist_quote` (come allowlist ma mantiene il contesto esplicito di citazione/risposta). Override per canale: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: include gli stati dei canali sani nell'output di Heartbeat. +- `channels.defaults.heartbeat.showAlerts`: include gli stati degradati/con errore nell'output di Heartbeat. +- `channels.defaults.heartbeat.useIndicator`: visualizza un output di Heartbeat compatto in stile indicatore. ### WhatsApp @@ -124,7 +124,7 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // spunte blu (false in modalità chat con sé stessi) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi } ``` -- I comandi in uscita usano come account predefinito `default` se presente; altrimenti il primo ID account configurato (ordinato). -- Il facoltativo `channels.whatsapp.defaultAccount` sovrascrive quella selezione predefinita di fallback quando corrisponde a un ID account configurato. -- La directory di autenticazione legacy Baileys a account singolo viene migrata da `openclaw doctor` in `whatsapp/default`. +- I comandi in uscita usano per impostazione predefinita l'account `default` se presente; altrimenti il primo ID account configurato (ordinato). +- Facoltativamente, `channels.whatsapp.defaultAccount` sovrascrive quella selezione dell'account predefinito di fallback quando corrisponde a un ID account configurato. +- La directory di autenticazione Baileys legacy per account singolo viene migrata da `openclaw doctor` in `whatsapp/default`. - Override per account: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,13 +225,13 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi } ``` -- Token del bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo file regolare; i symlink vengono rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. -- Il facoltativo `channels.telegram.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Nelle configurazioni multi-account (2+ ID account), imposta un predefinito esplicito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) per evitare l'instradamento di fallback; `openclaw doctor` avvisa quando questo manca o non è valido. -- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni ID supergroup, `/config set|unset`). -- Le voci `bindings[]` di primo livello con `type: "acp"` configurano associazioni ACP persistenti per i topic del forum (usa il canonico `chatId:topic:topicId` in `match.peer.id`). La semantica dei campi è condivisa in [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). -- Le anteprime di streaming Telegram usano `sendMessage` + `editMessageText` (funziona in chat dirette e di gruppo). -- Criterio di retry: vedi [Criterio di retry](/it/concepts/retry). +- Token bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo file regolare; i symlink vengono rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. +- Facoltativamente, `channels.telegram.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Nelle configurazioni multi-account (2+ ID account), imposta un valore predefinito esplicito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) per evitare il routing di fallback; `openclaw doctor` avvisa quando questo manca o non è valido. +- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni di ID supergruppo, `/config set|unset`). +- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per i topic del forum (usa il canonico `chatId:topic:topicId` in `match.peer.id`). La semantica dei campi è condivisa in [ACP Agents](/it/tools/acp-agents#channel-specific-settings). +- Le anteprime di streaming di Telegram usano `sendMessage` + `editMessageText` (funziona nelle chat dirette e di gruppo). +- Criterio di retry: vedi [Retry policy](/it/concepts/retry). ### Discord @@ -335,31 +335,31 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi - Token: `channels.discord.token`, con `DISCORD_BOT_TOKEN` come fallback per l'account predefinito. - Le chiamate dirette in uscita che forniscono un `token` Discord esplicito usano quel token per la chiamata; le impostazioni di retry/criterio dell'account continuano comunque a provenire dall'account selezionato nello snapshot runtime attivo. -- Il facoltativo `channels.discord.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Usa `user:` (DM) o `channel:` (canale guild) per le destinazioni di consegna; gli ID numerici semplici vengono rifiutati. -- Gli slug delle guild sono in minuscolo con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome in forma slug (senza `#`). Preferisci gli ID delle guild. -- I messaggi creati dai bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi restano comunque filtrati). -- `channels.discord.guilds..ignoreOtherMentions` (e gli override del canale) elimina i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). -- `maxLinesPerMessage` (predefinito 17) divide i messaggi molto alti anche quando sono sotto i 2000 caratteri. -- `channels.discord.threadBindings` controlla l'instradamento associato ai thread Discord: - - `enabled`: override Discord per le funzionalità di sessione associate ai thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/instradamento associati) - - `idleHours`: override Discord per l'auto-unfocus dopo inattività in ore (`0` lo disabilita) - - `maxAgeHours`: override Discord per l'età massima rigida in ore (`0` lo disabilita) - - `spawnSubagentSessions`: interruttore opt-in per la creazione/associazione automatica dei thread con `sessions_spawn({ thread: true })` -- Le voci `bindings[]` di primo livello con `type: "acp"` configurano associazioni ACP persistenti per canali e thread (usa l'ID del canale/thread in `match.peer.id`). La semantica dei campi è condivisa in [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` imposta il colore di accento per i contenitori Discord components v2. +- Facoltativamente, `channels.discord.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Usa `user:` (DM) o `channel:` (canale guild) per i target di consegna; gli ID numerici semplici vengono rifiutati. +- Gli slug delle guild sono in minuscolo con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome convertito in slug (senza `#`). Preferisci gli ID delle guild. +- I messaggi scritti dal bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi restano comunque filtrati). +- `channels.discord.guilds..ignoreOtherMentions` (e gli override a livello di canale) elimina i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). +- `maxLinesPerMessage` (predefinito 17) divide i messaggi alti anche quando sono sotto i 2000 caratteri. +- `channels.discord.threadBindings` controlla il routing vincolato ai thread di Discord: + - `enabled`: override Discord per le funzionalità di sessione vincolate ai thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/routing vincolati) + - `idleHours`: override Discord per il disancoraggio automatico per inattività in ore (`0` disabilita) + - `maxAgeHours`: override Discord per l'età massima rigida in ore (`0` disabilita) + - `spawnSubagentSessions`: interruttore opt-in per la creazione/associazione automatica dei thread di `sessions_spawn({ thread: true })` +- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per canali e thread (usa l'id di canale/thread in `match.peer.id`). La semantica dei campi è condivisa in [ACP Agents](/it/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` imposta il colore d'accento per i container dei componenti Discord v2. - `channels.discord.voice` abilita le conversazioni nei canali vocali Discord e gli override facoltativi di auto-join + TTS. - `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono passati a `@discordjs/voice` come opzioni DAVE (`true` e `24` per impostazione predefinita). -- OpenClaw prova inoltre a recuperare la ricezione vocale uscendo e rientrando in una sessione vocale dopo ripetuti errori di decrittazione. -- `channels.discord.streaming` è la chiave canonica della modalità di streaming. I valori legacy `streamMode` e booleani `streaming` vengono migrati automaticamente. +- OpenClaw inoltre tenta il ripristino della ricezione vocale uscendo e rientrando in una sessione vocale dopo ripetuti errori di decrittazione. +- `channels.discord.streaming` è la chiave canonica per la modalità di streaming. I valori legacy `streamMode` e booleani `streaming` vengono migrati automaticamente. - `channels.discord.autoPresence` mappa la disponibilità runtime alla presenza del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override facoltativi del testo di stato. -- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza per nome/tag mutabili (modalità di compatibilità break-glass). +- `channels.discord.dangerouslyAllowNameMatching` riabilita il matching mutabile per nome/tag (modalità di compatibilità break-glass). - `channels.discord.execApprovals`: consegna nativa Discord delle approvazioni exec e autorizzazione degli approvatori. - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. - - `approvers`: ID utente Discord autorizzati ad approvare le richieste exec. Quando omesso, usa come fallback `commands.ownerAllowFrom`. - - `agentFilter`: allowlist facoltativa di ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiave sessione (sottostringa o regex). - - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito) le invia ai DM dell'approvatore, `"channel"` le invia al canale di origine, `"both"` le invia a entrambi. Quando il target include `"channel"`, i pulsanti sono utilizzabili solo dagli approvatori risolti. + - `approvers`: ID utente Discord autorizzati ad approvare richieste exec. Usa `commands.ownerAllowFrom` come fallback quando omesso. + - `agentFilter`: allowlist facoltativa degli ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi per le chiavi di sessione (sottostringa o regex). + - `target`: dove inviare i prompt di approvazione. `"dm"` (predefinito) li invia nei DM dell'approvatore, `"channel"` li invia nel canale di origine, `"both"` li invia in entrambi. Quando il target include `"channel"`, i pulsanti sono utilizzabili solo dagli approvatori risolti. - `cleanupAfterResolve`: quando `true`, elimina i DM di approvazione dopo approvazione, rifiuto o timeout. **Modalità di notifica delle reazioni:** `off` (nessuna), `own` (messaggi del bot, predefinito), `all` (tutti i messaggi), `allowlist` (da `guilds..users` su tutti i messaggi). @@ -396,8 +396,8 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi - JSON dell'account di servizio: inline (`serviceAccount`) o basato su file (`serviceAccountFile`). - È supportato anche SecretRef dell'account di servizio (`serviceAccountRef`). - Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Usa `spaces/` o `users/` per le destinazioni di consegna. -- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza mutabile del principal email (modalità di compatibilità break-glass). +- Usa `spaces/` o `users/` per i target di consegna. +- `channels.googlechat.dangerouslyAllowNameMatching` riabilita il matching mutabile del principal email (modalità di compatibilità break-glass). ### Slack @@ -464,39 +464,34 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi } ``` -- La **modalità Socket** richiede sia `botToken` sia `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` per il fallback env dell'account predefinito). -- La **modalità HTTP** richiede `botToken` più `signingSecret` (alla radice o per account). -- `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe plaintext - oppure oggetti SecretRef. -- Gli snapshot degli account Slack espongono campi per-credential di origine/stato come - `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, in modalità HTTP, - `signingSecretStatus`. `configured_unavailable` significa che l'account è - configurato tramite SecretRef ma il percorso di comando/runtime corrente non ha potuto - risolvere il valore del segreto. +- **La modalità Socket** richiede sia `botToken` sia `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` per il fallback env dell'account predefinito). +- **La modalità HTTP** richiede `botToken` più `signingSecret` (alla radice o per account). +- `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe in chiaro o oggetti SecretRef. +- Gli snapshot degli account Slack espongono campi di origine/stato per credenziale, come `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, in modalità HTTP, `signingSecretStatus`. `configured_unavailable` significa che l'account è configurato tramite SecretRef ma il percorso attuale di comando/runtime non ha potuto risolvere il valore del secret. - `configWrites: false` blocca le scritture di configurazione avviate da Slack. -- Il facoltativo `channels.slack.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- `channels.slack.streaming.mode` è la chiave canonica della modalità di streaming Slack. `channels.slack.streaming.nativeTransport` controlla il trasporto di streaming nativo di Slack. I valori legacy `streamMode`, booleani `streaming` e `nativeStreaming` vengono migrati automaticamente. -- Usa `user:` (DM) o `channel:` per le destinazioni di consegna. +- Facoltativamente, `channels.slack.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.slack.streaming.mode` è la chiave canonica per la modalità di streaming di Slack. `channels.slack.streaming.nativeTransport` controlla il trasporto di streaming nativo di Slack. I valori legacy `streamMode`, booleani `streaming` e `nativeStreaming` vengono migrati automaticamente. +- Usa `user:` (DM) o `channel:` per i target di consegna. **Modalità di notifica delle reazioni:** `off`, `own` (predefinito), `all`, `allowlist` (da `reactionAllowlist`). **Isolamento della sessione thread:** `thread.historyScope` è per-thread (predefinito) o condiviso nel canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. -- Lo streaming nativo Slack più lo stato del thread Slack in stile assistente "is typing..." richiedono una destinazione thread di risposta. I DM di primo livello restano fuori thread per impostazione predefinita, quindi usano `typingReaction` o la consegna normale invece dell'anteprima in stile thread. -- `typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre è in corso una risposta, poi la rimuove al completamento. Usa uno shortcode emoji Slack come `"hourglass_flowing_sand"`. +- Lo streaming nativo di Slack, insieme allo stato del thread in stile assistente Slack "is typing...", richiede un target di risposta nel thread. I DM di livello superiore restano off-thread per impostazione predefinita, quindi usano `typingReaction` o la consegna normale invece dell'anteprima in stile thread. +- `typingReaction` aggiunge una reazione temporanea al messaggio Slack in entrata mentre è in corso una risposta, poi la rimuove al completamento. Usa uno shortcode emoji Slack come `"hourglass_flowing_sand"`. - `channels.slack.execApprovals`: consegna nativa Slack delle approvazioni exec e autorizzazione degli approvatori. Stesso schema di Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID utente Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` o `"both"`). -| Gruppo di azioni | Predefinito | Note | -| ---------------- | ----------- | ------------------------ | -| reactions | abilitato | Reagire + elencare reazioni | -| messages | abilitato | Leggere/inviare/modificare/eliminare | -| pins | abilitato | Fissare/rimuovere/elencare | -| memberInfo | abilitato | Informazioni membro | +| Gruppo di azioni | Predefinito | Note | +| ---------------- | ----------- | ----------------------- | +| reactions | abilitato | Reagisci + elenca reazioni | +| messages | abilitato | Leggi/invia/modifica/elimina | +| pins | abilitato | Fissa/rimuovi/elenca | +| memberInfo | abilitato | Informazioni membro | | emojiList | abilitato | Elenco emoji personalizzate | ### Mattermost -Mattermost viene distribuito come plugin: `openclaw plugins install @openclaw/mattermost`. +Mattermost viene distribuito come Plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -528,21 +523,16 @@ Mattermost viene distribuito come plugin: `openclaw plugins install @openclaw/ma Modalità chat: `oncall` (risponde a @-mention, predefinito), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con il prefisso trigger). -Quando i comandi nativi Mattermost sono abilitati: +Quando i comandi nativi di Mattermost sono abilitati: -- `commands.callbackPath` deve essere un percorso (ad esempio `/api/channels/mattermost/command`), non un URL completo. -- `commands.callbackUrl` deve risolvere l'endpoint Gateway OpenClaw ed essere raggiungibile dal server Mattermost. -- I callback slash nativi vengono autenticati con i token per-comando restituiti - da Mattermost durante la registrazione del comando slash. Se la registrazione fallisce o non - viene attivato alcun comando, OpenClaw rifiuta i callback con - `Unauthorized: invalid command token.` -- Per host callback privati/tailnet/interni, Mattermost può richiedere - che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio del callback. - Usa valori host/dominio, non URL completi. +- `commands.callbackPath` deve essere un percorso (per esempio `/api/channels/mattermost/command`), non un URL completo. +- `commands.callbackUrl` deve risolversi nell'endpoint Gateway di OpenClaw ed essere raggiungibile dal server Mattermost. +- Le callback slash native vengono autenticate con i token per comando restituiti da Mattermost durante la registrazione degli slash command. Se la registrazione fallisce o non viene attivato alcun comando, OpenClaw rifiuta le callback con `Unauthorized: invalid command token.` +- Per host di callback privati/tailnet/interni, Mattermost può richiedere che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio della callback. Usa valori host/dominio, non URL completi. - `channels.mattermost.configWrites`: consente o nega le scritture di configurazione avviate da Mattermost. - `channels.mattermost.requireMention`: richiede `@mention` prima di rispondere nei canali. -- `channels.mattermost.groups..requireMention`: override per-canale del controllo delle menzioni (`"*"` per il predefinito). -- Il facoltativo `channels.mattermost.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.mattermost.groups..requireMention`: override per canale del gating per menzione (`"*"` come predefinito). +- Facoltativamente, `channels.mattermost.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### Signal @@ -551,7 +541,7 @@ Quando i comandi nativi Mattermost sono abilitati: channels: { signal: { enabled: true, - account: "+15555550123", // associazione account facoltativa + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -567,11 +557,11 @@ Quando i comandi nativi Mattermost sono abilitati: - `channels.signal.account`: fissa l'avvio del canale a una specifica identità account Signal. - `channels.signal.configWrites`: consente o nega le scritture di configurazione avviate da Signal. -- Il facoltativo `channels.signal.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Facoltativamente, `channels.signal.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### BlueBubbles -BlueBubbles è il percorso iMessage consigliato (basato su plugin, configurato in `channels.bluebubbles`). +BlueBubbles è il percorso iMessage consigliato (supportato da Plugin, configurato sotto `channels.bluebubbles`). ```json5 { @@ -579,16 +569,16 @@ BlueBubbles è il percorso iMessage consigliato (basato su plugin, configurato i bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, controlli gruppo e azioni avanzate: - // vedi /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` - Percorsi delle chiavi principali coperti qui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Il facoltativo `channels.bluebubbles.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa di destinazione (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- Facoltativamente, `channels.bluebubbles.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Le voci `bindings[]` di livello superiore con `type: "acp"` possono associare le conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). - La configurazione completa del canale BlueBubbles è documentata in [BlueBubbles](/it/channels/bluebubbles). ### iMessage @@ -617,17 +607,17 @@ OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non è richiesto alcun daemon o p } ``` -- Il facoltativo `channels.imessage.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Facoltativamente, `channels.imessage.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. - Richiede l'accesso completo al disco per il DB di Messages. -- Preferisci destinazioni `chat_id:`. Usa `imsg chats --limit 20` per elencare le chat. -- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero allegati via SCP. -- `attachmentRoots` e `remoteAttachmentRoots` limitano i percorsi degli allegati in ingresso (predefinito: `/Users/*/Library/Messages/Attachments`). +- Preferisci target `chat_id:`. Usa `imsg chats --limit 20` per elencare le chat. +- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero degli allegati tramite SCP. +- `attachmentRoots` e `remoteAttachmentRoots` limitano i percorsi degli allegati in entrata (predefinito: `/Users/*/Library/Messages/Attachments`). - SCP usa il controllo rigoroso della chiave host, quindi assicurati che la chiave host del relay esista già in `~/.ssh/known_hosts`. - `channels.imessage.configWrites`: consente o nega le scritture di configurazione avviate da iMessage. -- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o una destinazione chat esplicita (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- Le voci `bindings[]` di livello superiore con `type: "acp"` possono associare le conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o un target chat esplicito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -638,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix è basato su plugin ed è configurato in `channels.matrix`. +Matrix è supportato da Plugin ed è configurato sotto `channels.matrix`. ```json5 { @@ -668,25 +658,25 @@ Matrix è basato su plugin ed è configurato in `channels.matrix`. } ``` -- L'autenticazione tramite token usa `accessToken`; l'autenticazione tramite password usa `userId` + `password`. -- `channels.matrix.proxy` instrada il traffico HTTP di Matrix attraverso un proxy HTTP(S) esplicito. Gli account nominati possono sovrascriverlo con `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` consente homeserver privati/interni. `proxy` e questo opt-in di rete sono controlli indipendenti. +- L'autenticazione con token usa `accessToken`; l'autenticazione con password usa `userId` + `password`. +- `channels.matrix.proxy` instrada il traffico HTTP Matrix tramite un proxy HTTP(S) esplicito. Gli account con nome possono sovrascriverlo con `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` consente homeserver privati/interni. `proxy` e questa attivazione della rete sono controlli indipendenti. - `channels.matrix.defaultAccount` seleziona l'account preferito nelle configurazioni multi-account. -- `channels.matrix.autoJoin` ha come predefinito `off`, quindi le stanze invitate e i nuovi inviti in stile DM vengono ignorati finché non imposti `autoJoin: "allowlist"` con `autoJoinAllowlist` oppure `autoJoin: "always"`. +- `channels.matrix.autoJoin` è impostato su `off` per impostazione predefinita, quindi le stanze invitate e i nuovi inviti in stile DM vengono ignorati finché non imposti `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. - `channels.matrix.execApprovals`: consegna nativa Matrix delle approvazioni exec e autorizzazione degli approvatori. - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. - - `approvers`: ID utente Matrix (ad es. `@owner:example.org`) autorizzati ad approvare richieste exec. - - `agentFilter`: allowlist facoltativa di ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiave sessione (sottostringa o regex). - - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito), `"channel"` (stanza di origine) oppure `"both"`. + - `approvers`: ID utente Matrix (ad esempio `@owner:example.org`) autorizzati ad approvare richieste exec. + - `agentFilter`: allowlist facoltativa degli ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi per le chiavi di sessione (sottostringa o regex). + - `target`: dove inviare i prompt di approvazione. `"dm"` (predefinito), `"channel"` (stanza di origine) o `"both"`. - Override per account: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` controlla come i DM Matrix vengono raggruppati nelle sessioni: `per-user` (predefinito) condivide per peer instradato, mentre `per-room` isola ogni stanza DM. +- `channels.matrix.dm.sessionScope` controlla come i DM Matrix vengono raggruppati in sessioni: `per-user` (predefinito) condivide per peer instradato, mentre `per-room` isola ogni stanza DM. - Le probe di stato Matrix e le ricerche live nella directory usano lo stesso criterio proxy del traffico runtime. -- La configurazione completa di Matrix, le regole di destinazione e gli esempi di configurazione sono documentati in [Matrix](/it/channels/matrix). +- La configurazione completa di Matrix, le regole di targeting e gli esempi di configurazione sono documentati in [Matrix](/it/channels/matrix). ### Microsoft Teams -Microsoft Teams è basato su plugin ed è configurato in `channels.msteams`. +Microsoft Teams è supportato da Plugin ed è configurato sotto `channels.msteams`. ```json5 { @@ -694,19 +684,19 @@ Microsoft Teams è basato su plugin ed è configurato in `channels.msteams`. msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, criteri team/canale: - // vedi /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` - Percorsi delle chiavi principali coperti qui: `channels.msteams`, `channels.msteams.configWrites`. -- La configurazione completa di Teams (credenziali, Webhook, criterio DM/gruppo, override per-team/per-canale) è documentata in [Microsoft Teams](/it/channels/msteams). +- La configurazione completa di Teams (credenziali, Webhook, criterio DM/gruppo, override per team/per canale) è documentata in [Microsoft Teams](/it/channels/msteams). ### IRC -IRC è basato su plugin ed è configurato in `channels.irc`. +IRC è supportato da Plugin ed è configurato sotto `channels.irc`. ```json5 { @@ -728,12 +718,12 @@ IRC è basato su plugin ed è configurato in `channels.irc`. ``` - Percorsi delle chiavi principali coperti qui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Il facoltativo `channels.irc.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/controllo delle menzioni) è documentata in [IRC](/it/channels/irc). +- Facoltativamente, `channels.irc.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/gating per menzione) è documentata in [IRC](/it/channels/irc). ### Multi-account (tutti i canali) -Esegui più account per canale (ciascuno con il proprio `accountId`): +Esegui più account per canale (ognuno con il proprio `accountId`): ```json5 { @@ -741,11 +731,11 @@ Esegui più account per canale (ciascuno con il proprio `accountId`): telegram: { accounts: { default: { - name: "Bot principale", + name: "Primary bot", botToken: "123456:ABC...", }, alerts: { - name: "Bot avvisi", + name: "Alerts bot", botToken: "987654:XYZ...", }, }, @@ -754,28 +744,28 @@ Esegui più account per canale (ciascuno con il proprio `accountId`): } ``` -- `default` viene usato quando `accountId` è omesso (CLI + instradamento). +- `default` viene usato quando `accountId` è omesso (CLI + routing). - I token env si applicano solo all'account **default**. -- Le impostazioni di base del canale si applicano a tutti gli account a meno che non vengano sovrascritte per account. -- Usa `bindings[].match.accountId` per instradare ciascun account a un agente diverso. -- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora su una configurazione del canale top-level a account singolo, OpenClaw promuove prima i valori top-level a account singolo con ambito account nella mappa account del canale così l'account originale continua a funzionare. La maggior parte dei canali li sposta in `channels..accounts.default`; Matrix può invece mantenere un target nominato/default esistente corrispondente. -- Le associazioni esistenti solo-canale (senza `accountId`) continuano a corrispondere all'account predefinito; le associazioni con ambito account restano facoltative. -- Anche `openclaw doctor --fix` ripara forme miste spostando i valori top-level a account singolo con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può invece mantenere un target nominato/default esistente corrispondente. +- Le impostazioni di base del canale si applicano a tutti gli account, a meno che non vengano sovrascritte per account. +- Usa `bindings[].match.accountId` per instradare ogni account a un agente diverso. +- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora su una configurazione di canale top-level a account singolo, OpenClaw promuove prima i valori top-level a account singolo con ambito account nella mappa account del canale, in modo che l'account originale continui a funzionare. La maggior parte dei canali li sposta in `channels..accounts.default`; Matrix può invece preservare un target con nome/predefinito esistente corrispondente. +- I binding esistenti solo-canale (senza `accountId`) continuano a corrispondere all'account predefinito; i binding con ambito account restano facoltativi. +- `openclaw doctor --fix` ripara anche le forme miste spostando i valori top-level a account singolo con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può invece preservare un target con nome/predefinito esistente corrispondente. -### Altri canali plugin +### Altri canali Plugin -Molti canali plugin sono configurati come `channels.` e documentati nelle rispettive pagine dedicate al canale (ad esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). -Vedi l'indice completo dei canali: [Canali](/it/channels). +Molti canali Plugin sono configurati come `channels.` e documentati nelle rispettive pagine dedicate del canale (ad esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +Vedi l'indice completo dei canali: [Channels](/it/channels). -### Controllo delle menzioni nelle chat di gruppo +### Gating per menzione nelle chat di gruppo -I messaggi di gruppo hanno come predefinito **richiedere menzione** (menzione nei metadati o pattern regex sicuri). Si applica alle chat di gruppo di WhatsApp, Telegram, Discord, Google Chat e iMessage. +I messaggi di gruppo richiedono per impostazione predefinita una **menzione obbligatoria** (menzione nei metadati o pattern regex sicuri). Si applica alle chat di gruppo di WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipi di menzione:** -- **Menzioni nei metadati**: @-mention native della piattaforma. Ignorate in modalità chat con sé stessi su WhatsApp. +- **Menzioni nei metadati**: @-mention native della piattaforma. Ignorate nella modalità self-chat di WhatsApp. - **Pattern di testo**: pattern regex sicuri in `agents.list[].groupChat.mentionPatterns`. I pattern non validi e le ripetizioni annidate non sicure vengono ignorati. -- Il controllo delle menzioni viene applicato solo quando il rilevamento è possibile (menzioni native o almeno un pattern). +- Il gating per menzione viene applicato solo quando il rilevamento è possibile (menzioni native o almeno un pattern). ```json5 { @@ -805,13 +795,13 @@ I messaggi di gruppo hanno come predefinito **richiedere menzione** (menzione ne } ``` -Risoluzione: override per-DM → valore predefinito del provider → nessun limite (tutto mantenuto). +Risoluzione: override per-DM → predefinito del provider → nessun limite (tutto mantenuto). Supportati: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Modalità chat con sé stessi +#### Modalità self-chat -Includi il tuo numero in `allowFrom` per abilitare la modalità chat con sé stessi (ignora le @-mention native, risponde solo ai pattern di testo): +Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignora le @-mention native, risponde solo ai pattern di testo): ```json5 { @@ -832,21 +822,21 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità chat con sé ste } ``` -### Comandi (gestione dei comandi in chat) +### Comandi (gestione dei comandi chat) ```json5 { commands: { - native: "auto", // registra comandi nativi quando supportati - nativeSkills: "auto", // registra comandi nativi Skills quando supportati - text: true, // analizza /commands nei messaggi di chat - bash: false, // consente ! (alias: /bash) + native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // consente /config - mcp: false, // consente /mcp - plugins: false, // consente /plugins - debug: false, // consente /debug - restart: true, // consente /restart + strumento gateway restart + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,32 +851,32 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità chat con sé ste -- Questo blocco configura le superfici dei comandi. Per il catalogo corrente dei comandi integrati + inclusi, vedi [Comandi slash](/it/tools/slash-commands). -- Questa pagina è un **riferimento delle chiavi di configurazione**, non il catalogo completo dei comandi. I comandi posseduti da canali/plugin come QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice` sono documentati nelle rispettive pagine di canale/plugin oltre che in [Comandi slash](/it/tools/slash-commands). -- I comandi di testo devono essere messaggi **autonomi** con `/` iniziale. +- Questo blocco configura le superfici dei comandi. Per il catalogo corrente dei comandi integrati + bundled, vedi [Slash Commands](/it/tools/slash-commands). +- Questa pagina è un **riferimento delle chiavi di configurazione**, non il catalogo completo dei comandi. I comandi posseduti da canali/plugin come QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice` sono documentati nelle rispettive pagine del canale/plugin più [Slash Commands](/it/tools/slash-commands). +- I comandi di testo devono essere messaggi **standalone** con `/` iniziale. - `native: "auto"` attiva i comandi nativi per Discord/Telegram, lascia Slack disattivato. -- `nativeSkills: "auto"` attiva i comandi nativi Skills per Discord/Telegram, lascia Slack disattivato. +- `nativeSkills: "auto"` attiva i comandi nativi delle Skills per Discord/Telegram, lascia Slack disattivato. - Override per canale: `channels.discord.commands.native` (bool o `"auto"`). `false` cancella i comandi registrati in precedenza. -- Sovrascrivi la registrazione dei Skills nativi per canale con `channels..commands.nativeSkills`. +- Sovrascrivi la registrazione nativa delle Skills per canale con `channels..commands.nativeSkills`. - `channels.telegram.customCommands` aggiunge voci extra al menu del bot Telegram. - `bash: true` abilita `! ` per la shell host. Richiede `tools.elevated.enabled` e il mittente in `tools.elevated.allowFrom.`. -- `config: true` abilita `/config` (legge/scrive `openclaw.json`). Per i client `chat.send` del Gateway, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; il comando di sola lettura `/config show` resta disponibile ai normali client operatore con ambito di scrittura. -- `mcp: true` abilita `/mcp` per la configurazione del server MCP gestita da OpenClaw in `mcp.servers`. -- `plugins: true` abilita `/plugins` per discovery dei plugin, installazione e controlli di abilitazione/disabilitazione. -- `channels..configWrites` controlla le mutazioni di configurazione per canale (predefinito: true). -- Per i canali multi-account, `channels..accounts..configWrites` controlla anche le scritture che puntano a quell'account (ad esempio `/allowlist --config --account ` o `/config set channels..accounts....`). +- `config: true` abilita `/config` (legge/scrive `openclaw.json`). Per i client `chat.send` del Gateway, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; `/config show` in sola lettura resta disponibile ai normali client operator con ambito di scrittura. +- `mcp: true` abilita `/mcp` per la configurazione del server MCP gestita da OpenClaw sotto `mcp.servers`. +- `plugins: true` abilita `/plugins` per la scoperta dei plugin, l'installazione e i controlli di abilitazione/disabilitazione. +- `channels..configWrites` regola le mutazioni di configurazione per canale (predefinito: true). +- Per i canali multi-account, anche `channels..accounts..configWrites` regola le scritture che puntano a quell'account (per esempio `/allowlist --config --account ` o `/config set channels..accounts....`). - `restart: false` disabilita `/restart` e le azioni dello strumento di riavvio del Gateway. Predefinito: `true`. -- `ownerAllowFrom` è l'allowlist esplicita del proprietario per comandi/strumenti riservati al proprietario. È separata da `allowFrom`. -- `ownerDisplay: "hash"` applica hash agli ID del proprietario nel prompt di sistema. Imposta `ownerDisplaySecret` per controllare l'hash. -- `allowFrom` è per-provider. Quando impostato, è l'**unica** fonte di autorizzazione (le allowlist/l'associazione del canale e `useAccessGroups` vengono ignorati). +- `ownerAllowFrom` è la allowlist esplicita del proprietario per comandi/strumenti riservati al proprietario. È separata da `allowFrom`. +- `ownerDisplay: "hash"` applica l'hash agli ID del proprietario nel prompt di sistema. Imposta `ownerDisplaySecret` per controllare l'hashing. +- `allowFrom` è per-provider. Quando è impostato, è l'**unica** fonte di autorizzazione (le allowlist/l'associazione del canale e `useAccessGroups` vengono ignorati). - `useAccessGroups: false` consente ai comandi di bypassare i criteri dei gruppi di accesso quando `allowFrom` non è impostato. - Mappa della documentazione dei comandi: - - catalogo integrato + incluso: [Comandi slash](/it/tools/slash-commands) - - superfici di comando specifiche del canale: [Canali](/it/channels) + - catalogo integrato + bundled: [Slash Commands](/it/tools/slash-commands) + - superfici di comando specifiche del canale: [Channels](/it/channels) - comandi QQ Bot: [QQ Bot](/it/channels/qqbot) - - comandi di associazione: [Associazione](/it/channels/pairing) - - comando card di LINE: [LINE](/it/channels/line) - - memory dreaming: [Dreaming](/it/concepts/dreaming) + - comandi di associazione: [Pairing](/it/channels/pairing) + - comando scheda LINE: [LINE](/it/channels/line) + - Dreaming della memoria: [Dreaming](/it/concepts/dreaming) @@ -906,7 +896,7 @@ Predefinito: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Root repository facoltativa mostrata nella riga Runtime del prompt di sistema. Se non impostata, OpenClaw la rileva automaticamente risalendo dal workspace. +Radice del repository facoltativa mostrata nella riga Runtime del prompt di sistema. Se non impostata, OpenClaw la rileva automaticamente risalendo dalla workspace. ```json5 { @@ -916,7 +906,7 @@ Root repository facoltativa mostrata nella riga Runtime del prompt di sistema. S ### `agents.defaults.skills` -Allowlist predefinita facoltativa di Skills per gli agenti che non impostano +Allowlist predefinita facoltativa delle Skills per gli agenti che non impostano `agents.list[].skills`. ```json5 @@ -924,9 +914,9 @@ Allowlist predefinita facoltativa di Skills per gli agenti che non impostano agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // eredita github, weather - { id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti - { id: "locked-down", skills: [] }, // nessun Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } @@ -935,12 +925,11 @@ Allowlist predefinita facoltativa di Skills per gli agenti che non impostano - Ometti `agents.defaults.skills` per Skills senza restrizioni per impostazione predefinita. - Ometti `agents.list[].skills` per ereditare i valori predefiniti. - Imposta `agents.list[].skills: []` per non avere Skills. -- Una lista non vuota `agents.list[].skills` è l'insieme finale per quell'agente; non - viene unita ai valori predefiniti. +- Una lista non vuota in `agents.list[].skills` è l'insieme finale per quell'agente; non viene unita ai valori predefiniti. ### `agents.defaults.skipBootstrap` -Disabilita la creazione automatica dei file bootstrap del workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Disabilita la creazione automatica dei file bootstrap della workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -950,9 +939,9 @@ Disabilita la creazione automatica dei file bootstrap del workspace (`AGENTS.md` ### `agents.defaults.contextInjection` -Controlla quando i file bootstrap del workspace vengono iniettati nel prompt di sistema. Predefinito: `"always"`. +Controlla quando i file bootstrap della workspace vengono iniettati nel prompt di sistema. Predefinito: `"always"`. -- `"continuation-skip"`: i turni di continuazione sicuri (dopo una risposta completata dell'assistente) saltano la reiniezione del bootstrap del workspace, riducendo la dimensione del prompt. Le esecuzioni Heartbeat e i retry post-Compaction continuano a ricostruire il contesto. +- `"continuation-skip"`: i turni di continuazione sicura (dopo una risposta completata dell'assistente) saltano la re-iniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni di Heartbeat e i retry post-Compaction ricostruiscono comunque il contesto. ```json5 { @@ -962,7 +951,7 @@ Controlla quando i file bootstrap del workspace vengono iniettati nel prompt di ### `agents.defaults.bootstrapMaxChars` -Numero massimo di caratteri per file bootstrap del workspace prima del troncamento. Predefinito: `12000`. +Numero massimo di caratteri per file bootstrap della workspace prima del troncamento. Predefinito: `12000`. ```json5 { @@ -972,7 +961,7 @@ Numero massimo di caratteri per file bootstrap del workspace prima del troncamen ### `agents.defaults.bootstrapTotalMaxChars` -Numero massimo totale di caratteri iniettati in tutti i file bootstrap del workspace. Predefinito: `60000`. +Numero massimo totale di caratteri iniettati in tutti i file bootstrap della workspace. Predefinito: `60000`. ```json5 { @@ -987,7 +976,7 @@ Predefinito: `"once"`. - `"off"`: non iniettare mai il testo di avviso nel prompt di sistema. - `"once"`: inietta l'avviso una volta per ogni firma di troncamento univoca (consigliato). -- `"always"`: inietta l'avviso a ogni esecuzione quando esiste un troncamento. +- `"always"`: inietta l'avviso a ogni esecuzione quando è presente un troncamento. ```json5 { @@ -997,23 +986,25 @@ Predefinito: `"once"`. ### Mappa di proprietà del budget di contesto -OpenClaw ha più budget ad alto volume per prompt/contesto, e sono -intenzionalmente suddivisi per sottosistema invece di confluire tutti in un'unica impostazione generica. +OpenClaw ha più budget di prompt/contesto ad alto volume, ed essi sono +intenzionalmente suddivisi per sottosistema invece di passare tutti attraverso +un'unica impostazione generica. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - normale iniezione bootstrap del workspace. + normale iniezione bootstrap della workspace. - `agents.defaults.startupContext.*`: - preludio di avvio one-shot per `/new` e `/reset`, inclusi i file recenti giornalieri - `memory/*.md`. + preludio di avvio one-shot di `/new` e `/reset`, inclusi i file + `memory/*.md` giornalieri recenti. - `skills.limits.*`: - lista compatta di Skills iniettata nel prompt di sistema. + l'elenco compatto delle Skills iniettato nel prompt di sistema. - `agents.defaults.contextLimits.*`: - estratti runtime limitati e blocchi iniettati posseduti dal runtime. + estratti runtime delimitati e blocchi posseduti dal runtime iniettati. - `memory.qmd.limits.*`: - indicizzazione degli snippet di ricerca memoria e dimensionamento dell'iniezione. + dimensionamento dello snippet e dell'iniezione della ricerca in memoria indicizzata. -Usa l'override corrispondente per-agente solo quando un agente ha bisogno di un budget diverso: +Usa l'override corrispondente per agente solo quando un agente ha bisogno di un +budget diverso: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` @@ -1041,7 +1032,7 @@ Controlla il preludio di avvio del primo turno iniettato nelle esecuzioni bare ` #### `agents.defaults.contextLimits` -Valori predefiniti condivisi per le superfici di contesto runtime limitate. +Valori predefiniti condivisi per le superfici di contesto runtime delimitate. ```json5 { @@ -1058,18 +1049,14 @@ Valori predefiniti condivisi per le superfici di contesto runtime limitate. } ``` -- `memoryGetMaxChars`: limite predefinito dell'estratto `memory_get` prima che vengano aggiunti i metadati - di troncamento e l'avviso di continuazione. -- `memoryGetDefaultLines`: finestra di righe predefinita di `memory_get` quando `lines` viene - omesso. -- `toolResultMaxChars`: limite live del risultato dello strumento usato per i risultati persistiti e - il recupero da overflow. -- `postCompactionMaxChars`: limite dell'estratto AGENTS.md usato durante l'iniezione - di refresh post-Compaction. +- `memoryGetMaxChars`: limite predefinito dell'estratto `memory_get` prima che vengano aggiunti i metadati di troncamento e l'avviso di continuazione. +- `memoryGetDefaultLines`: finestra di righe predefinita di `memory_get` quando `lines` è omesso. +- `toolResultMaxChars`: limite live del risultato dello strumento usato per i risultati persistiti e il recupero da overflow. +- `postCompactionMaxChars`: limite dell'estratto di AGENTS.md usato durante l'iniezione di refresh post-Compaction. #### `agents.list[].contextLimits` -Override per-agente per le impostazioni condivise `contextLimits`. I campi omessi ereditano +Override per agente delle impostazioni condivise `contextLimits`. I campi omessi ereditano da `agents.defaults.contextLimits`. ```json5 @@ -1096,8 +1083,8 @@ da `agents.defaults.contextLimits`. #### `skills.limits.maxSkillsPromptChars` -Limite globale per la lista compatta di Skills iniettata nel prompt di sistema. Questo -non influisce sulla lettura dei file `SKILL.md` su richiesta. +Limite globale per l'elenco compatto delle Skills iniettato nel prompt di sistema. Questo +non influisce sulla lettura on demand dei file `SKILL.md`. ```json5 { @@ -1111,7 +1098,7 @@ non influisce sulla lettura dei file `SKILL.md` su richiesta. #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Override per-agente per il budget del prompt Skills. +Override per agente del budget del prompt delle Skills. ```json5 { @@ -1133,7 +1120,7 @@ Override per-agente per il budget del prompt Skills. Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine del transcript/strumento prima delle chiamate al provider. Predefinito: `1200`. -Valori più bassi in genere riducono l'uso di vision-token e la dimensione del payload della richiesta per esecuzioni ricche di screenshot. +Valori più bassi di solito riducono l'uso dei token per la visione e la dimensione del payload della richiesta nelle esecuzioni con molti screenshot. Valori più alti preservano più dettaglio visivo. ```json5 @@ -1154,7 +1141,7 @@ Fuso orario per il contesto del prompt di sistema (non per i timestamp dei messa ### `agents.defaults.timeFormat` -Formato orario nel prompt di sistema. Predefinito: `auto` (preferenza OS). +Formato dell'ora nel prompt di sistema. Predefinito: `auto` (preferenza OS). ```json5 { @@ -1192,7 +1179,7 @@ Formato orario nel prompt di sistema. Predefinito: `auto` (preferenza OS). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // parametri provider predefiniti globali + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1211,49 +1198,49 @@ Formato orario nel prompt di sistema. Predefinito: `auto` (preferenza OS). } ``` -- `model`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). +- `model`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - La forma stringa imposta solo il modello primario. - La forma oggetto imposta il primario più i modelli di failover ordinati. -- `imageModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). +- `imageModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dal percorso dello strumento `image` come configurazione del modello di visione. - - Usato anche come instradamento di fallback quando il modello selezionato/predefinito non può accettare input immagine. -- `imageGenerationModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). + - Usato anche come routing di fallback quando il modello selezionato/predefinito non può accettare input immagine. +- `imageGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dalla capacità condivisa di generazione immagini e da qualsiasi futura superficie di strumento/plugin che generi immagini. - - Valori tipici: `google/gemini-3.1-flash-image-preview` per la generazione immagini Gemini nativa, `fal/fal-ai/flux/dev` per fal, oppure `openai/gpt-image-2` per OpenAI Images. - - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente (ad esempio `GEMINI_API_KEY` o `GOOGLE_API_KEY` per `google/*`, `OPENAI_API_KEY` per `openai/*`, `FAL_KEY` per `fal/*`). - - Se omesso, `image_generate` può comunque dedurre un valore predefinito del provider supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di ID provider. -- `musicGenerationModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). + - Valori tipici: `google/gemini-3.1-flash-image-preview` per la generazione immagini nativa di Gemini, `fal/fal-ai/flux/dev` per fal, oppure `openai/gpt-image-2` per OpenAI Images. + - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente (per esempio `GEMINI_API_KEY` o `GOOGLE_API_KEY` per `google/*`, `OPENAI_API_KEY` per `openai/*`, `FAL_KEY` per `fal/*`). + - Se omesso, `image_generate` può comunque dedurre un provider predefinito supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di provider-id. +- `musicGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dalla capacità condivisa di generazione musicale e dallo strumento integrato `music_generate`. - Valori tipici: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` oppure `minimax/music-2.5+`. - - Se omesso, `music_generate` può comunque dedurre un valore predefinito del provider supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione musicale registrati in ordine di ID provider. + - Se omesso, `music_generate` può comunque dedurre un provider predefinito supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione musicale registrati in ordine di provider-id. - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente. -- `videoGenerationModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). +- `videoGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dalla capacità condivisa di generazione video e dallo strumento integrato `video_generate`. - Valori tipici: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` oppure `qwen/wan2.7-r2v`. - - Se omesso, `video_generate` può comunque dedurre un valore predefinito del provider supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione video registrati in ordine di ID provider. + - Se omesso, `video_generate` può comunque dedurre un provider predefinito supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione video registrati in ordine di provider-id. - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente. - - Il provider di generazione video Qwen incluso supporta fino a 1 video in uscita, 1 immagine in ingresso, 4 video in ingresso, durata di 10 secondi e opzioni a livello provider `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. -- `pdfModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). - - Usato dallo strumento `pdf` per l'instradamento del modello. - - Se omesso, lo strumento PDF usa come fallback `imageModel`, poi il modello di sessione/predefinito risolto. + - Il provider bundled di generazione video Qwen supporta fino a 1 video in output, 1 immagine in input, 4 video in input, durata di 10 secondi e opzioni a livello provider `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. +- `pdfModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). + - Usato dallo strumento `pdf` per il routing del modello. + - Se omesso, lo strumento PDF torna a `imageModel`, poi al modello di sessione/predefinito risolto. - `pdfMaxBytesMb`: limite predefinito della dimensione PDF per lo strumento `pdf` quando `maxBytesMb` non viene passato al momento della chiamata. -- `pdfMaxPages`: numero massimo di pagine considerato dalla modalità fallback di estrazione nello strumento `pdf`. -- `verboseDefault`: livello verbose predefinito per gli agenti. Valori: `"off"`, `"on"`, `"full"`. Predefinito: `"off"`. -- `elevatedDefault`: livello predefinito di output elevated per gli agenti. Valori: `"off"`, `"on"`, `"ask"`, `"full"`. Predefinito: `"on"`. -- `model.primary`: formato `provider/model` (ad esempio `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca di provider configurato per quell'esatto ID modello, e solo dopo usa come fallback il provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw usa come fallback il primo provider/modello configurato invece di mostrare un valore predefinito obsoleto di un provider rimosso. -- `models`: catalogo dei modelli configurato e allowlist per `/model`. Ogni voce può includere `alias` (scorciatoia) e `params` (specifici del provider, ad esempio `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parametri provider predefiniti globali applicati a tutti i modelli. Impostati in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). -- Precedenza di merge di `params` (configurazione): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per-modello), poi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Caching del prompt](/it/reference/prompt-caching) per i dettagli. -- `embeddedHarness`: criterio runtime predefinito per l'agente embedded di basso livello. Usa `runtime: "auto"` per lasciare che gli harness di plugin registrati rivendichino i modelli supportati, `runtime: "pi"` per forzare l'harness PI integrato, oppure un ID harness registrato come `runtime: "codex"`. Imposta `fallback: "none"` per disabilitare il fallback automatico a PI. -- Gli strumenti di scrittura della configurazione che modificano questi campi (ad esempio `/models set`, `/models set-image` e i comandi di aggiunta/rimozione fallback) salvano la forma oggetto canonica e preservano le liste fallback esistenti quando possibile. -- `maxConcurrent`: numero massimo di esecuzioni agente parallele tra sessioni (ogni sessione resta comunque serializzata). Predefinito: 4. +- `pdfMaxPages`: massimo predefinito di pagine considerate dalla modalità di fallback di estrazione nello strumento `pdf`. +- `verboseDefault`: livello verboso predefinito per gli agenti. Valori: `"off"`, `"on"`, `"full"`. Predefinito: `"off"`. +- `elevatedDefault`: livello predefinito di output elevato per gli agenti. Valori: `"off"`, `"on"`, `"ask"`, `"full"`. Predefinito: `"on"`. +- `model.primary`: formato `provider/model` (ad esempio `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca del provider configurato per quell'esatto model id e solo dopo torna al provider predefinito configurato (comportamento di compatibilità deprecato, quindi è preferibile usare `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw torna al primo provider/modello configurato invece di esporre un valore predefinito obsoleto di un provider rimosso. +- `models`: il catalogo dei modelli configurato e l'allowlist per `/model`. Ogni voce può includere `alias` (scorciatoia) e `params` (specifici del provider, per esempio `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parametri provider predefiniti globali applicati a tutti i modelli. Impostali in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). +- Precedenza di unione di `params` (config): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per modello), poi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Prompt Caching](/it/reference/prompt-caching) per i dettagli. +- `embeddedHarness`: criterio predefinito del runtime embedded di basso livello per l'agente. Usa `runtime: "auto"` per lasciare che gli harness plugin registrati rivendichino i modelli supportati, `runtime: "pi"` per forzare l'harness PI integrato, oppure un ID harness registrato come `runtime: "codex"`. Imposta `fallback: "none"` per disabilitare il fallback automatico a PI. +- I writer di configurazione che mutano questi campi (per esempio `/models set`, `/models set-image` e i comandi add/remove dei fallback) salvano la forma oggetto canonica e preservano le liste di fallback esistenti quando possibile. +- `maxConcurrent`: massimo numero di esecuzioni parallele di agenti tra le sessioni (ogni sessione resta comunque serializzata). Predefinito: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` controlla quale esecutore di basso livello esegue i turni dell'agente embedded. +`embeddedHarness` controlla quale esecutore di basso livello esegue i turni degli agenti embedded. La maggior parte dei deployment dovrebbe mantenere il valore predefinito `{ runtime: "auto", fallback: "pi" }`. -Usalo quando un plugin fidato fornisce un harness nativo, come l'harness app-server -Codex incluso. +Usalo quando un plugin attendibile fornisce un harness nativo, come l'harness bundled +del server dell'app Codex. ```json5 { @@ -1269,13 +1256,13 @@ Codex incluso. } ``` -- `runtime`: `"auto"`, `"pi"` o un ID harness plugin registrato. Il plugin Codex incluso registra `codex`. -- `fallback`: `"pi"` o `"none"`. `"pi"` mantiene l'harness PI integrato come fallback di compatibilità. `"none"` fa fallire la selezione di un harness plugin mancante o non supportato invece di usare silenziosamente PI. -- Override env: `OPENCLAW_AGENT_RUNTIME=` sovrascrive `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disabilita il fallback a PI per quel processo. -- Per deployment solo-Codex, imposta `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. -- Questo controlla solo l'harness di chat embedded. Generazione media, vision, PDF, musica, video e TTS continuano a usare le rispettive impostazioni provider/modello. +- `runtime`: `"auto"`, `"pi"` oppure un ID harness plugin registrato. Il plugin Codex bundled registra `codex`. +- `fallback`: `"pi"` oppure `"none"`. `"pi"` mantiene l'harness PI integrato come fallback di compatibilità quando non viene selezionato alcun harness plugin. `"none"` fa fallire la selezione mancante o non supportata dell'harness plugin invece di usare silenziosamente PI. Gli errori degli harness plugin selezionati vengono sempre esposti direttamente. +- Override d'ambiente: `OPENCLAW_AGENT_RUNTIME=` sovrascrive `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disabilita il fallback a PI per quel processo. +- Per deployment solo Codex, imposta `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. +- Questo controlla solo l'harness chat embedded. Generazione media, visione, PDF, musica, video e TTS usano comunque le rispettive impostazioni provider/modello. -**Scorciatoie alias integrate** (si applicano solo quando il modello è in `agents.defaults.models`): +**Abbreviazioni alias integrate** (si applicano solo quando il modello è in `agents.defaults.models`): | Alias | Modello | | ------------------- | ------------------------------------- | @@ -1290,13 +1277,13 @@ Codex incluso. Gli alias configurati da te hanno sempre la precedenza su quelli predefiniti. -I modelli Z.AI GLM-4.x abilitano automaticamente la modalità thinking a meno che tu non imposti `--thinking off` o definisca tu stesso `agents.defaults.models["zai/"].params.thinking`. -I modelli Z.AI abilitano `tool_stream` per impostazione predefinita per lo streaming delle chiamate agli strumenti. Imposta `agents.defaults.models["zai/"].params.tool_stream` su `false` per disabilitarlo. -I modelli Anthropic Claude 4.6 usano per impostazione predefinita il thinking `adaptive` quando non è impostato alcun livello di thinking esplicito. +I modelli Z.AI GLM-4.x abilitano automaticamente la modalità thinking, a meno che tu non imposti `--thinking off` o definisca tu stesso `agents.defaults.models["zai/"].params.thinking`. +I modelli Z.AI abilitano `tool_stream` per impostazione predefinita per lo streaming delle chiamate strumento. Imposta `agents.defaults.models["zai/"].params.tool_stream` su `false` per disabilitarlo. +I modelli Anthropic Claude 4.6 usano per impostazione predefinita il thinking `adaptive` quando non è impostato un livello di thinking esplicito. ### `agents.defaults.cliBackends` -Backend CLI facoltativi per esecuzioni fallback solo testo (senza chiamate a strumenti). Utili come backup quando i provider API falliscono. +CLI backend facoltativi per esecuzioni di fallback solo testo (senza chiamate a strumenti). Utili come backup quando i provider API falliscono. ```json5 { @@ -1324,19 +1311,19 @@ Backend CLI facoltativi per esecuzioni fallback solo testo (senza chiamate a str } ``` -- I backend CLI sono pensati prima di tutto per il testo; gli strumenti sono sempre disabilitati. -- Le sessioni sono supportate quando `sessionArg` è impostato. -- Il pass-through delle immagini è supportato quando `imageArg` accetta percorsi file. +- I CLI backend sono orientati al testo; gli strumenti sono sempre disabilitati. +- Sessioni supportate quando `sessionArg` è impostato. +- Pass-through immagini supportato quando `imageArg` accetta percorsi file. ### `agents.defaults.systemPromptOverride` -Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Impostalo a livello predefinito (`agents.defaults.systemPromptOverride`) o per agente (`agents.list[].systemPromptOverride`). I valori per agente hanno la precedenza; un valore vuoto o composto solo da spazi viene ignorato. Utile per esperimenti controllati sul prompt. +Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Impostalo a livello predefinito (`agents.defaults.systemPromptOverride`) o per agente (`agents.list[].systemPromptOverride`). I valori per agente hanno la precedenza; un valore vuoto o contenente solo spazi viene ignorato. Utile per esperimenti controllati sul prompt. ```json5 { agents: { defaults: { - systemPromptOverride: "Sei un assistente utile.", + systemPromptOverride: "You are a helpful assistant.", }, }, } @@ -1344,24 +1331,24 @@ Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fi ### `agents.defaults.heartbeat` -Esecuzioni Heartbeat periodiche. +Esecuzioni periodiche di Heartbeat. ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m disabilita + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // predefinito: true; false omette la sezione Heartbeat dal prompt di sistema - lightContext: false, // predefinito: false; true mantiene solo HEARTBEAT.md tra i file bootstrap del workspace - isolatedSession: false, // predefinito: false; true esegue ogni heartbeat in una sessione nuova (senza cronologia conversazione) + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (predefinito) | block - target: "none", // predefinito: none | opzioni: last | whatsapp | telegram | discord | ... - prompt: "Leggi HEARTBEAT.md se esiste...", + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, timeoutSeconds: 45, @@ -1372,14 +1359,14 @@ Esecuzioni Heartbeat periodiche. ``` - `every`: stringa durata (ms/s/m/h). Predefinito: `30m` (autenticazione con chiave API) oppure `1h` (autenticazione OAuth). Imposta `0m` per disabilitare. -- `includeSystemPromptSection`: quando false, omette la sezione Heartbeat dal prompt di sistema e salta l'iniezione di `HEARTBEAT.md` nel contesto bootstrap. Predefinito: `true`. -- `suppressToolErrorWarnings`: quando true, sopprime i payload di avviso degli errori degli strumenti durante le esecuzioni Heartbeat. -- `timeoutSeconds`: tempo massimo in secondi consentito per un turno agente Heartbeat prima che venga interrotto. Lascia non impostato per usare `agents.defaults.timeoutSeconds`. -- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna a destinazione diretta. `block` sopprime la consegna a destinazione diretta ed emette `reason=dm-blocked`. -- `lightContext`: quando true, le esecuzioni Heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` tra i file bootstrap del workspace. -- `isolatedSession`: quando true, ogni Heartbeat viene eseguito in una sessione nuova senza cronologia conversazione precedente. Stesso schema di isolamento di Cron `sessionTarget: "isolated"`. Riduce il costo in token per Heartbeat da ~100K a ~2-5K token. -- Per agente: imposta `agents.list[].heartbeat`. Quando un qualunque agente definisce `heartbeat`, **solo quegli agenti** eseguono Heartbeat. -- Gli Heartbeat eseguono turni agente completi: intervalli più brevi consumano più token. +- `includeSystemPromptSection`: quando è false, omette la sezione Heartbeat dal prompt di sistema e salta l'iniezione di `HEARTBEAT.md` nel contesto bootstrap. Predefinito: `true`. +- `suppressToolErrorWarnings`: quando è true, sopprime i payload di avviso di errore degli strumenti durante le esecuzioni di Heartbeat. +- `timeoutSeconds`: tempo massimo in secondi consentito per un turno agente di Heartbeat prima che venga interrotto. Lascialo non impostato per usare `agents.defaults.timeoutSeconds`. +- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna con target diretto. `block` sopprime la consegna con target diretto ed emette `reason=dm-blocked`. +- `lightContext`: quando è true, le esecuzioni di Heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` dai file bootstrap della workspace. +- `isolatedSession`: quando è true, ogni Heartbeat viene eseguito in una sessione nuova senza cronologia di conversazione precedente. Stesso schema di isolamento di Cron `sessionTarget: "isolated"`. Riduce il costo in token per Heartbeat da ~100K a ~2-5K token. +- Per agente: imposta `agents.list[].heartbeat`. Quando un qualsiasi agente definisce `heartbeat`, **solo quegli agenti** eseguono Heartbeat. +- Gli Heartbeat eseguono turni completi dell'agente: intervalli più brevi consumano più token. ### `agents.defaults.compaction` @@ -1389,19 +1376,19 @@ Esecuzioni Heartbeat periodiche. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id di un plugin provider Compaction registrato (facoltativo) + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserva esattamente gli ID di deployment, gli ID ticket e le coppie host:port.", // usato quando identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disabilita la reiniezione - model: "openrouter/anthropic/claude-sonnet-4-6", // override facoltativo del modello solo per Compaction - notifyUser: true, // invia brevi notifiche all'utente quando Compaction inizia e termina (predefinito: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "La sessione si sta avvicinando a Compaction. Memorizza ora le memorie durevoli.", - prompt: "Scrivi eventuali note durature in memory/YYYY-MM-DD.md; rispondi con l'esatto token silenzioso NO_REPLY se non c'è nulla da memorizzare.", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1409,19 +1396,19 @@ Esecuzioni Heartbeat periodiche. } ``` -- `mode`: `default` o `safeguard` (riepilogo a blocchi per cronologie lunghe). Vedi [Compaction](/it/concepts/compaction). -- `provider`: id di un plugin provider Compaction registrato. Quando impostato, viene chiamato `summarize()` del provider invece del riepilogo LLM integrato. In caso di errore usa come fallback quello integrato. Impostare un provider forza `mode: "safeguard"`. Vedi [Compaction](/it/concepts/compaction). +- `mode`: `default` oppure `safeguard` (riassunto a blocchi per cronologie lunghe). Vedi [Compaction](/it/concepts/compaction). +- `provider`: id di un provider Plugin di Compaction registrato. Quando impostato, viene chiamato `summarize()` del provider invece del riassunto LLM integrato. In caso di errore torna al comportamento integrato. L'impostazione di un provider forza `mode: "safeguard"`. Vedi [Compaction](/it/concepts/compaction). - `timeoutSeconds`: numero massimo di secondi consentiti per una singola operazione di Compaction prima che OpenClaw la interrompa. Predefinito: `900`. -- `identifierPolicy`: `strict` (predefinito), `off` o `custom`. `strict` antepone linee guida integrate per la conservazione di identificatori opachi durante il riepilogo di Compaction. +- `identifierPolicy`: `strict` (predefinito), `off` oppure `custom`. `strict` antepone indicazioni integrate per la conservazione di identificatori opachi durante il riassunto della Compaction. - `identifierInstructions`: testo facoltativo personalizzato per la conservazione degli identificatori usato quando `identifierPolicy=custom`. -- `postCompactionSections`: nomi facoltativi di sezioni H2/H3 di AGENTS.md da reiniettare dopo Compaction. Predefinito: `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando non è impostato o è esplicitamente impostato a quella coppia predefinita, anche le vecchie intestazioni `Every Session`/`Safety` sono accettate come fallback legacy. -- `model`: override facoltativo `provider/model-id` solo per il riepilogo di Compaction. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di Compaction devono essere eseguiti con un altro; quando non è impostato, Compaction usa il modello primario della sessione. -- `notifyUser`: quando `true`, invia brevi notifiche all'utente quando Compaction inizia e quando termina (ad esempio, "Compacting context..." e "Compaction complete"). Disabilitato per impostazione predefinita per mantenere Compaction silenzioso. -- `memoryFlush`: turno agentico silenzioso prima della Compaction automatica per archiviare memorie durevoli. Saltato quando il workspace è in sola lettura. +- `postCompactionSections`: nomi facoltativi delle sezioni H2/H3 di AGENTS.md da re-iniettare dopo la Compaction. Predefinito `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la re-iniezione. Quando non è impostato o è esplicitamente impostato su quella coppia predefinita, vengono accettate anche le intestazioni legacy `Every Session`/`Safety` come fallback legacy. +- `model`: override facoltativo `provider/model-id` solo per il riassunto della Compaction. Usalo quando la sessione principale deve mantenere un modello ma i riassunti della Compaction devono essere eseguiti con un altro; se non impostato, la Compaction usa il modello primario della sessione. +- `notifyUser`: quando `true`, invia brevi notifiche all'utente quando la Compaction inizia e quando termina (per esempio, "Compacting context..." e "Compaction complete"). Disabilitato per impostazione predefinita per mantenere silenziosa la Compaction. +- `memoryFlush`: turno agentico silenzioso prima della Compaction automatica per memorizzare ricordi durevoli. Saltato quando la workspace è in sola lettura. ### `agents.defaults.contextPruning` -Esegue il pruning dei **vecchi risultati degli strumenti** dal contesto in memoria prima dell'invio all'LLM. **Non** modifica la cronologia della sessione su disco. +Rimuove **i vecchi risultati degli strumenti** dal contesto in memoria prima dell'invio all'LLM. **Non** modifica la cronologia della sessione su disco. ```json5 { @@ -1429,13 +1416,13 @@ Esegue il pruning dei **vecchi risultati degli strumenti** dal contesto in memor defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // durata (ms/s/m/h), unità predefinita: minuti + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Contenuto del vecchio risultato dello strumento cancellato]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1446,22 +1433,22 @@ Esegue il pruning dei **vecchi risultati degli strumenti** dal contesto in memor - `mode: "cache-ttl"` abilita i passaggi di pruning. -- `ttl` controlla con quale frequenza il pruning può essere eseguito di nuovo (dopo l'ultimo accesso alla cache). -- Il pruning prima tronca in modo soft i risultati degli strumenti troppo grandi, poi cancella in modo hard i risultati degli strumenti più vecchi se necessario. +- `ttl` controlla quanto spesso il pruning può essere eseguito di nuovo (dopo l'ultimo tocco della cache). +- Il pruning esegue prima un soft-trim dei risultati degli strumenti troppo grandi, poi se necessario svuota completamente i risultati degli strumenti più vecchi. -Il **soft-trim** mantiene inizio + fine e inserisce `...` nel mezzo. +**Soft-trim** mantiene l'inizio + la fine e inserisce `...` al centro. -L'**hard-clear** sostituisce l'intero risultato dello strumento con il placeholder. +**Hard-clear** sostituisce l'intero risultato dello strumento con il segnaposto. Note: -- I blocchi immagine non vengono mai troncati/cancellati. +- I blocchi immagine non vengono mai troncati/svuotati. - I rapporti sono basati sui caratteri (approssimativi), non su conteggi esatti di token. - Se esistono meno di `keepLastAssistants` messaggi dell'assistente, il pruning viene saltato. -Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli sul comportamento. +Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli del comportamento. ### Streaming a blocchi @@ -1473,17 +1460,17 @@ Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli sul comporta blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (usa minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } ``` - I canali non-Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. -- Override per canale: `channels..blockStreamingCoalesce` (e varianti per-account). Signal/Slack/Discord/Google Chat hanno come predefinito `minChars: 1500`. -- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500ms. Override per-agente: `agents.list[].humanDelay`. +- Override per canale: `channels..blockStreamingCoalesce` (e varianti per account). Signal/Slack/Discord/Google Chat usano come predefinito `minChars: 1500`. +- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500ms. Override per agente: `agents.list[].humanDelay`. -Vedi [Streaming](/it/concepts/streaming) per il comportamento e i dettagli di chunking. +Vedi [Streaming](/it/concepts/streaming) per i dettagli su comportamento + suddivisione in blocchi. ### Indicatori di digitazione @@ -1498,10 +1485,10 @@ Vedi [Streaming](/it/concepts/streaming) per il comportamento e i dettagli di ch } ``` -- Valori predefiniti: `instant` per chat dirette/menzioni, `message` per chat di gruppo senza menzione. -- Override per-sessione: `session.typingMode`, `session.typingIntervalSeconds`. +- Predefiniti: `instant` per chat dirette/menzioni, `message` per chat di gruppo senza menzione. +- Override per sessione: `session.typingMode`, `session.typingIntervalSeconds`. -Vedi [Indicatori di digitazione](/it/concepts/typing-indicators). +Vedi [Typing Indicators](/it/concepts/typing-indicators). @@ -1553,7 +1540,7 @@ Sandboxing facoltativo per l'agente embedded. Vedi [Sandboxing](/it/gateway/sand identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Sono supportati anche SecretRef / contenuti inline: + // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1602,7 +1589,7 @@ Sandboxing facoltativo per l'agente embedded. Vedi [Sandboxing](/it/gateway/sand } ``` - + **Backend:** @@ -1610,46 +1597,46 @@ Sandboxing facoltativo per l'agente embedded. Vedi [Sandboxing](/it/gateway/sand - `ssh`: runtime remoto generico basato su SSH - `openshell`: runtime OpenShell -Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del runtime vengono spostate in +Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del runtime si spostano in `plugins.entries.openshell.config`. -**Configurazione backend SSH:** +**Configurazione del backend SSH:** -- `target`: destinazione SSH nel formato `user@host[:port]` +- `target`: target SSH nel formato `user@host[:port]` - `command`: comando del client SSH (predefinito: `ssh`) -- `workspaceRoot`: root remota assoluta usata per i workspace per-scope +- `workspaceRoot`: radice remota assoluta usata per le workspace per scope - `identityFile` / `certificateFile` / `knownHostsFile`: file locali esistenti passati a OpenSSH - `identityData` / `certificateData` / `knownHostsData`: contenuti inline o SecretRef che OpenClaw materializza in file temporanei a runtime - `strictHostKeyChecking` / `updateHostKeys`: impostazioni del criterio della chiave host di OpenSSH -**Precedenza autenticazione SSH:** +**Precedenza di autenticazione SSH:** - `identityData` ha la precedenza su `identityFile` - `certificateData` ha la precedenza su `certificateFile` - `knownHostsData` ha la precedenza su `knownHostsFile` -- I valori `*Data` basati su SecretRef vengono risolti dallo snapshot runtime attivo dei segreti prima dell'avvio della sessione sandbox +- I valori `*Data` supportati da SecretRef vengono risolti dallo snapshot runtime attivo dei secret prima dell'avvio della sessione sandbox -**Comportamento backend SSH:** +**Comportamento del backend SSH:** -- inizializza una volta il workspace remoto dopo la creazione o ricreazione -- poi mantiene canonico il workspace SSH remoto +- inizializza la workspace remota una volta dopo la creazione o la ricreazione +- poi mantiene la workspace SSH remota come canonica - instrada `exec`, gli strumenti file e i percorsi media tramite SSH -- non sincronizza automaticamente le modifiche remote verso l'host +- non sincronizza automaticamente con l'host le modifiche remote - non supporta container browser sandbox -**Accesso al workspace:** +**Accesso alla workspace:** -- `none`: workspace sandbox per-scope sotto `~/.openclaw/sandboxes` -- `ro`: workspace sandbox in `/workspace`, workspace agente montato in sola lettura in `/agent` -- `rw`: workspace agente montato in lettura/scrittura in `/workspace` +- `none`: workspace sandbox per scope sotto `~/.openclaw/sandboxes` +- `ro`: workspace sandbox in `/workspace`, workspace agente montata in sola lettura in `/agent` +- `rw`: workspace agente montata in lettura/scrittura in `/workspace` **Scope:** -- `session`: container + workspace per-sessione +- `session`: container + workspace per sessione - `agent`: un container + workspace per agente (predefinito) - `shared`: container e workspace condivisi (nessun isolamento tra sessioni) -**Configurazione plugin OpenShell:** +**Configurazione del Plugin OpenShell:** ```json5 { @@ -1662,10 +1649,10 @@ Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // facoltativo - gatewayEndpoint: "https://lab.example", // facoltativo - policy: "strict", // ID criterio OpenShell facoltativo - providers: ["openai"], // facoltativo + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -1677,29 +1664,29 @@ Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del **Modalità OpenShell:** -- `mirror`: inizializza il remoto dal locale prima di exec, sincronizza di nuovo dopo exec; il workspace locale resta canonico -- `remote`: inizializza il remoto una volta quando il sandbox viene creato, poi mantiene canonico il workspace remoto +- `mirror`: inizializza il remoto dal locale prima di `exec`, sincronizza indietro dopo `exec`; la workspace locale resta canonica +- `remote`: inizializza il remoto una volta quando viene creata la sandbox, poi mantiene la workspace remota come canonica -In modalità `remote`, le modifiche locali sull'host effettuate fuori da OpenClaw non vengono sincronizzate automaticamente nel sandbox dopo il passaggio di inizializzazione. -Il trasporto avviene tramite SSH nel sandbox OpenShell, ma il plugin possiede il ciclo di vita del sandbox e l'eventuale sincronizzazione mirror. +In modalità `remote`, le modifiche locali sull'host effettuate fuori da OpenClaw non vengono sincronizzate automaticamente nella sandbox dopo il passaggio di inizializzazione. +Il trasporto è SSH nella sandbox OpenShell, ma il Plugin possiede il ciclo di vita della sandbox e l'eventuale sincronizzazione mirror. **`setupCommand`** viene eseguito una volta dopo la creazione del container (tramite `sh -lc`). Richiede uscita di rete, root scrivibile, utente root. -**I container hanno come predefinito `network: "none"`** — imposta `"bridge"` (o una rete bridge personalizzata) se l'agente ha bisogno di accesso in uscita. +**I container usano per impostazione predefinita `network: "none"`** — impostalo su `"bridge"` (o una rete bridge personalizzata) se l'agente ha bisogno di accesso in uscita. `"host"` è bloccato. `"container:"` è bloccato per impostazione predefinita a meno che tu non imposti esplicitamente `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Gli allegati in ingresso** vengono preparati in `media/inbound/*` nel workspace attivo. +**Gli allegati in entrata** vengono preparati in `media/inbound/*` nella workspace attiva. **`docker.binds`** monta directory host aggiuntive; i bind globali e per-agente vengono uniti. -**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP in un container. L'URL noVNC viene iniettato nel prompt di sistema. Non richiede `browser.enabled` in `openclaw.json`. +**Browser sandboxed** (`sandbox.browser.enabled`): Chromium + CDP in un container. L'URL noVNC viene iniettato nel prompt di sistema. Non richiede `browser.enabled` in `openclaw.json`. L'accesso osservatore noVNC usa per impostazione predefinita l'autenticazione VNC e OpenClaw emette un URL con token a breve durata (invece di esporre la password nell'URL condiviso). -- `allowHostControl: false` (predefinito) blocca le sessioni sandbox dal puntare al browser host. -- `network` ha come predefinito `openclaw-sandbox-browser` (rete bridge dedicata). Imposta `bridge` solo quando vuoi esplicitamente connettività bridge globale. -- `cdpSourceRange` limita facoltativamente l'ingresso CDP al bordo del container a un intervallo CIDR (ad esempio `172.21.0.1/32`). -- `sandbox.browser.binds` monta directory host aggiuntive solo nel container browser sandbox. Quando impostato (incluso `[]`), sostituisce `docker.binds` per il container browser. +- `allowHostControl: false` (predefinito) blocca le sessioni sandboxed che tentano di puntare al browser host. +- `network` usa per impostazione predefinita `openclaw-sandbox-browser` (rete bridge dedicata). Impostalo su `bridge` solo quando vuoi esplicitamente una connettività bridge globale. +- `cdpSourceRange` limita facoltativamente l'ingresso CDP al bordo del container a un intervallo CIDR (per esempio `172.21.0.1/32`). +- `sandbox.browser.binds` monta directory host aggiuntive solo nel container browser sandbox. Quando è impostato (incluso `[]`), sostituisce `docker.binds` per il container browser. - I valori predefiniti di avvio sono definiti in `scripts/sandbox-browser-entrypoint.sh` e ottimizzati per host container: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -1731,9 +1718,9 @@ L'accesso osservatore noVNC usa per impostazione predefinita l'autenticazione VN -Il sandboxing del browser e `sandbox.docker.binds` sono solo Docker. +Il sandboxing del browser e `sandbox.docker.binds` sono solo per Docker. -Crea le immagini: +Compila le immagini: ```bash scripts/sandbox-setup.sh # immagine sandbox principale @@ -1752,13 +1739,13 @@ scripts/sandbox-browser-setup.sh # immagine browser facoltativa name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // oppure { primary, fallbacks } - thinkingDefault: "high", // override per-agente del livello di thinking - reasoningDefault: "on", // override per-agente della visibilità del reasoning - fastModeDefault: false, // override per-agente della fast mode + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // sovrascrive per chiave i params corrispondenti di defaults.models - skills: ["docs-search"], // sostituisce agents.defaults.skills quando impostato + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1790,24 +1777,24 @@ scripts/sandbox-browser-setup.sh # immagine browser facoltativa ``` - `id`: ID agente stabile (obbligatorio). -- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se nessuno è impostato, la prima voce della lista è quella predefinita. -- `model`: la forma stringa sovrascrive solo `primary`; la forma oggetto `{ primary, fallbacks }` sovrascrive entrambi (`[]` disabilita i fallback globali). I processi Cron che sovrascrivono solo `primary` continuano comunque a ereditare i fallback predefiniti a meno che tu non imposti `fallbacks: []`. -- `params`: params stream per-agente uniti sopra la voce del modello selezionato in `agents.defaults.models`. Usalo per override specifici dell'agente come `cacheRetention`, `temperature` o `maxTokens` senza duplicare l'intero catalogo modelli. -- `skills`: allowlist Skills facoltativa per-agente. Se omessa, l'agente eredita `agents.defaults.skills` quando impostato; una lista esplicita sostituisce i valori predefiniti invece di unirli, e `[]` significa nessun Skills. -- `thinkingDefault`: livello predefinito di thinking facoltativo per-agente (`off | minimal | low | medium | high | xhigh | adaptive | max`). Sovrascrive `agents.defaults.thinkingDefault` per questo agente quando non è impostato alcun override per-messaggio o di sessione. -- `reasoningDefault`: visibilità predefinita facoltativa del reasoning per-agente (`on | off | stream`). Si applica quando non è impostato alcun override di reasoning per-messaggio o di sessione. -- `fastModeDefault`: valore predefinito facoltativo per-agente per la fast mode (`true | false`). Si applica quando non è impostato alcun override della fast mode per-messaggio o di sessione. -- `embeddedHarness`: override facoltativo per-agente del criterio harness di basso livello. Usa `{ runtime: "codex", fallback: "none" }` per rendere un agente solo-Codex mentre gli altri agenti mantengono il fallback PI predefinito. -- `runtime`: descrittore runtime facoltativo per-agente. Usa `type: "acp"` con i valori predefiniti `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando l'agente deve usare per impostazione predefinita sessioni harness ACP. -- `identity.avatar`: percorso relativo al workspace, URL `http(s)` oppure URI `data:`. -- `identity` deriva valori predefiniti: `ackReaction` da `emoji`, `mentionPatterns` da `name`/`emoji`. +- `default`: quando più agenti sono impostati, vince il primo (viene registrato un avviso). Se nessuno è impostato, il primo elemento della lista è il predefinito. +- `model`: la forma stringa sovrascrive solo `primary`; la forma oggetto `{ primary, fallbacks }` sovrascrive entrambi (`[]` disabilita i fallback globali). I job Cron che sovrascrivono solo `primary` ereditano comunque i fallback predefiniti a meno che tu non imposti `fallbacks: []`. +- `params`: parametri di stream per agente uniti sopra la voce modello selezionata in `agents.defaults.models`. Usali per override specifici dell'agente come `cacheRetention`, `temperature` o `maxTokens` senza duplicare l'intero catalogo modelli. +- `skills`: allowlist facoltativa di Skills per agente. Se omessa, l'agente eredita `agents.defaults.skills` quando è impostato; una lista esplicita sostituisce i valori predefiniti invece di unirsi a essi, e `[]` significa nessuna Skills. +- `thinkingDefault`: livello thinking predefinito facoltativo per agente (`off | minimal | low | medium | high | xhigh | adaptive | max`). Sovrascrive `agents.defaults.thinkingDefault` per questo agente quando non è impostato alcun override per messaggio o sessione. +- `reasoningDefault`: visibilità predefinita facoltativa del reasoning per agente (`on | off | stream`). Si applica quando non è impostato alcun override di reasoning per messaggio o sessione. +- `fastModeDefault`: valore predefinito facoltativo per agente per la fast mode (`true | false`). Si applica quando non è impostato alcun override di fast mode per messaggio o sessione. +- `embeddedHarness`: override facoltativo per agente del criterio dell'harness di basso livello. Usa `{ runtime: "codex", fallback: "none" }` per rendere un agente solo-Codex mentre gli altri agenti mantengono il fallback PI predefinito. +- `runtime`: descrittore runtime facoltativo per agente. Usa `type: "acp"` con i valori predefiniti di `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando l'agente deve usare come predefinito sessioni harness ACP. +- `identity.avatar`: percorso relativo alla workspace, URL `http(s)` oppure URI `data:`. +- `identity` deriva i valori predefiniti: `ackReaction` da `emoji`, `mentionPatterns` da `name`/`emoji`. - `subagents.allowAgents`: allowlist di ID agente per `sessions_spawn` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). -- Protezione ereditarietà sandbox: se la sessione richiedente è in sandbox, `sessions_spawn` rifiuta destinazioni che verrebbero eseguite senza sandbox. -- `subagents.requireAgentId`: quando true, blocca le chiamate `sessions_spawn` che omettono `agentId` (forza una selezione esplicita del profilo; predefinito: false). +- Guardia di ereditarietà sandbox: se la sessione richiedente è sandboxed, `sessions_spawn` rifiuta i target che verrebbero eseguiti senza sandbox. +- `subagents.requireAgentId`: quando è true, blocca le chiamate `sessions_spawn` che omettono `agentId` (forza la selezione esplicita del profilo; predefinito: false). --- -## Instradamento multi-agente +## Routing multi-agente Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/it/concepts/multi-agent). @@ -1826,29 +1813,29 @@ Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/ } ``` -### Campi di corrispondenza delle binding +### Campi di corrispondenza del binding -- `type` (facoltativo): `route` per l'instradamento normale (type mancante usa come predefinito route), `acp` per associazioni persistenti delle conversazioni ACP. +- `type` (facoltativo): `route` per il routing normale (se manca il tipo viene usato route), `acp` per binding conversazione ACP persistenti. - `match.channel` (obbligatorio) - `match.accountId` (facoltativo; `*` = qualsiasi account; omesso = account predefinito) - `match.peer` (facoltativo; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (facoltativo; specifici del canale) +- `match.guildId` / `match.teamId` (facoltativo; specifico del canale) - `acp` (facoltativo; solo per voci `type: "acp"`): `{ mode, label, cwd, backend }` -**Ordine deterministico di corrispondenza:** +**Ordine di corrispondenza deterministico:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (esatto, senza peer/guild/team) -5. `match.accountId: "*"` (esteso al canale) +5. `match.accountId: "*"` (a livello canale) 6. Agente predefinito All'interno di ogni livello, vince la prima voce `bindings` corrispondente. -Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine dei livelli di binding route sopra. +Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine dei livelli di binding route sopra riportato. -### Profili di accesso per-agente +### Profili di accesso per agente @@ -1943,7 +1930,7 @@ Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della c -Vedi [Sandbox & Tools multi-agente](/it/tools/multi-agent-sandbox-tools) per i dettagli sulla precedenza. +Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i dettagli sulla precedenza. --- @@ -1969,22 +1956,22 @@ Vedi [Sandbox & Tools multi-agente](/it/tools/multi-agent-sandbox-tools) per i d }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // salta il fork del thread padre sopra questo numero di token (0 disabilita) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // durata oppure false - maxDiskBytes: "500mb", // hard budget facoltativo - highWaterBytes: "400mb", // target di pulizia facoltativo + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // inattività predefinita per auto-unfocus in ore (`0` disabilita) - maxAgeHours: 0, // età massima rigida predefinita in ore (`0` disabilita) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // legacy (il runtime usa sempre "main") + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1997,33 +1984,33 @@ Vedi [Sandbox & Tools multi-agente](/it/tools/multi-agent-sandbox-tools) per i d - **`scope`**: strategia base di raggruppamento delle sessioni per i contesti di chat di gruppo. - - `per-sender` (predefinito): ogni mittente ottiene una sessione isolata all'interno di un contesto di canale. - - `global`: tutti i partecipanti in un contesto di canale condividono una singola sessione (usalo solo quando è intenzionale avere un contesto condiviso). + - `per-sender` (predefinito): ogni mittente ottiene una sessione isolata all'interno di un contesto canale. + - `global`: tutti i partecipanti in un contesto canale condividono una singola sessione (usalo solo quando è previsto un contesto condiviso). - **`dmScope`**: come vengono raggruppati i DM. - `main`: tutti i DM condividono la sessione principale. - `per-peer`: isola per ID mittente tra i canali. - `per-channel-peer`: isola per canale + mittente (consigliato per inbox multiutente). - `per-account-channel-peer`: isola per account + canale + mittente (consigliato per multi-account). -- **`identityLinks`**: mappa ID canonici a peer con prefisso provider per la condivisione delle sessioni tra canali. -- **`reset`**: criterio di reset principale. `daily` reimposta all'ora locale `atHour`; `idle` reimposta dopo `idleMinutes`. Quando entrambi sono configurati, vince quello che scade prima. +- **`identityLinks`**: mappa gli ID canonici ai peer con prefisso provider per la condivisione di sessione tra canali. +- **`reset`**: criterio di reset primario. `daily` esegue il reset a `atHour` ora locale; `idle` esegue il reset dopo `idleMinutes`. Quando entrambi sono configurati, vince quello che scade per primo. - **`resetByType`**: override per tipo (`direct`, `group`, `thread`). Il legacy `dm` è accettato come alias di `direct`. -- **`parentForkMaxTokens`**: numero massimo di `totalTokens` della sessione padre consentito quando viene creata una sessione thread derivata (predefinito `100000`). - - Se `totalTokens` del padre è sopra questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia del transcript del padre. - - Imposta `0` per disabilitare questa protezione e consentire sempre il fork dal padre. -- **`mainKey`**: campo legacy. Il runtime usa sempre `"main"` per il bucket principale della chat diretta. -- **`agentToAgent.maxPingPongTurns`**: numero massimo di turni di risposta reciproca tra agenti durante scambi agent-to-agent (intero, intervallo: `0`–`5`). `0` disabilita il chaining ping-pong. -- **`sendPolicy`**: corrispondenza per `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. La prima deny vince. -- **`maintenance`**: controlli di pulizia + retention del session-store. +- **`parentForkMaxTokens`**: massimo `totalTokens` della sessione padre consentito quando si crea una sessione thread forkata (predefinito `100000`). + - Se `totalTokens` del padre è sopra questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia della trascrizione del padre. + - Imposta `0` per disabilitare questa guardia e consentire sempre il forking del padre. +- **`mainKey`**: campo legacy. Il runtime usa sempre `"main"` per il bucket principale delle chat dirette. +- **`agentToAgent.maxPingPongTurns`**: massimo numero di turni di risposta reciproca tra agenti durante gli scambi agent-to-agent (intero, intervallo: `0`–`5`). `0` disabilita il concatenamento ping-pong. +- **`sendPolicy`**: corrisponde per `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. Il primo deny vince. +- **`maintenance`**: controlli di pulizia + conservazione dell'archivio sessioni. - `mode`: `warn` emette solo avvisi; `enforce` applica la pulizia. - - `pruneAfter`: soglia di età per le voci obsolete (predefinito `30d`). + - `pruneAfter`: soglia di età per le voci stale (predefinito `30d`). - `maxEntries`: numero massimo di voci in `sessions.json` (predefinito `500`). - `rotateBytes`: ruota `sessions.json` quando supera questa dimensione (predefinito `10mb`). - - `resetArchiveRetention`: retention per gli archivi transcript `*.reset.`. Per impostazione predefinita usa `pruneAfter`; imposta `false` per disabilitare. - - `maxDiskBytes`: budget disco facoltativo per la directory delle sessioni. In modalità `warn` registra avvisi; in modalità `enforce` rimuove prima gli artefatti/sessioni più vecchi. + - `resetArchiveRetention`: conservazione per gli archivi trascrizione `*.reset.`. Per impostazione predefinita usa `pruneAfter`; imposta `false` per disabilitare. + - `maxDiskBytes`: budget disco facoltativo per la directory delle sessioni. In modalità `warn` registra avvisi; in modalità `enforce` rimuove prima gli artifact/sessioni più vecchi. - `highWaterBytes`: target facoltativo dopo la pulizia del budget. Per impostazione predefinita è l'`80%` di `maxDiskBytes`. -- **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione associate ai thread. +- **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione vincolate ai thread. - `enabled`: interruttore master predefinito (i provider possono sovrascriverlo; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: inattività predefinita per auto-unfocus in ore (`0` disabilita; i provider possono sovrascrivere) + - `idleHours`: disancoraggio automatico predefinito per inattività in ore (`0` disabilita; i provider possono sovrascrivere) - `maxAgeHours`: età massima rigida predefinita in ore (`0` disabilita; i provider possono sovrascrivere) @@ -2035,7 +2022,7 @@ Vedi [Sandbox & Tools multi-agente](/it/tools/multi-agent-sandbox-tools) per i d ```json5 { messages: { - responsePrefix: "🦞", // oppure "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2050,7 +2037,7 @@ Vedi [Sandbox & Tools multi-agente](/it/tools/multi-agent-sandbox-tools) per i d }, }, inbound: { - debounceMs: 2000, // 0 disabilita + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -2066,32 +2053,32 @@ Override per canale/account: `channels..responsePrefix`, `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback identity. -- Ambito: `group-mentions` (predefinito), `group-all`, `direct`, `all`. +- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback dell'identità. +- Scope: `group-mentions` (predefinito), `group-all`, `direct`, `all`. - `removeAckAfterReply`: rimuove la conferma dopo la risposta su Slack, Discord e Telegram. - `messages.statusReactions.enabled`: abilita le reazioni di stato del ciclo di vita su Slack, Discord e Telegram. - Su Slack e Discord, lasciarlo non impostato mantiene abilitate le reazioni di stato quando le reazioni di conferma sono attive. + Su Slack e Discord, se non impostato mantiene abilitate le reazioni di stato quando le reazioni di conferma sono attive. Su Telegram, impostalo esplicitamente su `true` per abilitare le reazioni di stato del ciclo di vita. -### Debounce in ingresso +### Debounce in entrata -Raggruppa messaggi rapidi solo testo dello stesso mittente in un singolo turno agente. I file multimediali/gli allegati svuotano immediatamente. I comandi di controllo bypassano il debouncing. +Raggruppa i messaggi rapidi solo testo dello stesso mittente in un singolo turno agente. I media/gli allegati forzano immediatamente lo svuotamento. I comandi di controllo bypassano il debounce. ### TTS (text-to-speech) @@ -2135,10 +2122,10 @@ Raggruppa messaggi rapidi solo testo dello stesso mittente in un singolo turno a ``` - `auto` controlla la modalità auto-TTS predefinita: `off`, `always`, `inbound` oppure `tagged`. `/tts on|off` può sovrascrivere le preferenze locali e `/tts status` mostra lo stato effettivo. -- `summaryModel` sovrascrive `agents.defaults.model.primary` per l'auto-summary. -- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` ha come predefinito `false` (opt-in). +- `summaryModel` sovrascrive `agents.defaults.model.primary` per il riepilogo automatico. +- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` usa `false` come predefinito (opt-in). - Le chiavi API usano come fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` sovrascrive l'endpoint OpenAI TTS. L'ordine di risoluzione è configurazione, poi `OPENAI_TTS_BASE_URL`, poi `https://api.openai.com/v1`. +- `openai.baseUrl` sovrascrive l'endpoint TTS OpenAI. L'ordine di risoluzione è config, poi `OPENAI_TTS_BASE_URL`, poi `https://api.openai.com/v1`. - Quando `openai.baseUrl` punta a un endpoint non OpenAI, OpenClaw lo tratta come un server TTS compatibile con OpenAI e allenta la convalida di modello/voce. --- @@ -2170,12 +2157,12 @@ Valori predefiniti per la modalità Talk (macOS/iOS/Android). ``` - `talk.provider` deve corrispondere a una chiave in `talk.providers` quando sono configurati più provider Talk. -- Le chiavi Talk flat legacy (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono solo per compatibilità e vengono migrate automaticamente in `talk.providers.`. +- Le chiavi Talk legacy flat (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono solo per compatibilità e vengono migrate automaticamente in `talk.providers.`. - Gli ID voce usano come fallback `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. -- `providers.*.apiKey` accetta stringhe plaintext oppure oggetti SecretRef. +- `providers.*.apiKey` accetta stringhe in chiaro o oggetti SecretRef. - Il fallback `ELEVENLABS_API_KEY` si applica solo quando non è configurata alcuna chiave API Talk. -- `providers.*.voiceAliases` consente alle direttive Talk di usare nomi descrittivi. -- `silenceTimeoutMs` controlla quanto a lungo la modalità Talk attende dopo il silenzio dell'utente prima di inviare la trascrizione. Se non impostato, mantiene la finestra di pausa predefinita della piattaforma (`700 ms su macOS e Android, 900 ms su iOS`). +- `providers.*.voiceAliases` consente alle direttive Talk di usare nomi amichevoli. +- `silenceTimeoutMs` controlla per quanto tempo la modalità Talk attende dopo il silenzio dell'utente prima di inviare la trascrizione. Se non impostato, mantiene la finestra di pausa predefinita della piattaforma (`700 ms su macOS e Android, 900 ms su iOS`). --- @@ -2185,35 +2172,35 @@ Valori predefiniti per la modalità Talk (macOS/iOS/Android). `tools.profile` imposta una allowlist di base prima di `tools.allow`/`tools.deny`: -L'onboarding locale imposta come predefinito per le nuove configurazioni locali `tools.profile: "coding"` quando non è impostato (i profili espliciti esistenti vengono preservati). +L'onboarding locale imposta per default le nuove configurazioni locali su `tools.profile: "coding"` quando non è impostato (i profili espliciti esistenti vengono preservati). -| Profilo | Include | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | solo `session_status` | +| Profilo | Include | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | solo `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Nessuna restrizione (uguale a non impostato) | +| `full` | Nessuna restrizione (uguale a non impostato) | ### Gruppi di strumenti -| Gruppo | Strumenti | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` è accettato come alias di `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Gruppo | Strumenti | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` è accettato come alias di `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Tutti gli strumenti integrati (esclude i plugin provider) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Tutti gli strumenti integrati (esclude i plugin provider) | ### `tools.allow` / `tools.deny` -Criterio globale di allow/deny degli strumenti (deny vince). Non distingue tra maiuscole e minuscole, supporta wildcard `*`. Applicato anche quando il sandbox Docker è disattivato. +Criterio globale allow/deny degli strumenti (deny vince). Case-insensitive, supporta wildcard `*`. Applicato anche quando la sandbox Docker è disattivata. ```json5 { @@ -2239,7 +2226,7 @@ Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: pro ### `tools.elevated` -Controlla l'accesso exec elevated fuori dal sandbox: +Controlla l'accesso exec elevato fuori dalla sandbox: ```json5 { @@ -2255,9 +2242,9 @@ Controlla l'accesso exec elevated fuori dal sandbox: } ``` -- L'override per-agente (`agents.list[].tools.elevated`) può solo restringere ulteriormente. -- `/elevated on|off|ask|full` memorizza lo stato per sessione; le direttive inline si applicano al singolo messaggio. -- `exec` elevated bypassa il sandboxing e usa il percorso di escape configurato (`gateway` per impostazione predefinita, oppure `node` quando la destinazione exec è `node`). +- L'override per agente (`agents.list[].tools.elevated`) può solo restringere ulteriormente. +- `/elevated on|off|ask|full` memorizza lo stato per sessione; le direttive inline si applicano a un singolo messaggio. +- `exec` elevato bypassa il sandboxing e usa il percorso di escape configurato (`gateway` per impostazione predefinita, oppure `node` quando il target exec è `node`). ### `tools.exec` @@ -2281,8 +2268,8 @@ Controlla l'accesso exec elevated fuori dal sandbox: ### `tools.loopDetection` -I controlli di sicurezza del loop degli strumenti sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. -Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sovrascritte per-agente in `agents.list[].tools.loopDetection`. +I controlli di sicurezza dei loop degli strumenti sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. +Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sovrascritte per agente in `agents.list[].tools.loopDetection`. ```json5 { @@ -2303,13 +2290,13 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s } ``` -- `historySize`: cronologia massima delle chiamate agli strumenti mantenuta per l'analisi dei loop. +- `historySize`: massimo storico delle chiamate strumento conservato per l'analisi dei loop. - `warningThreshold`: soglia del pattern ripetuto senza progresso per gli avvisi. - `criticalThreshold`: soglia ripetuta più alta per bloccare i loop critici. -- `globalCircuitBreakerThreshold`: soglia di arresto rigida per qualsiasi esecuzione senza progresso. -- `detectors.genericRepeat`: avvisa in caso di chiamate ripetute stesso-strumento/stessi-argomenti. -- `detectors.knownPollNoProgress`: avvisa/blocca sugli strumenti poll noti (`process.poll`, `command_status`, ecc.). -- `detectors.pingPong`: avvisa/blocca sui pattern alternati a coppie senza progresso. +- `globalCircuitBreakerThreshold`: soglia di stop rigido per qualsiasi esecuzione senza progresso. +- `detectors.genericRepeat`: avvisa in caso di chiamate ripetute allo stesso strumento/con gli stessi argomenti. +- `detectors.knownPollNoProgress`: avvisa/blocca i noti strumenti di polling (`process.poll`, `command_status`, ecc.). +- `detectors.pingPong`: avvisa/blocca i pattern a coppie alternate senza progresso. - Se `warningThreshold >= criticalThreshold` oppure `criticalThreshold >= globalCircuitBreakerThreshold`, la convalida fallisce. ### `tools.web` @@ -2320,14 +2307,14 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s web: { search: { enabled: true, - apiKey: "brave_api_key", // oppure env BRAVE_API_KEY + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // facoltativo; omettilo per il rilevamento automatico + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2344,7 +2331,7 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s ### `tools.media` -Configura la comprensione dei file multimediali in ingresso (immagine/audio/video): +Configura la comprensione dei media in entrata (immagine/audio/video): ```json5 { @@ -2352,7 +2339,7 @@ Configura la comprensione dei file multimediali in ingresso (immagine/audio/vide media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: invia direttamente al canale i contenuti musicali/video asincroni completati + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2376,32 +2363,32 @@ Configura la comprensione dei file multimediali in ingresso (immagine/audio/vide } ``` - + -**Voce provider** (`type: "provider"` oppure omesso): +**Voce provider** (`type: "provider"` o omesso): -- `provider`: ID provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) -- `model`: override dell'ID modello -- `profile` / `preferredProfile`: selezione del profilo `auth-profiles.json` +- `provider`: id del provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) +- `model`: override dell'id modello +- `profile` / `preferredProfile`: selezione del profilo in `auth-profiles.json` **Voce CLI** (`type: "cli"`): - `command`: eseguibile da avviare -- `args`: argomenti template (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) +- `args`: argomenti con template (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) **Campi comuni:** - `capabilities`: elenco facoltativo (`image`, `audio`, `video`). Predefiniti: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: override per voce. -- In caso di errore si usa come fallback la voce successiva. +- In caso di errore, si passa alla voce successiva. L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → variabili env → `models.providers.*.apiKey`. **Campi di completamento asincrono:** -- `asyncCompletion.directSend`: quando `true`, i task asincroni completati `music_generate` +- `asyncCompletion.directSend`: quando è `true`, le attività asincrone completate di `music_generate` e `video_generate` provano prima la consegna diretta al canale. Predefinito: `false` - (percorso legacy di riattivazione della sessione richiedente/consegna del modello). + (percorso legacy di riattivazione sessione richiedente/consegna del modello). @@ -2420,9 +2407,9 @@ L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → ### `tools.sessions` -Controlla quali sessioni possono essere usate come destinazione dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). +Controlla quali sessioni possono essere destinazione degli strumenti sessione (`sessions_list`, `sessions_history`, `sessions_send`). -Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i sottoagenti). +Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagenti). ```json5 { @@ -2438,25 +2425,25 @@ Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i sotto Note: - `self`: solo la chiave della sessione corrente. -- `tree`: sessione corrente + sessioni generate dalla sessione corrente (sottoagenti). -- `agent`: qualsiasi sessione appartenente all'ID agente corrente (può includere altri utenti se esegui sessioni per-mittente sotto lo stesso ID agente). +- `tree`: sessione corrente + sessioni generate dalla sessione corrente (subagenti). +- `agent`: qualsiasi sessione appartenente all'id agente corrente (può includere altri utenti se esegui sessioni per-mittente sotto lo stesso id agente). - `all`: qualsiasi sessione. Il targeting cross-agent richiede comunque `tools.agentToAgent`. -- Restrizione sandbox: quando la sessione corrente è in sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. +- Blocco sandbox: quando la sessione corrente è sandboxed e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Controlla il supporto agli allegati inline per `sessions_spawn`. +Controlla il supporto degli allegati inline per `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: imposta true per consentire allegati file inline - maxTotalBytes: 5242880, // 5 MB totali su tutti i file + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // mantiene gli allegati quando cleanup="keep" + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2466,21 +2453,21 @@ Controlla il supporto agli allegati inline per `sessions_spawn`. Note: - Gli allegati sono supportati solo per `runtime: "subagent"`. Il runtime ACP li rifiuta. -- I file vengono materializzati nel workspace figlio in `.openclaw/attachments//` con un `.manifest.json`. +- I file vengono materializzati nella workspace figlia in `.openclaw/attachments//` con un `.manifest.json`. - Il contenuto degli allegati viene automaticamente redatto dalla persistenza del transcript. -- Gli input Base64 vengono convalidati con controlli rigorosi su alfabeto/padding e una protezione sulla dimensione prima della decodifica. +- Gli input Base64 vengono convalidati con controlli rigorosi su alfabeto/padding e con una guardia di dimensione prima della decodifica. - I permessi dei file sono `0700` per le directory e `0600` per i file. - La pulizia segue il criterio `cleanup`: `delete` rimuove sempre gli allegati; `keep` li conserva solo quando `retainOnSessionKeep: true`. ### `tools.experimental` -Flag sperimentali degli strumenti integrati. Disattivati per impostazione predefinita a meno che non si applichi una regola di auto-abilitazione rigorosamente agentic di GPT-5. +Flag sperimentali degli strumenti integrati. Disattivati per impostazione predefinita, a meno che non si applichi una regola di auto-abilitazione strict-agentic GPT-5. ```json5 { tools: { experimental: { - planTool: true, // abilita l'update_plan sperimentale + planTool: true, // enable experimental update_plan }, }, } @@ -2488,9 +2475,9 @@ Flag sperimentali degli strumenti integrati. Disattivati per impostazione predef Note: -- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori non banali a più fasi. -- Predefinito: `false` a meno che `agents.defaults.embeddedPi.executionContract` (o un override per-agente) sia impostato su `"strict-agentic"` per un'esecuzione OpenAI o OpenAI Codex della famiglia GPT-5. Imposta `true` per forzare l'attivazione dello strumento fuori da tale ambito, oppure `false` per mantenerlo disattivato anche per le esecuzioni GPT-5 strict-agentic. -- Quando è abilitato, il prompt di sistema aggiunge anche linee guida d'uso così il modello lo usa solo per lavori sostanziali e mantiene al massimo una fase `in_progress`. +- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento del lavoro non banale in più fasi. +- Predefinito: `false` a meno che `agents.defaults.embeddedPi.executionContract` (o un override per agente) sia impostato su `"strict-agentic"` per un'esecuzione OpenAI o OpenAI Codex della famiglia GPT-5. Imposta `true` per forzare l'attivazione dello strumento fuori da quell'ambito, oppure `false` per mantenerlo disattivato anche per le esecuzioni strict-agentic GPT-5. +- Quando è abilitato, il prompt di sistema aggiunge anche indicazioni d'uso in modo che il modello lo usi solo per lavoro sostanziale e mantenga al massimo un passaggio `in_progress`. ### `agents.defaults.subagents` @@ -2510,10 +2497,10 @@ Note: } ``` -- `model`: modello predefinito per i sottoagenti generati. Se omesso, i sottoagenti ereditano il modello del chiamante. -- `allowAgents`: allowlist predefinita degli ID agente di destinazione per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). -- `runTimeoutSeconds`: timeout predefinito (secondi) per `sessions_spawn` quando la chiamata allo strumento omette `runTimeoutSeconds`. `0` significa nessun timeout. -- Criterio strumenti per-sottoagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: modello predefinito per i subagenti generati. Se omesso, i subagenti ereditano il modello del chiamante. +- `allowAgents`: allowlist predefinita degli ID agente target per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). +- `runTimeoutSeconds`: timeout predefinito (secondi) per `sessions_spawn` quando la chiamata strumento omette `runTimeoutSeconds`. `0` significa nessun timeout. +- Criterio strumenti per subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -2524,7 +2511,7 @@ OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tra ```json5 { models: { - mode: "merge", // merge (predefinito) | replace + mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2549,47 +2536,47 @@ OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tra ``` - Usa `authHeader: true` + `headers` per esigenze di autenticazione personalizzate. -- Sovrascrivi la root di configurazione dell'agente con `OPENCLAW_AGENT_DIR` (oppure `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). -- Precedenza di merge per ID provider corrispondenti: +- Sovrascrivi la radice della configurazione dell'agente con `OPENCLAW_AGENT_DIR` (oppure `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). +- Precedenza di unione per ID provider corrispondenti: - I valori `baseUrl` non vuoti di `models.json` dell'agente hanno la precedenza. - - I valori `apiKey` non vuoti dell'agente hanno la precedenza solo quando quel provider non è gestito da SecretRef nel contesto corrente config/auth-profile. - - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker di origine (`ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec) invece di persistere i segreti risolti. - - I valori header del provider gestiti da SecretRef vengono aggiornati dai marker di origine (`secretref-env:ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec). + - I valori `apiKey` non vuoti dell'agente hanno la precedenza solo quando quel provider non è gestito da SecretRef nel contesto attuale di config/profilo auth. + - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker della sorgente (`ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec) invece di persistere i secret risolti. + - I valori header del provider gestiti da SecretRef vengono aggiornati dai marker della sorgente (`secretref-env:ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec). - `apiKey`/`baseUrl` dell'agente vuoti o mancanti usano come fallback `models.providers` nella configurazione. - - I valori `contextWindow`/`maxTokens` del modello corrispondente usano il valore più alto tra configurazione esplicita e valori impliciti del catalogo. - - Il valore `contextTokens` del modello corrispondente preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza modificare i metadati nativi del modello. + - `contextWindow`/`maxTokens` del modello corrispondente usano il valore più alto tra i valori espliciti di configurazione e i valori impliciti del catalogo. + - `contextTokens` del modello corrispondente preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza modificare i metadati nativi del modello. - Usa `models.mode: "replace"` quando vuoi che la configurazione riscriva completamente `models.json`. - - La persistenza dei marker è source-authoritative: i marker vengono scritti dallo snapshot attivo della configurazione sorgente (prima della risoluzione), non dai valori segreti runtime risolti. + - La persistenza dei marker è autorevole rispetto alla sorgente: i marker vengono scritti dallo snapshot attivo della configurazione sorgente (pre-risoluzione), non dai valori secret runtime risolti. ### Dettagli dei campi del provider -- `models.mode`: comportamento del catalogo provider (`merge` o `replace`). -- `models.providers`: mappa di provider personalizzati indicizzata per ID provider. +- `models.mode`: comportamento del catalogo provider (`merge` oppure `replace`). +- `models.providers`: mappa dei provider personalizzati indicizzata per id provider. - `models.providers.*.api`: adattatore di richiesta (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, ecc.). -- `models.providers.*.apiKey`: credenziale del provider (preferisci SecretRef/sostituzione env). +- `models.providers.*.apiKey`: credenziale del provider (preferire SecretRef/sostituzione env). - `models.providers.*.auth`: strategia di autenticazione (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: per Ollama + `openai-completions`, inietta `options.num_ctx` nelle richieste (predefinito: `true`). - `models.providers.*.authHeader`: forza il trasporto della credenziale nell'header `Authorization` quando richiesto. - `models.providers.*.baseUrl`: URL base dell'API upstream. -- `models.providers.*.headers`: header statici extra per instradamento proxy/tenant. -- `models.providers.*.request`: override del trasporto per le richieste HTTP del provider di modelli. +- `models.providers.*.headers`: header statici extra per il routing proxy/tenant. +- `models.providers.*.request`: override di trasporto per le richieste HTTP del model-provider. - `request.headers`: header extra (uniti ai valori predefiniti del provider). I valori accettano SecretRef. - `request.auth`: override della strategia di autenticazione. Modalità: `"provider-default"` (usa l'autenticazione integrata del provider), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` facoltativo). - `request.proxy`: override del proxy HTTP. Modalità: `"env-proxy"` (usa le variabili env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Entrambe le modalità accettano un sotto-oggetto `tls` facoltativo. - - `request.tls`: override TLS per le connessioni dirette. Campi: `ca`, `cert`, `key`, `passphrase` (tutti accettano SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: quando `true`, consente HTTPS verso `baseUrl` quando il DNS risolve a intervalli privati, CGNAT o simili, tramite la protezione fetch HTTP del provider (opt-in dell'operatore per endpoint OpenAI-compatibili self-hosted fidati). WebSocket usa lo stesso `request` per header/TLS ma non quella protezione SSRF di fetch. Predefinito `false`. + - `request.tls`: override TLS per connessioni dirette. Campi: `ca`, `cert`, `key`, `passphrase` (tutti accettano SecretRef), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork`: quando è `true`, consente HTTPS verso `baseUrl` quando il DNS si risolve in intervalli privati, CGNAT o simili, tramite la guardia fetch HTTP del provider (opt-in dell'operatore per endpoint OpenAI-compatibili self-hosted attendibili). WebSocket usa lo stesso `request` per header/TLS ma non quella guardia SSRF del fetch. Predefinito `false`. - `models.providers.*.models`: voci esplicite del catalogo modelli del provider. - `models.providers.*.models.*.contextWindow`: metadati della finestra di contesto nativa del modello. -- `models.providers.*.models.*.contextTokens`: limite di contesto runtime facoltativo. Usalo quando vuoi un budget di contesto effettivo più piccolo della `contextWindow` nativa del modello. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: hint di compatibilità facoltativo. Per `api: "openai-completions"` con un `baseUrl` non vuoto e non nativo (host diverso da `api.openai.com`), OpenClaw lo forza a `false` a runtime. `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. -- `models.providers.*.models.*.compat.requiresStringContent`: hint di compatibilità facoltativo per endpoint chat OpenAI-compatibili che accettano solo stringhe. Quando `true`, OpenClaw appiattisce gli array `messages[].content` di puro testo in stringhe semplici prima di inviare la richiesta. -- `plugins.entries.amazon-bedrock.config.discovery`: root delle impostazioni di auto-discovery di Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: attiva/disattiva la discovery implicita. -- `plugins.entries.amazon-bedrock.config.discovery.region`: regione AWS per la discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo per ID provider per una discovery mirata. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervallo di polling per il refresh della discovery. +- `models.providers.*.models.*.contextTokens`: limite facoltativo del contesto runtime. Usalo quando vuoi un budget di contesto effettivo più piccolo rispetto a `contextWindow` nativo del modello. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: hint di compatibilità facoltativo. Per `api: "openai-completions"` con un `baseUrl` non nativo non vuoto (host diverso da `api.openai.com`), OpenClaw lo forza a `false` a runtime. `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. +- `models.providers.*.models.*.compat.requiresStringContent`: hint di compatibilità facoltativo per endpoint chat OpenAI-compatibili che accettano solo stringhe. Quando è `true`, OpenClaw appiattisce gli array `messages[].content` di puro testo in stringhe semplici prima di inviare la richiesta. +- `plugins.entries.amazon-bedrock.config.discovery`: radice delle impostazioni di auto-discovery di Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: attiva/disattiva il discovery implicito. +- `plugins.entries.amazon-bedrock.config.discovery.region`: regione AWS per il discovery. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo provider-id per discovery mirato. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervallo di polling per l'aggiornamento del discovery. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: finestra di contesto di fallback per i modelli scoperti. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: numero massimo di token in uscita di fallback per i modelli scoperti. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token massimi di output di fallback per i modelli scoperti. ### Esempi di provider @@ -2704,11 +2691,11 @@ Imposta `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` sono alias accettati. Scorciatoia: `o } ``` -Per l'endpoint Cina: `baseUrl: "https://api.moonshot.cn/v1"` oppure `openclaw onboard --auth-choice moonshot-api-key-cn`. +Per l'endpoint China: `baseUrl: "https://api.moonshot.cn/v1"` oppure `openclaw onboard --auth-choice moonshot-api-key-cn`. Gli endpoint Moonshot nativi dichiarano compatibilità d'uso dello streaming sul trasporto condiviso -`openai-completions`, e OpenClaw si basa sulle capacità dell'endpoint -piuttosto che solo sull'ID provider integrato. +`openai-completions`, e OpenClaw si basa su tali capacità dell'endpoint +anziché solo sull'id del provider integrato. @@ -2765,7 +2752,7 @@ Compatibile con Anthropic, provider integrato. Scorciatoia: `openclaw onboard -- } ``` -Il base URL dovrebbe omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: `openclaw onboard --auth-choice synthetic-api-key`. +Il base URL deve omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2809,16 +2796,16 @@ Imposta `MINIMAX_API_KEY`. Scorciatoie: `openclaw onboard --auth-choice minimax-global-api` oppure `openclaw onboard --auth-choice minimax-cn-api`. Il catalogo modelli usa come predefinito solo M2.7. -Nel percorso di streaming compatibile con Anthropic, OpenClaw disabilita il thinking di MiniMax -per impostazione predefinita a meno che tu non imposti esplicitamente `thinking`. `/fast on` oppure -`params.fastMode: true` riscrivono `MiniMax-M2.7` in +Nel percorso di streaming Anthropic-compatible, OpenClaw disabilita il thinking di MiniMax +per impostazione predefinita, a meno che tu non imposti esplicitamente `thinking`. `/fast on` oppure +`params.fastMode: true` riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. -Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware adeguato; mantieni uniti i modelli hosted per il fallback. +Vedi [Local Models](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware serio; mantieni uniti i modelli hosted per il fallback. @@ -2839,7 +2826,7 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // oppure stringa plaintext + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2849,14 +2836,14 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode } ``` -- `allowBundled`: allowlist facoltativa solo per le Skills incluse (le Skills gestite/del workspace non sono interessate). -- `load.extraDirs`: root Skills condivise extra (precedenza più bassa). -- `install.preferBrew`: quando true, preferisce gli installer Homebrew quando `brew` è - disponibile prima di usare come fallback altri tipi di installer. -- `install.nodeManager`: preferenza del gestore Node per le specifiche - `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` disabilita una Skills anche se inclusa/installata. -- `entries..apiKey`: comodità per le Skills che dichiarano una variabile env primaria (stringa plaintext o oggetto SecretRef). +- `allowBundled`: allowlist facoltativa solo per le Skills bundled (le Skills managed/workspace non sono interessate). +- `load.extraDirs`: radici condivise aggiuntive delle Skills (precedenza più bassa). +- `install.preferBrew`: quando è true, preferisce i programmi di installazione Homebrew quando `brew` è + disponibile, prima di tornare ad altri tipi di installer. +- `install.nodeManager`: preferenza del gestore Node per le specifiche `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` disabilita una Skill anche se bundled/installata. +- `entries..apiKey`: comodità per le Skills che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). --- @@ -2885,42 +2872,42 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode ``` - Caricati da `~/.openclaw/extensions`, `/.openclaw/extensions`, più `plugins.load.paths`. -- La discovery accetta plugin OpenClaw nativi più bundle Codex compatibili e bundle Claude, inclusi bundle Claude senza manifest con layout predefinito. +- Il discovery accetta plugin OpenClaw nativi più bundle Codex compatibili e bundle Claude, inclusi i bundle Claude senza manifest con layout predefinito. - **Le modifiche di configurazione richiedono un riavvio del Gateway.** - `allow`: allowlist facoltativa (si caricano solo i plugin elencati). `deny` ha la precedenza. - `plugins.entries..apiKey`: campo di comodità per la chiave API a livello plugin (quando supportato dal plugin). - `plugins.entries..env`: mappa di variabili env con ambito plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, il core blocca `before_prompt_build` e ignora i campi che mutano il prompt del legacy `before_agent_start`, preservando però `modelOverride` e `providerOverride` legacy. Si applica agli hook dei plugin nativi e alle directory hook fornite dai bundle supportati. -- `plugins.entries..subagent.allowModelOverride`: considera esplicitamente affidabile questo plugin per richiedere override per-esecuzione di `provider` e `model` per le esecuzioni di sottoagenti in background. -- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di destinazioni canoniche `provider/model` per gli override affidabili dei sottoagenti. Usa `"*"` solo quando vuoi intenzionalmente consentire qualsiasi modello. +- `plugins.entries..hooks.allowPromptInjection`: quando è `false`, il core blocca `before_prompt_build` e ignora i campi legacy che mutano il prompt da `before_agent_start`, preservando però `modelOverride` e `providerOverride` legacy. Si applica agli hook dei plugin nativi e alle directory hook fornite dai bundle supportati. +- `plugins.entries..subagent.allowModelOverride`: si fida esplicitamente di questo plugin per richiedere override per esecuzione di `provider` e `model` per le esecuzioni di subagenti in background. +- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di target canonici `provider/model` per override fidati dei subagenti. Usa `"*"` solo quando vuoi intenzionalmente consentire qualsiasi modello. - `plugins.entries..config`: oggetto di configurazione definito dal plugin (convalidato dallo schema del plugin OpenClaw nativo quando disponibile). - `plugins.entries.firecrawl.config.webFetch`: impostazioni del provider web-fetch Firecrawl. - - `apiKey`: chiave API Firecrawl (accetta SecretRef). Usa come fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, il legacy `tools.web.fetch.firecrawl.apiKey` o la variabile env `FIRECRAWL_API_KEY`. + - `apiKey`: chiave API Firecrawl (accetta SecretRef). Usa come fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, il legacy `tools.web.fetch.firecrawl.apiKey` oppure la variabile env `FIRECRAWL_API_KEY`. - `baseUrl`: URL base API Firecrawl (predefinito: `https://api.firecrawl.dev`). - `onlyMainContent`: estrae solo il contenuto principale dalle pagine (predefinito: `true`). - `maxAgeMs`: età massima della cache in millisecondi (predefinito: `172800000` / 2 giorni). - `timeoutSeconds`: timeout della richiesta di scraping in secondi (predefinito: `60`). -- `plugins.entries.xai.config.xSearch`: impostazioni di xAI X Search (ricerca web Grok). +- `plugins.entries.xai.config.xSearch`: impostazioni xAI X Search (ricerca web Grok). - `enabled`: abilita il provider X Search. - `model`: modello Grok da usare per la ricerca (ad es. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: impostazioni memory dreaming. Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. - - `enabled`: interruttore principale dreaming (predefinito `false`). - - `frequency`: cadenza Cron per ogni sweep completa di Dreaming (predefinito `"0 3 * * *"`). - - il criterio di fase e le soglie sono dettagli di implementazione (non chiavi di configurazione visibili all'utente). -- La configurazione completa della memoria si trova in [Riferimento configurazione Memory](/it/reference/memory-config): +- `plugins.entries.memory-core.config.dreaming`: impostazioni del Dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. + - `enabled`: interruttore principale del Dreaming (predefinito `false`). + - `frequency`: cadenza Cron per ogni sweep completo di Dreaming (predefinito `"0 3 * * *"`). + - il criterio di fase e le soglie sono dettagli implementativi (non chiavi di configurazione rivolte all'utente). +- La configurazione completa della memoria si trova in [Memory configuration reference](/it/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- I plugin bundle Claude abilitati possono anche contribuire con valori predefiniti embedded Pi da `settings.json`; OpenClaw li applica come impostazioni agente sanificate, non come patch raw della configurazione OpenClaw. -- `plugins.slots.memory`: seleziona l'ID del plugin memoria attivo oppure `"none"` per disabilitare i plugin memoria. -- `plugins.slots.contextEngine`: seleziona l'ID del plugin motore di contesto attivo; per impostazione predefinita è `"legacy"` a meno che tu non installi e selezioni un altro motore. +- I plugin bundle Claude abilitati possono anche contribuire con valori predefiniti embedded Pi da `settings.json`; OpenClaw li applica come impostazioni sanificate dell'agente, non come patch raw della configurazione di OpenClaw. +- `plugins.slots.memory`: scegli l'id del plugin memoria attivo, oppure `"none"` per disabilitare i plugin memoria. +- `plugins.slots.contextEngine`: scegli l'id del plugin motore di contesto attivo; per impostazione predefinita è `"legacy"` a meno che tu non installi e selezioni un altro motore. - `plugins.installs`: metadati di installazione gestiti dalla CLI usati da `openclaw plugins update`. - Include `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - Tratta `plugins.installs.*` come stato gestito; preferisci i comandi CLI alle modifiche manuali. -Vedi [Plugin](/it/tools/plugin). +Vedi [Plugins](/it/tools/plugin). --- @@ -2933,8 +2920,8 @@ Vedi [Plugin](/it/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt-in solo per accesso fidato a reti private - // allowPrivateNetwork: true, // alias legacy + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2962,28 +2949,28 @@ Vedi [Plugin](/it/tools/plugin). - `evaluateEnabled: false` disabilita `act:evaluate` e `wait --fn`. - `ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato quando non impostato, quindi la navigazione del browser resta rigorosa per impostazione predefinita. -- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo quando ti fidi intenzionalmente della navigazione del browser su reti private. -- In modalità rigorosa, gli endpoint del profilo CDP remoto (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco di rete privata durante i controlli di raggiungibilità/discovery. -- `ssrfPolicy.allowPrivateNetwork` continua a essere supportato come alias legacy. +- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo quando ti fidi intenzionalmente della navigazione del browser sulla rete privata. +- In modalità rigorosa, gli endpoint dei profili CDP remoti (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco della rete privata durante i controlli di raggiungibilità/discovery. +- `ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy. - In modalità rigorosa, usa `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` per eccezioni esplicite. - I profili remoti sono solo attach-only (start/stop/reset disabilitati). - `profiles.*.cdpUrl` accetta `http://`, `https://`, `ws://` e `wss://`. Usa HTTP(S) quando vuoi che OpenClaw scopra `/json/version`; usa WS(S) - quando il provider ti fornisce un URL WebSocket DevTools diretto. + quando il tuo provider ti fornisce un URL WebSocket DevTools diretto. - I profili `existing-session` usano Chrome MCP invece di CDP e possono collegarsi all'host selezionato o tramite un browser Node connesso. - I profili `existing-session` possono impostare `userDataDir` per puntare a uno specifico - profilo di browser basato su Chromium come Brave o Edge. -- I profili `existing-session` mantengono gli attuali limiti del percorso Chrome MCP: - azioni guidate da snapshot/ref invece del targeting tramite selettore CSS, hook di upload di un solo file, - nessun override del timeout delle finestre di dialogo, nessun `wait --load networkidle`, e nessun - `responsebody`, esportazione PDF, intercettazione download o azioni batch. + profilo di browser basato su Chromium, come Brave o Edge. +- I profili `existing-session` mantengono gli attuali limiti di routing di Chrome MCP: + azioni guidate da snapshot/ref invece del targeting tramite selettore CSS, hook di upload + di un solo file, nessun override del timeout dei dialoghi, nessun `wait --load networkidle` + e nessun `responsebody`, esportazione PDF, intercettazione download o azioni batch. - I profili `openclaw` gestiti localmente assegnano automaticamente `cdpPort` e `cdpUrl`; imposta - `cdpUrl` esplicitamente solo per CDP remoto. -- Ordine di rilevamento automatico: browser predefinito se basato su Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Servizio di controllo: solo loopback (porta derivata da `gateway.port`, predefinito `18791`). -- `extraArgs` aggiunge flag di avvio extra allo startup locale di Chromium (ad esempio - `--disable-gpu`, dimensione finestra o flag di debug). + `cdpUrl` esplicitamente solo per il CDP remoto. +- Ordine di auto-rilevamento: browser predefinito se basato su Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Servizio di controllo: solo loopback (porta derivata da `gateway.port`, predefinita `18791`). +- `extraArgs` aggiunge flag di avvio extra all'avvio locale di Chromium (per esempio + `--disable-gpu`, dimensionamento della finestra o flag di debug). --- @@ -2995,14 +2982,14 @@ Vedi [Plugin](/it/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, testo breve, URL immagine o URI data + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` -- `seamColor`: colore di accento per la UI chrome dell'app nativa (tinta della bolla in modalità Talk, ecc.). -- `assistant`: override dell'identità della Control UI. Usa come fallback l'identità dell'agente attivo. +- `seamColor`: colore d'accento per il chrome dell'interfaccia nativa dell'app (tinta della bolla della modalità Talk, ecc.). +- `assistant`: override dell'identità dell'interfaccia di controllo. Usa come fallback l'identità dell'agente attivo. --- @@ -3017,8 +3004,8 @@ Vedi [Plugin](/it/tools/plugin). auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // oppure OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // per mode=trusted-proxy; vedi /gateway/trusted-proxy-auth + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3036,9 +3023,9 @@ Vedi [Plugin](/it/tools/plugin). basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // pericoloso: consente URL assoluti esterni http(s) per embed - // allowedOrigins: ["https://control.example.com"], // richiesto per Control UI non loopback - // dangerouslyAllowHostHeaderOriginFallback: false, // modalità pericolosa di fallback dell'origine tramite header Host + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3049,12 +3036,12 @@ Vedi [Plugin](/it/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Facoltativo. Predefinito false. + // Optional. Default false. allowRealIpFallback: false, tools: { - // deny HTTP aggiuntive per /tools/invoke + // Additional /tools/invoke HTTP denies deny: ["browser"], - // Rimuove strumenti dalla deny list HTTP predefinita + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -3071,44 +3058,44 @@ Vedi [Plugin](/it/tools/plugin). -- `mode`: `local` (esegue il Gateway) oppure `remote` (si collega a un Gateway remoto). Il Gateway rifiuta di avviarsi a meno che sia `local`. -- `port`: singola porta multiplexata per WS + HTTP. Precedenza: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local` (esegue il Gateway) oppure `remote` (si connette a un Gateway remoto). Il Gateway rifiuta di avviarsi a meno che non sia `local`. +- `port`: porta singola multiplexata per WS + HTTP. Precedenza: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (predefinito), `lan` (`0.0.0.0`), `tailnet` (solo IP Tailscale) oppure `custom`. -- **Alias bind legacy**: usa i valori della modalità bind in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), non alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Nota Docker**: il bind predefinito `loopback` ascolta su `127.0.0.1` dentro il container. Con il networking bridge di Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il Gateway non è raggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. -- **Auth**: obbligatoria per impostazione predefinita. I bind non loopback richiedono l'autenticazione del Gateway. In pratica questo significa un token/password condiviso oppure un reverse proxy identity-aware con `gateway.auth.mode: "trusted-proxy"`. La procedura guidata di onboarding genera un token per impostazione predefinita. -- Se sia `gateway.auth.token` sia `gateway.auth.password` sono configurati (inclusi SecretRef), imposta esplicitamente `gateway.auth.mode` su `token` oppure `password`. L'avvio e i flussi di installazione/riparazione del servizio falliscono quando entrambi sono configurati e la modalità non è impostata. -- `gateway.auth.mode: "none"`: modalità esplicita senza autenticazione. Usala solo per configurazioni loopback locali fidate; intenzionalmente non viene proposta dai prompt di onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega l'autenticazione a un reverse proxy identity-aware e si fida degli header identità da `gateway.trustedProxies` (vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth)). Questa modalità si aspetta una sorgente proxy **non loopback**; i reverse proxy loopback sullo stesso host non soddisfano l'autenticazione trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, gli header identità di Tailscale Serve possono soddisfare l'autenticazione di Control UI/WebSocket (verificata tramite `tailscale whois`). Gli endpoint HTTP API **non** usano quell'autenticazione Tailscale via header; seguono invece la normale modalità di autenticazione HTTP del Gateway. Questo flusso senza token presume che l'host del Gateway sia fidato. Per impostazione predefinita è `true` quando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitatore facoltativo dei tentativi di autenticazione falliti. Si applica per IP client e per ambito auth (shared-secret e device-token vengono tracciati in modo indipendente). I tentativi bloccati restituiscono `429` + `Retry-After`. - - Nel percorso async Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, clientIp}` vengono serializzati prima della scrittura del fallimento. Tentativi errati concorrenti dallo stesso client possono quindi attivare il limitatore sulla seconda richiesta invece di passare entrambi come semplici mismatch. - - `gateway.auth.rateLimit.exemptLoopback` ha come predefinito `true`; impostalo su `false` quando vuoi intenzionalmente limitare il traffico localhost (per configurazioni di test o deployment con proxy rigorosi). -- I tentativi di autenticazione WS con origine browser vengono sempre limitati con l'esenzione loopback disabilitata (defense-in-depth contro brute force localhost basati su browser). -- Su loopback, quei lockout per origine browser sono isolati per valore `Origin` +- **Alias bind legacy**: usa i valori della modalità bind in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), non gli alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Nota Docker**: il bind `loopback` predefinito ascolta su `127.0.0.1` all'interno del container. Con il networking bridge Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il gateway non è raggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. +- **Auth**: richiesta per impostazione predefinita. I bind non-loopback richiedono l'auth del Gateway. In pratica questo significa un token/password condiviso oppure un reverse proxy identity-aware con `gateway.auth.mode: "trusted-proxy"`. La procedura guidata di onboarding genera per impostazione predefinita un token. +- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` (inclusi SecretRef), imposta esplicitamente `gateway.auth.mode` su `token` oppure `password`. I flussi di avvio e di installazione/riparazione del servizio falliscono quando entrambi sono configurati e la modalità non è impostata. +- `gateway.auth.mode: "none"`: modalità esplicita senza auth. Usala solo per configurazioni trusted local loopback; intenzionalmente non è proposta dai prompt di onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega l'auth a un reverse proxy identity-aware e considera attendibili gli header identità da `gateway.trustedProxies` (vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth)). Questa modalità si aspetta una sorgente proxy **non-loopback**; i reverse proxy loopback sullo stesso host non soddisfano l'auth trusted-proxy. +- `gateway.auth.allowTailscale`: quando è `true`, gli header identità di Tailscale Serve possono soddisfare l'auth della Control UI/WebSocket (verificati tramite `tailscale whois`). Gli endpoint API HTTP **non** usano quell'auth tramite header Tailscale; seguono invece la normale modalità auth HTTP del gateway. Questo flusso senza token presume che l'host del gateway sia attendibile. Per impostazione predefinita è `true` quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limiter facoltativo per auth fallita. Si applica per IP client e per ambito auth (secret condiviso e token dispositivo sono tracciati in modo indipendente). I tentativi bloccati restituiscono `429` + `Retry-After`. + - Sul percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, clientIp}` vengono serializzati prima della scrittura del fallimento. I tentativi concorrenti errati dello stesso client possono quindi far scattare il limiter sulla seconda richiesta invece di passare entrambi come semplici mismatch. + - `gateway.auth.rateLimit.exemptLoopback` è `true` per impostazione predefinita; impostalo su `false` quando vuoi intenzionalmente limitare anche il traffico localhost (per setup di test o deployment proxy rigorosi). +- I tentativi di auth WS originati dal browser vengono sempre limitati con l'esenzione loopback disabilitata (difesa in profondità contro la forza bruta su localhost basata su browser). +- Su loopback, tali lockout originati dal browser sono isolati per valore `Origin` normalizzato, quindi fallimenti ripetuti da un'origine localhost non bloccano automaticamente un'origine diversa. -- `tailscale.mode`: `serve` (solo tailnet, bind loopback) oppure `funnel` (pubblico, richiede autenticazione). -- `controlUi.allowedOrigins`: allowlist esplicita delle origini browser per le connessioni WebSocket del Gateway. Obbligatoria quando sono previsti client browser da origini non loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modalità pericolosa che abilita il fallback dell'origine tramite header Host per deployment che si basano intenzionalmente sul criterio di origine basato su header Host. +- `tailscale.mode`: `serve` (solo tailnet, bind loopback) oppure `funnel` (pubblico, richiede auth). +- `controlUi.allowedOrigins`: allowlist esplicita delle origini browser per le connessioni WebSocket al Gateway. Richiesta quando sono previsti client browser da origini non-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modalità pericolosa che abilita il fallback dell'origine tramite header Host per i deployment che si basano intenzionalmente sul criterio di origine dell'header Host. - `remote.transport`: `ssh` (predefinito) oppure `direct` (ws/wss). Per `direct`, `remote.url` deve essere `ws://` oppure `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass lato client che consente `ws://` plaintext verso IP di reti private fidate; il predefinito resta loopback-only per plaintext. -- `gateway.remote.token` / `.password` sono campi credenziali del client remoto. Non configurano da soli l'autenticazione del Gateway. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS base del relay APNs esterno usato dalle build iOS ufficiali/TestFlight dopo che pubblicano registrazioni relay-backed sul Gateway. Questo URL deve corrispondere all'URL del relay compilato nella build iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout in millisecondi per l'invio Gateway-verso-relay. Predefinito `10000`. -- Le registrazioni relay-backed vengono delegate a una specifica identità Gateway. L'app iOS associata recupera `gateway.identity.get`, include quell'identità nella registrazione relay e inoltra al Gateway una grant di invio con ambito registrazione. Un altro Gateway non può riutilizzare quella registrazione memorizzata. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env temporanei per la configurazione relay sopra. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo per sviluppo per URL relay HTTP loopback. Gli URL relay di produzione devono restare su HTTPS. -- `gateway.channelHealthCheckMinutes`: intervallo del monitor di integrità dei canali in minuti. Imposta `0` per disabilitare globalmente i riavvii del monitor di integrità. Predefinito: `5`. -- `gateway.channelStaleEventThresholdMinutes`: soglia socket obsoleto in minuti. Mantienila maggiore o uguale a `gateway.channelHealthCheckMinutes`. Predefinito: `30`. -- `gateway.channelMaxRestartsPerHour`: numero massimo di riavvii del monitor di integrità per canale/account in un'ora mobile. Predefinito: `10`. -- `channels..healthMonitor.enabled`: opt-out per-canale dai riavvii del monitor di integrità mantenendo attivo il monitor globale. -- `channels..accounts..healthMonitor.enabled`: override per-account per i canali multi-account. Quando impostato, ha la precedenza sull'override a livello di canale. -- I percorsi di chiamata del Gateway locale possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. -- Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non risolto, la risoluzione fallisce in modalità fail-closed (nessun fallback remoto che maschera il problema). -- `trustedProxies`: IP dei reverse proxy che terminano TLS o iniettano header inoltrati del client. Elenca solo proxy sotto il tuo controllo. Le voci loopback restano valide per configurazioni con proxy sullo stesso host/rilevamento locale (ad esempio Tailscale Serve o un reverse proxy locale), ma **non** rendono le richieste loopback idonee a `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: quando `true`, il Gateway accetta `X-Real-IP` se `X-Forwarded-For` manca. Predefinito `false` per comportamento fail-closed. -- `gateway.tools.deny`: nomi di strumenti aggiuntivi bloccati per `POST /tools/invoke` HTTP (estende la deny list predefinita). +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass lato client che consente `ws://` in chiaro verso IP attendibili di rete privata; il predefinito resta solo-loopback per il plaintext. +- `gateway.remote.token` / `.password` sono campi credenziale del client remoto. Non configurano da soli l'auth del gateway. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base per il relay APNs esterno usato dalle build iOS ufficiali/TestFlight dopo che pubblicano registrazioni supportate da relay al gateway. Questo URL deve corrispondere all'URL relay compilato nella build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout in millisecondi dell'invio dal gateway al relay. Predefinito: `10000`. +- Le registrazioni supportate da relay vengono delegate a una specifica identità gateway. L'app iOS associata recupera `gateway.identity.get`, include tale identità nella registrazione relay e inoltra al gateway una send grant con ambito registrazione. Un altro gateway non può riutilizzare quella registrazione memorizzata. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env temporanei per la configurazione relay sopra riportata. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: via di fuga solo sviluppo per URL relay HTTP loopback. Gli URL relay di produzione dovrebbero restare su HTTPS. +- `gateway.channelHealthCheckMinutes`: intervallo del monitor di salute del canale in minuti. Imposta `0` per disabilitare globalmente i riavvii del monitor salute. Predefinito: `5`. +- `gateway.channelStaleEventThresholdMinutes`: soglia in minuti per socket stale. Mantienila maggiore o uguale a `gateway.channelHealthCheckMinutes`. Predefinito: `30`. +- `gateway.channelMaxRestartsPerHour`: massimo numero di riavvii del monitor salute per canale/account in un'ora mobile. Predefinito: `10`. +- `channels..healthMonitor.enabled`: opt-out per canale dei riavvii del monitor salute mantenendo abilitato il monitor globale. +- `channels..accounts..healthMonitor.enabled`: override per account nei canali multi-account. Quando impostato, ha la precedenza sull'override a livello canale. +- I percorsi di chiamata del gateway locale possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. +- Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non viene risolto, la risoluzione fallisce in modalità fail-closed (nessun fallback remoto che mascheri il problema). +- `trustedProxies`: IP di reverse proxy che terminano TLS o iniettano header client inoltrati. Elenca solo proxy che controlli. Le voci loopback restano valide per setup di proxy sullo stesso host/rilevamento locale (per esempio Tailscale Serve o un reverse proxy locale), ma **non** rendono le richieste loopback idonee per `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: quando è `true`, il gateway accetta `X-Real-IP` se manca `X-Forwarded-For`. Predefinito `false` per comportamento fail-closed. +- `gateway.tools.deny`: nomi di strumenti aggiuntivi bloccati per HTTP `POST /tools/invoke` (estende la deny list predefinita). - `gateway.tools.allow`: rimuove nomi di strumenti dalla deny list HTTP predefinita. @@ -3116,19 +3103,19 @@ Vedi [Plugin](/it/tools/plugin). ### Endpoint compatibili con OpenAI - Chat Completions: disabilitato per impostazione predefinita. Abilitalo con `gateway.http.endpoints.chatCompletions.enabled: true`. -- Responses API: `gateway.http.endpoints.responses.enabled`. +- API Responses: `gateway.http.endpoints.responses.enabled`. - Hardening degli input URL di Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Le allowlist vuote vengono trattate come non impostate; usa `gateway.http.endpoints.responses.files.allowUrl=false` - e/o `gateway.http.endpoints.responses.images.allowUrl=false` per disabilitare il fetch degli URL. + e/o `gateway.http.endpoints.responses.images.allowUrl=false` per disabilitare il recupero tramite URL. - Header facoltativo di hardening della risposta: - - `gateway.http.securityHeaders.strictTransportSecurity` (impostalo solo per origini HTTPS sotto il tuo controllo; vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (impostalo solo per origini HTTPS che controlli; vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolamento multi-instance +### Isolamento multi-istanza -Esegui più Gateway su un host con porte e directory di stato univoche: +Esegui più gateway su un solo host con porte e directory di stato uniche: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3138,7 +3125,7 @@ openclaw gateway --port 19001 Flag di comodità: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile ` (usa `~/.openclaw-`). -Vedi [Gateway multipli](/it/gateway/multiple-gateways). +Vedi [Multiple Gateways](/it/gateway/multiple-gateways). ### `gateway.tls` @@ -3156,11 +3143,11 @@ Vedi [Gateway multipli](/it/gateway/multiple-gateways). } ``` -- `enabled`: abilita la terminazione TLS sul listener del Gateway (HTTPS/WSS) (predefinito: `false`). -- `autoGenerate`: genera automaticamente una coppia cert/key locale self-signed quando i file espliciti non sono configurati; solo per uso locale/dev. +- `enabled`: abilita la terminazione TLS sul listener del gateway (HTTPS/WSS) (predefinito: `false`). +- `autoGenerate`: genera automaticamente una coppia locale certificato/chiave self-signed quando non sono configurati file espliciti; solo per uso locale/dev. - `certPath`: percorso filesystem del file certificato TLS. -- `keyPath`: percorso filesystem della chiave privata TLS; mantienilo con permessi limitati. -- `caPath`: percorso facoltativo del bundle CA per la verifica client o catene di trust personalizzate. +- `keyPath`: percorso filesystem del file chiave privata TLS; mantienilo con permessi limitati. +- `caPath`: percorso facoltativo del bundle CA per la verifica del client o per catene di trust personalizzate. ### `gateway.reload` @@ -3176,13 +3163,13 @@ Vedi [Gateway multipli](/it/gateway/multiple-gateways). } ``` -- `mode`: controlla come vengono applicate le modifiche di configurazione a runtime. +- `mode`: controlla come le modifiche di configurazione vengono applicate a runtime. - `"off"`: ignora le modifiche live; i cambiamenti richiedono un riavvio esplicito. - - `"restart"`: riavvia sempre il processo Gateway quando cambia la configurazione. - - `"hot"`: applica i cambiamenti in-process senza riavviare. - - `"hybrid"` (predefinito): prova prima l'hot reload; usa come fallback il riavvio se necessario. + - `"restart"`: riavvia sempre il processo gateway in caso di modifica di configurazione. + - `"hot"`: applica le modifiche in-process senza riavviare. + - `"hybrid"` (predefinito): prova prima il hot reload; se necessario ripiega sul riavvio. - `debounceMs`: finestra di debounce in ms prima che le modifiche di configurazione vengano applicate (intero non negativo). -- `deferralTimeoutMs`: tempo massimo in ms da attendere per le operazioni in corso prima di forzare un riavvio (predefinito: `300000` = 5 minuti). +- `deferralTimeoutMs`: tempo massimo in ms per attendere le operazioni in corso prima di forzare un riavvio (predefinito: `300000` = 5 minuti). --- @@ -3209,7 +3196,7 @@ Vedi [Gateway multipli](/it/gateway/multiple-gateways). wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "Da: {{messages[0].from}}\nOggetto: {{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3227,39 +3214,39 @@ Note di convalida e sicurezza: - `hooks.enabled=true` richiede un `hooks.token` non vuoto. - `hooks.token` deve essere **distinto** da `gateway.auth.token`; il riutilizzo del token Gateway viene rifiutato. - `hooks.path` non può essere `/`; usa un sottopercorso dedicato come `/hooks`. -- Se `hooks.allowRequestSessionKey=true`, limita `hooks.allowedSessionKeyPrefixes` (ad esempio `["hook:"]`). -- Se una mapping o un preset usa un `sessionKey` template, imposta `hooks.allowedSessionKeyPrefixes` e `hooks.allowRequestSessionKey=true`. Le chiavi statiche delle mapping non richiedono quell'opt-in. +- Se `hooks.allowRequestSessionKey=true`, limita `hooks.allowedSessionKeyPrefixes` (per esempio `["hook:"]`). +- Se una mapping o un preset usa un `sessionKey` con template, imposta `hooks.allowedSessionKeyPrefixes` e `hooks.allowRequestSessionKey=true`. Le chiavi statiche di mapping non richiedono questo opt-in. **Endpoint:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` dal payload della richiesta viene accettato solo quando `hooks.allowRequestSessionKey=true` (predefinito: `false`). + - `sessionKey` dal payload della richiesta è accettato solo quando `hooks.allowRequestSessionKey=true` (predefinito: `false`). - `POST /hooks/` → risolto tramite `hooks.mappings` - - I valori `sessionKey` delle mapping renderizzati tramite template vengono trattati come forniti esternamente e richiedono anch'essi `hooks.allowRequestSessionKey=true`. + - I valori `sessionKey` del mapping renderizzati tramite template sono trattati come forniti esternamente e richiedono anch'essi `hooks.allowRequestSessionKey=true`. - `match.path` corrisponde al sottopercorso dopo `/hooks` (ad es. `/hooks/gmail` → `gmail`). - `match.source` corrisponde a un campo del payload per percorsi generici. -- I template come `{{messages[0].subject}}` leggono dal payload. +- Template come `{{messages[0].subject}}` leggono dal payload. - `transform` può puntare a un modulo JS/TS che restituisce un'azione hook. - - `transform.module` deve essere un percorso relativo e resta all'interno di `hooks.transformsDir` (i percorsi assoluti e il traversal vengono rifiutati). -- `agentId` instrada verso uno specifico agente; gli ID sconosciuti usano come fallback quello predefinito. -- `allowedAgentIds`: limita l'instradamento esplicito (`*` o omesso = consenti tutti, `[]` = nega tutti). -- `defaultSessionKey`: chiave di sessione fissa facoltativa per le esecuzioni dell'agente hook senza `sessionKey` esplicito. -- `allowRequestSessionKey`: consente ai chiamanti di `/hooks/agent` e alle chiavi di sessione delle mapping guidate da template di impostare `sessionKey` (predefinito: `false`). -- `allowedSessionKeyPrefixes`: allowlist facoltativa di prefissi per valori `sessionKey` espliciti (richiesta + mapping), ad es. `["hook:"]`. Diventa obbligatoria quando una mapping o un preset usa un `sessionKey` template. -- `deliver: true` invia la risposta finale a un canale; `channel` ha come predefinito `last`. -- `model` sovrascrive l'LLM per questa esecuzione hook (deve essere consentito se il catalogo modelli è impostato). + - `transform.module` deve essere un percorso relativo e rimanere all'interno di `hooks.transformsDir` (i percorsi assoluti e il path traversal vengono rifiutati). +- `agentId` instrada verso un agente specifico; gli ID sconosciuti usano come fallback il predefinito. +- `allowedAgentIds`: limita il routing esplicito (`*` oppure omesso = consenti tutti, `[]` = nega tutti). +- `defaultSessionKey`: chiave sessione fissa facoltativa per le esecuzioni dell'agente hook senza `sessionKey` esplicito. +- `allowRequestSessionKey`: consente ai chiamanti `/hooks/agent` e alle chiavi sessione delle mapping guidate da template di impostare `sessionKey` (predefinito: `false`). +- `allowedSessionKeyPrefixes`: allowlist facoltativa di prefissi per i valori `sessionKey` espliciti (richiesta + mapping), ad es. `["hook:"]`. Diventa obbligatoria quando una qualsiasi mapping o preset usa un `sessionKey` con template. +- `deliver: true` invia la risposta finale a un canale; `channel` usa come predefinito `last`. +- `model` sovrascrive l'LLM per questa esecuzione hook (deve essere consentito se è impostato il catalogo modelli). ### Integrazione Gmail - Il preset Gmail integrato usa `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Se mantieni questo instradamento per-messaggio, imposta `hooks.allowRequestSessionKey: true` e limita `hooks.allowedSessionKeyPrefixes` in modo che corrisponda allo spazio dei nomi Gmail, ad esempio `["hook:", "hook:gmail:"]`. -- Se hai bisogno di `hooks.allowRequestSessionKey: false`, sovrascrivi il preset con un `sessionKey` statico invece del valore predefinito basato su template. +- Se mantieni quel routing per messaggio, imposta `hooks.allowRequestSessionKey: true` e limita `hooks.allowedSessionKeyPrefixes` in modo che corrispondano allo spazio dei nomi Gmail, per esempio `["hook:", "hook:gmail:"]`. +- Se ti serve `hooks.allowRequestSessionKey: false`, sovrascrivi il preset con un `sessionKey` statico invece del valore predefinito con template. ```json5 { @@ -3282,7 +3269,7 @@ Note di convalida e sicurezza: } ``` -- Il Gateway avvia automaticamente `gog gmail watch serve` all'avvio quando configurato. Imposta `OPENCLAW_SKIP_GMAIL_WATCHER=1` per disabilitarlo. +- Il Gateway avvia automaticamente `gog gmail watch serve` all'avvio quando è configurato. Imposta `OPENCLAW_SKIP_GMAIL_WATCHER=1` per disabilitarlo. - Non eseguire un `gog gmail watch serve` separato insieme al Gateway. --- @@ -3294,7 +3281,7 @@ Note di convalida e sicurezza: canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // oppure OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` @@ -3303,14 +3290,14 @@ Note di convalida e sicurezza: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Solo locale: mantieni `gateway.bind: "loopback"` (predefinito). -- Bind non loopback: le route canvas richiedono l'autenticazione del Gateway (token/password/trusted-proxy), come le altre superfici HTTP del Gateway. -- I WebView Node in genere non inviano header auth; dopo che un Node è associato e connesso, il Gateway pubblicizza URL capability con ambito Node per l'accesso canvas/A2UI. -- Gli URL capability sono associati alla sessione WS attiva del Node e scadono rapidamente. Non viene usato alcun fallback basato su IP. +- Bind non-loopback: le route canvas richiedono l'auth del Gateway (token/password/trusted-proxy), come le altre superfici HTTP del Gateway. +- I WebView Node in genere non inviano header auth; dopo che un Node è associato e connesso, il Gateway pubblicizza URL di capability con ambito Node per l'accesso canvas/A2UI. +- Gli URL di capability sono vincolati alla sessione WS attiva del Node e scadono rapidamente. Non viene usato il fallback basato su IP. - Inietta il client live-reload nell'HTML servito. - Crea automaticamente un `index.html` iniziale quando è vuoto. -- Serve anche A2UI in `/__openclaw__/a2ui/`. +- Serve anche A2UI su `/__openclaw__/a2ui/`. - Le modifiche richiedono un riavvio del Gateway. -- Disabilita il live reload per directory molto grandi o in caso di errori `EMFILE`. +- Disabilita il live reload per directory grandi o errori `EMFILE`. --- @@ -3330,7 +3317,7 @@ Note di convalida e sicurezza: - `minimal` (predefinito): omette `cliPath` + `sshPort` dai record TXT. - `full`: include `cliPath` + `sshPort`. -- L'hostname ha come predefinito `openclaw`. Sovrascrivilo con `OPENCLAW_MDNS_HOSTNAME`. +- L'hostname usa come predefinito `openclaw`. Sovrascrivilo con `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3342,7 +3329,7 @@ Note di convalida e sicurezza: } ``` -Scrive una zona DNS-SD unicast in `~/.openclaw/dns/`. Per la discovery cross-network, abbinala a un server DNS (consigliato CoreDNS) + DNS split di Tailscale. +Scrive una zona DNS-SD unicast sotto `~/.openclaw/dns/`. Per il discovery cross-network, abbinala a un server DNS (CoreDNS consigliato) + DNS split di Tailscale. Configurazione: `openclaw dns setup --apply`. @@ -3367,14 +3354,14 @@ Configurazione: `openclaw dns setup --apply`. } ``` -- Le variabili env inline vengono applicate solo se nell'ambiente del processo manca la chiave. -- File `.env`: `.env` della CWD + `~/.openclaw/.env` (nessuno dei due sovrascrive variabili esistenti). -- `shellEnv`: importa le chiavi attese mancanti dal profilo della tua shell di login. -- Vedi [Ambiente](/it/help/environment) per la precedenza completa. +- Le variabili env inline vengono applicate solo se nell'env del processo manca la chiave. +- File `.env`: `.env` della CWD + `~/.openclaw/.env` (nessuno dei due sovrascrive le variabili esistenti). +- `shellEnv`: importa le chiavi attese mancanti dal profilo della tua login shell. +- Vedi [Environment](/it/help/environment) per la precedenza completa. -### Sostituzione variabili env +### Sostituzione delle variabili env -Fai riferimento a variabili env in qualsiasi stringa di configurazione con `${VAR_NAME}`: +Fai riferimento alle variabili env in qualsiasi stringa di configurazione con `${VAR_NAME}`: ```json5 { @@ -3384,16 +3371,16 @@ Fai riferimento a variabili env in qualsiasi stringa di configurazione con `${VA } ``` -- Vengono riconosciuti solo nomi maiuscoli: `[A-Z_][A-Z0-9_]*`. +- Vengono riconosciuti solo nomi in maiuscolo: `[A-Z_][A-Z0-9_]*`. - Variabili mancanti/vuote generano un errore al caricamento della configurazione. - Usa l'escape `$${VAR}` per un `${VAR}` letterale. - Funziona con `$include`. --- -## Segreti +## Secret -I SecretRef sono additivi: i valori plaintext continuano a funzionare. +I SecretRef sono additivi: i valori in chiaro continuano a funzionare. ### `SecretRef` @@ -3405,25 +3392,25 @@ Usa una forma oggetto: Convalida: -- pattern `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- pattern `id` per `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `id` per `source: "file"`: puntatore JSON assoluto (ad esempio `"/providers/openai/apiKey"`) -- pattern `id` per `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- Gli `id` con `source: "exec"` non devono contenere segmenti di percorso delimitati da slash `.` o `..` (ad esempio `a/../b` viene rifiutato) +- pattern di `provider`: `^[a-z][a-z0-9_-]{0,63}$` +- pattern di id per `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` id: puntatore JSON assoluto (per esempio `"/providers/openai/apiKey"`) +- pattern di id per `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- gli id `source: "exec"` non devono contenere segmenti di percorso slash-delimited `.` o `..` (per esempio `a/../b` viene rifiutato) -### Superficie credenziali supportata +### Superficie delle credenziali supportate -- Matrice canonica: [Superficie credenziali SecretRef](/it/reference/secretref-credential-surface) -- `secrets apply` prende come destinazione i percorsi credenziali supportati di `openclaw.json`. -- I riferimenti `auth-profiles.json` sono inclusi nella risoluzione runtime e nella copertura dell'audit. +- Matrice canonica: [SecretRef Credential Surface](/it/reference/secretref-credential-surface) +- `secrets apply` punta ai percorsi credenziali supportati di `openclaw.json`. +- I ref in `auth-profiles.json` sono inclusi nella risoluzione runtime e nella copertura audit. -### Configurazione provider dei segreti +### Configurazione dei provider secret ```json5 { secrets: { providers: { - default: { source: "env" }, // provider env esplicito facoltativo + default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3449,11 +3436,11 @@ Note: - Il provider `file` supporta `mode: "json"` e `mode: "singleValue"` (`id` deve essere `"value"` in modalità singleValue). - Il provider `exec` richiede un percorso `command` assoluto e usa payload di protocollo su stdin/stdout. -- Per impostazione predefinita, i percorsi di comando symlink vengono rifiutati. Imposta `allowSymlinkCommand: true` per consentire percorsi symlink convalidando però il percorso della destinazione risolta. -- Se `trustedDirs` è configurato, il controllo delle directory fidate si applica al percorso della destinazione risolta. -- L'ambiente figlio di `exec` è minimo per impostazione predefinita; passa esplicitamente le variabili necessarie con `passEnv`. -- I SecretRef vengono risolti al momento dell'attivazione in uno snapshot in memoria, poi i percorsi di richiesta leggono solo quello snapshot. -- Il filtraggio della superficie attiva si applica durante l'attivazione: i riferimenti non risolti su superfici abilitate fanno fallire avvio/reload, mentre le superfici inattive vengono saltate con diagnostica. +- Per impostazione predefinita, i percorsi di comando symlink vengono rifiutati. Imposta `allowSymlinkCommand: true` per consentire percorsi symlink con convalida del percorso target risolto. +- Se `trustedDirs` è configurato, il controllo delle directory attendibili si applica al percorso target risolto. +- L'ambiente figlio `exec` è minimo per impostazione predefinita; passa esplicitamente le variabili richieste con `passEnv`. +- I ref secret vengono risolti al momento dell'attivazione in uno snapshot in memoria, poi i percorsi di richiesta leggono solo lo snapshot. +- Il filtro della superficie attiva si applica durante l'attivazione: i ref non risolti sulle superfici abilitate fanno fallire avvio/reload, mentre le superfici inattive vengono saltate con diagnostica. --- @@ -3475,13 +3462,13 @@ Note: } ``` -- I profili per-agente sono archiviati in `/auth-profiles.json`. -- `auth-profiles.json` supporta riferimenti a livello di valore (`keyRef` per `api_key`, `tokenRef` per `token`) per le modalità di credenziale statica. -- I profili in modalità OAuth (`auth.profiles..mode = "oauth"`) non supportano credenziali di auth-profile basate su SecretRef. -- Le credenziali runtime statiche provengono da snapshot in memoria risolti; le voci statiche legacy di `auth.json` vengono ripulite quando rilevate. +- I profili per agente sono memorizzati in `/auth-profiles.json`. +- `auth-profiles.json` supporta ref a livello di valore (`keyRef` per `api_key`, `tokenRef` per `token`) per le modalità di credenziale statica. +- I profili in modalità OAuth (`auth.profiles..mode = "oauth"`) non supportano credenziali auth-profile supportate da SecretRef. +- Le credenziali runtime statiche provengono da snapshot risolti in memoria; le voci legacy statiche di `auth.json` vengono ripulite quando vengono trovate. - Importazioni OAuth legacy da `~/.openclaw/credentials/oauth.json`. - Vedi [OAuth](/it/concepts/oauth). -- Comportamento runtime dei segreti e strumenti `audit/configure/apply`: [Gestione dei segreti](/it/gateway/secrets). +- Comportamento runtime dei secret e tooling `audit/configure/apply`: [Secrets Management](/it/gateway/secrets). ### `auth.cooldowns` @@ -3503,20 +3490,15 @@ Note: } ``` -- `billingBackoffHours`: backoff base in ore quando un profilo fallisce per veri - errori di fatturazione/credito insufficiente (predefinito: `5`). Il testo esplicito di fatturazione può - comunque finire qui anche su risposte `401`/`403`, ma i matcher testuali - specifici del provider restano limitati al provider che li possiede (ad esempio OpenRouter - `Key limit exceeded`). I messaggi retryable di finestra d'uso HTTP `402` o - di limite di spesa di organizzazione/workspace restano invece nel percorso `rate_limit`. -- `billingBackoffHoursByProvider`: override facoltativi per-provider per le ore di backoff di fatturazione. -- `billingMaxHours`: limite in ore per la crescita esponenziale del backoff di fatturazione (predefinito: `24`). -- `authPermanentBackoffMinutes`: backoff base in minuti per fallimenti `auth_permanent` ad alta confidenza (predefinito: `10`). -- `authPermanentMaxMinutes`: limite in minuti per la crescita del backoff `auth_permanent` (predefinito: `60`). +- `billingBackoffHours`: backoff base in ore quando un profilo fallisce per veri errori di billing/credito insufficiente (predefinito: `5`). Un testo di billing esplicito può comunque finire qui anche su risposte `401`/`403`, ma i matcher di testo specifici del provider restano confinati al provider che li possiede (per esempio OpenRouter `Key limit exceeded`). I messaggi di finestra d'uso `402` ritentabili o di limiti di spesa di organization/workspace restano invece nel percorso `rate_limit`. +- `billingBackoffHoursByProvider`: override facoltativi per provider delle ore di backoff di billing. +- `billingMaxHours`: limite in ore per la crescita esponenziale del backoff di billing (predefinito: `24`). +- `authPermanentBackoffMinutes`: backoff base in minuti per errori `auth_permanent` ad alta confidenza (predefinito: `10`). +- `authPermanentMaxMinutes`: limite in minuti per la crescita del backoff di `auth_permanent` (predefinito: `60`). - `failureWindowHours`: finestra mobile in ore usata per i contatori di backoff (predefinito: `24`). -- `overloadedProfileRotations`: numero massimo di rotazioni di auth-profile dello stesso provider per errori di overload prima di passare al fallback del modello (predefinito: `1`). Le forme provider-busy come `ModelNotReadyException` finiscono qui. -- `overloadedBackoffMs`: ritardo fisso prima di ritentare una rotazione di provider/profilo sovraccarico (predefinito: `0`). -- `rateLimitedProfileRotations`: numero massimo di rotazioni di auth-profile dello stesso provider per errori di rate-limit prima di passare al fallback del modello (predefinito: `1`). Quel bucket di rate-limit include testo modellato sul provider come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. +- `overloadedProfileRotations`: massimo numero di rotazioni dello stesso auth-profile provider per errori di overload prima di passare al fallback del modello (predefinito: `1`). Le forme di provider occupato come `ModelNotReadyException` finiscono qui. +- `overloadedBackoffMs`: ritardo fisso prima di riprovare una rotazione di provider/profile in overload (predefinito: `0`). +- `rateLimitedProfileRotations`: massimo numero di rotazioni dello stesso auth-profile provider per errori di rate limit prima di passare al fallback del modello (predefinito: `1`). Quel bucket di rate limit include testo sagomato dal provider come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- @@ -3537,8 +3519,8 @@ Note: - File di log predefinito: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Imposta `logging.file` per un percorso stabile. -- `consoleLevel` sale a `debug` quando si usa `--verbose`. -- `maxFileBytes`: dimensione massima del file di log in byte oltre la quale le scritture vengono soppresse (intero positivo; predefinito: `524288000` = 500 MB). Usa la rotazione log esterna per i deployment di produzione. +- `consoleLevel` sale a `debug` con `--verbose`. +- `maxFileBytes`: dimensione massima del file di log in byte prima che le scritture vengano soppresse (intero positivo; predefinito: `524288000` = 500 MB). Usa una rotazione esterna dei log per i deployment di produzione. --- @@ -3575,20 +3557,20 @@ Note: } ``` -- `enabled`: interruttore principale per l'output della strumentazione (predefinito: `true`). -- `flags`: array di stringhe flag che abilitano output di log mirato (supporta wildcard come `"telegram.*"` oppure `"*"`). -- `stuckSessionWarnMs`: soglia di età in ms per emettere avvisi di sessione bloccata mentre una sessione rimane nello stato di elaborazione. +- `enabled`: interruttore principale per l'output di strumentazione (predefinito: `true`). +- `flags`: array di stringhe flag che abilita output di log mirato (supporta wildcard come `"telegram.*"` oppure `"*"`). +- `stuckSessionWarnMs`: soglia di età in ms per emettere avvisi di sessione bloccata mentre una sessione resta nello stato di elaborazione. - `otel.enabled`: abilita la pipeline di esportazione OpenTelemetry (predefinito: `false`). - `otel.endpoint`: URL del collector per l'esportazione OTel. - `otel.protocol`: `"http/protobuf"` (predefinito) oppure `"grpc"`. - `otel.headers`: header di metadati HTTP/gRPC extra inviati con le richieste di esportazione OTel. - `otel.serviceName`: nome del servizio per gli attributi della risorsa. - `otel.traces` / `otel.metrics` / `otel.logs`: abilitano l'esportazione di trace, metriche o log. -- `otel.sampleRate`: frequenza di sampling delle trace `0`–`1`. +- `otel.sampleRate`: tasso di campionamento delle trace `0`–`1`. - `otel.flushIntervalMs`: intervallo periodico di flush della telemetria in ms. -- `cacheTrace.enabled`: registra snapshot di trace cache per esecuzioni embedded (predefinito: `false`). -- `cacheTrace.filePath`: percorso di output per il JSONL della trace cache (predefinito: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controllano cosa viene incluso nell'output della trace cache (tutti con predefinito: `true`). +- `cacheTrace.enabled`: registra snapshot di cache trace per le esecuzioni embedded (predefinito: `false`). +- `cacheTrace.filePath`: percorso di output per il JSONL di cache trace (predefinito: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controllano cosa è incluso nell'output di cache trace (tutti predefiniti: `true`). --- @@ -3611,11 +3593,11 @@ Note: ``` - `channel`: canale di rilascio per installazioni npm/git — `"stable"`, `"beta"` oppure `"dev"`. -- `checkOnStart`: controlla gli aggiornamenti npm all'avvio del Gateway (predefinito: `true`). +- `checkOnStart`: controlla la presenza di aggiornamenti npm all'avvio del gateway (predefinito: `true`). - `auto.enabled`: abilita l'auto-update in background per le installazioni di pacchetti (predefinito: `false`). -- `auto.stableDelayHours`: ritardo minimo in ore prima dell'applicazione automatica del canale stable (predefinito: `6`; massimo: `168`). -- `auto.stableJitterHours`: finestra extra in ore per distribuire il rollout del canale stable (predefinito: `12`; massimo: `168`). -- `auto.betaCheckIntervalHours`: frequenza in ore dei controlli del canale beta (predefinito: `1`; massimo: `24`). +- `auto.stableDelayHours`: ritardo minimo in ore prima dell'applicazione automatica sul canale stable (predefinito: `6`; max: `168`). +- `auto.stableJitterHours`: finestra aggiuntiva in ore per distribuire il rollout del canale stable (predefinito: `12`; max: `168`). +- `auto.betaCheckIntervalHours`: frequenza in ore dei controlli sul canale beta (predefinito: `1`; max: `24`). --- @@ -3650,19 +3632,19 @@ Note: - `enabled`: gate globale della funzionalità ACP (predefinito: `false`). - `dispatch.enabled`: gate indipendente per il dispatch dei turni di sessione ACP (predefinito: `true`). Imposta `false` per mantenere disponibili i comandi ACP bloccando però l'esecuzione. -- `backend`: ID backend runtime ACP predefinito (deve corrispondere a un plugin runtime ACP registrato). -- `defaultAgent`: ID agente ACP di fallback quando gli spawn non specificano una destinazione esplicita. -- `allowedAgents`: allowlist degli ID agente consentiti per le sessioni runtime ACP; vuota significa nessuna restrizione aggiuntiva. -- `maxConcurrentSessions`: numero massimo di sessioni ACP attive contemporaneamente. -- `stream.coalesceIdleMs`: finestra di flush per inattività in ms per il testo in streaming. -- `stream.maxChunkChars`: dimensione massima del blocco prima della suddivisione della proiezione del blocco in streaming. -- `stream.repeatSuppression`: sopprime righe di stato/strumento ripetute per turno (predefinito: `true`). -- `stream.deliveryMode`: `"live"` trasmette in modo incrementale; `"final_only"` bufferizza fino agli eventi terminali del turno. -- `stream.hiddenBoundarySeparator`: separatore prima del testo visibile dopo eventi nascosti degli strumenti (predefinito: `"paragraph"`). +- `backend`: id predefinito del backend runtime ACP (deve corrispondere a un plugin runtime ACP registrato). +- `defaultAgent`: id agente ACP target di fallback quando gli spawn non specificano un target esplicito. +- `allowedAgents`: allowlist degli id agente consentiti per le sessioni runtime ACP; vuoto significa nessuna restrizione aggiuntiva. +- `maxConcurrentSessions`: massimo numero di sessioni ACP attive contemporaneamente. +- `stream.coalesceIdleMs`: finestra di flush inattivo in ms per il testo in streaming. +- `stream.maxChunkChars`: dimensione massima del chunk prima della divisione della proiezione del blocco in streaming. +- `stream.repeatSuppression`: sopprime per turno le righe ripetute di stato/strumento (predefinito: `true`). +- `stream.deliveryMode`: `"live"` esegue lo streaming incrementale; `"final_only"` accumula fino agli eventi terminali del turno. +- `stream.hiddenBoundarySeparator`: separatore prima del testo visibile dopo eventi di strumento nascosti (predefinito: `"paragraph"`). - `stream.maxOutputChars`: massimo numero di caratteri di output dell'assistente proiettati per turno ACP. -- `stream.maxSessionUpdateChars`: massimo numero di caratteri per righe di stato/aggiornamento ACP proiettate. -- `stream.tagVisibility`: record da nomi tag a override booleani di visibilità per eventi in streaming. -- `runtime.ttlMinutes`: TTL di inattività in minuti per i worker di sessione ACP prima che siano idonei alla pulizia. +- `stream.maxSessionUpdateChars`: massimo numero di caratteri per le righe di stato/aggiornamento ACP proiettate. +- `stream.tagVisibility`: record dei nomi tag verso override booleani di visibilità per gli eventi in streaming. +- `runtime.ttlMinutes`: TTL inattivo in minuti per i worker di sessione ACP prima che siano idonei alla pulizia. - `runtime.installCommand`: comando di installazione facoltativo da eseguire durante il bootstrap di un ambiente runtime ACP. --- @@ -3679,17 +3661,17 @@ Note: } ``` -- `cli.banner.taglineMode` controlla lo stile della tagline del banner: +- `cli.banner.taglineMode` controlla lo stile del tagline del banner: - `"random"` (predefinito): tagline divertenti/stagionali a rotazione. - - `"default"`: tagline neutra fissa (`All your chats, one OpenClaw.`). - - `"off"`: nessun testo tagline (restano comunque mostrati titolo/versione del banner). -- Per nascondere l'intero banner (non solo le tagline), imposta la variabile env `OPENCLAW_HIDE_BANNER=1`. + - `"default"`: tagline neutro fisso (`All your chats, one OpenClaw.`). + - `"off"`: nessun testo tagline (titolo/versione del banner comunque mostrati). +- Per nascondere l'intero banner (non solo i tagline), imposta la variabile env `OPENCLAW_HIDE_BANNER=1`. --- -## Wizard +## Procedura guidata -Metadati scritti dai flussi CLI di configurazione guidata (`onboard`, `configure`, `doctor`): +Metadati scritti dai flussi di configurazione guidata della CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3707,13 +3689,13 @@ Metadati scritti dai flussi CLI di configurazione guidata (`onboard`, `configure ## Identità -Vedi i campi di identità di `agents.list` in [Valori predefiniti dell'agente](#agent-defaults). +Vedi i campi `identity` in `agents.list` sotto [Agent defaults](#agent-defaults). --- ## Bridge (legacy, rimosso) -Le build correnti non includono più il bridge TCP. I Node si collegano tramite WebSocket del Gateway. Le chiavi `bridge.*` non fanno più parte dello schema di configurazione (la convalida fallisce finché non vengono rimosse; `openclaw doctor --fix` può eliminare le chiavi sconosciute). +Le build attuali non includono più il bridge TCP. I Node si collegano tramite il WebSocket del Gateway. Le chiavi `bridge.*` non fanno più parte dello schema di configurazione (la convalida fallisce finché non vengono rimosse; `openclaw doctor --fix` può eliminare le chiavi sconosciute). @@ -3742,22 +3724,22 @@ Le build correnti non includono più il bridge TCP. I Node si collegano tramite cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // fallback deprecato per i job memorizzati con notify:true - webhookToken: "replace-with-dedicated-token", // bearer token facoltativo per auth Webhook in uscita - sessionRetention: "24h", // stringa durata oppure false + webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth + sessionRetention: "24h", // duration string or false runLog: { - maxBytes: "2mb", // predefinito 2_000_000 byte - keepLines: 2000, // predefinito 2000 + maxBytes: "2mb", // default 2_000_000 bytes + keepLines: 2000, // default 2000 }, }, } ``` -- `sessionRetention`: per quanto tempo mantenere le sessioni completate delle esecuzioni Cron isolate prima del pruning da `sessions.json`. Controlla anche la pulizia dei transcript Cron eliminati archiviati. Predefinito: `24h`; imposta `false` per disabilitare. -- `runLog.maxBytes`: dimensione massima per file di log dell'esecuzione (`cron/runs/.jsonl`) prima del pruning. Predefinito: `2_000_000` byte. +- `sessionRetention`: per quanto tempo mantenere le sessioni completate delle esecuzioni Cron isolate prima della rimozione da `sessions.json`. Controlla anche la pulizia delle trascrizioni Cron eliminate archiviate. Predefinito: `24h`; imposta `false` per disabilitare. +- `runLog.maxBytes`: dimensione massima per file di log di esecuzione (`cron/runs/.jsonl`) prima del pruning. Predefinito: `2_000_000` byte. - `runLog.keepLines`: righe più recenti mantenute quando viene attivato il pruning del log di esecuzione. Predefinito: `2000`. -- `webhookToken`: bearer token usato per la consegna POST Webhook di Cron (`delivery.mode = "webhook"`); se omesso non viene inviato alcun header auth. -- `webhook`: URL Webhook di fallback legacy deprecato (http/https) usato solo per i job memorizzati che hanno ancora `notify: true`. +- `webhookToken`: token bearer usato per la consegna POST al Webhook di Cron (`delivery.mode = "webhook"`); se omesso non viene inviato alcun header auth. +- `webhook`: URL Webhook legacy deprecato di fallback (http/https) usato solo per i job memorizzati che hanno ancora `notify: true`. ### `cron.retry` @@ -3777,7 +3759,7 @@ Le build correnti non includono più il bridge TCP. I Node si collegano tramite - `backoffMs`: array di ritardi di backoff in ms per ogni tentativo di retry (predefinito: `[30000, 60000, 300000]`; 1–10 voci). - `retryOn`: tipi di errore che attivano i retry — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettilo per ritentare tutti i tipi transitori. -Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione separata dei fallimenti. +Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione separata degli errori. ### `cron.failureAlert` @@ -3795,10 +3777,10 @@ Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione separa } ``` -- `enabled`: abilita gli avvisi di fallimento per i job Cron (predefinito: `false`). -- `after`: fallimenti consecutivi prima che venga inviato un avviso (intero positivo, min: `1`). +- `enabled`: abilita gli avvisi di errore per i job Cron (predefinito: `false`). +- `after`: numero di errori consecutivi prima che venga emesso un avviso (intero positivo, min: `1`). - `cooldownMs`: millisecondi minimi tra avvisi ripetuti per lo stesso job (intero non negativo). -- `mode`: modalità di consegna — `"announce"` invia tramite un messaggio di canale; `"webhook"` esegue un POST al Webhook configurato. +- `mode`: modalità di consegna — `"announce"` invia tramite un messaggio di canale; `"webhook"` pubblica sul Webhook configurato. - `accountId`: ID account o canale facoltativo per definire l'ambito della consegna dell'avviso. ### `cron.failureDestination` @@ -3816,45 +3798,45 @@ Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione separa } ``` -- Destinazione predefinita per le notifiche di fallimento Cron per tutti i job. -- `mode`: `"announce"` oppure `"webhook"`; ha come predefinito `"announce"` quando esistono dati di destinazione sufficienti. +- Destinazione predefinita per le notifiche di errore Cron per tutti i job. +- `mode`: `"announce"` oppure `"webhook"`; usa `"announce"` come predefinito quando esistono dati target sufficienti. - `channel`: override del canale per la consegna announce. `"last"` riusa l'ultimo canale di consegna noto. -- `to`: destinazione announce esplicita o URL Webhook. Obbligatorio per la modalità Webhook. +- `to`: target announce esplicito o URL Webhook. Obbligatorio per la modalità webhook. - `accountId`: override facoltativo dell'account per la consegna. -- `delivery.failureDestination` per-job sovrascrive questo valore predefinito globale. -- Quando non è impostata né una destinazione di fallimento globale né per-job, i job che già consegnano tramite `announce` usano come fallback quella destinazione announce primaria in caso di fallimento. -- `delivery.failureDestination` è supportato solo per i job `sessionTarget="isolated"` a meno che il `delivery.mode` primario del job non sia `"webhook"`. +- `delivery.failureDestination` per job sovrascrive questo valore predefinito globale. +- Quando né la destinazione di errore globale né quella per job sono impostate, i job che consegnano già tramite `announce` tornano a quel target announce primario anche in caso di errore. +- `delivery.failureDestination` è supportato solo per i job `sessionTarget="isolated"` a meno che `delivery.mode` primario del job non sia `"webhook"`. -Vedi [Cron Jobs](/it/automation/cron-jobs). Le esecuzioni Cron isolate sono tracciate come [attività in background](/it/automation/tasks). +Vedi [Cron Jobs](/it/automation/cron-jobs). Le esecuzioni Cron isolate sono tracciate come [background tasks](/it/automation/tasks). --- -## Variabili template del modello media +## Variabili di template del modello media -Placeholder template espansi in `tools.media.models[].args`: +Segnaposto del template espansi in `tools.media.models[].args`: -| Variabile | Descrizione | -| ------------------ | ------------------------------------------------ | -| `{{Body}}` | Corpo completo del messaggio in ingresso | -| `{{RawBody}}` | Corpo raw (senza wrapper di cronologia/mittente) | -| `{{BodyStripped}}` | Corpo con le menzioni di gruppo rimosse | -| `{{From}}` | Identificatore del mittente | -| `{{To}}` | Identificatore della destinazione | -| `{{MessageSid}}` | ID del messaggio del canale | -| `{{SessionId}}` | UUID della sessione corrente | -| `{{IsNewSession}}` | `"true"` quando viene creata una nuova sessione | -| `{{MediaUrl}}` | pseudo-URL del file multimediale in ingresso | -| `{{MediaPath}}` | percorso locale del file multimediale | -| `{{MediaType}}` | tipo di file multimediale (image/audio/document/…) | -| `{{Transcript}}` | trascrizione audio | -| `{{Prompt}}` | prompt media risolto per voci CLI | -| `{{MaxChars}}` | numero massimo di caratteri in uscita risolto per voci CLI | -| `{{ChatType}}` | `"direct"` oppure `"group"` | -| `{{GroupSubject}}` | oggetto del gruppo (best effort) | -| `{{GroupMembers}}` | anteprima dei membri del gruppo (best effort) | -| `{{SenderName}}` | nome visualizzato del mittente (best effort) | -| `{{SenderE164}}` | numero di telefono del mittente (best effort) | -| `{{Provider}}` | hint provider (whatsapp, telegram, discord, ecc.) | +| Variabile | Descrizione | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | Corpo completo del messaggio in entrata | +| `{{RawBody}}` | Corpo raw (senza wrapper cronologia/mittente) | +| `{{BodyStripped}}` | Corpo con le menzioni di gruppo rimosse | +| `{{From}}` | Identificatore del mittente | +| `{{To}}` | Identificatore della destinazione | +| `{{MessageSid}}` | ID messaggio del canale | +| `{{SessionId}}` | UUID della sessione corrente | +| `{{IsNewSession}}` | `"true"` quando viene creata una nuova sessione | +| `{{MediaUrl}}` | pseudo-URL del media in entrata | +| `{{MediaPath}}` | percorso locale del media | +| `{{MediaType}}` | tipo di media (image/audio/document/…) | +| `{{Transcript}}` | trascrizione audio | +| `{{Prompt}}` | prompt media risolto per le voci CLI | +| `{{MaxChars}}` | max caratteri di output risolti per le voci CLI | +| `{{ChatType}}` | `"direct"` oppure `"group"` | +| `{{GroupSubject}}` | oggetto del gruppo (best effort) | +| `{{GroupMembers}}` | anteprima dei membri del gruppo (best effort) | +| `{{SenderName}}` | nome visualizzato del mittente (best effort) | +| `{{SenderE164}}` | numero di telefono del mittente (best effort) | +| `{{Provider}}` | hint del provider (whatsapp, telegram, discord, ecc.) | --- @@ -3873,15 +3855,15 @@ Suddividi la configurazione in più file: } ``` -**Comportamento del merge:** +**Comportamento di merge:** - File singolo: sostituisce l'oggetto contenitore. - Array di file: deep-merge in ordine (quelli successivi sovrascrivono i precedenti). - Chiavi sibling: unite dopo gli include (sovrascrivono i valori inclusi). - Include annidati: fino a 10 livelli di profondità. -- Percorsi: risolti relativamente al file includente, ma devono restare all'interno della directory di configurazione di primo livello (`dirname` di `openclaw.json`). Le forme assolute/`../` sono consentite solo quando risolvono comunque all'interno di quel perimetro. +- Percorsi: risolti rispetto al file che include, ma devono restare all'interno della directory di configurazione di primo livello (`dirname` di `openclaw.json`). Le forme assolute/`../` sono consentite solo quando si risolvono comunque all'interno di quel limite. - Errori: messaggi chiari per file mancanti, errori di parsing e include circolari. --- -_Correlati: [Configurazione](/it/gateway/configuration) · [Esempi di configurazione](/it/gateway/configuration-examples) · [Doctor](/it/gateway/doctor)_ +_Correlati: [Configuration](/it/gateway/configuration) · [Configuration Examples](/it/gateway/configuration-examples) · [Doctor](/it/gateway/doctor)_ diff --git a/docs/it/gateway/heartbeat.md b/docs/it/gateway/heartbeat.md index b6fbc1fbe..077f7ba0f 100644 --- a/docs/it/gateway/heartbeat.md +++ b/docs/it/gateway/heartbeat.md @@ -1,36 +1,37 @@ --- read_when: - - Regolazione della cadenza o della messaggistica dell'heartbeat - - Decidere tra heartbeat e cron per le attività pianificate -summary: Messaggi di polling heartbeat e regole di notifica + - Regolazione della cadenza o dei messaggi di Heartbeat + - Decidere tra Heartbeat e Cron per le attività pianificate +summary: Messaggi di polling Heartbeat e regole di notifica title: Heartbeat x-i18n: - generated_at: "2026-04-11T02:44:45Z" + generated_at: "2026-04-22T08:20:06Z" model: gpt-5.4 provider: openai - source_hash: e4485072148753076d909867a623696829bf4a82dcd0479b95d5d0cae43100b0 + source_hash: 13004e4e20b02b08aaf16f22cdf664d0b59da69446ecb30453db51ffdfd1d267 source_path: gateway/heartbeat.md workflow: 15 --- # Heartbeat (Gateway) -> **Heartbeat o cron?** Consulta [Automazione e attività](/it/automation) per indicazioni su quando usare ciascuno. +> **Heartbeat o Cron?** Consulta [Automazione e attività](/it/automation) per indicazioni su quando usare ciascuno. -Heartbeat esegue **turni periodici dell'agente** nella sessione principale, così il modello può far emergere tutto ciò che richiede attenzione senza inviarti spam. +Heartbeat esegue **turni periodici dell'agente** nella sessione principale così il modello può +far emergere tutto ciò che richiede attenzione senza inviarti spam. Heartbeat è un turno pianificato della sessione principale — **non** crea record di [attività in background](/it/automation/tasks). -I record delle attività sono per lavoro separato (esecuzioni ACP, subagenti, job cron isolati). +I record delle attività sono per lavoro scollegato (esecuzioni ACP, subagenti, processi Cron isolati). Risoluzione dei problemi: [Attività pianificate](/it/automation/cron-jobs#troubleshooting) -## Avvio rapido (principianti) +## Guida rapida (principianti) -1. Lascia gli heartbeat abilitati (il valore predefinito è `30m`, oppure `1h` per l'autenticazione Anthropic OAuth/token, incluso il riutilizzo della Claude CLI) oppure imposta una tua cadenza. +1. Lascia attivi gli heartbeat (il valore predefinito è `30m`, oppure `1h` per l'autenticazione Anthropic OAuth/token, incluso il riutilizzo di Claude CLI) oppure imposta una cadenza personalizzata. 2. Crea una piccola checklist `HEARTBEAT.md` o un blocco `tasks:` nello spazio di lavoro dell'agente (facoltativo ma consigliato). -3. Decidi dove devono andare i messaggi heartbeat (`target: "none"` è il valore predefinito; imposta `target: "last"` per instradare verso l'ultimo contatto). -4. Facoltativo: abilita la consegna del ragionamento heartbeat per maggiore trasparenza. -5. Facoltativo: usa un contesto bootstrap leggero se le esecuzioni heartbeat richiedono solo `HEARTBEAT.md`. +3. Decidi dove devono andare i messaggi di heartbeat (`target: "none"` è il valore predefinito; imposta `target: "last"` per instradare verso l'ultimo contatto). +4. Facoltativo: abilita la consegna del ragionamento di heartbeat per maggiore trasparenza. +5. Facoltativo: usa un contesto bootstrap leggero se le esecuzioni di heartbeat richiedono solo `HEARTBEAT.md`. 6. Facoltativo: abilita sessioni isolate per evitare di inviare l'intera cronologia della conversazione a ogni heartbeat. 7. Facoltativo: limita gli heartbeat alle ore attive (ora locale). @@ -56,33 +57,45 @@ Configurazione di esempio: ## Valori predefiniti -- Intervallo: `30m` (oppure `1h` quando la modalità di autenticazione rilevata è Anthropic OAuth/token, incluso il riutilizzo della Claude CLI). Imposta `agents.defaults.heartbeat.every` oppure `agents.list[].heartbeat.every`; usa `0m` per disabilitare. +- Intervallo: `30m` (oppure `1h` quando la modalità di autenticazione rilevata è Anthropic OAuth/token, incluso il riutilizzo di Claude CLI). Imposta `agents.defaults.heartbeat.every` oppure `agents.list[].heartbeat.every`; usa `0m` per disabilitare. - Corpo del prompt (configurabile tramite `agents.defaults.heartbeat.prompt`): `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- Il prompt heartbeat viene inviato **verbatim** come messaggio utente. Il prompt di sistema include una sezione “Heartbeat” solo quando gli heartbeat sono abilitati per l'agente predefinito e l'esecuzione è contrassegnata internamente. -- Quando gli heartbeat sono disabilitati con `0m`, anche le esecuzioni normali omettono `HEARTBEAT.md` dal contesto bootstrap, così il modello non vede istruzioni solo-heartbeat. +- Il prompt di heartbeat viene inviato **testualmente** come messaggio utente. Il prompt + di sistema include una sezione “Heartbeat” solo quando gli heartbeat sono abilitati per l'agente + predefinito e l'esecuzione è contrassegnata internamente. +- Quando gli heartbeat sono disabilitati con `0m`, le esecuzioni normali omettono anche `HEARTBEAT.md` + dal contesto bootstrap così il modello non vede istruzioni riservate agli heartbeat. - Le ore attive (`heartbeat.activeHours`) vengono controllate nel fuso orario configurato. Fuori dalla finestra, gli heartbeat vengono saltati fino al tick successivo all'interno della finestra. -## A cosa serve il prompt heartbeat +## A cosa serve il prompt di heartbeat Il prompt predefinito è intenzionalmente ampio: -- **Attività in background**: “Consider outstanding tasks” spinge l'agente a rivedere i follow-up in sospeso (posta in arrivo, calendario, promemoria, lavoro in coda) e a far emergere ciò che è urgente. -- **Check-in con la persona**: “Checkup sometimes on your human during day time” incoraggia un occasionale messaggio leggero del tipo “ti serve qualcosa?”, ma evita spam notturno usando il tuo fuso orario locale configurato (vedi [/concepts/timezone](/it/concepts/timezone)). +- **Attività in background**: “Consider outstanding tasks” spinge l'agente a rivedere + i follow-up (posta in arrivo, calendario, promemoria, lavoro in coda) e a far emergere tutto ciò che è urgente. +- **Controllo con la persona**: “Checkup sometimes on your human during day time” incoraggia un + leggero messaggio occasionale del tipo “hai bisogno di qualcosa?”, ma evita lo spam notturno + usando il tuo fuso orario locale configurato (vedi [/concepts/timezone](/it/concepts/timezone)). -Heartbeat può reagire a [attività in background](/it/automation/tasks) completate, ma un'esecuzione heartbeat di per sé non crea un record attività. +Heartbeat può reagire alle [attività in background](/it/automation/tasks) completate, ma un'esecuzione heartbeat di per sé non crea un record attività. -Se vuoi che un heartbeat faccia qualcosa di molto specifico (ad esempio “controlla le statistiche Gmail PubSub” o “verifica lo stato del gateway”), imposta `agents.defaults.heartbeat.prompt` (oppure `agents.list[].heartbeat.prompt`) su un corpo personalizzato (inviato verbatim). +Se vuoi che un heartbeat faccia qualcosa di molto specifico (ad esempio “controlla le statistiche Gmail PubSub” +o “verifica lo stato del Gateway”), imposta `agents.defaults.heartbeat.prompt` (oppure +`agents.list[].heartbeat.prompt`) su un corpo personalizzato (inviato testualmente). ## Contratto di risposta -- Se non c'è nulla che richiede attenzione, rispondi con **`HEARTBEAT_OK`**. -- Durante le esecuzioni heartbeat, OpenClaw tratta `HEARTBEAT_OK` come un ack quando appare **all'inizio o alla fine** della risposta. Il token viene rimosso e la risposta viene scartata se il contenuto rimanente è **≤ `ackMaxChars`** (predefinito: 300). -- Se `HEARTBEAT_OK` appare **nel mezzo** di una risposta, non viene trattato in modo speciale. +- Se nulla richiede attenzione, rispondi con **`HEARTBEAT_OK`**. +- Durante le esecuzioni heartbeat, OpenClaw tratta `HEARTBEAT_OK` come conferma quando compare + all'**inizio o alla fine** della risposta. Il token viene rimosso e la risposta viene + scartata se il contenuto rimanente è **≤ `ackMaxChars`** (predefinito: 300). +- Se `HEARTBEAT_OK` compare **nel mezzo** di una risposta, non viene trattato + in modo speciale. - Per gli avvisi, **non** includere `HEARTBEAT_OK`; restituisci solo il testo dell'avviso. -Al di fuori degli heartbeat, un `HEARTBEAT_OK` isolato all'inizio/fine di un messaggio viene rimosso e registrato nel log; un messaggio che contiene solo `HEARTBEAT_OK` viene scartato. +Fuori dagli heartbeat, un `HEARTBEAT_OK` accidentale all'inizio/fine di un messaggio viene rimosso +e registrato; un messaggio che è solo `HEARTBEAT_OK` viene scartato. ## Configurazione @@ -95,9 +108,9 @@ Al di fuori degli heartbeat, un `HEARTBEAT_OK` isolato all'inizio/fine di un mes model: "anthropic/claude-opus-4-6", includeReasoning: false, // predefinito: false (consegna un messaggio separato Reasoning: quando disponibile) lightContext: false, // predefinito: false; true mantiene solo HEARTBEAT.md dai file bootstrap dello spazio di lavoro - isolatedSession: false, // predefinito: false; true esegue ogni heartbeat in una nuova sessione (senza cronologia conversazione) - target: "last", // predefinito: none | opzioni: last | none | (core o plugin, ad esempio "bluebubbles") - to: "+15551234567", // override facoltativo specifico del canale + isolatedSession: false, // predefinito: false; true esegue ogni heartbeat in una sessione nuova (senza cronologia conversazione) + target: "last", // predefinito: none | opzioni: last | none | (core o Plugin, ad es. "bluebubbles") + to: "+15551234567", // facoltativo, override specifico del canale accountId: "ops-bot", // id canale multi-account facoltativo prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", ackMaxChars: 300, // numero massimo di caratteri consentiti dopo HEARTBEAT_OK @@ -109,17 +122,17 @@ Al di fuori degli heartbeat, un `HEARTBEAT_OK` isolato all'inizio/fine di un mes ### Ambito e precedenza -- `agents.defaults.heartbeat` imposta il comportamento heartbeat globale. +- `agents.defaults.heartbeat` imposta il comportamento globale di heartbeat. - `agents.list[].heartbeat` viene unito sopra; se un agente ha un blocco `heartbeat`, **solo quegli agenti** eseguono heartbeat. - `channels.defaults.heartbeat` imposta i valori predefiniti di visibilità per tutti i canali. - `channels..heartbeat` sovrascrive i valori predefiniti del canale. -- `channels..accounts..heartbeat` (canali multi-account) sovrascrive per canale. +- `channels..accounts..heartbeat` (canali multi-account) sovrascrive le impostazioni per canale. ### Heartbeat per agente -Se una voce `agents.list[]` include un blocco `heartbeat`, **solo quegli agenti** +Se un qualsiasi elemento `agents.list[]` include un blocco `heartbeat`, **solo quegli agenti** eseguono heartbeat. Il blocco per agente viene unito sopra `agents.defaults.heartbeat` -(quindi puoi impostare una volta i valori condivisi e sovrascriverli per agente). +(così puoi impostare una volta valori predefiniti condivisi e sovrascriverli per singolo agente). Esempio: due agenti, solo il secondo agente esegue heartbeat. @@ -151,7 +164,7 @@ Esempio: due agenti, solo il secondo agente esegue heartbeat. ### Esempio di ore attive -Limita gli heartbeat alle ore lavorative in un fuso orario specifico: +Limita gli heartbeat all'orario lavorativo in un fuso orario specifico: ```json5 { @@ -163,7 +176,7 @@ Limita gli heartbeat alle ore lavorative in un fuso orario specifico: activeHours: { start: "09:00", end: "22:00", - timezone: "America/New_York", // facoltativo; usa il tuo userTimezone se impostato, altrimenti il fuso orario dell'host + timezone: "America/New_York", // facoltativo; usa userTimezone se impostato, altrimenti il fuso orario dell'host }, }, }, @@ -171,17 +184,17 @@ Limita gli heartbeat alle ore lavorative in un fuso orario specifico: } ``` -Fuori da questa finestra (prima delle 9 o dopo le 22 Eastern), gli heartbeat vengono saltati. Il tick pianificato successivo all'interno della finestra verrà eseguito normalmente. +Fuori da questa finestra (prima delle 9:00 o dopo le 22:00 Eastern), gli heartbeat vengono saltati. Il tick pianificato successivo all'interno della finestra verrà eseguito normalmente. ### Configurazione 24/7 Se vuoi che gli heartbeat vengano eseguiti tutto il giorno, usa uno di questi modelli: -- Ometti completamente `activeHours` (nessuna limitazione della finestra oraria; questo è il comportamento predefinito). +- Ometti completamente `activeHours` (nessuna limitazione di finestra oraria; è il comportamento predefinito). - Imposta una finestra di un'intera giornata: `activeHours: { start: "00:00", end: "24:00" }`. -Non impostare lo stesso orario per `start` e `end` (ad esempio `08:00` e `08:00`). -Questo viene trattato come una finestra di larghezza zero, quindi gli heartbeat vengono sempre saltati. +Non impostare la stessa ora per `start` ed `end` (ad esempio da `08:00` a `08:00`). +Questo viene trattato come una finestra di ampiezza zero, quindi gli heartbeat vengono sempre saltati. ### Esempio multi-account @@ -196,7 +209,7 @@ Usa `accountId` per puntare a un account specifico su canali multi-account come heartbeat: { every: "1h", target: "telegram", - to: "12345678:topic:42", // facoltativo: instrada verso un topic/thread specifico + to: "12345678:topic:42", // facoltativo: instrada a un topic/thread specifico accountId: "ops-bot", }, }, @@ -214,81 +227,84 @@ Usa `accountId` per puntare a un account specifico su canali multi-account come ### Note sui campi -- `every`: intervallo heartbeat (stringa durata; unità predefinita = minuti). +- `every`: intervallo heartbeat (stringa di durata; unità predefinita = minuti). - `model`: override facoltativo del modello per le esecuzioni heartbeat (`provider/model`). -- `includeReasoning`: quando abilitato, consegna anche il messaggio separato `Reasoning:` quando disponibile (stessa forma di `/reasoning on`). +- `includeReasoning`: quando abilitato, consegna anche il messaggio separato `Reasoning:` quando disponibile (stessa struttura di `/reasoning on`). - `lightContext`: quando è true, le esecuzioni heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` dai file bootstrap dello spazio di lavoro. -- `isolatedSession`: quando è true, ogni heartbeat viene eseguito in una nuova sessione senza cronologia di conversazione precedente. Usa lo stesso schema di isolamento di cron `sessionTarget: "isolated"`. Riduce drasticamente il costo in token per heartbeat. Combinalo con `lightContext: true` per il massimo risparmio. L'instradamento della consegna usa comunque il contesto della sessione principale. -- `session`: chiave di sessione facoltativa per le esecuzioni heartbeat. +- `isolatedSession`: quando è true, ogni heartbeat viene eseguito in una sessione nuova senza cronologia della conversazione precedente. Usa lo stesso schema di isolamento di Cron `sessionTarget: "isolated"`. Riduce drasticamente il costo in token per heartbeat. Combinalo con `lightContext: true` per il massimo risparmio. L'instradamento della consegna continua comunque a usare il contesto della sessione principale. +- `session`: chiave sessione facoltativa per le esecuzioni heartbeat. - `main` (predefinito): sessione principale dell'agente. - - Chiave di sessione esplicita (copiala da `openclaw sessions --json` o dalla [CLI sessions](/cli/sessions)). - - Formati della chiave di sessione: vedi [Sessioni](/it/concepts/session) e [Gruppi](/it/channels/groups). + - Chiave sessione esplicita (copiala da `openclaw sessions --json` o dalla [CLI sessions](/cli/sessions)). + - Formati della chiave sessione: vedi [Sessioni](/it/concepts/session) e [Gruppi](/it/channels/groups). - `target`: - `last`: consegna all'ultimo canale esterno usato. - - canale esplicito: qualunque canale configurato o id plugin, ad esempio `discord`, `matrix`, `telegram` o `whatsapp`. - - `none` (predefinito): esegue l'heartbeat ma **non consegna** all'esterno. + - canale esplicito: qualsiasi id di canale o Plugin configurato, per esempio `discord`, `matrix`, `telegram` o `whatsapp`. + - `none` (predefinito): esegui l'heartbeat ma **non consegnarlo** esternamente. - `directPolicy`: controlla il comportamento di consegna diretta/DM: - - `allow` (predefinito): consente la consegna heartbeat diretta/DM. - - `block`: sopprime la consegna diretta/DM (`reason=dm-blocked`). -- `to`: override facoltativo del destinatario (id specifico del canale, ad esempio E.164 per WhatsApp o un chat id Telegram). Per topic/thread Telegram, usa `:topic:`. -- `accountId`: id account facoltativo per canali multi-account. Quando `target: "last"`, l'id account si applica al canale last risolto se supporta gli account; altrimenti viene ignorato. Se l'id account non corrisponde a un account configurato per il canale risolto, la consegna viene saltata. + - `allow` (predefinito): consenti la consegna heartbeat diretta/DM. + - `block`: sopprimi la consegna diretta/DM (`reason=dm-blocked`). +- `to`: override facoltativo del destinatario (id specifico del canale, ad es. E.164 per WhatsApp o un id chat di Telegram). Per topic/thread di Telegram, usa `:topic:`. +- `accountId`: id account facoltativo per canali multi-account. Quando `target: "last"`, l'id account si applica all'ultimo canale risolto se supporta account; altrimenti viene ignorato. Se l'id account non corrisponde a un account configurato per il canale risolto, la consegna viene saltata. - `prompt`: sovrascrive il corpo del prompt predefinito (non viene unito). - `ackMaxChars`: numero massimo di caratteri consentiti dopo `HEARTBEAT_OK` prima della consegna. -- `suppressToolErrorWarnings`: quando è true, sopprime i payload di avviso errore degli strumenti durante le esecuzioni heartbeat. -- `activeHours`: limita le esecuzioni heartbeat a una finestra temporale. Oggetto con `start` (HH:MM, inclusivo; usa `00:00` per l'inizio del giorno), `end` (HH:MM, esclusivo; `24:00` consentito per la fine del giorno) e `timezone` facoltativo. - - Omitto oppure `"user"`: usa `agents.defaults.userTimezone` se impostato, altrimenti ripiega sul fuso orario del sistema host. +- `suppressToolErrorWarnings`: quando è true, sopprime i payload di avviso di errore degli strumenti durante le esecuzioni heartbeat. +- `activeHours`: limita le esecuzioni heartbeat a una finestra oraria. Oggetto con `start` (HH:MM, inclusivo; usa `00:00` per l'inizio del giorno), `end` (HH:MM esclusivo; `24:00` consentito per la fine del giorno) e `timezone` facoltativo. + - Ometti o `"user"`: usa `agents.defaults.userTimezone` se impostato, altrimenti ripiega sul fuso orario del sistema host. - `"local"`: usa sempre il fuso orario del sistema host. - - Qualsiasi identificatore IANA (ad esempio `America/New_York`): viene usato direttamente; se non valido, ripiega sul comportamento `"user"` sopra. - - `start` e `end` non devono essere uguali per una finestra attiva; valori uguali vengono trattati come larghezza zero (sempre fuori dalla finestra). + - Qualsiasi identificatore IANA (ad es. `America/New_York`): usato direttamente; se non valido, ripiega sul comportamento `"user"` descritto sopra. + - `start` ed `end` non devono essere uguali per una finestra attiva; valori uguali vengono trattati come ampiezza zero (sempre fuori finestra). - Fuori dalla finestra attiva, gli heartbeat vengono saltati fino al tick successivo all'interno della finestra. ## Comportamento di consegna -- Gli heartbeat vengono eseguiti nella sessione principale dell'agente per impostazione predefinita (`agent::`), - oppure `global` quando `session.scope = "global"`. Imposta `session` per sovrascrivere con una +- Per impostazione predefinita gli heartbeat vengono eseguiti nella sessione principale dell'agente (`agent::`), + oppure in `global` quando `session.scope = "global"`. Imposta `session` per sovrascrivere verso una sessione di canale specifica (Discord/WhatsApp/ecc.). - `session` influisce solo sul contesto di esecuzione; la consegna è controllata da `target` e `to`. - Per consegnare a un canale/destinatario specifico, imposta `target` + `to`. Con - `target: "last"`, la consegna usa l'ultimo canale esterno per quella sessione. -- Le consegne heartbeat consentono per impostazione predefinita destinazioni dirette/DM. Imposta `directPolicy: "block"` per sopprimere gli invii verso destinazioni dirette continuando comunque a eseguire il turno heartbeat. -- Se la coda principale è occupata, l'heartbeat viene saltato e ritentato più tardi. + `target: "last"`, la consegna usa l'ultimo canale esterno di quella sessione. +- Le consegne heartbeat consentono per impostazione predefinita destinazioni dirette/DM. Imposta `directPolicy: "block"` per sopprimere gli invii a destinazioni dirette continuando comunque a eseguire il turno heartbeat. +- Se la coda principale è occupata, l'heartbeat viene saltato e ritentato in seguito. - Se `target` non si risolve in alcuna destinazione esterna, l'esecuzione avviene comunque ma non viene inviato alcun messaggio in uscita. - Se `showOk`, `showAlerts` e `useIndicator` sono tutti disabilitati, l'esecuzione viene saltata subito con `reason=alerts-disabled`. - Se è disabilitata solo la consegna degli avvisi, OpenClaw può comunque eseguire l'heartbeat, aggiornare i timestamp delle attività in scadenza, ripristinare il timestamp di inattività della sessione e sopprimere il payload dell'avviso verso l'esterno. +- Se la destinazione heartbeat risolta supporta l'indicatore di digitazione, OpenClaw mostra la digitazione mentre + l'esecuzione heartbeat è attiva. Questo usa la stessa destinazione a cui l'heartbeat + invierebbe l'output della chat, ed è disabilitato da `typingMode: "never"`. - Le risposte solo-heartbeat **non** mantengono attiva la sessione; l'ultimo `updatedAt` viene ripristinato così la scadenza per inattività si comporta normalmente. -- Le [attività in background](/it/automation/tasks) separate possono accodare un evento di sistema e risvegliare l'heartbeat quando la sessione principale deve notare rapidamente qualcosa. Questo risveglio non fa sì che l'heartbeat esegua un'attività in background. +- Le [attività in background](/it/automation/tasks) scollegate possono accodare un evento di sistema e riattivare heartbeat quando la sessione principale deve notare rapidamente qualcosa. Questa riattivazione non fa dell'esecuzione heartbeat un'attività in background. ## Controlli di visibilità -Per impostazione predefinita, i riconoscimenti `HEARTBEAT_OK` vengono soppressi mentre il contenuto degli avvisi viene -consegnato. Puoi regolarlo per canale o per account: +Per impostazione predefinita, le conferme `HEARTBEAT_OK` vengono soppresse mentre il contenuto degli avvisi viene +consegnato. Puoi regolare questo comportamento per canale o per account: ```yaml channels: defaults: heartbeat: - showOk: false # Nascondi HEARTBEAT_OK (predefinito) + showOk: false # Nasconde HEARTBEAT_OK (predefinito) showAlerts: true # Mostra i messaggi di avviso (predefinito) - useIndicator: true # Emetti eventi indicatore (predefinito) + useIndicator: true # Emette eventi indicatore (predefinito) telegram: heartbeat: - showOk: true # Mostra i riconoscimenti OK su Telegram + showOk: true # Mostra le conferme OK su Telegram whatsapp: accounts: work: heartbeat: - showAlerts: false # Sopprimi la consegna degli avvisi per questo account + showAlerts: false # Sopprime la consegna degli avvisi per questo account ``` -Precedenza: per-account → per-channel → valori predefiniti del canale → valori predefiniti incorporati. +Precedenza: per-account → per-canale → valori predefiniti del canale → valori predefiniti integrati. ### Cosa fa ciascun flag -- `showOk`: invia un riconoscimento `HEARTBEAT_OK` quando il modello restituisce una risposta composta solo da OK. -- `showAlerts`: invia il contenuto dell'avviso quando il modello restituisce una risposta non-OK. -- `useIndicator`: emette eventi indicatore per le superfici di stato dell'interfaccia. +- `showOk`: invia una conferma `HEARTBEAT_OK` quando il modello restituisce una risposta di solo OK. +- `showAlerts`: invia il contenuto dell'avviso quando il modello restituisce una risposta diversa da OK. +- `useIndicator`: emette eventi indicatore per le superfici UI di stato. Se **tutti e tre** sono false, OpenClaw salta completamente l'esecuzione heartbeat (nessuna chiamata al modello). @@ -307,34 +323,33 @@ channels: accounts: ops: heartbeat: - showAlerts: false # sopprimi gli avvisi solo per l'account ops + showAlerts: false # sopprime gli avvisi solo per l'account ops telegram: heartbeat: showOk: true ``` -### Schemi comuni +### Modelli comuni -| Obiettivo | Configurazione | -| ---------------------------------------- | ----------------------------------------------------------------------------------------- | -| Comportamento predefinito (OK silenziosi, avvisi attivi) | _(nessuna configurazione necessaria)_ | +| Obiettivo | Configurazione | +| ---------------------------------------- | ---------------------------------------------------------------------------------------- | +| Comportamento predefinito (OK silenziosi, avvisi attivi) | _(nessuna configurazione necessaria)_ | | Completamente silenzioso (nessun messaggio, nessun indicatore) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | -| Solo indicatore (nessun messaggio) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| OK in un solo canale | `channels.telegram.heartbeat: { showOk: true }` | +| Solo indicatore (nessun messaggio) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | +| OK in un solo canale | `channels.telegram.heartbeat: { showOk: true }` | -## `HEARTBEAT.md` (facoltativo) +## HEARTBEAT.md (facoltativo) -Se nel workspace esiste un file `HEARTBEAT.md`, il prompt predefinito indica all'agente di -leggerlo. Consideralo come la tua “checklist heartbeat”: piccola, stabile e +Se nello spazio di lavoro esiste un file `HEARTBEAT.md`, il prompt predefinito dice all'agente di +leggerlo. Pensalo come la tua “checklist heartbeat”: piccola, stabile e sicura da includere ogni 30 minuti. Nelle esecuzioni normali, `HEARTBEAT.md` viene iniettato solo quando la guida heartbeat è -abilitata per l'agente predefinito. Disabilitare la cadenza heartbeat con `0m` o -impostare `includeSystemPromptSection: false` lo omette dal contesto bootstrap -normale. +abilitata per l'agente predefinito. Disabilitare la cadenza heartbeat con `0m` oppure +impostare `includeSystemPromptSection: false` lo omette dal normale contesto bootstrap. -Se `HEARTBEAT.md` esiste ma è di fatto vuoto (solo righe vuote e intestazioni markdown -come `# Heading`), OpenClaw salta l'esecuzione heartbeat per risparmiare chiamate API. +Se `HEARTBEAT.md` esiste ma è di fatto vuoto (solo righe vuote e intestazioni +markdown come `# Heading`), OpenClaw salta l'esecuzione heartbeat per risparmiare chiamate API. Questo salto viene riportato come `reason=empty-heartbeat-file`. Se il file manca, l'heartbeat viene comunque eseguito e il modello decide cosa fare. @@ -343,17 +358,17 @@ Mantienilo piccolo (checklist breve o promemoria) per evitare di appesantire il Esempio di `HEARTBEAT.md`: ```md -# Checklist heartbeat +# Checklist Heartbeat -- Scansione rapida: c'è qualcosa di urgente nelle caselle in arrivo? -- Se è giorno, fai un check-in leggero se non c'è nient'altro in sospeso. -- Se un'attività è bloccata, annota _cosa manca_ e chiedilo a Peter la prossima volta. +- Scansione rapida: c'è qualcosa di urgente nelle caselle di posta? +- Se è giorno, fai un rapido check-in se non c'è altro in sospeso. +- Se un'attività è bloccata, annota _che cosa manca_ e chiedilo a Peter la prossima volta. ``` ### Blocchi `tasks:` -`HEARTBEAT.md` supporta anche un piccolo blocco strutturato `tasks:` per controlli basati su intervalli -all'interno dello stesso heartbeat. +`HEARTBEAT.md` supporta anche un piccolo blocco strutturato `tasks:` per +controlli a intervallo all'interno di heartbeat stesso. Esempio: @@ -362,85 +377,85 @@ tasks: - name: inbox-triage interval: 30m - prompt: "Check for urgent unread emails and flag anything time sensitive." + prompt: "Controlla se ci sono email urgenti non lette e segnala tutto ciò che è sensibile al fattore tempo." - name: calendar-scan interval: 2h - prompt: "Check for upcoming meetings that need prep or follow-up." + prompt: "Controlla le riunioni imminenti che richiedono preparazione o follow-up." # Istruzioni aggiuntive -- Mantieni brevi gli avvisi. -- Se dopo tutte le attività in scadenza non c'è nulla che richiede attenzione, rispondi HEARTBEAT_OK. +- Mantieni gli avvisi brevi. +- Se nulla richiede attenzione dopo tutte le attività in scadenza, rispondi HEARTBEAT_OK. ``` Comportamento: -- OpenClaw analizza il blocco `tasks:` e controlla ogni attività rispetto al proprio `interval`. +- OpenClaw analizza il blocco `tasks:` e controlla ciascuna attività rispetto al proprio `interval`. - Solo le attività **in scadenza** vengono incluse nel prompt heartbeat per quel tick. -- Se non ci sono attività in scadenza, l'heartbeat viene saltato interamente (`reason=no-tasks-due`) per evitare una chiamata al modello sprecata. -- Il contenuto non-task in `HEARTBEAT.md` viene preservato e aggiunto come contesto supplementare dopo l'elenco delle attività in scadenza. -- I timestamp dell'ultima esecuzione delle attività vengono salvati nello stato della sessione (`heartbeatTaskState`), così gli intervalli sopravvivono ai normali riavvii. -- I timestamp delle attività vengono avanzati solo dopo che un'esecuzione heartbeat completa il proprio normale percorso di risposta. Le esecuzioni saltate `empty-heartbeat-file` / `no-tasks-due` non contrassegnano le attività come completate. +- Se non ci sono attività in scadenza, l'heartbeat viene saltato completamente (`reason=no-tasks-due`) per evitare una chiamata al modello sprecata. +- Il contenuto non relativo alle attività in `HEARTBEAT.md` viene preservato e aggiunto come contesto supplementare dopo l'elenco delle attività in scadenza. +- I timestamp dell'ultima esecuzione delle attività vengono archiviati nello stato della sessione (`heartbeatTaskState`), così gli intervalli sopravvivono ai normali riavvii. +- I timestamp delle attività vengono avanzati solo dopo che un'esecuzione heartbeat completa il normale percorso di risposta. Le esecuzioni saltate `empty-heartbeat-file` / `no-tasks-due` non segnano le attività come completate. -La modalità task è utile quando vuoi che un singolo file heartbeat contenga diversi controlli periodici senza pagarli tutti a ogni tick. +La modalità attività è utile quando vuoi che un solo file heartbeat contenga diversi controlli periodici senza pagare per tutti a ogni tick. -### L'agente può aggiornare `HEARTBEAT.md`? +### L'agente può aggiornare HEARTBEAT.md? Sì — se glielo chiedi. -`HEARTBEAT.md` è semplicemente un file normale nel workspace dell'agente, quindi puoi dire -all'agente (in una chat normale) qualcosa come: +`HEARTBEAT.md` è solo un normale file nello spazio di lavoro dell'agente, quindi puoi dire all'agente +(in una chat normale) qualcosa come: - “Aggiorna `HEARTBEAT.md` per aggiungere un controllo giornaliero del calendario.” -- “Riscrivi `HEARTBEAT.md` in modo che sia più corto e focalizzato sui follow-up della posta in arrivo.” +- “Riscrivi `HEARTBEAT.md` in modo che sia più breve e focalizzato sui follow-up della posta in arrivo.” -Se vuoi che questo accada in modo proattivo, puoi anche includere una riga esplicita nel -prompt heartbeat come: “If the checklist becomes stale, update HEARTBEAT.md -with a better one.” +Se vuoi che questo avvenga in modo proattivo, puoi anche includere una riga esplicita nel +prompt heartbeat, come: “Se la checklist diventa obsoleta, aggiorna HEARTBEAT.md +con una migliore.” Nota di sicurezza: non inserire segreti (chiavi API, numeri di telefono, token privati) in -`HEARTBEAT.md` — entra a far parte del contesto del prompt. +`HEARTBEAT.md` — diventa parte del contesto del prompt. -## Risveglio manuale (su richiesta) +## Riattivazione manuale (su richiesta) -Puoi accodare un evento di sistema e attivare un heartbeat immediato con: +Puoi accodare un evento di sistema e attivare immediatamente un heartbeat con: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -Se più agenti hanno `heartbeat` configurato, un risveglio manuale esegue immediatamente gli -heartbeat di ciascuno di quegli agenti. +Se più agenti hanno `heartbeat` configurato, una riattivazione manuale esegue immediatamente gli +heartbeat di ciascuno di questi agenti. -Usa `--mode next-heartbeat` per attendere il prossimo tick pianificato. +Usa `--mode next-heartbeat` per attendere il tick pianificato successivo. ## Consegna del ragionamento (facoltativa) -Per impostazione predefinita, gli heartbeat consegnano solo il payload finale della “risposta”. +Per impostazione predefinita, gli heartbeat consegnano solo il payload finale di “risposta”. Se vuoi trasparenza, abilita: - `agents.defaults.heartbeat.includeReasoning: true` Quando è abilitato, gli heartbeat consegneranno anche un messaggio separato con prefisso -`Reasoning:` (stessa forma di `/reasoning on`). Questo può essere utile quando l'agente -gestisce più sessioni/codex e vuoi vedere perché ha deciso di inviarti un ping -— ma può anche esporre più dettagli interni di quanto desideri. È preferibile lasciarlo +`Reasoning:` (stessa struttura di `/reasoning on`). Può essere utile quando l'agente +gestisce più sessioni/codex e vuoi capire perché ha deciso di inviarti un ping +— ma può anche esporre più dettagli interni di quanti tu ne voglia. È preferibile tenerlo disattivato nelle chat di gruppo. ## Attenzione ai costi -Gli heartbeat eseguono turni completi dell'agente. Intervalli più brevi consumano più token. Per ridurre il costo: +Gli heartbeat eseguono turni completi dell'agente. Intervalli più brevi consumano più token. Per ridurre i costi: -- Usa `isolatedSession: true` per evitare di inviare l'intera cronologia della conversazione (~100K token fino a ~2-5K per esecuzione). +- Usa `isolatedSession: true` per evitare di inviare l'intera cronologia della conversazione (~100K token ridotti a ~2-5K per esecuzione). - Usa `lightContext: true` per limitare i file bootstrap al solo `HEARTBEAT.md`. -- Imposta un `model` più economico (ad esempio `ollama/llama3.2:1b`). -- Mantieni piccolo `HEARTBEAT.md`. -- Usa `target: "none"` se vuoi solo aggiornamenti di stato interni. +- Imposta un `model` più economico (ad es. `ollama/llama3.2:1b`). +- Mantieni `HEARTBEAT.md` piccolo. +- Usa `target: "none"` se vuoi solo aggiornamenti dello stato interno. ## Correlati -- [Automazione e attività](/it/automation) — tutti i meccanismi di automazione a colpo d'occhio -- [Attività in background](/it/automation/tasks) — come viene tracciato il lavoro separato -- [Fuso orario](/it/concepts/timezone) — come il fuso orario influisce sulla pianificazione heartbeat +- [Automazione e attività](/it/automation) — panoramica di tutti i meccanismi di automazione +- [Attività in background](/it/automation/tasks) — come viene tracciato il lavoro scollegato +- [Fuso orario](/it/concepts/timezone) — come il fuso orario influisce sulla pianificazione di heartbeat - [Risoluzione dei problemi](/it/automation/cron-jobs#troubleshooting) — debug dei problemi di automazione diff --git a/docs/it/plugins/building-plugins.md b/docs/it/plugins/building-plugins.md index 7447f3421..3d85ccde3 100644 --- a/docs/it/plugins/building-plugins.md +++ b/docs/it/plugins/building-plugins.md @@ -2,30 +2,30 @@ read_when: - Vuoi creare un nuovo plugin OpenClaw - Hai bisogno di una guida rapida per lo sviluppo di plugin - - Stai aggiungendo un nuovo canale, provider, strumento o altra capacità a OpenClaw + - Stai aggiungendo un nuovo canale, provider, strumento o un'altra funzionalità a OpenClaw sidebarTitle: Getting Started summary: Crea il tuo primo plugin OpenClaw in pochi minuti -title: Creazione di plugin +title: Creazione di Plugin x-i18n: - generated_at: "2026-04-07T08:14:44Z" + generated_at: "2026-04-22T08:20:02Z" model: gpt-5.4 provider: openai - source_hash: 509c1f5abe1a0a74966054ed79b71a1a7ee637a43b1214c424acfe62ddf48eef + source_hash: 67368be311537f984f14bea9239b88c3eccf72a76c9dd1347bb041e02697ae24 source_path: plugins/building-plugins.md workflow: 15 --- -# Creazione di plugin +# Creazione di Plugin -I plugin estendono OpenClaw con nuove capacità: canali, provider di modelli, -speech, trascrizione in tempo reale, voce in tempo reale, comprensione dei media, generazione di immagini, -generazione video, recupero web, ricerca web, strumenti agente o qualsiasi +I plugin estendono OpenClaw con nuove funzionalità: canali, provider di modelli, +voce, trascrizione in tempo reale, voce in tempo reale, comprensione dei media, generazione +di immagini, generazione di video, recupero web, ricerca web, strumenti per agenti o qualsiasi combinazione. Non è necessario aggiungere il tuo plugin al repository OpenClaw. Pubblicalo su [ClawHub](/it/tools/clawhub) o su npm e gli utenti lo installano con `openclaw plugins install `. OpenClaw prova prima ClawHub e -passa automaticamente a npm in fallback. +passa automaticamente a npm in caso di fallback. ## Prerequisiti @@ -42,20 +42,20 @@ passa automaticamente a npm in fallback. Aggiungi un provider di modelli (LLM, proxy o endpoint personalizzato) - - Registra strumenti agente, hook di eventi o servizi — continua sotto + + Registra strumenti per agenti, hook di evento o servizi — continua sotto Se un plugin di canale è facoltativo e potrebbe non essere installato quando -viene eseguito l'onboarding/setup, usa `createOptionalChannelSetupSurface(...)` da -`openclaw/plugin-sdk/channel-setup`. Produce una coppia adattatore di setup + procedura guidata -che segnala il requisito di installazione e fallisce in modo chiuso sulle scritture di configurazione reali +vengono eseguiti onboarding/configurazione, usa `createOptionalChannelSetupSurface(...)` da +`openclaw/plugin-sdk/channel-setup`. Produce una coppia adattatore di configurazione + procedura guidata +che segnala il requisito di installazione e blocca in modo sicuro le scritture reali di configurazione finché il plugin non è installato. -## Avvio rapido: plugin tool +## Avvio rapido: plugin di strumento -Questa guida crea un plugin minimo che registra uno strumento agente. I plugin di canale +Questa guida crea un plugin minimo che registra uno strumento per agenti. I plugin di canale e provider hanno guide dedicate collegate sopra. @@ -125,13 +125,13 @@ e provider hanno guide dedicate collegate sopra. `definePluginEntry` è per i plugin non di canale. Per i canali, usa `defineChannelPluginEntry` — vedi [Plugin di canale](/it/plugins/sdk-channel-plugins). - Per le opzioni complete del punto di ingresso, vedi [Punti di ingresso](/it/plugins/sdk-entrypoints). + Per tutte le opzioni del punto di ingresso, vedi [Punti di ingresso](/it/plugins/sdk-entrypoints). - **Plugin esterni:** convalida e pubblica con ClawHub, poi installa: + **Plugin esterni:** valida e pubblica con ClawHub, poi installa: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -142,7 +142,7 @@ e provider hanno guide dedicate collegate sopra. OpenClaw controlla anche ClawHub prima di npm per specifiche di pacchetto semplici come `@myorg/openclaw-my-plugin`. - **Plugin nel repository:** inseriscili nell'albero workspace dei plugin inclusi — vengono rilevati automaticamente. + **Plugin nel repository:** posizionali sotto l'albero workspace dei plugin inclusi — vengono rilevati automaticamente. ```bash pnpm test -- /my-plugin/ @@ -151,56 +151,62 @@ e provider hanno guide dedicate collegate sopra. -## Capacità dei plugin +## Funzionalità dei plugin -Un singolo plugin può registrare un numero qualsiasi di capacità tramite l'oggetto `api`: +Un singolo plugin può registrare qualsiasi numero di funzionalità tramite l'oggetto `api`: -| Capacità | Metodo di registrazione | Guida dettagliata | -| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | -| Inferenza di testo (LLM) | `api.registerProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins) | -| Backend di inferenza CLI | `api.registerCliBackend(...)` | [Backend CLI](/it/gateway/cli-backends) | -| Canale / messaggistica | `api.registerChannel(...)` | [Plugin di canale](/it/plugins/sdk-channel-plugins) | -| Speech (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Funzionalità | Metodo di registrazione | Guida dettagliata | +| --------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | +| Inferenza di testo (LLM) | `api.registerProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins) | +| Backend di inferenza CLI | `api.registerCliBackend(...)` | [Backend CLI](/it/gateway/cli-backends) | +| Canale / messaggistica | `api.registerChannel(...)` | [Plugin di canale](/it/plugins/sdk-channel-plugins) | +| Voce (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Trascrizione in tempo reale | `api.registerRealtimeTranscriptionProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Voce in tempo reale | `api.registerRealtimeVoiceProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Comprensione dei media | `api.registerMediaUnderstandingProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Generazione di immagini | `api.registerImageGenerationProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Generazione musicale | `api.registerMusicGenerationProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Generazione video | `api.registerVideoGenerationProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Recupero web | `api.registerWebFetchProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Ricerca web | `api.registerWebSearchProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Strumenti agente | `api.registerTool(...)` | Sotto | -| Comandi personalizzati | `api.registerCommand(...)` | [Punti di ingresso](/it/plugins/sdk-entrypoints) | -| Hook di eventi | `api.registerHook(...)` | [Punti di ingresso](/it/plugins/sdk-entrypoints) | -| Route HTTP | `api.registerHttpRoute(...)` | [Internals](/it/plugins/architecture#gateway-http-routes) | -| Sottocomandi CLI | `api.registerCli(...)` | [Punti di ingresso](/it/plugins/sdk-entrypoints) | +| Voce in tempo reale | `api.registerRealtimeVoiceProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Comprensione dei media | `api.registerMediaUnderstandingProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Generazione di immagini | `api.registerImageGenerationProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Generazione musicale | `api.registerMusicGenerationProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Generazione di video | `api.registerVideoGenerationProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Recupero web | `api.registerWebFetchProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Ricerca web | `api.registerWebSearchProvider(...)` | [Plugin provider](/it/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Estensione Pi incorporata | `api.registerEmbeddedExtensionFactory(...)` | [Panoramica SDK](/it/plugins/sdk-overview#registration-api) | +| Strumenti per agenti | `api.registerTool(...)` | Sotto | +| Comandi personalizzati | `api.registerCommand(...)` | [Punti di ingresso](/it/plugins/sdk-entrypoints) | +| Hook di evento | `api.registerHook(...)` | [Punti di ingresso](/it/plugins/sdk-entrypoints) | +| Route HTTP | `api.registerHttpRoute(...)` | [Internals](/it/plugins/architecture#gateway-http-routes) | +| Sottocomandi CLI | `api.registerCli(...)` | [Punti di ingresso](/it/plugins/sdk-entrypoints) | Per l'API di registrazione completa, vedi [Panoramica SDK](/it/plugins/sdk-overview#registration-api). -Se il tuo plugin registra metodi RPC gateway personalizzati, mantienili su un -prefisso specifico del plugin. Gli spazi dei nomi admin core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e vengono sempre risolti in +Usa `api.registerEmbeddedExtensionFactory(...)` quando un plugin ha bisogno di hook +embedded-runner nativi di Pi, come la riscrittura asincrona di `tool_result` prima che venga emesso il messaggio finale +del risultato dello strumento. Preferisci i normali hook dei plugin OpenClaw quando +il lavoro non richiede la tempistica delle estensioni Pi. + +Se il tuo plugin registra metodi RPC Gateway personalizzati, mantienili su un +prefisso specifico del plugin. Gli spazi dei nomi di amministrazione core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e vengono sempre risolti a `operator.admin`, anche se un plugin richiede un ambito più ristretto. -Semantica delle guardie hook da tenere presente: +Semantica delle guardie degli hook da tenere presente: -- `before_tool_call`: `{ block: true }` è terminale e ferma gli handler con priorità inferiore. +- `before_tool_call`: `{ block: true }` è terminale e interrompe gli handler con priorità inferiore. - `before_tool_call`: `{ block: false }` viene trattato come nessuna decisione. -- `before_tool_call`: `{ requireApproval: true }` mette in pausa l'esecuzione dell'agente e richiede l'approvazione dell'utente tramite overlay di approvazione exec, pulsanti Telegram, interazioni Discord o il comando `/approve` su qualsiasi canale. -- `before_install`: `{ block: true }` è terminale e ferma gli handler con priorità inferiore. +- `before_tool_call`: `{ requireApproval: true }` mette in pausa l'esecuzione dell'agente e chiede all'utente l'approvazione tramite l'overlay di approvazione exec, i pulsanti Telegram, le interazioni Discord o il comando `/approve` su qualsiasi canale. +- `before_install`: `{ block: true }` è terminale e interrompe gli handler con priorità inferiore. - `before_install`: `{ block: false }` viene trattato come nessuna decisione. -- `message_sending`: `{ cancel: true }` è terminale e ferma gli handler con priorità inferiore. +- `message_sending`: `{ cancel: true }` è terminale e interrompe gli handler con priorità inferiore. - `message_sending`: `{ cancel: false }` viene trattato come nessuna decisione. -Il comando `/approve` gestisce sia le approvazioni exec sia quelle dei plugin con fallback limitato: quando un ID di approvazione exec non viene trovato, OpenClaw riprova lo stesso ID tramite le approvazioni del plugin. L'inoltro delle approvazioni del plugin può essere configurato in modo indipendente tramite `approvals.plugin` nella config. +Il comando `/approve` gestisce sia le approvazioni exec sia quelle dei plugin con fallback limitato: quando un id di approvazione exec non viene trovato, OpenClaw ritenta lo stesso id tramite le approvazioni dei plugin. L'inoltro delle approvazioni dei plugin può essere configurato in modo indipendente tramite `approvals.plugin` nella configurazione. -Se una logica di approvazione personalizzata deve rilevare quel medesimo caso di fallback limitato, +Se una logica di approvazione personalizzata deve rilevare questo stesso caso di fallback limitato, preferisci `isApprovalNotFoundError` da `openclaw/plugin-sdk/error-runtime` -invece di fare il matching manuale delle stringhe di scadenza dell'approvazione. +invece di confrontare manualmente le stringhe di scadenza dell'approvazione. -Vedi [Semantica delle decisioni hook nella panoramica SDK](/it/plugins/sdk-overview#hook-decision-semantics) per i dettagli. +Vedi [Semantica delle decisioni degli hook nella panoramica SDK](/it/plugins/sdk-overview#hook-decision-semantics) per i dettagli. -## Registrazione degli strumenti agente +## Registrazione degli strumenti per agenti Gli strumenti sono funzioni tipizzate che l'LLM può chiamare. Possono essere obbligatori (sempre disponibili) o facoltativi (attivazione esplicita dell'utente): @@ -232,7 +238,7 @@ register(api) { } ``` -Gli utenti abilitano gli strumenti facoltativi nella config: +Gli utenti abilitano gli strumenti facoltativi nella configurazione: ```json5 { @@ -240,9 +246,9 @@ Gli utenti abilitano gli strumenti facoltativi nella config: } ``` -- I nomi degli strumenti non devono entrare in conflitto con gli strumenti core (i conflitti vengono saltati) +- I nomi degli strumenti non devono entrare in conflitto con gli strumenti core (i conflitti vengono ignorati) - Usa `optional: true` per strumenti con effetti collaterali o requisiti binari aggiuntivi -- Gli utenti possono abilitare tutti gli strumenti di un plugin aggiungendo l'ID del plugin a `tools.allow` +- Gli utenti possono abilitare tutti gli strumenti di un plugin aggiungendo l'id del plugin a `tools.allow` ## Convenzioni di importazione @@ -256,29 +262,29 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { ... } from "openclaw/plugin-sdk"; ``` -Per il riferimento completo ai sottopercorsi, vedi [Panoramica SDK](/it/plugins/sdk-overview). +Per il riferimento completo dei sottopercorsi, vedi [Panoramica SDK](/it/plugins/sdk-overview). All'interno del tuo plugin, usa file barrel locali (`api.ts`, `runtime-api.ts`) per -le importazioni interne — non importare mai il tuo stesso plugin tramite il suo percorso SDK. +le importazioni interne — non importare mai il tuo plugin tramite il suo percorso SDK. Per i plugin provider, mantieni gli helper specifici del provider in quei barrel -alla radice del pacchetto, a meno che il punto di estensione non sia davvero generico. Esempi inclusi attuali: +alla radice del pacchetto, a meno che l'interfaccia non sia davvero generica. Esempi attuali inclusi: - Anthropic: wrapper di stream Claude e helper `service_tier` / beta -- OpenAI: builder dei provider, helper per il modello predefinito, provider realtime -- OpenRouter: builder del provider più helper di onboarding/config +- OpenAI: builder di provider, helper per i modelli predefiniti, provider realtime +- OpenRouter: builder di provider più helper di onboarding/configurazione -Se un helper è utile solo all'interno di un pacchetto provider incluso, mantienilo su quel -punto di estensione alla radice del pacchetto invece di promuoverlo in `openclaw/plugin-sdk/*`. +Se un helper è utile solo all'interno di un pacchetto provider incluso, mantienilo su quella +interfaccia alla radice del pacchetto invece di promuoverlo in `openclaw/plugin-sdk/*`. -Esistono ancora alcuni punti di estensione helper generati `openclaw/plugin-sdk/` per -la manutenzione e la compatibilità dei plugin inclusi, ad esempio -`plugin-sdk/feishu-setup` o `plugin-sdk/zalo-setup`. Trattali come superfici riservate, +Esistono ancora alcune interfacce helper generate `openclaw/plugin-sdk/` per +la manutenzione e la compatibilità dei plugin inclusi, per esempio +`plugin-sdk/feishu-setup` o `plugin-sdk/zalo-setup`. Trattale come superfici riservate, non come il modello predefinito per nuovi plugin di terze parti. ## Checklist pre-invio -**package.json** ha metadati `openclaw` corretti +**package.json** ha i metadati `openclaw` corretti Il manifest **openclaw.plugin.json** è presente e valido Il punto di ingresso usa `defineChannelPluginEntry` o `definePluginEntry` Tutte le importazioni usano percorsi mirati `plugin-sdk/` @@ -286,14 +292,14 @@ non come il modello predefinito per nuovi plugin di terze parti. I test passano (`pnpm test -- /my-plugin/`) `pnpm check` passa (plugin nel repository) -## Test delle beta release +## Test delle release beta -1. Tieni d'occhio i tag delle release GitHub su [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) e iscriviti tramite `Watch` > `Releases`. I tag beta hanno un aspetto simile a `v2026.3.N-beta.1`. Puoi anche attivare le notifiche per l'account X ufficiale di OpenClaw [@openclaw](https://x.com/openclaw) per gli annunci delle release. -2. Testa il tuo plugin con il tag beta non appena compare. La finestra prima della stabile di solito dura solo poche ore. -3. Scrivi nel thread del tuo plugin nel canale Discord `plugin-forum` dopo il test con `all good` oppure con ciò che si è rotto. Se non hai ancora un thread, creane uno. -4. Se qualcosa si rompe, apri o aggiorna un issue con titolo `Beta blocker: - ` e applica l'etichetta `beta-blocker`. Inserisci il link dell'issue nel tuo thread. -5. Apri una PR verso `main` con titolo `fix(): beta blocker - ` e collega l'issue sia nella PR sia nel tuo thread Discord. I contributor non possono etichettare le PR, quindi il titolo è il segnale lato PR per maintainer e automazione. I blocker con una PR vengono uniti; i blocker senza PR potrebbero comunque essere rilasciati. I maintainer osservano questi thread durante i test beta. -6. Il silenzio significa verde. Se perdi la finestra, probabilmente la tua correzione finirà nel ciclo successivo. +1. Tieni d'occhio i tag di release GitHub su [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) e iscriviti tramite `Watch` > `Releases`. I tag beta hanno un aspetto simile a `v2026.3.N-beta.1`. Puoi anche attivare le notifiche per l'account X ufficiale di OpenClaw [@openclaw](https://x.com/openclaw) per gli annunci di rilascio. +2. Testa il tuo plugin con il tag beta non appena compare. La finestra prima della versione stabile in genere dura solo poche ore. +3. Pubblica nel thread del tuo plugin nel canale Discord `plugin-forum` dopo il test con `all good` oppure indicando cosa si è rotto. Se non hai ancora un thread, creane uno. +4. Se qualcosa si rompe, apri o aggiorna un issue intitolato `Beta blocker: - ` e applica l'etichetta `beta-blocker`. Inserisci il link dell'issue nel tuo thread. +5. Apri una PR verso `main` intitolata `fix(): beta blocker - ` e collega l'issue sia nella PR sia nel tuo thread Discord. I collaboratori non possono etichettare le PR, quindi il titolo è il segnale lato PR per i maintainer e per l'automazione. I blocker con una PR vengono uniti; quelli senza potrebbero comunque essere rilasciati. I maintainer monitorano questi thread durante i test beta. +6. Il silenzio significa verde. Se perdi la finestra, probabilmente la tua correzione arriverà nel ciclo successivo. ## Passaggi successivi @@ -308,10 +314,10 @@ non come il modello predefinito per nuovi plugin di terze parti. Riferimento della mappa di importazione e dell'API di registrazione - TTS, ricerca, sottoagente tramite api.runtime + TTS, ricerca, subagent tramite api.runtime - - Utilità e pattern di test + + Utility e modelli di test Riferimento completo dello schema del manifest @@ -320,7 +326,7 @@ non come il modello predefinito per nuovi plugin di terze parti. ## Correlati -- [Architettura dei plugin](/it/plugins/architecture) — approfondimento sull'architettura interna +- [Architettura dei plugin](/it/plugins/architecture) — analisi approfondita dell'architettura interna - [Panoramica SDK](/it/plugins/sdk-overview) — riferimento del Plugin SDK - [Manifest](/it/plugins/manifest) — formato del manifest del plugin - [Plugin di canale](/it/plugins/sdk-channel-plugins) — creazione di plugin di canale diff --git a/docs/it/plugins/codex-harness.md b/docs/it/plugins/codex-harness.md index dec88c8ac..f880d6794 100644 --- a/docs/it/plugins/codex-harness.md +++ b/docs/it/plugins/codex-harness.md @@ -1,65 +1,56 @@ --- read_when: - - Vuoi usare l'harness app-server Codex incluso - - Ti servono riferimenti ai modelli Codex ed esempi di configurazione - - Vuoi disabilitare il fallback PI per distribuzioni solo Codex -summary: Esegui i turni degli agenti embedded di OpenClaw tramite l'harness app-server Codex incluso + - Vuoi usare l'harness app-server Codex incluso nel pacchetto + - Hai bisogno di riferimenti al modello Codex ed esempi di configurazione + - Vuoi disabilitare il fallback PI per le distribuzioni solo Codex +summary: Esegui i turni dell'agente incorporato di OpenClaw tramite l'harness app-server Codex incluso nel pacchetto title: Harness Codex x-i18n: - generated_at: "2026-04-21T08:25:21Z" + generated_at: "2026-04-22T08:20:01Z" model: gpt-5.4 provider: openai - source_hash: 3f0cdaf68be3b2257de1046103ff04f53f9d3a65ffc15ab7af5ab1f425643d6c + source_hash: d45dbd39a7d8ebb3a39d8dca3a5125c07b7168d1658ca07b85792645fb98613c source_path: plugins/codex-harness.md workflow: 15 --- # Harness Codex -Il plugin `codex` incluso consente a OpenClaw di eseguire i turni degli agenti embedded tramite -l'app-server Codex invece che tramite l'harness PI integrato. +Il plugin `codex` incluso nel pacchetto consente a OpenClaw di eseguire i turni dell'agente incorporato tramite l'app-server Codex invece che tramite l'harness PI integrato. -Usalo quando vuoi che Codex gestisca la sessione agente di basso livello: discovery -dei modelli, ripresa nativa dei thread, compattazione nativa ed esecuzione dell'app-server. -OpenClaw continua comunque a gestire canali chat, file di sessione, selezione del modello, strumenti, -approvazioni, consegna dei media e il mirror visibile della trascrizione. +Usalo quando vuoi che Codex gestisca la sessione agente di basso livello: rilevamento dei modelli, ripresa nativa del thread, Compaction nativa ed esecuzione dell'app-server. +OpenClaw continua comunque a gestire i canali di chat, i file di sessione, la selezione del modello, gli strumenti, le approvazioni, la consegna dei contenuti multimediali e il mirror visibile della trascrizione. -L'harness è disattivato per impostazione predefinita. Viene selezionato solo quando il plugin `codex` è -abilitato e il modello risolto è un modello `codex/*`, oppure quando forzi esplicitamente -`embeddedHarness.runtime: "codex"` o `OPENCLAW_AGENT_RUNTIME=codex`. -Se non configuri mai `codex/*`, le esecuzioni esistenti PI, OpenAI, Anthropic, Gemini, local -e custom-provider mantengono il loro comportamento attuale. +L'harness è disattivato per impostazione predefinita. Viene selezionato solo quando il plugin `codex` è abilitato e il modello risolto è un modello `codex/*`, oppure quando forzi esplicitamente `embeddedHarness.runtime: "codex"` o `OPENCLAW_AGENT_RUNTIME=codex`. +Se non configuri mai `codex/*`, le esecuzioni esistenti PI, OpenAI, Anthropic, Gemini, local e custom-provider mantengono il comportamento attuale. -## Scegli il prefisso modello corretto +## Scegli il prefisso di modello corretto OpenClaw ha percorsi separati per l'accesso in stile OpenAI e Codex: -| Riferimento modello | Percorso runtime | Usalo quando | -| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Provider OpenAI tramite plumbing OpenClaw/PI | Vuoi accesso diretto all'API OpenAI Platform con `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.4` | Provider OpenAI Codex OAuth tramite PI | Vuoi ChatGPT/Codex OAuth senza l'harness app-server Codex. | -| `codex/gpt-5.4` | Provider Codex incluso più harness Codex | Vuoi l'esecuzione nativa dell'app-server Codex per il turno agente embedded. | +| Riferimento modello | Percorso runtime | Usalo quando | +| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | +| `openai/gpt-5.4` | Provider OpenAI tramite l'infrastruttura OpenClaw/PI | Vuoi l'accesso diretto all'API di OpenAI Platform con `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.4` | Provider OpenAI Codex OAuth tramite PI | Vuoi ChatGPT/Codex OAuth senza l'harness app-server Codex. | +| `codex/gpt-5.4` | Provider Codex incluso più harness Codex | Vuoi l'esecuzione nativa dell'app-server Codex per il turno dell'agente incorporato. | -L'harness Codex acquisisce solo i riferimenti modello `codex/*`. I riferimenti esistenti `openai/*`, -`openai-codex/*`, Anthropic, Gemini, xAI, local e custom provider mantengono -i loro percorsi normali. +L'harness Codex gestisce solo i riferimenti modello `codex/*`. I riferimenti esistenti `openai/*`, `openai-codex/*`, Anthropic, Gemini, xAI, local e custom provider mantengono i loro percorsi normali. ## Requisiti -- OpenClaw con il plugin `codex` incluso disponibile. +- OpenClaw con il plugin `codex` incluso nel pacchetto disponibile. - App-server Codex `0.118.0` o successivo. -- Autenticazione Codex disponibile per il processo app-server. +- Autenticazione Codex disponibile per il processo dell'app-server. -Il plugin blocca handshake app-server più vecchi o senza versione. Questo mantiene -OpenClaw sulla superficie di protocollo su cui è stato testato. +Il plugin blocca gli handshake dell'app-server più vecchi o senza versione. In questo modo +OpenClaw resta sulla superficie di protocollo con cui è stato testato. -Per test live e smoke test Docker, l'autenticazione di solito proviene da `OPENAI_API_KEY`, più -file facoltativi della CLI Codex come `~/.codex/auth.json` e +Per i test smoke live e Docker, l'autenticazione di solito proviene da `OPENAI_API_KEY`, più file facoltativi della CLI Codex come `~/.codex/auth.json` e `~/.codex/config.toml`. Usa lo stesso materiale di autenticazione usato dal tuo app-server Codex locale. ## Configurazione minima -Usa `codex/gpt-5.4`, abilita il plugin incluso e forza l'harness `codex`: +Usa `codex/gpt-5.4`, abilita il plugin incluso nel pacchetto e forza l'harness `codex`: ```json5 { @@ -82,7 +73,7 @@ Usa `codex/gpt-5.4`, abilita il plugin incluso e forza l'harness `codex`: } ``` -Se la tua configurazione usa `plugins.allow`, includi anche `codex` lì: +Se la tua configurazione usa `plugins.allow`, includi anche `codex`: ```json5 { @@ -97,14 +88,11 @@ Se la tua configurazione usa `plugins.allow`, includi anche `codex` lì: } ``` -Impostare `agents.defaults.model` o il modello di un agente su `codex/` inoltre -abilita automaticamente il plugin `codex` incluso. La voce esplicita del plugin è comunque -utile nelle configurazioni condivise perché rende evidente l'intento della distribuzione. +Impostare `agents.defaults.model` o il modello di un agente su `codex/` abilita automaticamente anche il plugin `codex` incluso nel pacchetto. La voce esplicita del plugin resta comunque utile nelle configurazioni condivise perché rende evidente l'intento di distribuzione. ## Aggiungere Codex senza sostituire gli altri modelli -Mantieni `runtime: "auto"` quando vuoi Codex per i modelli `codex/*` e PI per -tutto il resto: +Mantieni `runtime: "auto"` quando vuoi Codex per i modelli `codex/*` e PI per tutto il resto: ```json5 { @@ -136,17 +124,16 @@ tutto il resto: } ``` -Con questa struttura: +Con questa configurazione: - `/model codex` o `/model codex/gpt-5.4` usa l'harness app-server Codex. - `/model gpt` o `/model openai/gpt-5.4` usa il percorso del provider OpenAI. - `/model opus` usa il percorso del provider Anthropic. -- Se viene selezionato un modello non-Codex, PI resta l'harness di compatibilità. +- Se viene selezionato un modello non Codex, PI resta l'harness di compatibilità. ## Distribuzioni solo Codex -Disabilita il fallback PI quando devi dimostrare che ogni turno dell'agente embedded usa -l'harness Codex: +Disabilita il fallback PI quando devi dimostrare che ogni turno dell'agente incorporato usa l'harness Codex: ```json5 { @@ -170,14 +157,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Con il fallback disabilitato, OpenClaw fallisce subito se il plugin Codex è disabilitato, -se il modello richiesto non è un riferimento `codex/*`, se l'app-server è troppo vecchio o se -l'app-server non può avviarsi. +Con il fallback disabilitato, OpenClaw fallisce subito se il plugin Codex è disabilitato, se il modello richiesto non è un riferimento `codex/*`, se l'app-server è troppo vecchio o se l'app-server non può avviarsi. -## Codex per agente +## Codex per singolo agente -Puoi rendere un agente solo Codex mentre l'agente predefinito mantiene la normale -selezione automatica: +Puoi rendere un agente solo Codex mentre l'agente predefinito mantiene la normale selezione automatica: ```json5 { @@ -208,20 +192,17 @@ selezione automatica: } ``` -Usa i normali comandi di sessione per cambiare agenti e modelli. `/new` crea una nuova -sessione OpenClaw e l'harness Codex crea o riprende il suo thread sidecar app-server -quando necessario. `/reset` cancella il binding della sessione OpenClaw per quel thread. +Usa i normali comandi di sessione per cambiare agenti e modelli. `/new` crea una nuova sessione OpenClaw e l'harness Codex crea o riprende il proprio thread sidecar dell'app-server secondo necessità. `/reset` cancella l'associazione della sessione OpenClaw per quel thread. -## Discovery dei modelli +## Rilevamento dei modelli -Per impostazione predefinita, il plugin Codex chiede all'app-server i modelli disponibili. Se -la discovery fallisce o va in timeout, usa il catalogo fallback incluso: +Per impostazione predefinita, il plugin Codex chiede all'app-server i modelli disponibili. Se il rilevamento fallisce o va in timeout, usa il catalogo di fallback incluso nel pacchetto: - `codex/gpt-5.4` - `codex/gpt-5.4-mini` - `codex/gpt-5.2` -Puoi regolare la discovery in `plugins.entries.codex.config.discovery`: +Puoi regolare il rilevamento in `plugins.entries.codex.config.discovery`: ```json5 { @@ -241,8 +222,7 @@ Puoi regolare la discovery in `plugins.entries.codex.config.discovery`: } ``` -Disabilita la discovery quando vuoi che l'avvio eviti di sondare Codex e resti sul -catalogo fallback: +Disabilita il rilevamento quando vuoi che l'avvio eviti di interrogare Codex e usi solo il catalogo di fallback: ```json5 { @@ -269,9 +249,7 @@ Per impostazione predefinita, il plugin avvia Codex localmente con: codex app-server --listen stdio:// ``` -Per impostazione predefinita, OpenClaw chiede a Codex di richiedere approvazioni native. Puoi regolare ulteriormente -questa policy, ad esempio rendendola più rigida e instradando le revisioni tramite il -guardian: +Per impostazione predefinita, OpenClaw chiede a Codex di richiedere approvazioni native. Puoi regolare ulteriormente questa policy, ad esempio irrigidendola e instradando le revisioni tramite il guardian: ```json5 { @@ -317,22 +295,21 @@ Per un app-server già in esecuzione, usa il trasporto WebSocket: Campi `appServer` supportati: -| Campo | Predefinito | Significato | -| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` avvia Codex; `"websocket"` si connette a `url`. | -| `command` | `"codex"` | Eseguibile per il trasporto stdio. | -| `args` | `["app-server", "--listen", "stdio://"]` | Argomenti per il trasporto stdio. | -| `url` | non impostato | URL WebSocket dell'app-server. | -| `authToken` | non impostato | Token Bearer per il trasporto WebSocket. | -| `headers` | `{}` | Header WebSocket aggiuntivi. | -| `requestTimeoutMs` | `60000` | Timeout per le chiamate control-plane dell'app-server. | -| `approvalPolicy` | `"on-request"` | Policy di approvazione nativa Codex inviata a start/resume/turn del thread. | -| `sandbox` | `"workspace-write"` | Modalità sandbox nativa Codex inviata a start/resume del thread. | -| `approvalsReviewer` | `"user"` | Usa `"guardian_subagent"` per lasciare che il guardian Codex esamini le approvazioni native. | -| `serviceTier` | non impostato | Service tier Codex facoltativo, ad esempio `"priority"`. | +| Campo | Predefinito | Significato | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` avvia Codex; `"websocket"` si connette a `url`. | +| `command` | `"codex"` | Eseguibile per il trasporto stdio. | +| `args` | `["app-server", "--listen", "stdio://"]` | Argomenti per il trasporto stdio. | +| `url` | non impostato | URL dell'app-server WebSocket. | +| `authToken` | non impostato | Bearer token per il trasporto WebSocket. | +| `headers` | `{}` | Intestazioni WebSocket aggiuntive. | +| `requestTimeoutMs` | `60000` | Timeout per le chiamate al control plane dell'app-server. | +| `approvalPolicy` | `"on-request"` | Policy di approvazione nativa Codex inviata a avvio/ripresa/turno del thread. | +| `sandbox` | `"workspace-write"` | Modalità sandbox nativa Codex inviata a avvio/ripresa del thread. | +| `approvalsReviewer` | `"user"` | Usa `"guardian_subagent"` per lasciare che il guardian Codex esamini le approvazioni native. | +| `serviceTier` | non impostato | Livello di servizio Codex facoltativo, ad esempio `"priority"`. | -Le variabili d'ambiente meno recenti continuano a funzionare come fallback per i test locali quando -il campo di configurazione corrispondente non è impostato: +Le vecchie variabili d'ambiente funzionano ancora come fallback per i test locali quando il campo di configurazione corrispondente non è impostato: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -358,7 +335,7 @@ Codex locale con trasporto stdio predefinito: } ``` -Validazione harness solo Codex, con fallback PI disabilitato: +Validazione dell'harness solo Codex, con fallback PI disabilitato: ```json5 { @@ -375,7 +352,7 @@ Validazione harness solo Codex, con fallback PI disabilitato: } ``` -Approvazioni Codex revisionate dal guardian: +Approvazioni Codex esaminate dal guardian: ```json5 { @@ -396,7 +373,7 @@ Approvazioni Codex revisionate dal guardian: } ``` -App-server remoto con header espliciti: +App-server remoto con intestazioni esplicite: ```json5 { @@ -419,16 +396,11 @@ App-server remoto con header espliciti: } ``` -Il cambio modello resta controllato da OpenClaw. Quando una sessione OpenClaw è collegata -a un thread Codex esistente, il turno successivo invia di nuovo all' -app-server il modello `codex/*`, provider, policy di approvazione, sandbox e service tier attualmente selezionati. -Passare da `codex/gpt-5.4` a `codex/gpt-5.2` mantiene il binding del thread ma chiede a Codex di continuare con il -nuovo modello selezionato. +Il cambio di modello resta controllato da OpenClaw. Quando una sessione OpenClaw è collegata a un thread Codex esistente, il turno successivo invia di nuovo all'app-server il modello `codex/*`, il provider, la policy di approvazione, il sandbox e il livello di servizio attualmente selezionati. Passare da `codex/gpt-5.4` a `codex/gpt-5.2` mantiene l'associazione del thread ma chiede a Codex di continuare con il modello appena selezionato. ## Comando Codex -Il plugin incluso registra `/codex` come comando slash autorizzato. È -generico e funziona su qualunque canale che supporti i comandi di testo OpenClaw. +Il plugin incluso nel pacchetto registra `/codex` come comando slash autorizzato. È generico e funziona su qualsiasi canale che supporti i comandi testuali di OpenClaw. Forme comuni: @@ -436,63 +408,43 @@ Forme comuni: - `/codex models` elenca i modelli live dell'app-server Codex. - `/codex threads [filter]` elenca i thread Codex recenti. - `/codex resume ` collega la sessione OpenClaw corrente a un thread Codex esistente. -- `/codex compact` chiede all'app-server Codex di compattare il thread collegato. +- `/codex compact` chiede all'app-server Codex di eseguire la Compaction del thread collegato. - `/codex review` avvia la revisione nativa Codex per il thread collegato. -- `/codex account` mostra stato dell'account e dei limiti di frequenza. +- `/codex account` mostra lo stato dell'account e dei limiti di frequenza. - `/codex mcp` elenca lo stato dei server MCP dell'app-server Codex. - `/codex skills` elenca le Skills dell'app-server Codex. -`/codex resume` scrive lo stesso file di binding sidecar che l'harness usa per -i normali turni. Al messaggio successivo, OpenClaw riprende quel thread Codex, passa il -modello OpenClaw `codex/*` attualmente selezionato all'app-server e mantiene abilitata la -cronologia estesa. +`/codex resume` scrive lo stesso file di associazione sidecar che l'harness usa per i turni normali. Nel messaggio successivo, OpenClaw riprende quel thread Codex, passa all'app-server il modello OpenClaw `codex/*` attualmente selezionato e mantiene abilitata la cronologia estesa. -La superficie dei comandi richiede Codex app-server `0.118.0` o successivo. I singoli -metodi di controllo vengono riportati come `unsupported by this Codex app-server` se un -futuro app-server o un app-server personalizzato non espone quel metodo JSON-RPC. +La superficie dei comandi richiede Codex app-server `0.118.0` o successivo. I singoli metodi di controllo vengono segnalati come `unsupported by this Codex app-server` se un app-server futuro o personalizzato non espone quel metodo JSON-RPC. -## Strumenti, media e compattazione +## Strumenti, contenuti multimediali e Compaction -L'harness Codex cambia solo l'esecutore embedded dell'agente di basso livello. +L'harness Codex cambia solo l'esecutore di basso livello dell'agente incorporato. -OpenClaw continua a costruire l'elenco degli strumenti e a ricevere risultati dinamici degli strumenti dall' -harness. Testo, immagini, video, musica, TTS, approvazioni e output degli strumenti di messaggistica -continuano a passare attraverso il normale percorso di consegna OpenClaw. +OpenClaw continua a costruire l'elenco degli strumenti e a ricevere risultati dinamici degli strumenti dall'harness. Testo, immagini, video, musica, TTS, approvazioni e output degli strumenti di messaggistica continuano a passare attraverso il normale percorso di consegna di OpenClaw. -Quando il modello selezionato usa l'harness Codex, la compattazione nativa del thread viene -delegata all'app-server Codex. OpenClaw mantiene un mirror della trascrizione per cronologia del canale, -ricerca, `/new`, `/reset` e futuri cambi di modello o harness. Il -mirror include il prompt utente, il testo finale dell'assistente e record leggeri di ragionamento o piano di Codex -quando l'app-server li emette. +Quando il modello selezionato usa l'harness Codex, la compattazione nativa del thread viene delegata all'app-server Codex. OpenClaw mantiene un mirror della trascrizione per la cronologia del canale, la ricerca, `/new`, `/reset` e futuri cambi di modello o harness. Il mirror include il prompt dell'utente, il testo finale dell'assistente e record leggeri di ragionamento o piano di Codex quando l'app-server li emette. -La generazione di media non richiede PI. Immagine, video, musica, PDF, TTS e comprensione -dei media continuano a usare le impostazioni provider/modello corrispondenti come -`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` e -`messages.tts`. +La generazione di contenuti multimediali non richiede PI. La generazione di immagini, video, musica, PDF, TTS e la comprensione dei contenuti multimediali continuano a usare le impostazioni provider/modello corrispondenti come `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` e `messages.tts`. ## Risoluzione dei problemi -**Codex non compare in `/model`:** abilita `plugins.entries.codex.enabled`, -imposta un riferimento modello `codex/*`, oppure controlla se `plugins.allow` esclude `codex`. +**Codex non compare in `/model`:** abilita `plugins.entries.codex.enabled`, imposta un riferimento modello `codex/*` oppure verifica se `plugins.allow` esclude `codex`. -**OpenClaw fa fallback a PI:** imposta `embeddedHarness.fallback: "none"` oppure -`OPENCLAW_AGENT_HARNESS_FALLBACK=none` durante i test. +**OpenClaw usa PI invece di Codex:** se nessun harness Codex gestisce l'esecuzione, OpenClaw può usare PI come backend di compatibilità. Imposta `embeddedHarness.runtime: "codex"` per forzare la selezione di Codex durante i test, oppure `embeddedHarness.fallback: "none"` per fallire quando nessun harness plugin corrisponde. Una volta selezionato Codex app-server, i suoi errori emergono direttamente senza configurazioni di fallback aggiuntive. -**L'app-server viene rifiutato:** aggiorna Codex in modo che l'handshake dell'app-server -riporti la versione `0.118.0` o successiva. +**L'app-server viene rifiutato:** aggiorna Codex in modo che l'handshake dell'app-server riporti la versione `0.118.0` o successiva. -**La discovery dei modelli è lenta:** riduci `plugins.entries.codex.config.discovery.timeoutMs` -oppure disabilita la discovery. +**Il rilevamento dei modelli è lento:** riduci `plugins.entries.codex.config.discovery.timeoutMs` o disabilita il rilevamento. -**Il trasporto WebSocket fallisce immediatamente:** controlla `appServer.url`, `authToken` -e che l'app-server remoto parli la stessa versione del protocollo app-server Codex. +**Il trasporto WebSocket fallisce immediatamente:** controlla `appServer.url`, `authToken` e che l'app-server remoto parli la stessa versione del protocollo app-server Codex. -**Un modello non-Codex usa PI:** è previsto. L'harness Codex gestisce solo -i riferimenti modello `codex/*`. +**Un modello non Codex usa PI:** è previsto. L'harness Codex gestisce solo i riferimenti modello `codex/*`. ## Correlati -- [Agent Harness Plugins](/it/plugins/sdk-agent-harness) -- [Model Providers](/it/concepts/model-providers) -- [Configuration Reference](/it/gateway/configuration-reference) -- [Testing](/it/help/testing#live-codex-app-server-harness-smoke) +- [Plugin Harness agente](/it/plugins/sdk-agent-harness) +- [Provider di modelli](/it/concepts/model-providers) +- [Riferimento configurazione](/it/gateway/configuration-reference) +- [Test](/it/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/it/plugins/manifest.md b/docs/it/plugins/manifest.md index 2edf33f93..4ceb0a4a9 100644 --- a/docs/it/plugins/manifest.md +++ b/docs/it/plugins/manifest.md @@ -1,78 +1,81 @@ --- read_when: - - Stai creando un Plugin OpenClaw - - Devi distribuire uno schema di configurazione del Plugin o eseguire il debug degli errori di validazione del Plugin -summary: Manifest del Plugin + requisiti dello schema JSON (validazione rigorosa della configurazione) + - Stai creando un plugin OpenClaw + - Devi distribuire uno schema di configurazione del plugin o eseguire il debug degli errori di validazione del plugin +summary: Requisiti del manifest del Plugin + schema JSON (validazione rigorosa della configurazione) title: Manifest del Plugin x-i18n: - generated_at: "2026-04-22T04:24:25Z" + generated_at: "2026-04-22T08:20:00Z" model: gpt-5.4 provider: openai - source_hash: 52a52f7e2c78bbef2cc51ade6eb12b6edc950237bdfc478f6e82248374c687bf + source_hash: 085c1baccb96b8e6bd4033ad11bdd5f79bdb0daec470e977fce723c3ae38cc99 source_path: plugins/manifest.md workflow: 15 --- # Manifest del Plugin (`openclaw.plugin.json`) -Questa pagina riguarda solo il **manifest nativo del Plugin OpenClaw**. +Questa pagina riguarda solo il **manifest nativo del plugin OpenClaw**. -Per i layout bundle compatibili, vedi [Plugin bundles](/it/plugins/bundles). +Per i layout bundle compatibili, vedi [Bundle di plugin](/it/plugins/bundles). I formati bundle compatibili usano file manifest diversi: -- bundle Codex: `.codex-plugin/plugin.json` -- bundle Claude: `.claude-plugin/plugin.json` o il layout predefinito del componente Claude - senza manifest -- bundle Cursor: `.cursor-plugin/plugin.json` +- Bundle Codex: `.codex-plugin/plugin.json` +- Bundle Claude: `.claude-plugin/plugin.json` o il layout predefinito del componente Claude + senza un manifest +- Bundle Cursor: `.cursor-plugin/plugin.json` OpenClaw rileva automaticamente anche questi layout bundle, ma non vengono validati rispetto allo schema `openclaw.plugin.json` descritto qui. -Per i bundle compatibili, OpenClaw al momento legge i metadati del bundle più le root skill -dichiarate, le root dei comandi Claude, i valori predefiniti `settings.json` del bundle Claude, +Per i bundle compatibili, OpenClaw attualmente legge i metadati del bundle più le +radici delle Skills dichiarate, le radici dei comandi Claude, i valori predefiniti di `settings.json` del bundle Claude, i valori predefiniti LSP del bundle Claude e i pacchetti hook supportati quando il layout corrisponde -alle aspettative runtime di OpenClaw. +alle aspettative del runtime OpenClaw. -Ogni Plugin OpenClaw nativo **deve** distribuire un file `openclaw.plugin.json` nella -**root del Plugin**. OpenClaw usa questo manifest per validare la configurazione -**senza eseguire codice del Plugin**. I manifest mancanti o non validi vengono trattati come -errori del Plugin e bloccano la validazione della configurazione. +Ogni plugin OpenClaw nativo **deve** distribuire un file `openclaw.plugin.json` nella +**radice del plugin**. OpenClaw usa questo manifest per validare la configurazione +**senza eseguire codice del plugin**. I manifest mancanti o non validi vengono trattati come +errori del plugin e bloccano la validazione della configurazione. -Vedi la guida completa al sistema Plugin: [Plugins](/it/tools/plugin). -Per il modello di capability nativo e le indicazioni attuali sulla compatibilità esterna: -[Capability model](/it/plugins/architecture#public-capability-model). +Vedi la guida completa al sistema di plugin: [Plugin](/it/tools/plugin). +Per il modello di capacità nativo e le indicazioni correnti sulla compatibilità esterna: +[Modello di capacità](/it/plugins/architecture#public-capability-model). ## Cosa fa questo file `openclaw.plugin.json` è il metadato che OpenClaw legge prima di caricare il codice -del tuo Plugin. +del tuo plugin. Usalo per: -- identità del Plugin +- identità del plugin - validazione della configurazione -- metadati di autenticazione e onboarding che devono essere disponibili senza avviare il runtime del Plugin -- hint di attivazione economici che le superfici del control plane possono ispezionare prima che il runtime venga caricato -- descrittori di configurazione economici che le superfici di setup/onboarding possono ispezionare prima che il runtime venga caricato -- metadati di alias e auto-enable che devono essere risolti prima che il runtime del Plugin venga caricato -- metadati shorthand di proprietà della famiglia di modelli che devono auto-attivare il - Plugin prima che il runtime venga caricato -- snapshot statici di proprietà delle capability usati per il wiring di compatibilità dei plugin inclusi e - per la copertura dei contratti -- metadati economici del runner QA che l'host condiviso `openclaw qa` può ispezionare - prima che il runtime del Plugin venga caricato -- metadati di configurazione specifici del canale che devono fondersi nelle superfici di catalogo e validazione - senza caricare il runtime -- hint UI della configurazione +- metadati di autenticazione e onboarding che devono essere disponibili senza avviare il + runtime del plugin +- suggerimenti di attivazione leggeri che le superfici di control plane possono ispezionare prima che il runtime + venga caricato +- descrittori di configurazione leggeri che le superfici di setup/onboarding possono ispezionare prima che il + runtime venga caricato +- metadati di alias e abilitazione automatica che devono essere risolti prima che il runtime del plugin venga caricato +- metadati abbreviati di appartenenza alla famiglia di modelli che devono auto-attivare il + plugin prima che il runtime venga caricato +- snapshot statiche di appartenenza delle capacità usate per il wiring di compatibilità bundle e la + copertura dei contratti +- metadati leggeri del runner QA che l'host condiviso `openclaw qa` può ispezionare + prima che il runtime del plugin venga caricato +- metadati di configurazione specifici del canale che devono essere uniti nelle + superfici di catalogo e validazione senza caricare il runtime +- suggerimenti UI per la configurazione Non usarlo per: -- registrare il comportamento runtime +- registrare il comportamento a runtime - dichiarare entrypoint del codice - metadati di installazione npm -Questi appartengono al codice del tuo Plugin e a `package.json`. +Questi appartengono al codice del tuo plugin e a `package.json`. ## Esempio minimo @@ -87,7 +90,7 @@ Questi appartengono al codice del tuo Plugin e a `package.json`. } ``` -## Esempio avanzato +## Esempio completo ```json { @@ -152,66 +155,67 @@ Questi appartengono al codice del tuo Plugin e a `package.json`. ## Riferimento dei campi di primo livello -| Campo | Obbligatorio | Tipo | Significato | -| ----------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Sì | `string` | ID canonico del Plugin. È l'ID usato in `plugins.entries.`. | -| `configSchema` | Sì | `object` | JSON Schema inline per la configurazione di questo Plugin. | -| `enabledByDefault` | No | `true` | Contrassegna un Plugin incluso come abilitato per impostazione predefinita. Omettilo, oppure imposta qualsiasi valore diverso da `true`, per lasciare il Plugin disabilitato per impostazione predefinita. | -| `legacyPluginIds` | No | `string[]` | ID legacy che vengono normalizzati a questo ID canonico del Plugin. | -| `autoEnableWhenConfiguredProviders` | No | `string[]` | ID provider che devono abilitare automaticamente questo Plugin quando autenticazione, configurazione o riferimenti ai modelli li menzionano. | -| `kind` | No | `"memory"` \| `"context-engine"` | Dichiara un tipo esclusivo di Plugin usato da `plugins.slots.*`. | -| `channels` | No | `string[]` | ID canale posseduti da questo Plugin. Usati per discovery e validazione della configurazione. | -| `providers` | No | `string[]` | ID provider posseduti da questo Plugin. | -| `modelSupport` | No | `object` | Metadati shorthand della famiglia di modelli posseduti dal manifest usati per auto-caricare il Plugin prima del runtime. | -| `providerEndpoints` | No | `object[]` | Metadati di host/baseUrl degli endpoint posseduti dal manifest per route provider che il core deve classificare prima che il runtime del provider venga caricato. | -| `cliBackends` | No | `string[]` | ID backend CLI inference posseduti da questo Plugin. Usati per l'auto-attivazione all'avvio da riferimenti espliciti di configurazione. | -| `syntheticAuthRefs` | No | `string[]` | Riferimenti provider o backend CLI il cui hook di autenticazione sintetica posseduto dal Plugin deve essere sondata durante la discovery a freddo dei modelli prima che il runtime venga caricato. | -| `nonSecretAuthMarkers` | No | `string[]` | Valori placeholder di chiave API posseduti dal Plugin incluso che rappresentano stato di credenziali locali, OAuth o ambient non segrete. | -| `commandAliases` | No | `object[]` | Nomi di comando posseduti da questo Plugin che devono produrre diagnostica consapevole del Plugin nella configurazione e nella CLI prima che il runtime venga caricato. | -| `providerAuthEnvVars` | No | `Record` | Metadati env a basso costo per l'autenticazione del provider che OpenClaw può ispezionare senza caricare il codice del Plugin. | -| `providerAuthAliases` | No | `Record` | ID provider che devono riutilizzare un altro ID provider per la ricerca dell'autenticazione, ad esempio un provider coding che condivide la chiave API del provider base e i profili di autenticazione. | -| `channelEnvVars` | No | `Record` | Metadati env a basso costo del canale che OpenClaw può ispezionare senza caricare il codice del Plugin. Usalo per superfici di setup o autenticazione del canale guidate da env che helper generici di avvio/config dovrebbero vedere. | -| `providerAuthChoices` | No | `object[]` | Metadati di scelta di autenticazione a basso costo per picker di onboarding, risoluzione del provider preferito e semplice wiring dei flag CLI. | -| `activation` | No | `object` | Hint di attivazione a basso costo per caricamento attivato da provider, comando, canale, route e capability. Solo metadati; il runtime del Plugin resta proprietario del comportamento reale. | -| `setup` | No | `object` | Descrittori di setup/onboarding a basso costo che superfici di discovery e setup possono ispezionare senza caricare il runtime del Plugin. | -| `qaRunners` | No | `object[]` | Descrittori di runner QA a basso costo usati dall'host condiviso `openclaw qa` prima che il runtime del Plugin venga caricato. | -| `contracts` | No | `object` | Snapshot statico di capability del plugin incluso per speech, trascrizione realtime, voce realtime, comprensione dei contenuti multimediali, generazione di immagini, generazione musicale, generazione video, web-fetch, ricerca web e proprietà dei tool. | -| `channelConfigs` | No | `Record` | Metadati di configurazione del canale posseduti dal manifest uniti alle superfici di discovery e validazione prima che il runtime venga caricato. | -| `skills` | No | `string[]` | Directory Skills da caricare, relative alla root del Plugin. | -| `name` | No | `string` | Nome del Plugin leggibile dall'utente. | -| `description` | No | `string` | Breve riepilogo mostrato nelle superfici del Plugin. | -| `version` | No | `string` | Versione informativa del Plugin. | -| `uiHints` | No | `Record` | Etichette UI, placeholder e hint di sensibilità per i campi di configurazione. | +| Campo | Obbligatorio | Tipo | Cosa significa | +| ------------------------------------ | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Sì | `string` | ID canonico del plugin. È l'ID usato in `plugins.entries.`. | +| `configSchema` | Sì | `object` | Schema JSON inline per la configurazione di questo plugin. | +| `enabledByDefault` | No | `true` | Contrassegna un plugin bundle come abilitato per impostazione predefinita. Omettilo, oppure imposta qualsiasi valore diverso da `true`, per lasciare il plugin disabilitato per impostazione predefinita. | +| `legacyPluginIds` | No | `string[]` | ID legacy che vengono normalizzati a questo ID canonico del plugin. | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | ID provider che dovrebbero abilitare automaticamente questo plugin quando auth, configurazione o riferimenti a modelli li menzionano. | +| `kind` | No | `"memory"` \| `"context-engine"` | Dichiara un tipo esclusivo di plugin usato da `plugins.slots.*`. | +| `channels` | No | `string[]` | ID canale posseduti da questo plugin. Usati per rilevamento e validazione della configurazione. | +| `providers` | No | `string[]` | ID provider posseduti da questo plugin. | +| `modelSupport` | No | `object` | Metadati abbreviati di famiglia di modelli posseduti dal manifest usati per caricare automaticamente il plugin prima del runtime. | +| `providerEndpoints` | No | `object[]` | Metadati di host/baseUrl degli endpoint posseduti dal manifest per route provider che il core deve classificare prima che il runtime del provider venga caricato. | +| `cliBackends` | No | `string[]` | ID backend di inferenza CLI posseduti da questo plugin. Usati per l'auto-attivazione all'avvio da riferimenti espliciti nella configurazione. | +| `syntheticAuthRefs` | No | `string[]` | Riferimenti a provider o backend CLI il cui hook di auth sintetica, posseduto dal plugin, dovrebbe essere sondato durante il rilevamento a freddo dei modelli prima che il runtime venga caricato. | +| `nonSecretAuthMarkers` | No | `string[]` | Valori segnaposto di chiavi API posseduti da plugin bundle che rappresentano stato credenziali locale, OAuth o ambient non segreto. | +| `commandAliases` | No | `object[]` | Nomi di comando posseduti da questo plugin che dovrebbero produrre configurazione consapevole del plugin e diagnostica CLI prima che il runtime venga caricato. | +| `providerAuthEnvVars` | No | `Record` | Metadati leggeri delle variabili d'ambiente di auth del provider che OpenClaw può ispezionare senza caricare il codice del plugin. | +| `providerAuthAliases` | No | `Record` | ID provider che dovrebbero riutilizzare un altro ID provider per la ricerca auth, ad esempio un provider di coding che condivide la chiave API del provider di base e i profili auth. | +| `channelEnvVars` | No | `Record` | Metadati leggeri delle variabili d'ambiente del canale che OpenClaw può ispezionare senza caricare il codice del plugin. Usali per superfici di setup o auth del canale guidate da env che helper generici di avvio/configurazione dovrebbero vedere. | +| `providerAuthChoices` | No | `object[]` | Metadati leggeri delle scelte auth per selettori di onboarding, risoluzione del provider preferito e semplice wiring di flag CLI. | +| `activation` | No | `object` | Suggerimenti di attivazione leggeri per caricamento attivato da provider, comando, canale, route e capacità. Solo metadati; il runtime del plugin continua a possedere il comportamento effettivo. | +| `setup` | No | `object` | Descrittori leggeri di setup/onboarding che le superfici di rilevamento e setup possono ispezionare senza caricare il runtime del plugin. | +| `qaRunners` | No | `object[]` | Descrittori leggeri del runner QA usati dall'host condiviso `openclaw qa` prima che il runtime del plugin venga caricato. | +| `contracts` | No | `object` | Snapshot statico di capacità bundle per proprietà di speech, trascrizione realtime, voce realtime, comprensione dei media, generazione di immagini, generazione musicale, generazione video, recupero web, ricerca web e tool. | +| `mediaUnderstandingProviderMetadata` | No | `Record` | Valori predefiniti leggeri di comprensione dei media per ID provider dichiarati in `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | No | `Record` | Metadati di configurazione del canale posseduti dal manifest, uniti nelle superfici di rilevamento e validazione prima che il runtime venga caricato. | +| `skills` | No | `string[]` | Directory Skills da caricare, relative alla radice del plugin. | +| `name` | No | `string` | Nome leggibile del plugin. | +| `description` | No | `string` | Breve riepilogo mostrato nelle superfici del plugin. | +| `version` | No | `string` | Versione informativa del plugin. | +| `uiHints` | No | `Record` | Etichette UI, segnaposto e suggerimenti di sensibilità per i campi di configurazione. | ## Riferimento `providerAuthChoices` -Ogni voce `providerAuthChoices` descrive una singola scelta di onboarding o autenticazione. +Ogni voce `providerAuthChoices` descrive una scelta di onboarding o auth. OpenClaw la legge prima che il runtime del provider venga caricato. -| Campo | Obbligatorio | Tipo | Significato | +| Campo | Obbligatorio | Tipo | Cosa significa | | --------------------- | ------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Sì | `string` | ID del provider a cui appartiene questa scelta. | -| `method` | Sì | `string` | ID del metodo di autenticazione a cui fare dispatch. | -| `choiceId` | Sì | `string` | ID stabile della scelta di autenticazione usato dai flussi di onboarding e CLI. | -| `choiceLabel` | No | `string` | Etichetta rivolta all'utente. Se omessa, OpenClaw usa `choiceId` come fallback. | -| `choiceHint` | No | `string` | Breve testo di aiuto per il picker. | -| `assistantPriority` | No | `number` | I valori più bassi vengono ordinati prima nei picker interattivi guidati dall'assistant. | -| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Nasconde la scelta dai picker dell'assistant pur consentendo ancora la selezione manuale da CLI. | -| `deprecatedChoiceIds` | No | `string[]` | ID legacy della scelta che devono reindirizzare gli utenti a questa scelta sostitutiva. | -| `groupId` | No | `string` | ID gruppo facoltativo per raggruppare scelte correlate. | -| `groupLabel` | No | `string` | Etichetta rivolta all'utente per quel gruppo. | +| `provider` | Sì | `string` | ID provider a cui appartiene questa scelta. | +| `method` | Sì | `string` | ID del metodo auth a cui instradare. | +| `choiceId` | Sì | `string` | ID stabile della scelta auth usato dai flussi di onboarding e CLI. | +| `choiceLabel` | No | `string` | Etichetta visibile all'utente. Se omessa, OpenClaw usa `choiceId` come fallback. | +| `choiceHint` | No | `string` | Breve testo di aiuto per il selettore. | +| `assistantPriority` | No | `number` | I valori più bassi vengono ordinati prima nei selettori interattivi guidati dall'assistente. | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Nasconde la scelta dai selettori dell'assistente pur consentendo comunque la selezione manuale da CLI. | +| `deprecatedChoiceIds` | No | `string[]` | ID legacy di scelta che dovrebbero reindirizzare gli utenti a questa scelta sostitutiva. | +| `groupId` | No | `string` | ID di gruppo opzionale per raggruppare scelte correlate. | +| `groupLabel` | No | `string` | Etichetta visibile all'utente per quel gruppo. | | `groupHint` | No | `string` | Breve testo di aiuto per il gruppo. | -| `optionKey` | No | `string` | Chiave opzione interna per semplici flussi di autenticazione con un solo flag. | -| `cliFlag` | No | `string` | Nome del flag CLI, come `--openrouter-api-key`. | -| `cliOption` | No | `string` | Forma completa dell'opzione CLI, come `--openrouter-api-key `. | +| `optionKey` | No | `string` | Chiave opzione interna per flussi auth semplici a flag singolo. | +| `cliFlag` | No | `string` | Nome del flag CLI, ad esempio `--openrouter-api-key`. | +| `cliOption` | No | `string` | Forma completa dell'opzione CLI, ad esempio `--openrouter-api-key `. | | `cliDescription` | No | `string` | Descrizione usata nell'help della CLI. | -| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | In quali superfici di onboarding deve comparire questa scelta. Se omesso, il valore predefinito è `["text-inference"]`. | +| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | In quali superfici di onboarding dovrebbe apparire questa scelta. Se omesso, il valore predefinito è `["text-inference"]`. | ## Riferimento `commandAliases` -Usa `commandAliases` quando un Plugin possiede un nome di comando runtime che gli utenti potrebbero -inserire erroneamente in `plugins.allow` o provare a eseguire come comando CLI root. OpenClaw -usa questi metadati per la diagnostica senza importare il codice runtime del Plugin. +Usa `commandAliases` quando un plugin possiede un nome di comando runtime che gli utenti potrebbero +inserire per errore in `plugins.allow` o provare a eseguire come comando CLI root. OpenClaw +usa questi metadati per la diagnostica senza importare il codice runtime del plugin. ```json { @@ -225,22 +229,22 @@ usa questi metadati per la diagnostica senza importare il codice runtime del Plu } ``` -| Campo | Obbligatorio | Tipo | Significato | -| ------------ | ------------ | ----------------- | ------------------------------------------------------------------------ | -| `name` | Sì | `string` | Nome del comando che appartiene a questo Plugin. | -| `kind` | No | `"runtime-slash"` | Contrassegna l'alias come comando slash della chat invece che comando CLI root. | -| `cliCommand` | No | `string` | Comando CLI root correlato da suggerire per operazioni CLI, se esiste. | +| Campo | Obbligatorio | Tipo | Cosa significa | +| ------------ | ------------ | ----------------- | ----------------------------------------------------------------------- | +| `name` | Sì | `string` | Nome del comando che appartiene a questo plugin. | +| `kind` | No | `"runtime-slash"` | Contrassegna l'alias come comando slash di chat anziché come comando CLI root. | +| `cliCommand` | No | `string` | Comando CLI root correlato da suggerire per operazioni CLI, se esiste. | ## Riferimento `activation` -Usa `activation` quando il Plugin può dichiarare in modo economico quali eventi del control plane +Usa `activation` quando il plugin può dichiarare in modo leggero quali eventi del control plane dovrebbero attivarlo in seguito. ## Riferimento `qaRunners` -Usa `qaRunners` quando un Plugin contribuisce con uno o più transport runner sotto -la root condivisa `openclaw qa`. Mantieni questi metadati economici e statici; il runtime del Plugin -resta proprietario dell'effettiva registrazione CLI tramite una superficie leggera +Usa `qaRunners` quando un plugin contribuisce con uno o più runner di trasporto sotto la radice condivisa +`openclaw qa`. Mantieni questi metadati leggeri e statici; il runtime del plugin continua a possedere +la registrazione CLI effettiva tramite una superficie leggera `runtime-api.ts` che esporta `qaRunnerCliRegistrations`. ```json @@ -248,21 +252,21 @@ resta proprietario dell'effettiva registrazione CLI tramite una superficie legge "qaRunners": [ { "commandName": "matrix", - "description": "Esegue la lane QA live Matrix supportata da Docker contro un homeserver usa e getta" + "description": "Esegui la corsia QA live Matrix supportata da Docker contro un homeserver usa e getta" } ] } ``` -| Campo | Obbligatorio | Tipo | Significato | -| ------------- | ------------ | -------- | --------------------------------------------------------------- | -| `commandName` | Sì | `string` | Sottocomando montato sotto `openclaw qa`, ad esempio `matrix`. | -| `description` | No | `string` | Testo di help di fallback usato quando l'host condiviso ha bisogno di un comando stub. | +| Campo | Obbligatorio | Tipo | Cosa significa | +| ------------- | ------------ | -------- | ----------------------------------------------------------------- | +| `commandName` | Sì | `string` | Sottocomando montato sotto `openclaw qa`, ad esempio `matrix`. | +| `description` | No | `string` | Testo di help di fallback usato quando l'host condiviso richiede un comando stub. | Questo blocco contiene solo metadati. Non registra comportamento runtime e non -sostituisce `register(...)`, `setupEntry` o altri entrypoint runtime/Plugin. -Gli attuali consumer lo usano come hint di restringimento prima di un caricamento più ampio del Plugin, quindi -metadati di attivazione mancanti di solito comportano solo un costo in termini di prestazioni; non dovrebbero +sostituisce `register(...)`, `setupEntry` o altri entrypoint runtime/plugin. +I consumer attuali lo usano come suggerimento di restringimento prima di un caricamento plugin più ampio, quindi +la mancanza di metadati di attivazione di solito comporta solo un costo in termini di prestazioni; non dovrebbe cambiare la correttezza finché esistono ancora i fallback legacy di proprietà del manifest. ```json @@ -277,27 +281,27 @@ cambiare la correttezza finché esistono ancora i fallback legacy di proprietà } ``` -| Campo | Obbligatorio | Tipo | Significato | -| ---------------- | ------------ | ---------------------------------------------------- | -------------------------------------------------------------- | -| `onProviders` | No | `string[]` | ID provider che devono attivare questo Plugin quando richiesti. | -| `onCommands` | No | `string[]` | ID comando che devono attivare questo Plugin. | -| `onChannels` | No | `string[]` | ID canale che devono attivare questo Plugin. | -| `onRoutes` | No | `string[]` | Tipi di route che devono attivare questo Plugin. | -| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Hint ampi di capability usati dalla pianificazione di attivazione del control plane. | +| Campo | Obbligatorio | Tipo | Cosa significa | +| ---------------- | ------------ | ---------------------------------------------------- | ----------------------------------------------------------------- | +| `onProviders` | No | `string[]` | ID provider che dovrebbero attivare questo plugin quando richiesti. | +| `onCommands` | No | `string[]` | ID comando che dovrebbero attivare questo plugin. | +| `onChannels` | No | `string[]` | ID canale che dovrebbero attivare questo plugin. | +| `onRoutes` | No | `string[]` | Tipi di route che dovrebbero attivare questo plugin. | +| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Suggerimenti ampi di capacità usati dalla pianificazione di attivazione del control plane. | Consumer live attuali: -- la pianificazione CLI attivata da comando fa fallback ai legacy - `commandAliases[].cliCommand` oppure `commandAliases[].name` -- la pianificazione di setup/canale attivata da canale fa fallback alla proprietà legacy `channels[]` - quando mancano metadati espliciti di attivazione del canale -- la pianificazione di setup/runtime attivata da provider fa fallback alla proprietà legacy - `providers[]` e a `cliBackends[]` di primo livello quando mancano metadati espliciti - di attivazione del provider +- la pianificazione CLI attivata dai comandi usa come fallback + `commandAliases[].cliCommand` o `commandAliases[].name` legacy +- la pianificazione setup/canale attivata dai canali usa come fallback la proprietà + `channels[]` legacy quando mancano metadati espliciti di attivazione del canale +- la pianificazione setup/runtime attivata dai provider usa come fallback la proprietà + legacy `providers[]` e `cliBackends[]` di primo livello quando mancano metadati espliciti di attivazione + del provider ## Riferimento `setup` -Usa `setup` quando le superfici di setup e onboarding hanno bisogno di metadati economici posseduti dal Plugin +Usa `setup` quando le superfici di setup e onboarding hanno bisogno di metadati leggeri posseduti dal plugin prima che il runtime venga caricato. ```json @@ -317,40 +321,41 @@ prima che il runtime venga caricato. } ``` -`cliBackends` di primo livello resta valido e continua a descrivere i backend CLI inference. -`setup.cliBackends` è la superficie descrittiva specifica del setup per +`cliBackends` di primo livello resta valido e continua a descrivere i backend +di inferenza CLI. `setup.cliBackends` è la superficie descrittiva specifica del setup per i flussi di control plane/setup che devono restare solo metadati. -Quando presenti, `setup.providers` e `setup.cliBackends` sono la superficie preferita -descriptor-first per la discovery del setup. Se il descrittore restringe solo il Plugin candidato e il setup ha ancora bisogno di hook runtime più ricchi al momento del setup, +Quando presenti, `setup.providers` e `setup.cliBackends` sono la superficie di lookup preferita, +basata prima sui descrittori, per il rilevamento del setup. Se il descrittore restringe solo +il plugin candidato e il setup ha ancora bisogno di hook runtime più ricchi in fase di setup, imposta `requiresRuntime: true` e mantieni `setup-api` come percorso di esecuzione di fallback. -Poiché la ricerca del setup può eseguire codice `setup-api` posseduto dal Plugin, i valori normalizzati -`setup.providers[].id` e `setup.cliBackends[]` devono restare univoci tra -i Plugin rilevati. La proprietà ambigua fallisce in modo fail-closed invece di scegliere un -vincitore in base all'ordine di discovery. +Poiché il lookup del setup può eseguire codice `setup-api` posseduto dal plugin, i valori normalizzati +di `setup.providers[].id` e `setup.cliBackends[]` devono restare univoci tra +i plugin rilevati. Una proprietà ambigua fallisce in modo conservativo invece di scegliere un +vincitore in base all'ordine di rilevamento. ### Riferimento `setup.providers` -| Campo | Obbligatorio | Tipo | Significato | -| ------------- | ------------ | ---------- | --------------------------------------------------------------------------------- | -| `id` | Sì | `string` | ID provider esposto durante setup o onboarding. Mantieni gli ID normalizzati globalmente univoci. | -| `authMethods` | No | `string[]` | ID dei metodi di setup/autenticazione che questo provider supporta senza caricare il runtime completo. | -| `envVars` | No | `string[]` | Variabili d'ambiente che le superfici generiche di setup/stato possono controllare prima che il runtime del Plugin venga caricato. | +| Campo | Obbligatorio | Tipo | Cosa significa | +| ------------- | ------------ | ---------- | ----------------------------------------------------------------------------------- | +| `id` | Sì | `string` | ID provider esposto durante setup o onboarding. Mantieni gli ID normalizzati univoci a livello globale. | +| `authMethods` | No | `string[]` | ID dei metodi di setup/auth che questo provider supporta senza caricare il runtime completo. | +| `envVars` | No | `string[]` | Variabili d'ambiente che le superfici generiche di setup/stato possono controllare prima che il runtime del plugin venga caricato. | ### Campi `setup` -| Campo | Obbligatorio | Tipo | Significato | -| ------------------ | ------------ | ---------- | ------------------------------------------------------------------------------------------------ | -| `providers` | No | `object[]` | Descrittori di setup del provider esposti durante setup e onboarding. | -| `cliBackends` | No | `string[]` | ID backend al momento del setup usati per la ricerca descriptor-first del setup. Mantieni gli ID normalizzati globalmente univoci. | -| `configMigrations` | No | `string[]` | ID di migrazione della configurazione posseduti dalla superficie setup di questo Plugin. | -| `requiresRuntime` | No | `boolean` | Se il setup ha ancora bisogno dell'esecuzione di `setup-api` dopo la ricerca del descrittore. | +| Campo | Obbligatorio | Tipo | Cosa significa | +| ------------------ | ------------ | ---------- | -------------------------------------------------------------------------------------------------- | +| `providers` | No | `object[]` | Descrittori di setup del provider esposti durante setup e onboarding. | +| `cliBackends` | No | `string[]` | ID backend in fase di setup usati per il lookup del setup descriptor-first. Mantieni gli ID normalizzati univoci a livello globale. | +| `configMigrations` | No | `string[]` | ID di migrazione della configurazione posseduti dalla superficie di setup di questo plugin. | +| `requiresRuntime` | No | `boolean` | Se il setup richiede ancora l'esecuzione di `setup-api` dopo il lookup del descrittore. | ## Riferimento `uiHints` -`uiHints` è una mappa dai nomi dei campi di configurazione a piccoli hint di rendering. +`uiHints` è una mappa dai nomi dei campi di configurazione a piccoli suggerimenti di rendering. ```json { @@ -365,25 +370,26 @@ vincitore in base all'ordine di discovery. } ``` -Ogni hint di campo può includere: +Ogni suggerimento di campo può includere: -| Campo | Tipo | Significato | +| Campo | Tipo | Cosa significa | | ------------- | ---------- | ---------------------------------------- | -| `label` | `string` | Etichetta del campo rivolta all'utente. | +| `label` | `string` | Etichetta del campo visibile all'utente. | | `help` | `string` | Breve testo di aiuto. | -| `tags` | `string[]` | Tag UI facoltativi. | +| `tags` | `string[]` | Tag UI opzionali. | | `advanced` | `boolean` | Contrassegna il campo come avanzato. | -| `sensitive` | `boolean` | Contrassegna il campo come secret o sensibile. | -| `placeholder` | `string` | Testo segnaposto per gli input del modulo. | +| `sensitive` | `boolean` | Contrassegna il campo come segreto o sensibile. | +| `placeholder` | `string` | Testo segnaposto per gli input dei moduli. | ## Riferimento `contracts` -Usa `contracts` solo per metadati statici di proprietà delle capability che OpenClaw può -leggere senza importare il runtime del Plugin. +Usa `contracts` solo per metadati statici di proprietà delle capacità che OpenClaw può +leggere senza importare il runtime del plugin. ```json { "contracts": { + "embeddedExtensionFactories": ["pi"], "speechProviders": ["openai"], "realtimeTranscriptionProviders": ["openai"], "realtimeVoiceProviders": ["openai"], @@ -397,23 +403,61 @@ leggere senza importare il runtime del Plugin. } ``` -Ogni elenco è facoltativo: +Ogni lista è facoltativa: -| Campo | Tipo | Significato | -| -------------------------------- | ---------- | ------------------------------------------------------------ | -| `speechProviders` | `string[]` | ID provider speech posseduti da questo Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | ID provider di trascrizione realtime posseduti da questo Plugin. | -| `realtimeVoiceProviders` | `string[]` | ID provider di voce realtime posseduti da questo Plugin. | -| `mediaUnderstandingProviders` | `string[]` | ID provider di comprensione dei contenuti multimediali posseduti da questo Plugin. | -| `imageGenerationProviders` | `string[]` | ID provider di generazione immagini posseduti da questo Plugin. | -| `videoGenerationProviders` | `string[]` | ID provider di generazione video posseduti da questo Plugin. | -| `webFetchProviders` | `string[]` | ID provider web-fetch posseduti da questo Plugin. | -| `webSearchProviders` | `string[]` | ID provider di ricerca web posseduti da questo Plugin. | -| `tools` | `string[]` | Nomi dei tool agent posseduti da questo Plugin per i controlli di contratto dei plugin inclusi. | +| Campo | Tipo | Cosa significa | +| -------------------------------- | ---------- | --------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | ID runtime incorporati per cui un plugin bundle può registrare factory. | +| `speechProviders` | `string[]` | ID provider speech posseduti da questo plugin. | +| `realtimeTranscriptionProviders` | `string[]` | ID provider di trascrizione realtime posseduti da questo plugin. | +| `realtimeVoiceProviders` | `string[]` | ID provider voce realtime posseduti da questo plugin. | +| `mediaUnderstandingProviders` | `string[]` | ID provider di comprensione dei media posseduti da questo plugin. | +| `imageGenerationProviders` | `string[]` | ID provider di generazione immagini posseduti da questo plugin. | +| `videoGenerationProviders` | `string[]` | ID provider di generazione video posseduti da questo plugin. | +| `webFetchProviders` | `string[]` | ID provider di recupero web posseduti da questo plugin. | +| `webSearchProviders` | `string[]` | ID provider di ricerca web posseduti da questo plugin. | +| `tools` | `string[]` | Nomi dei tool agente posseduti da questo plugin per i controlli dei contratti bundle. | + +## Riferimento `mediaUnderstandingProviderMetadata` + +Usa `mediaUnderstandingProviderMetadata` quando un provider di comprensione dei media ha +modelli predefiniti, priorità di fallback auto-auth o supporto nativo ai documenti di cui +gli helper core generici hanno bisogno prima che il runtime venga caricato. Le chiavi devono anche essere dichiarate in +`contracts.mediaUnderstandingProviders`. + +```json +{ + "contracts": { + "mediaUnderstandingProviders": ["example"] + }, + "mediaUnderstandingProviderMetadata": { + "example": { + "capabilities": ["image", "audio"], + "defaultModels": { + "image": "example-vision-latest", + "audio": "example-transcribe-latest" + }, + "autoPriority": { + "image": 40 + }, + "nativeDocumentInputs": ["pdf"] + } + } +} +``` + +Ogni voce provider può includere: + +| Campo | Tipo | Cosa significa | +| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Capacità media esposte da questo provider. | +| `defaultModels` | `Record` | Valori predefiniti capacità-modello usati quando la configurazione non specifica un modello. | +| `autoPriority` | `Record` | I numeri più bassi vengono ordinati prima per il fallback automatico del provider basato sulle credenziali. | +| `nativeDocumentInputs` | `"pdf"[]` | Input documento nativi supportati dal provider. | ## Riferimento `channelConfigs` -Usa `channelConfigs` quando un plugin di canale ha bisogno di metadati di configurazione economici prima +Usa `channelConfigs` quando un plugin canale ha bisogno di metadati di configurazione leggeri prima che il runtime venga caricato. ```json @@ -429,12 +473,12 @@ che il runtime venga caricato. }, "uiHints": { "homeserverUrl": { - "label": "URL dell'homeserver", + "label": "URL homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Connessione all'homeserver Matrix", + "description": "Connessione homeserver Matrix", "preferOver": ["matrix-legacy"] } } @@ -443,18 +487,18 @@ che il runtime venga caricato. Ogni voce canale può includere: -| Campo | Tipo | Significato | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema per `channels.`. Obbligatorio per ogni voce di configurazione canale dichiarata. | -| `uiHints` | `Record` | Etichette UI/placeholder/hint di sensibilità facoltativi per quella sezione di configurazione del canale. | -| `label` | `string` | Etichetta del canale unita alle superfici di picker e inspect quando i metadati runtime non sono pronti. | -| `description` | `string` | Breve descrizione del canale per le superfici inspect e catalogo. | -| `preferOver` | `string[]` | ID Plugin legacy o di priorità inferiore che questo canale deve superare nelle superfici di selezione. | +| Campo | Tipo | Cosa significa | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | Schema JSON per `channels.`. Obbligatorio per ogni voce dichiarata di configurazione del canale. | +| `uiHints` | `Record` | Etichette UI/segnaposto/suggerimenti di sensibilità facoltativi per quella sezione di configurazione del canale. | +| `label` | `string` | Etichetta del canale unita nelle superfici di selezione e ispezione quando i metadati runtime non sono pronti. | +| `description` | `string` | Breve descrizione del canale per le superfici di ispezione e catalogo. | +| `preferOver` | `string[]` | ID plugin legacy o a priorità inferiore che questo canale dovrebbe superare nelle superfici di selezione. | ## Riferimento `modelSupport` -Usa `modelSupport` quando OpenClaw deve dedurre il tuo Plugin provider da -ID di modello shorthand come `gpt-5.4` o `claude-sonnet-4.6` prima che il runtime del Plugin +Usa `modelSupport` quando OpenClaw dovrebbe dedurre il tuo plugin provider da +ID modello abbreviati come `gpt-5.4` o `claude-sonnet-4.6` prima che il runtime del plugin venga caricato. ```json @@ -470,83 +514,83 @@ OpenClaw applica questa precedenza: - i riferimenti espliciti `provider/model` usano i metadati `providers` del manifest proprietario - `modelPatterns` hanno precedenza su `modelPrefixes` -- se un Plugin non incluso e un Plugin incluso corrispondono entrambi, vince il Plugin - non incluso +- se corrispondono sia un plugin non bundle sia un plugin bundle, vince il plugin + non bundle - l'ambiguità rimanente viene ignorata finché l'utente o la configurazione non specificano un provider Campi: -| Campo | Tipo | Significato | -| --------------- | ---------- | ---------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Prefissi confrontati con `startsWith` sugli ID di modello shorthand. | -| `modelPatterns` | `string[]` | Sorgenti regex confrontate sugli ID di modello shorthand dopo la rimozione del suffisso del profilo. | +| Campo | Tipo | Cosa significa | +| --------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Prefissi confrontati con `startsWith` rispetto agli ID modello abbreviati. | +| `modelPatterns` | `string[]` | Sorgenti regex confrontate rispetto agli ID modello abbreviati dopo la rimozione del suffisso del profilo. | -Le chiavi legacy di capability di primo livello sono deprecate. Usa `openclaw doctor --fix` per +Le chiavi legacy di capacità di primo livello sono deprecate. Usa `openclaw doctor --fix` per spostare `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` sotto `contracts`; il normale caricamento del manifest non tratta più quei campi di primo livello come -proprietà di capability. +proprietà delle capacità. -## Manifest rispetto a `package.json` +## Manifest rispetto a package.json -I due file svolgono compiti diversi: +I due file hanno ruoli diversi: -| File | Usalo per | +| File | Usalo per | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Discovery, validazione della configurazione, metadati della scelta di autenticazione e hint UI che devono esistere prima che il codice del Plugin venga eseguito | -| `package.json` | Metadati npm, installazione delle dipendenze e blocco `openclaw` usato per entrypoint, gating di installazione, setup o metadati di catalogo | +| `openclaw.plugin.json` | Rilevamento, validazione della configurazione, metadati delle scelte auth e suggerimenti UI che devono esistere prima dell'esecuzione del codice del plugin | +| `package.json` | Metadati npm, installazione delle dipendenze e blocco `openclaw` usato per entrypoint, gating dell'installazione, setup o metadati di catalogo | -Se non sei sicuro di dove appartenga un metadato, usa questa regola: +Se non sei sicuro di dove debba andare un metadato, usa questa regola: -- se OpenClaw deve conoscerlo prima di caricare il codice del Plugin, mettilo in `openclaw.plugin.json` -- se riguarda packaging, file di entry o comportamento di installazione npm, mettilo in `package.json` +- se OpenClaw deve conoscerlo prima di caricare il codice del plugin, inseriscilo in `openclaw.plugin.json` +- se riguarda packaging, file di entry o comportamento di installazione npm, inseriscilo in `package.json` -### Campi `package.json` che influenzano la discovery +### Campi `package.json` che influenzano il rilevamento -Alcuni metadati del Plugin pre-runtime vivono intenzionalmente in `package.json` sotto il blocco +Alcuni metadati del plugin pre-runtime vivono intenzionalmente in `package.json` sotto il blocco `openclaw` invece che in `openclaw.plugin.json`. Esempi importanti: -| Campo | Significato | -| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Dichiara gli entrypoint nativi del Plugin. Deve restare dentro la directory del pacchetto del Plugin. | -| `openclaw.runtimeExtensions` | Dichiara gli entrypoint runtime JavaScript buildati per i pacchetti installati. Deve restare dentro la directory del pacchetto del Plugin. | -| `openclaw.setupEntry` | Entry point leggero solo-setup usato durante onboarding, avvio canale differito e discovery di stato canale/SecretRef in sola lettura. Deve restare dentro la directory del pacchetto del Plugin. | -| `openclaw.runtimeSetupEntry` | Dichiara l'entrypoint setup JavaScript buildato per i pacchetti installati. Deve restare dentro la directory del pacchetto del Plugin. | -| `openclaw.channel` | Metadati economici del catalogo canale come etichette, percorsi docs, alias e testo di selezione. | -| `openclaw.channel.configuredState` | Metadati leggeri del controllo dello stato configurato che possono rispondere a "esiste già una configurazione solo-env?" senza caricare il runtime completo del canale. | -| `openclaw.channel.persistedAuthState` | Metadati leggeri del controllo dello stato di autenticazione persistito che possono rispondere a "qualcosa è già autenticato?" senza caricare il runtime completo del canale. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Hint di installazione/aggiornamento per Plugin inclusi e pubblicati esternamente. | -| `openclaw.install.defaultChoice` | Percorso di installazione preferito quando sono disponibili più sorgenti di installazione. | -| `openclaw.install.minHostVersion` | Versione minima supportata dell'host OpenClaw, usando una soglia semver come `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Consente un ristretto percorso di recupero di reinstallazione del Plugin incluso quando la configurazione non è valida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Consente alle superfici del canale solo-setup di caricarsi prima del plugin di canale completo durante l'avvio. | +| Campo | Cosa significa | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.extensions` | Dichiara entrypoint nativi del plugin. Devono restare all'interno della directory del pacchetto plugin. | +| `openclaw.runtimeExtensions` | Dichiara entrypoint runtime JavaScript compilati per i pacchetti installati. Devono restare all'interno della directory del pacchetto plugin. | +| `openclaw.setupEntry` | EntryPoint leggero solo setup usato durante onboarding, avvio differito del canale e rilevamento in sola lettura di stato del canale/SecretRef. Deve restare all'interno della directory del pacchetto plugin. | +| `openclaw.runtimeSetupEntry` | Dichiara l'entrypoint setup JavaScript compilato per i pacchetti installati. Deve restare all'interno della directory del pacchetto plugin. | +| `openclaw.channel` | Metadati leggeri del catalogo canali come etichette, percorsi della documentazione, alias e testo di selezione. | +| `openclaw.channel.configuredState` | Metadati leggeri del controllo dello stato configurato che possono rispondere a "esiste già una configurazione solo-env?" senza caricare il runtime completo del canale. | +| `openclaw.channel.persistedAuthState` | Metadati leggeri del controllo dello stato auth persistito che possono rispondere a "qualcuno ha già effettuato l'accesso?" senza caricare il runtime completo del canale. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Suggerimenti di installazione/aggiornamento per plugin bundle e plugin pubblicati esternamente. | +| `openclaw.install.defaultChoice` | Percorso di installazione preferito quando sono disponibili più sorgenti di installazione. | +| `openclaw.install.minHostVersion` | Versione minima supportata dell'host OpenClaw, usando una soglia semver come `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Consente un percorso ristretto di ripristino tramite reinstallazione del plugin bundle quando la configurazione non è valida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Consente alle superfici del canale solo setup di caricarsi prima del plugin canale completo durante l'avvio. | `openclaw.install.minHostVersion` viene applicato durante l'installazione e il caricamento del registro dei manifest. I valori non validi vengono rifiutati; i valori -validi ma più recenti saltano il Plugin su host più vecchi. +più recenti ma validi saltano il plugin sugli host meno recenti. -I plugin di canale dovrebbero fornire `openclaw.setupEntry` quando stato, elenco canali -o scansioni SecretRef devono identificare gli account configurati senza caricare il runtime completo. -L'entrypoint di setup dovrebbe esporre metadati del canale più adattatori sicuri per setup di configurazione, -stato e secret; mantieni client di rete, listener del gateway e runtime di trasporto -nell'entrypoint principale dell'extension. +I plugin canale dovrebbero fornire `openclaw.setupEntry` quando stato, elenco canali +o scansioni SecretRef devono identificare account configurati senza caricare il runtime completo. +L'entry setup dovrebbe esporre metadati del canale più adattatori di configurazione, +stato e segreti sicuri per il setup; mantieni client di rete, listener Gateway e runtime di trasporto +nell'entrypoint principale dell'estensione. -I campi di entrypoint runtime non sovrascrivono i controlli dei confini del pacchetto per i campi -di entrypoint sorgente. Ad esempio, `openclaw.runtimeExtensions` non può rendere caricabile un -percorso `openclaw.extensions` che esce dai confini. +I campi dell'entrypoint runtime non ignorano i controlli dei confini del pacchetto per i campi +dell'entrypoint sorgente. Per esempio, `openclaw.runtimeExtensions` non può rendere +caricabile un percorso `openclaw.extensions` che esce dai confini consentiti. `openclaw.install.allowInvalidConfigRecovery` è intenzionalmente ristretto. Non -rende installabili configurazioni arbitrarie non funzionanti. Oggi consente solo ai flussi di installazione di recuperare da specifici errori di aggiornamento stantii del Plugin incluso, come un -percorso del Plugin incluso mancante o una voce `channels.` obsoleta per quello stesso -Plugin incluso. Errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori +rende installabili configurazioni arbitrarie non valide. Oggi consente solo ai flussi di installazione +di recuperare da specifici errori obsoleti di aggiornamento dei plugin bundle, come un +percorso mancante di plugin bundle o una voce `channels.` obsoleta per quello stesso +plugin bundle. Errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori a `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` è un metadato di pacchetto per un piccolo -modulo checker: +`openclaw.channel.persistedAuthState` è un metadato di pacchetto per un piccolo modulo di controllo: ```json { @@ -562,13 +606,13 @@ modulo checker: } ``` -Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di un probe economico yes/no -sull'autenticazione prima che il plugin di canale completo venga caricato. L'export di destinazione dovrebbe essere una piccola +Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di una sonda auth +economica sì/no prima che il plugin canale completo venga caricato. L'export di destinazione dovrebbe essere una piccola funzione che legge solo lo stato persistito; non instradarla attraverso il barrel runtime completo del canale. -`openclaw.channel.configuredState` segue la stessa forma per controlli economici -dello stato configurato solo-env: +`openclaw.channel.configuredState` segue la stessa forma per controlli economici dello stato +configurato solo-env: ```json { @@ -584,94 +628,96 @@ dello stato configurato solo-env: } ``` -Usalo quando un canale può rispondere allo stato configurato da env o da altri piccoli -input non-runtime. Se il controllo richiede la risoluzione completa della configurazione o il reale -runtime del canale, mantieni quella logica nell'hook `config.hasConfiguredState` del Plugin. +Usalo quando un canale può determinare lo stato configurato da env o altri input minimi +non runtime. Se il controllo richiede la risoluzione completa della configurazione o il vero +runtime del canale, mantieni invece quella logica nell'hook `config.hasConfiguredState` +del plugin. -## Precedenza della discovery (ID Plugin duplicati) +## Precedenza di rilevamento (ID plugin duplicati) -OpenClaw rileva i Plugin da diverse root (inclusi, installazione globale, workspace, percorsi espliciti selezionati dalla configurazione). Se due discovery condividono lo stesso `id`, viene mantenuto solo il manifest con **precedenza più alta**; i duplicati con precedenza inferiore vengono scartati invece di essere caricati accanto. +OpenClaw rileva i plugin da diverse radici (bundle, installazione globale, workspace, percorsi espliciti selezionati dalla configurazione). Se due rilevamenti condividono lo stesso `id`, viene mantenuto solo il manifest con la **precedenza più alta**; i duplicati con precedenza inferiore vengono scartati invece di essere caricati accanto ad esso. Precedenza, dalla più alta alla più bassa: 1. **Selezionato dalla configurazione** — un percorso fissato esplicitamente in `plugins.entries.` -2. **Incluso** — Plugin distribuiti con OpenClaw -3. **Installazione globale** — Plugin installati nella root globale dei Plugin OpenClaw -4. **Workspace** — Plugin rilevati relativamente al workspace corrente +2. **Bundle** — plugin distribuiti con OpenClaw +3. **Installazione globale** — plugin installati nella radice globale dei plugin OpenClaw +4. **Workspace** — plugin rilevati relativamente al workspace corrente Implicazioni: -- Una copia forkata o obsoleta di un Plugin incluso presente nel workspace non sovrascriverà la build inclusa. -- Per sovrascrivere davvero un Plugin incluso con uno locale, fissalo tramite `plugins.entries.` in modo che vinca per precedenza invece di affidarti alla discovery del workspace. -- Gli scarti dei duplicati vengono registrati nei log così Doctor e la diagnostica di avvio possono puntare alla copia scartata. +- Una copia forkata o obsoleta di un plugin bundle presente nel workspace non oscurerà la build bundle. +- Per sovrascrivere davvero un plugin bundle con uno locale, fissalo tramite `plugins.entries.` in modo che vinca per precedenza invece di affidarti al rilevamento del workspace. +- Gli scarti dei duplicati vengono registrati nei log in modo che Doctor e la diagnostica di avvio possano indicare la copia scartata. -## Requisiti JSON Schema +## Requisiti dello schema JSON -- **Ogni Plugin deve distribuire un JSON Schema**, anche se non accetta alcuna configurazione. -- Uno schema vuoto è accettabile (ad esempio, `{ "type": "object", "additionalProperties": false }`). -- Gli schemi vengono validati in fase di lettura/scrittura della configurazione, non a runtime. +- **Ogni plugin deve distribuire uno schema JSON**, anche se non accetta configurazione. +- È accettabile uno schema vuoto (per esempio, `{ "type": "object", "additionalProperties": false }`). +- Gli schemi vengono validati al momento della lettura/scrittura della configurazione, non a runtime. -## Comportamento della validazione +## Comportamento di validazione -- Le chiavi `channels.*` sconosciute sono **errori**, a meno che l'ID canale non sia dichiarato da - un manifest di Plugin. +- Le chiavi `channels.*` sconosciute sono **errori**, a meno che l'ID del canale non sia dichiarato da + un manifest del plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` - devono riferirsi a ID Plugin **rilevabili**. Gli ID sconosciuti sono **errori**. -- Se un Plugin è installato ma ha un manifest o uno schema mancante o non valido, - la validazione fallisce e Doctor segnala l'errore del Plugin. -- Se esiste configurazione del Plugin ma il Plugin è **disabilitato**, la configurazione viene mantenuta e - viene mostrato un **warning** in Doctor + nei log. + devono fare riferimento a ID plugin **rilevabili**. Gli ID sconosciuti sono **errori**. +- Se un plugin è installato ma ha un manifest o uno schema mancante o non valido, + la validazione fallisce e Doctor segnala l'errore del plugin. +- Se la configurazione del plugin esiste ma il plugin è **disabilitato**, la configurazione viene mantenuta e + viene mostrato un **avviso** in Doctor + nei log. -Vedi [Configuration reference](/it/gateway/configuration) per lo schema completo `plugins.*`. +Vedi [Riferimento della configurazione](/it/gateway/configuration) per lo schema completo di `plugins.*`. ## Note -- Il manifest è **obbligatorio per i Plugin OpenClaw nativi**, inclusi i caricamenti dal filesystem locale. -- Il runtime carica comunque separatamente il modulo del Plugin; il manifest serve solo per - discovery + validazione. +- Il manifest è **obbligatorio per i plugin OpenClaw nativi**, inclusi i caricamenti locali dal filesystem. +- Il runtime continua comunque a caricare separatamente il modulo del plugin; il manifest serve solo per + rilevamento + validazione. - I manifest nativi vengono analizzati con JSON5, quindi commenti, virgole finali e - chiavi senza virgolette sono accettati finché il valore finale resta comunque un oggetto. + chiavi non tra virgolette sono accettati purché il valore finale resti comunque un oggetto. - Solo i campi del manifest documentati vengono letti dal loader del manifest. Evita di aggiungere - qui chiavi personalizzate di primo livello. -- `providerAuthEnvVars` è il percorso di metadati economico per probe di autenticazione, validazione - di env-marker e superfici simili di autenticazione provider che non dovrebbero avviare il runtime del Plugin + qui chiavi di primo livello personalizzate. +- `providerAuthEnvVars` è il percorso di metadati economico per sonde auth, validazione + dei marker env e superfici simili di auth del provider che non dovrebbero avviare il runtime del plugin solo per ispezionare i nomi env. -- `providerAuthAliases` consente alle varianti di provider di riutilizzare le variabili d'ambiente - di autenticazione di un altro provider, i profili di autenticazione, l'autenticazione basata su configurazione e la scelta di onboarding della chiave API - senza codificare rigidamente questa relazione nel core. -- `providerEndpoints` consente ai Plugin provider di possedere semplici metadati di matching - host/baseUrl dell'endpoint. Usalo solo per classi di endpoint che il core supporta già; - il Plugin resta comunque proprietario del comportamento runtime. -- `syntheticAuthRefs` è il percorso di metadati economico per hook di autenticazione sintetica - posseduti dal provider che devono essere visibili alla cold model discovery prima che esista il registro runtime. Elenca solo i riferimenti il cui provider runtime o backend CLI effettivamente - implementa `resolveSyntheticAuth`. -- `nonSecretAuthMarkers` è il percorso di metadati economico per valori placeholder - di chiave API posseduti dai plugin inclusi, come marcatori di credenziali locali, OAuth o ambient. - Il core li tratta come non-secret per la visualizzazione dell'autenticazione e gli audit dei secret senza +- `providerAuthAliases` consente alle varianti di provider di riutilizzare le variabili d'ambiente auth + di un altro provider, i profili auth, l'auth basata sulla configurazione e la scelta di onboarding + della chiave API senza codificare rigidamente quella relazione nel core. +- `providerEndpoints` consente ai plugin provider di possedere semplici metadati di corrispondenza + host/baseUrl degli endpoint. Usalo solo per classi di endpoint già supportate dal core; + il plugin continua a possedere il comportamento runtime. +- `syntheticAuthRefs` è il percorso di metadati economico per hook di auth sintetica + posseduti dal provider che devono essere visibili al rilevamento a freddo dei modelli prima che esista il registro + runtime. Elenca solo riferimenti il cui provider runtime o backend CLI implementa realmente + `resolveSyntheticAuth`. +- `nonSecretAuthMarkers` è il percorso di metadati economico per chiavi API segnaposto + possedute da plugin bundle, come marker di credenziali locali, OAuth o ambient. + Il core le tratta come non segreti per la visualizzazione auth e gli audit dei segreti senza codificare rigidamente il provider proprietario. -- `channelEnvVars` è il percorso di metadati economico per fallback env della shell, prompt di setup - e superfici simili del canale che non dovrebbero avviare il runtime del Plugin +- `channelEnvVars` è il percorso di metadati economico per fallback shell-env, prompt di setup + e superfici di canale simili che non dovrebbero avviare il runtime del plugin solo per ispezionare i nomi env. I nomi env sono metadati, non attivazione di per sé: stato, audit, validazione della consegna Cron e altre superfici in sola lettura - continuano ad applicare la policy di fiducia del Plugin e di attivazione effettiva prima di - trattare una variabile d'ambiente come canale configurato. -- `providerAuthChoices` è il percorso di metadati economico per picker della scelta di autenticazione, - risoluzione `--auth-choice`, mappatura del provider preferito e semplice registrazione - dei flag CLI di onboarding prima che il runtime del provider venga caricato. Per i metadati della procedura guidata runtime - che richiedono codice provider, vedi - [Provider runtime hooks](/it/plugins/architecture#provider-runtime-hooks). -- I tipi esclusivi di Plugin vengono selezionati tramite `plugins.slots.*`. + applicano comunque il criterio di fiducia del plugin e di attivazione effettiva prima di + trattare una variabile env come un canale configurato. +- `providerAuthChoices` è il percorso di metadati economico per selettori di scelte auth, + risoluzione di `--auth-choice`, mappatura del provider preferito e semplice registrazione + dei flag CLI di onboarding prima che il runtime del provider venga caricato. Per i metadati del wizard runtime + che richiedono codice del provider, vedi + [Hook runtime del provider](/it/plugins/architecture#provider-runtime-hooks). +- I tipi esclusivi di plugin vengono selezionati tramite `plugins.slots.*`. - `kind: "memory"` viene selezionato da `plugins.slots.memory`. - `kind: "context-engine"` viene selezionato da `plugins.slots.contextEngine` (predefinito: `legacy` integrato). - `channels`, `providers`, `cliBackends` e `skills` possono essere omessi quando un - Plugin non ne ha bisogno. -- Se il tuo Plugin dipende da moduli nativi, documenta i passaggi di build e ogni - requisito di allowlist del package manager (ad esempio, pnpm `allow-build-scripts` + plugin non ne ha bisogno. +- Se il tuo plugin dipende da moduli nativi, documenta i passaggi di build e qualsiasi + requisito di allowlist del gestore di pacchetti (per esempio, pnpm `allow-build-scripts` - `pnpm rebuild `). ## Correlati -- [Building Plugins](/it/plugins/building-plugins) — primi passi con i Plugin -- [Plugin Architecture](/it/plugins/architecture) — architettura interna -- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento dell'SDK del Plugin +- [Creazione di Plugin](/it/plugins/building-plugins) — guida introduttiva ai plugin +- [Architettura dei Plugin](/it/plugins/architecture) — architettura interna +- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento del Plugin SDK diff --git a/docs/it/plugins/sdk-agent-harness.md b/docs/it/plugins/sdk-agent-harness.md index bb771ad6a..92af0ebf8 100644 --- a/docs/it/plugins/sdk-agent-harness.md +++ b/docs/it/plugins/sdk-agent-harness.md @@ -1,51 +1,58 @@ --- read_when: - - Stai modificando il runtime dell'agente incorporato o il registro dell'harness - - Stai registrando un harness dell'agente da un plugin incluso o attendibile + - Stai modificando il runtime dell’agente embedded o il registro harness + - Stai registrando un harness dell’agente da un plugin incluso o attendibile - Devi capire come il plugin Codex si relaziona ai provider di modelli sidebarTitle: Agent Harness -summary: Superficie SDK sperimentale per i plugin che sostituiscono l'esecutore dell'agente incorporato di basso livello -title: Plugin Harness dell'agente +summary: Superficie SDK sperimentale per i plugin che sostituiscono l’esecutore agente embedded di basso livello +title: Plugin Harness dell’agente x-i18n: - generated_at: "2026-04-12T00:19:02Z" + generated_at: "2026-04-22T08:20:16Z" model: gpt-5.4 provider: openai - source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365 + source_hash: 728fef59ae3cce29a3348842820f1f71a2eac98ae6b276179bce6c85d16613df source_path: plugins/sdk-agent-harness.md workflow: 15 --- -# Plugin Harness dell'agente +# Plugin Harness dell’agente -Un **agent harness** è l'esecutore di basso livello per un turno preparato di un agente OpenClaw. Non è un provider di modelli, non è un canale e non è un registro di strumenti. +Un **agent harness** è l’esecutore di basso livello per un singolo turno agente +OpenClaw preparato. Non è un provider di modelli, non è un canale e non è un registro di strumenti. -Usa questa superficie solo per plugin nativi inclusi o attendibili. Il contratto è ancora sperimentale perché i tipi dei parametri rispecchiano intenzionalmente l'attuale runner incorporato. +Usa questa superficie solo per plugin nativi inclusi o attendibili. Il contratto è +ancora sperimentale perché i tipi dei parametri rispecchiano intenzionalmente l’attuale +runner embedded. ## Quando usare un harness -Registra un agent harness quando una famiglia di modelli ha un proprio runtime di sessione nativo e il normale trasporto provider di OpenClaw è l'astrazione sbagliata. +Registra un agent harness quando una famiglia di modelli ha il proprio runtime +di sessione nativo e il normale trasporto provider di OpenClaw è l’astrazione sbagliata. Esempi: -- un server nativo per agenti di coding che gestisce thread e compattazione -- una CLI o un demone locale che deve trasmettere eventi nativi di piano/ragionamento/strumenti -- un runtime di modelli che ha bisogno di un proprio ID di ripresa oltre alla trascrizione di sessione OpenClaw +- un server di agenti di coding nativo che gestisce thread e Compaction +- una CLI o un demone locale che deve trasmettere in streaming eventi nativi di piano/ragionamento/strumenti +- un runtime di modello che richiede il proprio id di ripresa oltre alla + trascrizione di sessione di OpenClaw -**Non** registrare un harness solo per aggiungere una nuova API LLM. Per normali API di modelli HTTP o WebSocket, crea un [plugin provider](/it/plugins/sdk-provider-plugins). +**Non** registrare un harness solo per aggiungere una nuova API LLM. Per normali API di modelli HTTP o +WebSocket, crea un [plugin provider](/it/plugins/sdk-provider-plugins). -## Cosa rimane di competenza del core +## Cosa continua a gestire il core Prima che venga selezionato un harness, OpenClaw ha già risolto: - provider e modello - stato di autenticazione del runtime -- livello di reasoning e budget di contesto -- la trascrizione OpenClaw / il file di sessione +- livello di ragionamento e budget di contesto +- il file di trascrizione/sessione di OpenClaw - workspace, sandbox e policy degli strumenti - callback di risposta del canale e callback di streaming -- fallback del modello e policy di cambio del modello live +- fallback del modello e policy di cambio modello live -Questa separazione è intenzionale. Un harness esegue un tentativo preparato; non sceglie i provider, non sostituisce la consegna del canale e non cambia silenziosamente modello. +Questa separazione è intenzionale. Un harness esegue un tentativo preparato; non sceglie +provider, non sostituisce la consegna del canale e non cambia modello in modo silenzioso. ## Registrare un harness @@ -83,53 +90,86 @@ export default definePluginEntry({ }); ``` -## Criterio di selezione +## Policy di selezione OpenClaw sceglie un harness dopo la risoluzione di provider/modello: -1. `OPENCLAW_AGENT_RUNTIME=` forza un harness registrato con quell'id. -2. `OPENCLAW_AGENT_RUNTIME=pi` forza l'harness PI integrato. -3. `OPENCLAW_AGENT_RUNTIME=auto` chiede agli harness registrati se supportano il provider/modello risolto. -4. Se nessun harness registrato corrisponde, OpenClaw usa PI a meno che il fallback a PI non sia disabilitato. +1. `OPENCLAW_AGENT_RUNTIME=` forza un harness registrato con quell’id. +2. `OPENCLAW_AGENT_RUNTIME=pi` forza l’harness PI integrato. +3. `OPENCLAW_AGENT_RUNTIME=auto` chiede agli harness registrati se supportano la + coppia provider/modello risolta. +4. Se nessun harness registrato corrisponde, OpenClaw usa PI a meno che il fallback PI non sia + disabilitato. -Gli errori forzati dell'harness del plugin emergono come errori di esecuzione. In modalità `auto`, OpenClaw può ricadere su PI quando l'harness del plugin selezionato fallisce prima che un turno produca effetti collaterali. Imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` o `embeddedHarness.fallback: "none"` per rendere invece quel fallback un errore irreversibile. +Gli errori degli harness plugin emergono come errori di esecuzione. In modalità `auto`, il fallback PI viene +usato solo quando nessun harness plugin registrato supporta la +coppia provider/modello risolta. Una volta che un harness plugin ha preso in carico un’esecuzione, OpenClaw non +riesegue quello stesso turno tramite PI perché ciò può cambiare la semantica di autenticazione/runtime +o duplicare gli effetti collaterali. -Il plugin Codex incluso registra `codex` come ID del proprio harness. Il core lo tratta come un normale ID di harness del plugin; gli alias specifici di Codex appartengono al plugin o alla configurazione dell'operatore, non al selettore di runtime condiviso. +Il plugin Codex incluso registra `codex` come id del proprio harness. Il core tratta questo valore +come un normale id di harness plugin; gli alias specifici di Codex appartengono al plugin +o alla configurazione dell’operatore, non al selettore di runtime condiviso. -## Associazione provider più harness +## Abbinamento provider più harness -La maggior parte degli harness dovrebbe anche registrare un provider. Il provider rende visibili al resto di OpenClaw i riferimenti ai modelli, lo stato di autenticazione, i metadati del modello e la selezione `/model`. L'harness poi rivendica quel provider in `supports(...)`. +La maggior parte degli harness dovrebbe registrare anche un provider. Il provider rende riferimenti di modello, +stato di autenticazione, metadati del modello e selezione `/model` visibili al resto di +OpenClaw. L’harness poi prende in carico quel provider in `supports(...)`. Il plugin Codex incluso segue questo schema: - id provider: `codex` -- riferimenti ai modelli per l'utente: `codex/gpt-5.4`, `codex/gpt-5.2` o un altro modello restituito dal server app Codex +- riferimenti di modello utente: `codex/gpt-5.4`, `codex/gpt-5.2` o un altro modello restituito + dal server app Codex - id harness: `codex` -- autenticazione: disponibilità sintetica del provider, perché l'harness Codex gestisce il login/sessione Codex nativo -- richiesta al server app: OpenClaw invia l'ID del modello senza prefissi a Codex e lascia che l'harness comunichi con il protocollo nativo del server app +- autenticazione: disponibilità sintetica del provider, perché l’harness Codex gestisce + il login/sessione Codex nativo +- richiesta app-server: OpenClaw invia a Codex l’id modello puro e lascia che l’harness parli con il protocollo app-server nativo -Il plugin Codex è aggiuntivo. I riferimenti semplici `openai/gpt-*` restano riferimenti del provider OpenAI e continuano a usare il normale percorso provider di OpenClaw. Seleziona `codex/gpt-*` quando vuoi autenticazione gestita da Codex, rilevamento dei modelli Codex, thread nativi ed esecuzione del server app Codex. `/model` può passare tra i modelli Codex restituiti dal server app Codex senza richiedere credenziali del provider OpenAI. +Il plugin Codex è additivo. I riferimenti semplici `openai/gpt-*` restano riferimenti del provider OpenAI +e continuano a usare il normale percorso provider di OpenClaw. Seleziona `codex/gpt-*` +quando vuoi autenticazione gestita da Codex, rilevamento dei modelli Codex, thread nativi e +esecuzione tramite app-server Codex. `/model` può passare tra i modelli Codex restituiti +dal server app Codex senza richiedere credenziali del provider OpenAI. -Per la configurazione dell'operatore, esempi di prefissi di modello e configurazioni solo Codex, vedi [Codex Harness](/it/plugins/codex-harness). +Per la configurazione dell’operatore, esempi di prefissi di modello e configurazioni solo Codex, vedi +[Codex Harness](/it/plugins/codex-harness). -OpenClaw richiede Codex app-server `0.118.0` o successivo. Il plugin Codex controlla l'handshake di inizializzazione dell'app-server e blocca i server più vecchi o senza versione, così OpenClaw viene eseguito solo sulla superficie di protocollo con cui è stato testato. +OpenClaw richiede Codex app-server `0.118.0` o successivo. Il plugin Codex controlla +l’handshake di inizializzazione dell’app-server e blocca server più vecchi o senza versione, così +OpenClaw viene eseguito solo sulla superficie di protocollo su cui è stato testato. ### Modalità harness Codex nativa -L'harness `codex` incluso è la modalità Codex nativa per i turni degli agenti OpenClaw incorporati. Abilita prima il plugin `codex` incluso e includi `codex` in `plugins.allow` se la tua configurazione usa una allowlist restrittiva. È diverso da `openai-codex/*`: +L’harness `codex` incluso è la modalità Codex nativa per i turni agente embedded di +OpenClaw. Abilita prima il plugin `codex` incluso e includi `codex` in +`plugins.allow` se la tua configurazione usa una allowlist restrittiva. È diverso +da `openai-codex/*`: - `openai-codex/*` usa OAuth ChatGPT/Codex tramite il normale percorso provider di OpenClaw. -- `codex/*` usa il provider Codex incluso e instrada il turno tramite il server app Codex. +- `codex/*` usa il provider Codex incluso e instrada il turno tramite Codex + app-server. -Quando questa modalità è in esecuzione, Codex gestisce l'ID del thread nativo, il comportamento di ripresa, la compattazione e l'esecuzione dell'app-server. OpenClaw continua comunque a gestire il canale di chat, il mirror della trascrizione visibile, la policy degli strumenti, le approvazioni, la consegna dei contenuti multimediali e la selezione della sessione. Usa `embeddedHarness.runtime: "codex"` con `embeddedHarness.fallback: "none"` quando devi dimostrare che viene usato il percorso del server app Codex e che il fallback a PI non sta nascondendo un harness nativo non funzionante. +Quando questa modalità è in esecuzione, Codex gestisce l’id thread nativo, il comportamento di ripresa, +Compaction e l’esecuzione dell’app-server. OpenClaw continua comunque a gestire il canale di chat, +il mirror della trascrizione visibile, la policy degli strumenti, le approvazioni, la consegna dei media e la +selezione della sessione. Usa `embeddedHarness.runtime: "codex"` con +`embeddedHarness.fallback: "none"` quando devi dimostrare che solo il percorso Codex +app-server può prendere in carico l’esecuzione. Questa configurazione è solo una protezione di selezione: +gli errori dell’app-server Codex falliscono già direttamente invece di ritentare tramite PI. -## Disabilitare il fallback a PI +## Disabilitare il fallback PI -Per impostazione predefinita, OpenClaw esegue gli agenti incorporati con `agents.defaults.embeddedHarness` impostato su `{ runtime: "auto", fallback: "pi" }`. In modalità `auto`, gli harness dei plugin registrati possono rivendicare una coppia provider/modello. Se nessuno corrisponde, oppure se un harness del plugin selezionato automaticamente fallisce prima di produrre output, OpenClaw ricade su PI. +Per impostazione predefinita, OpenClaw esegue gli agenti embedded con `agents.defaults.embeddedHarness` +impostato su `{ runtime: "auto", fallback: "pi" }`. In modalità `auto`, gli harness plugin registrati +possono prendere in carico una coppia provider/modello. Se nessuno corrisponde, OpenClaw torna a PI. -Imposta `fallback: "none"` quando devi dimostrare che un harness del plugin è l'unico runtime realmente utilizzato. Questo disabilita il fallback automatico a PI; non blocca un `runtime: "pi"` esplicito o `OPENCLAW_AGENT_RUNTIME=pi`. +Imposta `fallback: "none"` quando vuoi che la mancata selezione di un harness plugin provochi un errore +invece di usare PI. Gli errori degli harness plugin selezionati falliscono già in modo definitivo. Questo +non blocca un esplicito `runtime: "pi"` o `OPENCLAW_AGENT_RUNTIME=pi`. -Per esecuzioni incorporate solo Codex: +Per esecuzioni embedded solo Codex: ```json { @@ -145,7 +185,9 @@ Per esecuzioni incorporate solo Codex: } ``` -Se vuoi che qualunque harness del plugin registrato possa rivendicare i modelli corrispondenti ma non vuoi mai che OpenClaw ricada silenziosamente su PI, mantieni `runtime: "auto"` e disabilita il fallback: +Se vuoi che qualsiasi harness plugin registrato prenda in carico i modelli corrispondenti ma non +vuoi mai che OpenClaw ricada silenziosamente su PI, mantieni `runtime: "auto"` e disabilita +il fallback: ```json { @@ -160,7 +202,7 @@ Se vuoi che qualunque harness del plugin registrato possa rivendicare i modelli } ``` -Le override per agente usano la stessa struttura: +Le sovrascritture per agente usano la stessa struttura: ```json { @@ -185,7 +227,9 @@ Le override per agente usano la stessa struttura: } ``` -`OPENCLAW_AGENT_RUNTIME` continua a sovrascrivere il runtime configurato. Usa `OPENCLAW_AGENT_HARNESS_FALLBACK=none` per disabilitare il fallback a PI dall'ambiente. +`OPENCLAW_AGENT_RUNTIME` continua a sovrascrivere il runtime configurato. Usa +`OPENCLAW_AGENT_HARNESS_FALLBACK=none` per disabilitare il fallback PI tramite +l’ambiente. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -193,39 +237,53 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Con il fallback disabilitato, una sessione fallisce subito quando l'harness richiesto non è registrato, non supporta il provider/modello risolto o fallisce prima di produrre effetti collaterali del turno. Questo è intenzionale per i deployment solo Codex e per i test live che devono dimostrare che il percorso del server app Codex è effettivamente in uso. +Con il fallback disabilitato, una sessione fallisce in anticipo quando l’harness richiesto non è +registrato, non supporta la coppia provider/modello risolta o fallisce prima di +produrre effetti collaterali del turno. Questo è intenzionale per deployment solo Codex e +per test live che devono dimostrare che il percorso Codex app-server è effettivamente in uso. -Questa impostazione controlla solo l'harness dell'agente incorporato. Non disabilita l'instradamento specifico del provider per immagini, video, musica, TTS, PDF o altri modelli. +Questa impostazione controlla solo l’harness dell’agente embedded. Non disabilita +il routing specifico del provider per immagini, video, musica, TTS, PDF o altri modelli. ## Sessioni native e mirror della trascrizione -Un harness può mantenere un ID di sessione nativo, un ID di thread o un token di ripresa lato demone. Mantieni tale associazione esplicitamente legata alla sessione OpenClaw e continua a riflettere l'output visibile all'utente di assistente/strumenti nella trascrizione OpenClaw. +Un harness può mantenere un id di sessione nativo, un id thread o un token di ripresa lato demone. +Mantieni questa associazione esplicitamente collegata alla sessione OpenClaw e continua +a rispecchiare l’output di assistente/strumenti visibile all’utente nella trascrizione OpenClaw. -La trascrizione OpenClaw rimane il livello di compatibilità per: +La trascrizione OpenClaw resta il livello di compatibilità per: - cronologia della sessione visibile nel canale - ricerca e indicizzazione della trascrizione -- ritorno all'harness PI integrato in un turno successivo +- ritorno all’harness PI integrato in un turno successivo - comportamento generico di `/new`, `/reset` ed eliminazione della sessione -Se il tuo harness memorizza un'associazione sidecar, implementa `reset(...)` così OpenClaw può cancellarla quando la sessione OpenClaw proprietaria viene reimpostata. +Se il tuo harness memorizza un’associazione sidecar, implementa `reset(...)` affinché OpenClaw possa +cancellarla quando la sessione OpenClaw proprietaria viene reimpostata. -## Risultati di strumenti e contenuti multimediali +## Risultati di strumenti e media -Il core costruisce l'elenco degli strumenti OpenClaw e lo passa nel tentativo preparato. Quando un harness esegue una chiamata a strumento dinamica, restituisci il risultato dello strumento tramite la forma del risultato dell'harness invece di inviare tu stesso i contenuti multimediali al canale. +Il core costruisce l’elenco strumenti di OpenClaw e lo passa al tentativo preparato. +Quando un harness esegue una chiamata a strumento dinamica, restituisci il risultato dello strumento tramite +la forma del risultato dell’harness invece di inviare tu stesso i media del canale. -Questo mantiene output di testo, immagine, video, musica, TTS, approvazione e strumenti di messaggistica sullo stesso percorso di consegna delle esecuzioni supportate da PI. +Questo mantiene testo, immagine, video, musica, TTS, approvazione e output degli strumenti di messaggistica +sullo stesso percorso di consegna delle esecuzioni supportate da PI. ## Limitazioni attuali -- Il percorso di import pubblico è generico, ma alcuni alias di tipo attempt/result riportano ancora nomi `Pi` per compatibilità. -- L'installazione di harness di terze parti è sperimentale. Preferisci i plugin provider finché non ti serve un runtime di sessione nativo. -- Il cambio di harness è supportato tra i turni. Non cambiare harness nel mezzo di un turno dopo che sono iniziati strumenti nativi, approvazioni, testo dell'assistente o invii di messaggi. +- Il percorso di import pubblico è generico, ma alcuni alias di tipi tentativo/risultato + portano ancora nomi `Pi` per compatibilità. +- L’installazione di harness di terze parti è sperimentale. Preferisci i plugin provider + finché non ti serve un runtime di sessione nativo. +- Il cambio di harness è supportato tra i turni. Non cambiare harness nel + mezzo di un turno dopo che strumenti nativi, approvazioni, testo dell’assistente o invii di messaggi + sono già iniziati. ## Correlati -- [Panoramica SDK](/it/plugins/sdk-overview) +- [Panoramica dell’SDK](/it/plugins/sdk-overview) - [Helper di runtime](/it/plugins/sdk-runtime) -- [Plugin provider](/it/plugins/sdk-provider-plugins) +- [Plugin Provider](/it/plugins/sdk-provider-plugins) - [Codex Harness](/it/plugins/codex-harness) - [Provider di modelli](/it/concepts/model-providers) diff --git a/docs/it/plugins/sdk-channel-plugins.md b/docs/it/plugins/sdk-channel-plugins.md index ac07966c2..157f1fa33 100644 --- a/docs/it/plugins/sdk-channel-plugins.md +++ b/docs/it/plugins/sdk-channel-plugins.md @@ -1,109 +1,120 @@ --- read_when: - - Stai creando un nuovo Plugin di canale di messaggistica + - Stai creando un nuovo plugin di canale di messaggistica - Vuoi collegare OpenClaw a una piattaforma di messaggistica - - Hai bisogno di comprendere la superficie dell'adapter ChannelPlugin + - Devi capire la superficie dell'adattatore ChannelPlugin sidebarTitle: Channel Plugins -summary: Guida passo passo per creare un Plugin di canale di messaggistica per OpenClaw +summary: Guida passo passo per creare un plugin di canale di messaggistica per OpenClaw title: Creazione di Plugin di canale x-i18n: - generated_at: "2026-04-22T04:24:44Z" + generated_at: "2026-04-22T08:20:36Z" model: gpt-5.4 provider: openai - source_hash: f08bf785cd2e16ed6ce0317f4fd55c9eccecf7476d84148ad47e7be516dd71fb + source_hash: e67d8c4be8cc4a312e5480545497b139c27bed828304de251e6258a3630dd9b5 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # Creazione di Plugin di canale -Questa guida illustra come creare un Plugin di canale che colleghi OpenClaw a una -piattaforma di messaggistica. Alla fine avrai un canale funzionante con sicurezza DM, -pairing, threading delle risposte e messaggistica in uscita. +Questa guida illustra come creare un plugin di canale che collega OpenClaw a una +piattaforma di messaggistica. Alla fine avrai un canale funzionante con sicurezza +DM, pairing, threading delle risposte e messaggistica in uscita. - Se non hai mai creato prima alcun Plugin OpenClaw, leggi prima - [Per iniziare](/it/plugins/building-plugins) per la struttura di base del - pacchetto e la configurazione del manifest. + Se non hai mai creato prima alcun plugin OpenClaw, leggi prima + [Getting Started](/it/plugins/building-plugins) per la struttura di base del + pacchetto e l'impostazione del manifest. -## Come funzionano i Plugin di canale +## Come funzionano i plugin di canale -I Plugin di canale non hanno bisogno di propri strumenti send/edit/react. OpenClaw mantiene un unico -strumento `message` condiviso nel core. Il tuo Plugin possiede: +I plugin di canale non hanno bisogno di strumenti propri per inviare/modificare/reagire. OpenClaw mantiene in core un unico strumento `message` condiviso. Il tuo plugin gestisce: -- **Configurazione** — risoluzione dell'account e procedura guidata di configurazione -- **Sicurezza** — criterio DM e allowlist +- **Config** — risoluzione dell'account e procedura guidata di configurazione +- **Security** — criteri DM e allowlist - **Pairing** — flusso di approvazione DM -- **Grammatica della sessione** — come gli ID di conversazione specifici del provider vengono mappati a chat base, ID thread e fallback parent -- **In uscita** — invio di testo, contenuti multimediali e sondaggi alla piattaforma -- **Threading** — come vengono strutturate le risposte in thread +- **Session grammar** — come gli id di conversazione specifici del provider vengono mappati alle chat di base, agli id thread e ai fallback padre +- **Outbound** — invio di testo, media e sondaggi alla piattaforma +- **Threading** — come vengono organizzate le risposte in thread +- **Heartbeat typing** — segnali opzionali di digitazione/occupato per i target di consegna heartbeat -Il core possiede lo strumento di messaggio condiviso, il wiring dei prompt, la forma esterna della chiave di sessione, -la gestione generica `:thread:` e il dispatch. +Il core gestisce lo strumento message condiviso, il wiring del prompt, la forma +esterna della chiave di sessione, la gestione generica `:thread:` e il dispatch. -Se il tuo canale aggiunge parametri allo strumento di messaggio che trasportano sorgenti multimediali, esponi questi +Se il tuo canale supporta indicatori di digitazione al di fuori delle risposte in ingresso, esponi +`heartbeat.sendTyping(...)` nel plugin di canale. Il core lo richiama con il +target di consegna heartbeat risolto prima che inizi l'esecuzione del modello heartbeat e +usa il ciclo di vita condiviso di keepalive/cleanup della digitazione. Aggiungi `heartbeat.clearTyping(...)` +quando la piattaforma richiede un segnale esplicito di arresto. + +Se il tuo canale aggiunge parametri dello strumento message che trasportano sorgenti multimediali, esponi quei nomi di parametro tramite `describeMessageTool(...).mediaSourceParams`. Il core usa -questo elenco esplicito per la normalizzazione dei percorsi sandbox e la policy di accesso ai contenuti multimediali in uscita, -così i Plugin non hanno bisogno di casi speciali nel core condiviso per parametri specifici del provider come -avatar, allegato o immagine di copertina. +questo elenco esplicito per la normalizzazione dei percorsi sandbox e per i criteri di accesso ai media in uscita, +così i plugin non hanno bisogno di casi speciali nel core condiviso per parametri specifici del provider +come avatar, allegati o immagini di copertina. Preferisci restituire una mappa indicizzata per azione come -`{ "set-profile": ["avatarUrl", "avatarPath"] }` così azioni non correlate non -ereditano gli argomenti multimediali di un'altra azione. Un array piatto continua a funzionare per -parametri che sono intenzionalmente condivisi tra tutte le azioni esposte. +`{ "set-profile": ["avatarUrl", "avatarPath"] }` in modo che azioni non correlate non +ereditino gli argomenti media di un'altra azione. Un array piatto continua a funzionare per parametri +che sono intenzionalmente condivisi tra tutte le azioni esposte. -Se la tua piattaforma memorizza scope extra all'interno degli ID di conversazione, mantieni quel parsing -nel Plugin con `messaging.resolveSessionConversation(...)`. Questo è l'hook canonico -per mappare `rawId` all'ID di conversazione base, all'ID thread facoltativo, +Se la tua piattaforma memorizza ambito aggiuntivo negli id di conversazione, mantieni quel parsing +nel plugin con `messaging.resolveSessionConversation(...)`. Questo è l'hook canonico +per mappare `rawId` all'id di conversazione di base, all'eventuale id thread, a `baseConversationId` esplicito e a qualsiasi `parentConversationCandidates`. Quando restituisci `parentConversationCandidates`, mantienili ordinati dal -parent più ristretto alla conversazione più ampia/base. +padre più specifico a quello più ampio/conversazione di base. -I Plugin inclusi che hanno bisogno dello stesso parsing prima che il registro dei canali si avvii -possono anche esporre un file `session-key-api.ts` di livello superiore con un export -`resolveSessionConversation(...)` corrispondente. Il core usa questa superficie sicura per il bootstrap -solo quando il registro runtime del Plugin non è ancora disponibile. +I plugin bundled che hanno bisogno dello stesso parsing prima che il registro dei canali venga avviato +possono anche esporre un file `session-key-api.ts` di primo livello con una +esportazione `resolveSessionConversation(...)` corrispondente. Il core usa questa superficie +sicura per il bootstrap solo quando il registro runtime dei plugin non è ancora disponibile. -`messaging.resolveParentConversationCandidates(...)` resta disponibile come fallback legacy di compatibilità quando un Plugin ha bisogno solo di fallback parent sopra l'ID generico/raw. Se esistono entrambi gli hook, il core usa prima `resolveSessionConversation(...).parentConversationCandidates` e ricorre a `resolveParentConversationCandidates(...)` solo quando l'hook canonico li omette. +`messaging.resolveParentConversationCandidates(...)` rimane disponibile come +fallback di compatibilità legacy quando un plugin ha bisogno solo di fallback padre +in aggiunta all'id generico/raw. Se entrambi gli hook esistono, il core usa prima +`resolveSessionConversation(...).parentConversationCandidates` e ricorre a +`resolveParentConversationCandidates(...)` solo quando l'hook canonico +li omette. -## Approvazioni e funzionalità del canale +## Approvazioni e capacità del canale -La maggior parte dei Plugin di canale non ha bisogno di codice specifico per le approvazioni. +La maggior parte dei plugin di canale non ha bisogno di codice specifico per le approvazioni. -- Il core possiede `/approve` nella stessa chat, i payload condivisi dei pulsanti di approvazione e la consegna generica di fallback. -- Preferisci un unico oggetto `approvalCapability` sul Plugin di canale quando il canale ha bisogno di comportamento specifico per le approvazioni. -- `ChannelPlugin.approvals` è stato rimosso. Inserisci i fatti di consegna/rendering/autenticazione delle approvazioni su `approvalCapability`. -- `plugin.auth` è solo per login/logout; il core non legge più hook di autenticazione delle approvazioni da quell'oggetto. -- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` sono la seam canonica per l'autenticazione delle approvazioni. -- Usa `approvalCapability.getActionAvailabilityState` per la disponibilità dell'autenticazione delle approvazioni nella stessa chat. -- Se il tuo canale espone approvazioni exec native, usa `approvalCapability.getExecInitiatingSurfaceState` per lo stato della superficie di avvio/client nativo quando differisce dall'autenticazione di approvazione nella stessa chat. Il core usa questo hook specifico per exec per distinguere `enabled` da `disabled`, decidere se il canale iniziale supporta approvazioni exec native e includere il canale nelle indicazioni di fallback del client nativo. `createApproverRestrictedNativeApprovalCapability(...)` compila questo punto per il caso comune. -- Usa `outbound.shouldSuppressLocalPayloadPrompt` oppure `outbound.beforeDeliverPayload` per comportamenti specifici del canale nel ciclo di vita del payload, come nascondere prompt locali di approvazione duplicati o inviare indicatori di digitazione prima della consegna. -- Usa `approvalCapability.delivery` solo per instradamento di approvazione nativa o soppressione del fallback. -- Usa `approvalCapability.nativeRuntime` per i fatti di approvazione nativa posseduti dal canale. Mantienilo lazy sugli entrypoint hot del canale con `createLazyChannelApprovalNativeRuntimeAdapter(...)`, che può importare il tuo modulo runtime su richiesta lasciando comunque al core l'assemblaggio del ciclo di vita delle approvazioni. +- Il core gestisce `/approve` nella stessa chat, i payload dei pulsanti di approvazione condivisi e la consegna di fallback generica. +- Preferisci un unico oggetto `approvalCapability` nel plugin di canale quando il canale necessita di comportamento specifico per le approvazioni. +- `ChannelPlugin.approvals` è rimosso. Inserisci i fatti di consegna/rendering/auth delle approvazioni in `approvalCapability`. +- `plugin.auth` è solo per login/logout; il core non legge più da quell'oggetto gli hook auth delle approvazioni. +- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` sono la seam canonica per l'auth delle approvazioni. +- Usa `approvalCapability.getActionAvailabilityState` per la disponibilità dell'auth di approvazione nella stessa chat. +- Se il tuo canale espone approvazioni exec native, usa `approvalCapability.getExecInitiatingSurfaceState` per lo stato della superficie iniziale/client nativo quando differisce dall'auth di approvazione nella stessa chat. Il core usa questo hook specifico per exec per distinguere `enabled` da `disabled`, decidere se il canale iniziale supporta approvazioni exec native e includere il canale nelle indicazioni di fallback del client nativo. `createApproverRestrictedNativeApprovalCapability(...)` lo compila per il caso comune. +- Usa `outbound.shouldSuppressLocalPayloadPrompt` o `outbound.beforeDeliverPayload` per comportamenti del ciclo di vita del payload specifici del canale, come nascondere prompt locali di approvazione duplicati o inviare indicatori di digitazione prima della consegna. +- Usa `approvalCapability.delivery` solo per il routing nativo delle approvazioni o la soppressione del fallback. +- Usa `approvalCapability.nativeRuntime` per i fatti di approvazione nativa gestiti dal canale. Mantienilo lazy negli entrypoint caldi del canale con `createLazyChannelApprovalNativeRuntimeAdapter(...)`, che può importare il tuo modulo runtime on demand pur permettendo al core di assemblare il ciclo di vita dell'approvazione. - Usa `approvalCapability.render` solo quando un canale ha davvero bisogno di payload di approvazione personalizzati invece del renderer condiviso. -- Usa `approvalCapability.describeExecApprovalSetup` quando il canale vuole che la risposta del percorso disabilitato spieghi esattamente quali manopole di configurazione servono per abilitare le approvazioni exec native. L'hook riceve `{ channel, channelLabel, accountId }`; i canali con account denominato dovrebbero renderizzare percorsi con scope per account come `channels..accounts..execApprovals.*` invece dei valori predefiniti di livello superiore. -- Se un canale può dedurre identità DM stabili simili a owner dalla configurazione esistente, usa `createResolvedApproverActionAuthAdapter` da `openclaw/plugin-sdk/approval-runtime` per limitare `/approve` nella stessa chat senza aggiungere logica specifica per le approvazioni nel core. -- Se un canale ha bisogno di consegna nativa delle approvazioni, mantieni il codice del canale concentrato sulla normalizzazione del target più i fatti di trasporto/presentazione. Usa `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` da `openclaw/plugin-sdk/approval-runtime`. Metti i fatti specifici del canale dietro `approvalCapability.nativeRuntime`, idealmente tramite `createChannelApprovalNativeRuntimeAdapter(...)` o `createLazyChannelApprovalNativeRuntimeAdapter(...)`, così il core può assemblare l'handler e possedere filtro delle richieste, instradamento, dedupe, scadenza, sottoscrizione Gateway e avvisi routed-elsewhere. `nativeRuntime` è suddiviso in alcune seam più piccole: +- Usa `approvalCapability.describeExecApprovalSetup` quando il canale vuole che la risposta del percorso disabilitato spieghi le esatte manopole di configurazione necessarie per abilitare le approvazioni exec native. L'hook riceve `{ channel, channelLabel, accountId }`; i canali con account nominati devono renderizzare percorsi con ambito account come `channels..accounts..execApprovals.*` invece dei default di primo livello. +- Se un canale può dedurre identità DM stabili simili a proprietari dalla configurazione esistente, usa `createResolvedApproverActionAuthAdapter` da `openclaw/plugin-sdk/approval-runtime` per limitare `/approve` nella stessa chat senza aggiungere logica core specifica per le approvazioni. +- Se un canale ha bisogno della consegna nativa delle approvazioni, mantieni il codice del canale focalizzato sulla normalizzazione del target più i fatti di trasporto/presentazione. Usa `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` da `openclaw/plugin-sdk/approval-runtime`. Inserisci i fatti specifici del canale dietro `approvalCapability.nativeRuntime`, idealmente tramite `createChannelApprovalNativeRuntimeAdapter(...)` o `createLazyChannelApprovalNativeRuntimeAdapter(...)`, così il core può assemblare l'handler e gestire filtro delle richieste, routing, deduplica, scadenza, sottoscrizione Gateway e avvisi di instradamento altrove. `nativeRuntime` è suddiviso in alcune seam più piccole: - `availability` — se l'account è configurato e se una richiesta deve essere gestita -- `presentation` — mappare il view model condiviso dell'approvazione in payload nativi pending/resolved/expired o azioni finali -- `transport` — preparare i target più inviare/aggiornare/eliminare messaggi di approvazione nativi -- `interactions` — hook facoltativi bind/unbind/clear-action per pulsanti o reazioni native -- `observe` — hook facoltativi per la diagnostica della consegna -- Se il canale ha bisogno di oggetti posseduti dal runtime come un client, token, app Bolt o ricevitore webhook, registrali tramite `openclaw/plugin-sdk/channel-runtime-context`. Il registro generico runtime-context permette al core di avviare handler guidati dalle funzionalità dallo stato di avvio del canale senza aggiungere glue wrapper specifici per le approvazioni. -- Ricorri ai livelli più bassi `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` solo quando la seam guidata dalle funzionalità non è ancora abbastanza espressiva. -- I canali di approvazione nativi devono instradare sia `accountId` sia `approvalKind` tramite questi helper. `accountId` mantiene la policy di approvazione multi-account confinata al giusto account bot, e `approvalKind` mantiene disponibile al canale il comportamento exec vs approvazione del Plugin senza branch hardcoded nel core. -- Ora anche gli avvisi di rerouting delle approvazioni appartengono al core. I Plugin di canale non dovrebbero inviare i propri messaggi di follow-up del tipo "l'approvazione è andata nei DM / in un altro canale" da `createChannelNativeApprovalRuntime`; invece, esponi un instradamento accurato origin + approver-DM tramite gli helper condivisi delle funzionalità di approvazione e lascia che il core aggreghi le consegne effettive prima di pubblicare qualsiasi avviso nella chat che ha avviato la richiesta. -- Mantieni il tipo di ID dell'approvazione consegnata end-to-end. I client nativi non dovrebbero - dedurre o riscrivere l'instradamento di approvazione exec vs Plugin dallo stato locale del canale. -- Diversi tipi di approvazione possono intenzionalmente esporre diverse superfici native. - Esempi inclusi attuali: - - Slack mantiene disponibile l'instradamento nativo delle approvazioni sia per gli ID exec sia per quelli del Plugin. - - Matrix mantiene lo stesso instradamento nativo DM/canale e la stessa UX a reazioni per le approvazioni exec - e del Plugin, pur lasciando che l'autenticazione differisca per tipo di approvazione. -- `createApproverRestrictedNativeApprovalAdapter` esiste ancora come wrapper di compatibilità, ma il nuovo codice dovrebbe preferire il costruttore di funzionalità ed esporre `approvalCapability` sul Plugin. +- `presentation` — mappa il view model di approvazione condiviso in payload nativi pending/resolved/expired o azioni finali +- `transport` — prepara i target più l'invio/aggiornamento/eliminazione dei messaggi di approvazione nativi +- `interactions` — hook opzionali bind/unbind/clear-action per pulsanti o reazioni native +- `observe` — hook opzionali per la diagnostica di consegna +- Se il canale ha bisogno di oggetti gestiti dal runtime come un client, token, app Bolt o ricevitore Webhook, registrali tramite `openclaw/plugin-sdk/channel-runtime-context`. Il registro generico runtime-context permette al core di avviare handler guidati dalle capacità a partire dallo stato di avvio del canale senza aggiungere codice wrapper specifico per le approvazioni. +- Ricorri a `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` di livello più basso solo quando la seam guidata dalle capacità non è ancora abbastanza espressiva. +- I canali di approvazione nativa devono instradare sia `accountId` sia `approvalKind` attraverso quegli helper. `accountId` mantiene l'ambito dei criteri di approvazione multi-account sul corretto account bot, e `approvalKind` mantiene disponibile per il canale il comportamento exec rispetto a quello di approvazione plugin senza rami hardcoded nel core. +- Il core ora gestisce anche gli avvisi di reinstradamento delle approvazioni. I plugin di canale non devono inviare i propri messaggi di follow-up "l'approvazione è andata ai DM / a un altro canale" da `createChannelNativeApprovalRuntime`; invece, esponi un routing accurato tra origine e DM dell'approvatore tramite gli helper condivisi di capability di approvazione e lascia che il core aggreghi le consegne effettive prima di pubblicare un eventuale avviso nella chat iniziale. +- Mantieni il tipo di id di approvazione consegnato end-to-end. I client nativi non devono + dedurre o riscrivere il routing dell'approvazione exec rispetto a plugin in base allo stato locale del canale. +- Diversi tipi di approvazione possono esporre intenzionalmente superfici native differenti. + Esempi bundled attuali: + - Slack mantiene disponibile il routing di approvazione nativa sia per gli id exec sia per quelli plugin. + - Matrix mantiene lo stesso routing DM/canale nativo e la stessa UX a reazioni per le approvazioni exec + e plugin, pur consentendo comunque che l'auth differisca in base al tipo di approvazione. +- `createApproverRestrictedNativeApprovalAdapter` esiste ancora come wrapper di compatibilità, ma il nuovo codice deve preferire il builder di capability ed esporre `approvalCapability` nel plugin. -Per gli entrypoint hot del canale, preferisci i sottopercorsi runtime più stretti quando ti -serve solo una parte di quella famiglia: +Per gli entrypoint caldi del canale, preferisci i sottopercorsi runtime più ristretti quando ti serve solo +una parte di quella famiglia: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -120,47 +131,50 @@ Allo stesso modo, preferisci `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` e -`openclaw/plugin-sdk/reply-chunking` quando non ti serve la -superficie ombrello più ampia. +`openclaw/plugin-sdk/reply-chunking` quando non ti serve la superficie umbrella +più ampia. -Per la configurazione in particolare: +Per la setup in particolare: -- `openclaw/plugin-sdk/setup-runtime` copre gli helper di configurazione sicuri per il runtime: - adapter di patch di configurazione import-safe (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` copre gli helper di setup sicuri per il runtime: + adattatori di patch setup sicuri all'import (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), output di note di lookup, - `promptResolvedAllowFrom`, `splitSetupEntries` e i costruttori - delegati di setup-proxy -- `openclaw/plugin-sdk/setup-adapter-runtime` è la seam stretta dell'adapter - sensibile all'env per `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` copre i costruttori di configurazione - per installazione facoltativa più alcuni primitivi sicuri per la configurazione: + `createSetupInputPresenceValidator`), output delle note di lookup, + `promptResolvedAllowFrom`, `splitSetupEntries` e i builder del + proxy di setup delegato +- `openclaw/plugin-sdk/setup-adapter-runtime` è la seam adattatore stretta consapevole dell'env + per `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` copre i builder setup a installazione opzionale + più alcune primitive sicure per il setup: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Se il tuo canale supporta configurazione o autenticazione guidata da env e i -flussi generici di avvio/configurazione devono conoscere quei nomi env prima del caricamento del runtime, -dichiarali nel manifest del Plugin con `channelEnvVars`. Mantieni `envVars` del runtime del canale -o costanti locali solo per il testo rivolto agli operatori. +Se il tuo canale supporta setup o auth guidati da env e i flussi generici di avvio/config +devono conoscere quei nomi env prima che il runtime venga caricato, dichiarali nel +manifest del plugin con `channelEnvVars`. Mantieni `envVars` del runtime del canale o costanti locali +solo per il testo rivolto agli operatori. -Se il tuo canale può apparire in `status`, `channels list`, `channels status` o -nelle scansioni SecretRef prima che il runtime del Plugin si avvii, aggiungi `openclaw.setupEntry` in -`package.json`. Quell'entrypoint dovrebbe essere sicuro da importare in percorsi di comando in sola lettura -e dovrebbe restituire i metadati del canale, l'adapter di configurazione sicuro per setup, l'adapter di stato -e i metadati del target segreto del canale necessari per quei riepiloghi. Non avviare client, listener o runtime di trasporto dall'entry di setup. +Se il tuo canale può comparire in `status`, `channels list`, `channels status` o +nelle scansioni SecretRef prima che il runtime del plugin si avvii, aggiungi `openclaw.setupEntry` in +`package.json`. Quell'entrypoint deve essere sicuro da importare in percorsi di comando in sola lettura +e deve restituire i metadati del canale, l'adattatore config sicuro per il setup, l'adattatore di stato +e i metadati del target secret del canale necessari per quei riepiloghi. Non avviare +client, listener o runtime di trasporto dall'entry di setup. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` e `splitSetupEntries` -- usa la seam più ampia `openclaw/plugin-sdk/setup` solo quando ti servono anche gli - helper condivisi più pesanti di setup/configurazione come +- usa la seam più ampia `openclaw/plugin-sdk/setup` solo quando hai bisogno anche degli + helper condivisi più pesanti di setup/config come `moveSingleAccountChannelSectionToDefaultAccount(...)` -Se il tuo canale vuole solo pubblicizzare "installa prima questo Plugin" nelle -superfici di configurazione, preferisci `createOptionalChannelSetupSurface(...)`. L'adapter/procedura guidata generata fallisce in modalità chiusa sulle scritture di configurazione e sulla finalizzazione, e riusa lo -stesso messaggio di installazione richiesta tra validazione, finalize e testo del link alla documentazione. +Se il tuo canale vuole solo pubblicizzare "installa prima questo plugin" nelle +superfici di setup, preferisci `createOptionalChannelSetupSurface(...)`. L'adattatore/procedura guidata generati +falliscono in modo chiuso sulle scritture di configurazione e sulla finalizzazione, e riusano +lo stesso messaggio di installazione richiesta in validazione, finalize e testo con link alla documentazione. -Per altri percorsi hot del canale, preferisci gli helper stretti rispetto alle più ampie superfici legacy: +Per altri percorsi caldi del canale, preferisci gli helper stretti rispetto alle +superfici legacy più ampie: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, @@ -168,42 +182,43 @@ Per altri percorsi hot del canale, preferisci gli helper stretti rispetto alle p `openclaw/plugin-sdk/account-helpers` per la configurazione multi-account e il fallback dell'account predefinito - `openclaw/plugin-sdk/inbound-envelope` e - `openclaw/plugin-sdk/inbound-reply-dispatch` per il wiring di route/envelope inbound e + `openclaw/plugin-sdk/inbound-reply-dispatch` per il wiring di route/envelope in ingresso e record-and-dispatch - `openclaw/plugin-sdk/messaging-targets` per parsing/matching dei target - `openclaw/plugin-sdk/outbound-media` e - `openclaw/plugin-sdk/outbound-runtime` per caricamento dei contenuti multimediali più delegate di - identità/invio outbound e pianificazione del payload + `openclaw/plugin-sdk/outbound-runtime` per il caricamento dei media più le + delegate di identità/invio in uscita e la pianificazione del payload - `buildThreadAwareOutboundSessionRoute(...)` da - `openclaw/plugin-sdk/channel-core` quando una route outbound deve preservare un - `replyToId`/`threadId` esplicito o recuperare la sessione `:thread:` corrente - dopo che la chiave di sessione base continua a corrispondere. I Plugin provider possono sostituire - precedenza, comportamento del suffisso e normalizzazione dell'ID thread quando la loro piattaforma - ha semantica nativa di consegna in thread. + `openclaw/plugin-sdk/channel-core` quando una route in uscita deve preservare un + `replyToId`/`threadId` esplicito o recuperare la sessione corrente `:thread:` + dopo che la chiave di sessione di base continua comunque a corrispondere. I plugin provider possono sovrascrivere + precedenza, comportamento del suffisso e normalizzazione dell'id thread quando la loro piattaforma + ha semantiche native di consegna nei thread. - `openclaw/plugin-sdk/thread-bindings-runtime` per il ciclo di vita dei thread-binding - e la registrazione degli adapter -- `openclaw/plugin-sdk/agent-media-payload` solo quando è ancora richiesto un layout legacy del - campo payload agente/media -- `openclaw/plugin-sdk/telegram-command-config` per normalizzazione dei comandi personalizzati Telegram, - validazione di duplicati/conflitti e un contratto di configurazione dei comandi stabile nel fallback + e la registrazione degli adattatori +- `openclaw/plugin-sdk/agent-media-payload` solo quando è ancora richiesto un layout legacy + dei campi del payload agent/media +- `openclaw/plugin-sdk/telegram-command-config` per la normalizzazione dei comandi personalizzati di Telegram, + la validazione di duplicati/conflitti e un contratto di configurazione dei comandi + stabile nel fallback -I canali solo-auth di solito possono fermarsi al percorso predefinito: il core gestisce le approvazioni e il Plugin espone solo le funzionalità outbound/auth. I canali con approvazione nativa come Matrix, Slack, Telegram e i trasporti chat personalizzati dovrebbero usare gli helper nativi condivisi invece di implementare da soli il proprio ciclo di vita delle approvazioni. +I canali solo auth di solito possono fermarsi al percorso predefinito: il core gestisce le approvazioni e il plugin espone soltanto capacità outbound/auth. I canali con approvazioni native come Matrix, Slack, Telegram e i trasporti chat personalizzati devono usare gli helper nativi condivisi invece di implementare da soli il ciclo di vita delle approvazioni. -## Criterio di menzione inbound +## Criteri delle menzioni in ingresso -Mantieni la gestione delle menzioni inbound divisa in due livelli: +Mantieni la gestione delle menzioni in ingresso suddivisa in due livelli: -- raccolta delle evidenze posseduta dal Plugin -- valutazione condivisa del criterio +- raccolta delle evidenze gestita dal plugin +- valutazione dei criteri condivisa -Usa `openclaw/plugin-sdk/channel-mention-gating` per le decisioni sul criterio di menzione. -Usa `openclaw/plugin-sdk/channel-inbound` solo quando ti serve il barrel helper inbound -più ampio. +Usa `openclaw/plugin-sdk/channel-mention-gating` per le decisioni sui criteri delle menzioni. +Usa `openclaw/plugin-sdk/channel-inbound` solo quando hai bisogno del barrel helper +più ampio per l'inbound. -Adatto alla logica locale del Plugin: +Adatto alla logica locale del plugin: -- rilevamento di reply-to-bot -- rilevamento di quoted-bot +- rilevamento della risposta al bot +- rilevamento della citazione del bot - controlli di partecipazione al thread - esclusioni di messaggi di servizio/sistema - cache native della piattaforma necessarie per dimostrare la partecipazione del bot @@ -212,15 +227,15 @@ Adatto all'helper condiviso: - `requireMention` - risultato di menzione esplicita -- allowlist di menzione implicita +- allowlist di menzioni implicite - bypass dei comandi - decisione finale di skip -Flusso preferito: +Flusso consigliato: -1. Calcolare i fatti locali della menzione. -2. Passare questi fatti a `resolveInboundMentionDecision({ facts, policy })`. -3. Usare `decision.effectiveWasMentioned`, `decision.shouldBypassMention` e `decision.shouldSkip` nel tuo gate inbound. +1. Calcola i fatti locali sulle menzioni. +2. Passa questi fatti a `resolveInboundMentionDecision({ facts, policy })`. +3. Usa `decision.effectiveWasMentioned`, `decision.shouldBypassMention` e `decision.shouldSkip` nel tuo gate inbound. ```typescript import { @@ -259,8 +274,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` espone gli stessi helper di menzione condivisi per -i Plugin di canale inclusi che dipendono già dall'iniezione runtime: +`api.runtime.channel.mentions` espone gli stessi helper condivisi per le menzioni per +i plugin di canale bundled che già dipendono dall'iniezione runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -273,18 +288,18 @@ Se ti servono solo `implicitMentionKindWhen` e `openclaw/plugin-sdk/channel-mention-gating` per evitare di caricare helper runtime inbound non correlati. -I vecchi helper `resolveMentionGating*` restano su -`openclaw/plugin-sdk/channel-inbound` solo come export di compatibilità. Il nuovo codice -dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. +I vecchi helper `resolveMentionGating*` restano in +`openclaw/plugin-sdk/channel-inbound` solo come esportazioni di compatibilità. Il nuovo codice +deve usare `resolveInboundMentionDecision({ facts, policy })`. -## Procedura guidata +## Guida passo passo - Crea i file standard del Plugin. Il campo `channel` in `package.json` è - ciò che rende questo un Plugin di canale. Per la superficie completa dei metadati del pacchetto, - vedi [Configurazione e setup del Plugin](/it/plugins/sdk-setup#openclaw-channel): + Crea i file standard del plugin. Il campo `channel` in `package.json` è + ciò che rende questo un plugin di canale. Per la superficie completa dei metadati del pacchetto, + vedi [Plugin Setup and Config](/it/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -298,7 +313,7 @@ dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Collega OpenClaw ad Acme Chat." + "blurb": "Connect OpenClaw to Acme Chat." } } } @@ -310,7 +325,7 @@ dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Plugin di canale Acme Chat", + "description": "Acme Chat channel plugin", "configSchema": { "type": "object", "additionalProperties": false, @@ -333,9 +348,9 @@ dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. - - L'interfaccia `ChannelPlugin` ha molte superfici adapter opzionali. Inizia con - il minimo — `id` e `setup` — e aggiungi adapter secondo necessità. + + L'interfaccia `ChannelPlugin` ha molte superfici adattatore opzionali. Inizia con + il minimo — `id` e `setup` — e aggiungi adattatori secondo necessità. Crea `src/channel.ts`: @@ -431,23 +446,23 @@ dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. ``` - Invece di implementare manualmente interfacce adapter di basso livello, passi + Invece di implementare manualmente interfacce adattatore di basso livello, passi opzioni dichiarative e il builder le compone: - | Opzione | Cosa collega | + | Option | Cosa collega | | --- | --- | - | `security.dm` | Resolver di sicurezza DM con scope dai campi di configurazione | + | `security.dm` | Resolver di sicurezza DM con ambito dai campi di configurazione | | `pairing.text` | Flusso di pairing DM basato su testo con scambio di codice | - | `threading` | Resolver della modalità reply-to (fissa, con scope per account o personalizzata) | + | `threading` | Resolver della modalità reply-to (fissa, con ambito account o personalizzata) | | `outbound.attachedResults` | Funzioni di invio che restituiscono metadati del risultato (ID messaggio) | - Puoi anche passare oggetti adapter raw invece delle opzioni dichiarative - se hai bisogno di pieno controllo. + Puoi anche passare oggetti adattatore grezzi invece delle opzioni dichiarative + se hai bisogno del pieno controllo. - + Crea `index.ts`: ```typescript index.ts @@ -483,16 +498,16 @@ dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. }); ``` - Inserisci i descrittori CLI posseduti dal canale in `registerCliMetadata(...)` così OpenClaw + Inserisci i descrittori CLI gestiti dal canale in `registerCliMetadata(...)` così OpenClaw può mostrarli nell'help root senza attivare il runtime completo del canale, - mentre i normali caricamenti completi continuano a raccogliere gli stessi descrittori per la registrazione reale dei comandi. - Mantieni `registerFull(...)` per il lavoro solo runtime. - Se `registerFull(...)` registra metodi RPC del Gateway, usa un - prefisso specifico del Plugin. I namespace admin del core (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e vengono sempre - risolti in `operator.admin`. - `defineChannelPluginEntry` gestisce automaticamente la separazione delle modalità di registrazione. Vedi - [Entrypoint](/it/plugins/sdk-entrypoints#definechannelpluginentry) per tutte le + mentre i normali caricamenti completi continuano a rilevare gli stessi descrittori per la vera registrazione + dei comandi. Mantieni `registerFull(...)` per il lavoro solo runtime. + Se `registerFull(...)` registra metodi RPC Gateway, usa un + prefisso specifico del plugin. I namespace amministrativi del core (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e si + risolvono sempre in `operator.admin`. + `defineChannelPluginEntry` gestisce automaticamente la divisione delle modalità di registrazione. Vedi + [Entry Points](/it/plugins/sdk-entrypoints#definechannelpluginentry) per tutte le opzioni. @@ -507,33 +522,33 @@ dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw carica questo invece dell'entry completa quando il canale è disabilitato - o non configurato. Evita di trascinare codice runtime pesante durante i flussi di setup. - Vedi [Setup e configurazione](/it/plugins/sdk-setup#setup-entry) per i dettagli. + OpenClaw carica questa entry invece dell'entry completa quando il canale è disabilitato + o non configurato. Evita di caricare codice runtime pesante durante i flussi di setup. + Vedi [Setup and Config](/it/plugins/sdk-setup#setup-entry) per i dettagli. - I canali workspace inclusi che dividono gli export sicuri per il setup in moduli - laterali possono usare `defineBundledChannelSetupEntry(...)` da - `openclaw/plugin-sdk/channel-entry-contract` quando hanno anche bisogno di un - setter runtime esplicito per il tempo di setup. + I canali workspace bundled che separano le esportazioni sicure per il setup in moduli + sidecar possono usare `defineBundledChannelSetupEntry(...)` da + `openclaw/plugin-sdk/channel-entry-contract` quando hanno bisogno anche di un + setter runtime esplicito al tempo di setup. - - Il tuo Plugin deve ricevere i messaggi dalla piattaforma e inoltrarli a - OpenClaw. Il pattern tipico è un webhook che verifica la richiesta e la - inoltra tramite l'handler inbound del tuo canale: + + Il tuo plugin deve ricevere messaggi dalla piattaforma e inoltrarli a + OpenClaw. Il pattern tipico è un Webhook che verifica la richiesta e + la invia tramite l'handler inbound del tuo canale: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // autenticazione gestita dal plugin (verifica tu stesso le firme) + auth: "plugin", // auth gestita dal plugin (verifica tu stesso le firme) handler: async (req, res) => { const event = parseWebhookPayload(req); // Il tuo handler inbound inoltra il messaggio a OpenClaw. - // Il wiring esatto dipende dal tuo SDK della piattaforma — - // vedi un esempio reale nel pacchetto Plugin incluso Microsoft Teams o Google Chat. + // Il wiring esatto dipende dal tuo SDK di piattaforma — + // vedi un esempio reale nel pacchetto plugin bundled di Microsoft Teams o Google Chat. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -545,9 +560,9 @@ dovrebbe usare `resolveInboundMentionDecision({ facts, policy })`. ``` - La gestione dei messaggi inbound è specifica del canale. Ogni Plugin di canale possiede - la propria pipeline inbound. Guarda i Plugin di canale inclusi - (ad esempio il pacchetto Plugin Microsoft Teams o Google Chat) per pattern reali. + La gestione dei messaggi in ingresso è specifica del canale. Ogni plugin di canale gestisce + la propria pipeline inbound. Guarda i plugin di canale bundled + (per esempio il pacchetto plugin di Microsoft Teams o Google Chat) per pattern reali. @@ -605,8 +620,8 @@ Scrivi test colocati in `src/channel.test.ts`: ├── openclaw.plugin.json # Manifest con schema di configurazione ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Export pubblici (facoltativo) -├── runtime-api.ts # Export runtime interni (facoltativo) +├── api.ts # Esportazioni pubbliche (facoltativo) +├── runtime-api.ts # Esportazioni runtime interne (facoltativo) └── src/ ├── channel.ts # ChannelPlugin tramite createChatChannelPlugin ├── channel.test.ts # Test @@ -618,29 +633,29 @@ Scrivi test colocati in `src/channel.test.ts`: - Modalità reply fisse, con scope per account o personalizzate + Modalità di risposta fisse, con ambito account o personalizzate - describeMessageTool e rilevamento delle azioni + describeMessageTool e discovery delle azioni inferTargetChatType, looksLikeId, resolveTarget - TTS, STT, contenuti multimediali, sottoagente tramite api.runtime + TTS, STT, media, subagent tramite api.runtime -Alcune seam helper incluse esistono ancora per la manutenzione e la -compatibilità dei Plugin inclusi. Non sono il pattern consigliato per i nuovi Plugin di canale; -preferisci i sottopercorsi generici channel/setup/reply/runtime dalla superficie -SDK comune, a meno che tu non stia mantenendo direttamente quella famiglia di Plugin inclusi. +Alcune seam helper bundled esistono ancora per la manutenzione dei plugin bundled e +la compatibilità. Non sono il pattern consigliato per i nuovi plugin di canale; +preferisci i sottopercorsi generici channel/setup/reply/runtime dalla superficie SDK +comune a meno che tu non stia mantenendo direttamente quella famiglia di plugin bundled. ## Passi successivi -- [Plugin provider](/it/plugins/sdk-provider-plugins) — se il tuo Plugin fornisce anche modelli -- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento completo degli import dei sottopercorsi -- [SDK Testing](/it/plugins/sdk-testing) — utilità di test e test di contratto -- [Manifest del Plugin](/it/plugins/manifest) — schema completo del manifest +- [Provider Plugins](/it/plugins/sdk-provider-plugins) — se il tuo plugin fornisce anche modelli +- [SDK Overview](/it/plugins/sdk-overview) — riferimento completo per gli import subpath +- [SDK Testing](/it/plugins/sdk-testing) — utility di test e test di contratto +- [Plugin Manifest](/it/plugins/manifest) — schema completo del manifest diff --git a/docs/it/plugins/sdk-overview.md b/docs/it/plugins/sdk-overview.md index 668de8933..97b51c311 100644 --- a/docs/it/plugins/sdk-overview.md +++ b/docs/it/plugins/sdk-overview.md @@ -1,320 +1,320 @@ --- read_when: - - Hai bisogno di sapere da quale subpath dell'SDK importare - - Vuoi un riferimento per tutti i metodi di registrazione in OpenClawPluginApi + - Devi sapere da quale sottopercorso dell'SDK importare + - Vuoi un riferimento per tutti i metodi di registrazione su OpenClawPluginApi - Stai cercando una specifica esportazione dell'SDK sidebarTitle: SDK Overview -summary: Mappa degli import, riferimento dell'API di registrazione e architettura dell'SDK -title: Panoramica dell'SDK Plugin +summary: Mappa di importazione, riferimento API di registrazione e architettura SDK +title: Panoramica dell'SDK del Plugin x-i18n: - generated_at: "2026-04-22T04:25:35Z" + generated_at: "2026-04-22T08:20:51Z" model: gpt-5.4 provider: openai - source_hash: 8045c11976bbda6afe3303a0aab08caf0d0a86ebcf1aaaf927943b90cc517673 + source_hash: e57019e6f9a7fed7842ac575e025b6db41d125f5fa9d0d1de03923fdb1f6bcc3 source_path: plugins/sdk-overview.md workflow: 15 --- -# Panoramica dell'SDK Plugin +# Panoramica dell'SDK del Plugin -L'SDK Plugin è il contratto tipizzato tra Plugin e core. Questa pagina è il +L'SDK del Plugin è il contratto tipizzato tra i plugin e il core. Questa pagina è il riferimento per **cosa importare** e **cosa puoi registrare**. **Cerchi una guida pratica?** - - Primo Plugin? Inizia con [Per iniziare](/it/plugins/building-plugins) - - Plugin di canale? Vedi [Plugin di canale](/it/plugins/sdk-channel-plugins) - - Plugin provider? Vedi [Plugin provider](/it/plugins/sdk-provider-plugins) + - Primo Plugin? Inizia con [Getting Started](/it/plugins/building-plugins) + - Plugin di canale? Vedi [Channel Plugins](/it/plugins/sdk-channel-plugins) + - Plugin provider? Vedi [Provider Plugins](/it/plugins/sdk-provider-plugins) -## Convenzione di import +## Convenzione di importazione -Importa sempre da un subpath specifico: +Importa sempre da uno specifico sottopercorso: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Ogni subpath è un modulo piccolo e autosufficiente. Questo mantiene veloce l'avvio e -previene problemi di dipendenze circolari. Per helper di entry/build specifici del canale, +Ogni sottopercorso è un modulo piccolo e autosufficiente. Questo mantiene veloce l'avvio e +previene problemi di dipendenze circolari. Per gli helper di entry/build specifici del canale, preferisci `openclaw/plugin-sdk/channel-core`; mantieni `openclaw/plugin-sdk/core` per -la superficie umbrella più ampia e helper condivisi come +la surface ombrello più ampia e gli helper condivisi come `buildChannelConfigSchema`. -Non aggiungere né dipendere da seam di convenienza con nomi di provider come +Non aggiungere né dipendere da seam di convenienza con nome del provider come `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` o -seam helper con branding del canale. I Plugin bundled dovrebbero comporre subpath -generici dell'SDK all'interno dei propri barrel `api.ts` o `runtime-api.ts`, e il core -dovrebbe usare quei barrel locali al Plugin oppure aggiungere un contratto SDK -generico e ristretto quando l'esigenza è davvero cross-channel. +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, o +seam helper con brand del canale. I plugin inclusi dovrebbero comporre sottopercorsi +SDK generici all'interno dei propri barrel `api.ts` o `runtime-api.ts`, e il core +dovrebbe usare tali barrel locali al plugin oppure aggiungere un contratto SDK generico e ristretto +quando l'esigenza è davvero cross-channel. -La export map generata contiene ancora un piccolo insieme di seam helper per Plugin bundled -come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +La mappa di esportazione generata contiene ancora un piccolo insieme di seam helper +dei plugin inclusi come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Questi -subpath esistono solo per manutenzione e compatibilità dei Plugin bundled; sono +sottopercorsi esistono solo per manutenzione e compatibilità dei plugin inclusi; sono intenzionalmente omessi dalla tabella comune qui sotto e non sono il percorso di -import consigliato per nuovi Plugin di terze parti. +importazione consigliato per nuovi plugin di terze parti. -## Riferimento dei subpath +## Riferimento dei sottopercorsi -I subpath usati più comunemente, raggruppati per scopo. L'elenco completo generato di -oltre 200 subpath si trova in `scripts/lib/plugin-sdk-entrypoints.json`. +I sottopercorsi usati più comunemente, raggruppati per scopo. L'elenco completo generato di +oltre 200 sottopercorsi si trova in `scripts/lib/plugin-sdk-entrypoints.json`. -I subpath helper riservati ai Plugin bundled compaiono ancora in quell'elenco generato. -Trattali come superfici di dettaglio implementativo/compatibilità, a meno che una pagina della documentazione +I sottopercorsi helper riservati ai plugin inclusi compaiono ancora in quell'elenco generato. +Trattali come dettagli di implementazione/surface di compatibilità, a meno che una pagina della documentazione non ne promuova esplicitamente uno come pubblico. ### Entry del Plugin -| Subpath | Key exports | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Sottopercorso | Esportazioni chiave | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - - | Subpath | Key exports | + + | Sottopercorso | Esportazioni chiave | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Esportazione dello schema Zod root `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Esportazione dello schema Zod radice `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Helper condivisi per la procedura guidata di setup, prompt allowlist, builder dello stato di setup | + | `plugin-sdk/setup` | Helper condivisi per setup wizard, prompt allowlist, builder di stato del setup | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helper per config/action-gate multi-account, helper di fallback dell'account predefinito | + | `plugin-sdk/account-core` | Helper per config/gate di azione multi-account, helper di fallback per account predefinito | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper di normalizzazione dell'account-id | - | `plugin-sdk/account-resolution` | Ricerca account + helper di fallback predefinito | - | `plugin-sdk/account-helpers` | Helper ristretti per elenco account/azioni account | + | `plugin-sdk/account-resolution` | Helper di ricerca account + fallback predefinito | + | `plugin-sdk/account-helpers` | Helper ristretti per elenco account/azione account | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Tipi di schema config del canale | - | `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati Telegram con fallback al contratto bundled | - | `plugin-sdk/command-gating` | Helper ristretti per il gate di autorizzazione dei comandi | + | `plugin-sdk/channel-config-schema` | Tipi di schema della configurazione del canale | + | `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati Telegram con fallback del contratto incluso | + | `plugin-sdk/command-gating` | Helper ristretti per gate di autorizzazione dei comandi | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, helper di ciclo di vita/finalizzazione per draft stream | - | `plugin-sdk/inbound-envelope` | Helper condivisi per route inbound + builder dell'envelope | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, helper di lifecycle/finalizzazione per draft stream | + | `plugin-sdk/inbound-envelope` | Helper condivisi per route inbound + builder envelope | | `plugin-sdk/inbound-reply-dispatch` | Helper condivisi per registrazione e dispatch inbound | | `plugin-sdk/messaging-targets` | Helper di parsing/matching dei target | | `plugin-sdk/outbound-media` | Helper condivisi per il caricamento dei media outbound | - | `plugin-sdk/outbound-runtime` | Helper per identità outbound, delega di invio e pianificazione dei payload | - | `plugin-sdk/poll-runtime` | Helper ristretti per la normalizzazione dei poll | - | `plugin-sdk/thread-bindings-runtime` | Helper di ciclo di vita e adapter per i thread-binding | + | `plugin-sdk/outbound-runtime` | Helper per identità outbound, delegato di invio e pianificazione del payload | + | `plugin-sdk/poll-runtime` | Helper ristretti di normalizzazione dei poll | + | `plugin-sdk/thread-bindings-runtime` | Helper di lifecycle e adapter per thread-binding | | `plugin-sdk/agent-media-payload` | Builder legacy del payload media dell'agente | - | `plugin-sdk/conversation-runtime` | Helper per conversazione/thread binding, pairing e binding configurati | - | `plugin-sdk/runtime-config-snapshot` | Helper per snapshot della config runtime | - | `plugin-sdk/runtime-group-policy` | Helper per la risoluzione della group-policy runtime | + | `plugin-sdk/conversation-runtime` | Helper per binding conversazione/thread, pairing e binding configurato | + | `plugin-sdk/runtime-config-snapshot` | Helper di snapshot della configurazione runtime | + | `plugin-sdk/runtime-group-policy` | Helper di risoluzione delle group policy runtime | | `plugin-sdk/channel-status` | Helper condivisi per snapshot/riepilogo dello stato del canale | - | `plugin-sdk/channel-config-primitives` | Primitive ristrette per lo schema config del canale | - | `plugin-sdk/channel-config-writes` | Helper di autorizzazione per le scritture di configurazione del canale | - | `plugin-sdk/channel-plugin-common` | Esportazioni prelude condivise del Plugin di canale | - | `plugin-sdk/allowlist-config-edit` | Helper di lettura/modifica della config allowlist | - | `plugin-sdk/group-access` | Helper condivisi per le decisioni di accesso ai gruppi | - | `plugin-sdk/direct-dm` | Helper condivisi per auth/guard dei DM diretti | - | `plugin-sdk/interactive-runtime` | Presentazione semantica dei messaggi, consegna e helper legacy per risposte interattive. Vedi [Presentazione dei messaggi](/it/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Barrel di compatibilità per debounce inbound, matching delle menzioni, helper di mention-policy e helper envelope | - | `plugin-sdk/channel-mention-gating` | Helper ristretti per mention-policy senza la più ampia superficie runtime inbound | - | `plugin-sdk/channel-location` | Helper per contesto di posizione e formattazione del canale | - | `plugin-sdk/channel-logging` | Helper di logging del canale per inbound scartati e errori typing/ack | - | `plugin-sdk/channel-send-result` | Tipi di risultato della risposta | - | `plugin-sdk/channel-actions` | Helper per azioni sui messaggi del canale, più helper di schema nativo deprecati mantenuti per compatibilità del Plugin | + | `plugin-sdk/channel-config-primitives` | Primitive ristrette di schema configurazione del canale | + | `plugin-sdk/channel-config-writes` | Helper di autorizzazione per scrittura della configurazione del canale | + | `plugin-sdk/channel-plugin-common` | Esportazioni di preambolo condivise del plugin di canale | + | `plugin-sdk/allowlist-config-edit` | Helper di lettura/modifica della configurazione allowlist | + | `plugin-sdk/group-access` | Helper condivisi per decisioni di accesso ai gruppi | + | `plugin-sdk/direct-dm` | Helper condivisi per auth/guard dei messaggi diretti | + | `plugin-sdk/interactive-runtime` | Helper per presentazione semantica dei messaggi, consegna e risposte interattive legacy. Vedi [Message Presentation](/it/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Barrel di compatibilità per debounce inbound, matching delle menzioni, helper di mention-policy ed envelope | + | `plugin-sdk/channel-mention-gating` | Helper ristretti di mention-policy senza la più ampia surface runtime inbound | + | `plugin-sdk/channel-location` | Helper di contesto e formattazione della posizione del canale | + | `plugin-sdk/channel-logging` | Helper di logging del canale per scarti inbound e errori di typing/ack | + | `plugin-sdk/channel-send-result` | Tipi del risultato di risposta | + | `plugin-sdk/channel-actions` | Helper per azioni sui messaggi del canale, più helper di schema nativo deprecati mantenuti per compatibilità dei plugin | | `plugin-sdk/channel-targets` | Helper di parsing/matching dei target | | `plugin-sdk/channel-contract` | Tipi di contratto del canale | - | `plugin-sdk/channel-feedback` | Wiring di feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Helper ristretti del contratto secret come `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipi di target secret | + | `plugin-sdk/channel-feedback` | Wiring di feedback/reazioni | + | `plugin-sdk/channel-secret-runtime` | Helper ristretti del contratto dei secret come `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipi target dei secret | - - | Subpath | Key exports | + + | Sottopercorso | Esportazioni chiave | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helper curati per il setup di provider locali/self-hosted | - | `plugin-sdk/self-hosted-provider-setup` | Helper mirati per il setup di provider self-hosted compatibili con OpenAI | + | `plugin-sdk/provider-setup` | Helper curati di setup per provider locali/self-hosted | + | `plugin-sdk/self-hosted-provider-setup` | Helper mirati di setup per provider self-hosted compatibili OpenAI | | `plugin-sdk/cli-backend` | Valori predefiniti del backend CLI + costanti watchdog | - | `plugin-sdk/provider-auth-runtime` | Helper runtime per la risoluzione delle API key dei Plugin provider | - | `plugin-sdk/provider-auth-api-key` | Helper di onboarding/scrittura profili per API key come `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Builder standard del risultato auth OAuth | - | `plugin-sdk/provider-auth-login` | Helper condivisi di login interattivo per Plugin provider | - | `plugin-sdk/provider-env-vars` | Helper di ricerca delle env var auth del provider | + | `plugin-sdk/provider-auth-runtime` | Helper runtime di risoluzione delle API key per plugin provider | + | `plugin-sdk/provider-auth-api-key` | Helper per onboarding/scrittura del profilo API key come `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Builder standard del risultato di autenticazione OAuth | + | `plugin-sdk/provider-auth-login` | Helper condivisi di login interattivo per plugin provider | + | `plugin-sdk/provider-env-vars` | Helper di ricerca delle env var di autenticazione del provider | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint provider e helper di normalizzazione model-id come `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper di endpoint provider e helper di normalizzazione dell'id modello come `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helper generici per capacità HTTP/endpoint dei provider | - | `plugin-sdk/provider-web-fetch-contract` | Helper ristretti per il contratto di config/selezione web-fetch come `enablePluginInConfig` e `WebFetchProviderPlugin` | + | `plugin-sdk/provider-http` | Helper generici di capacità HTTP/endpoint del provider | + | `plugin-sdk/provider-web-fetch-contract` | Helper ristretti del contratto di configurazione/selezione web-fetch come `enablePluginInConfig` e `WebFetchProviderPlugin` | | `plugin-sdk/provider-web-fetch` | Helper di registrazione/cache per provider web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helper ristretti di config/credenziali web-search per provider che non hanno bisogno del wiring di abilitazione Plugin | - | `plugin-sdk/provider-web-search-contract` | Helper ristretti per il contratto di config/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con ambito | + | `plugin-sdk/provider-web-search-config-contract` | Helper ristretti di configurazione/credenziali web-search per provider che non necessitano del wiring di abilitazione del plugin | + | `plugin-sdk/provider-web-search-contract` | Helper ristretti del contratto di configurazione/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con scope | | `plugin-sdk/provider-web-search` | Helper di registrazione/cache/runtime per provider web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, cleanup + diagnostica dello schema Gemini e helper compat xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia dello schema Gemini + diagnostica, e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` e simili | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di stream wrapper e helper condivisi per wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Helper di trasporto provider nativo come fetch protetto, trasformazioni dei messaggi di trasporto e stream di eventi di trasporto scrivibili | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi dei wrapper stream e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Helper di trasporto nativo del provider come fetch protetto, trasformazioni dei messaggi di trasporto e stream di eventi di trasporto scrivibili | | `plugin-sdk/provider-onboard` | Helper di patch della configurazione di onboarding | - | `plugin-sdk/global-singleton` | Helper singleton/map/cache locali al processo | + | `plugin-sdk/global-singleton` | Helper di singleton/map/cache locali al processo | - - | Subpath | Key exports | + + | Sottopercorso | Esportazioni chiave | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper del registro dei comandi, helper di autorizzazione del mittente | - | `plugin-sdk/command-status` | Builder di comandi/messaggi di aiuto come `buildCommandsMessagePaginated` e `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Helper per la risoluzione degli approvatori e auth delle azioni nella stessa chat | - | `plugin-sdk/approval-client-runtime` | Helper per profili/filtri di approvazione exec nativi | - | `plugin-sdk/approval-delivery-runtime` | Adapter di capacità/consegna per approvazioni native | - | `plugin-sdk/approval-gateway-runtime` | Helper condiviso per la risoluzione del gateway di approvazione | - | `plugin-sdk/approval-handler-adapter-runtime` | Helper leggeri di caricamento dell'adapter di approvazione nativa per entrypoint di canale hot | - | `plugin-sdk/approval-handler-runtime` | Helper runtime più ampi per l'handler di approvazione; preferisci i seam più ristretti adapter/gateway quando bastano | - | `plugin-sdk/approval-native-runtime` | Helper per target di approvazione nativa + binding account | - | `plugin-sdk/approval-reply-runtime` | Helper per payload di risposta delle approvazioni exec/plugin | - | `plugin-sdk/command-auth-native` | Helper di auth dei comandi nativi + target di sessione nativa | + | `plugin-sdk/command-status` | Builder di messaggi di comando/help come `buildCommandsMessagePaginated` e `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Helper di risoluzione dell'approvatore e di autenticazione delle azioni nella stessa chat | + | `plugin-sdk/approval-client-runtime` | Helper nativi di profilo/filtro per approvazione exec | + | `plugin-sdk/approval-delivery-runtime` | Adapter nativi di capability/consegna dell'approvazione | + | `plugin-sdk/approval-gateway-runtime` | Helper condiviso di risoluzione del gateway di approvazione | + | `plugin-sdk/approval-handler-adapter-runtime` | Helper leggeri di caricamento dell'adapter di approvazione nativo per entrypoint hot dei canali | + | `plugin-sdk/approval-handler-runtime` | Helper runtime più ampi per il gestore di approvazione; preferisci i seam più ristretti adapter/gateway quando sono sufficienti | + | `plugin-sdk/approval-native-runtime` | Helper nativi per target di approvazione + binding dell'account | + | `plugin-sdk/approval-reply-runtime` | Helper del payload di risposta per approvazione exec/plugin | + | `plugin-sdk/command-auth-native` | Helper nativi per autenticazione dei comandi + target di sessione nativo | | `plugin-sdk/command-detection` | Helper condivisi di rilevamento dei comandi | - | `plugin-sdk/command-surface` | Helper di normalizzazione del corpo del comando e command-surface | + | `plugin-sdk/command-surface` | Normalizzazione del corpo dei comandi e helper della surface dei comandi | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Helper ristretti di raccolta del contratto secret per superfici secret di canale/plugin | - | `plugin-sdk/secret-ref-runtime` | Helper ristretti `coerceSecretRef` e di typing SecretRef per parsing di contratto secret/config | + | `plugin-sdk/channel-secret-runtime` | Helper ristretti di raccolta del contratto dei secret per surface di secret di canale/plugin | + | `plugin-sdk/secret-ref-runtime` | Helper ristretti `coerceSecretRef` e di tipizzazione SecretRef per parsing di contratto/configurazione dei secret | | `plugin-sdk/security-runtime` | Helper condivisi per trust, gating DM, contenuto esterno e raccolta dei secret | | `plugin-sdk/ssrf-policy` | Helper di policy SSRF per allowlist host e rete privata | - | `plugin-sdk/ssrf-dispatcher` | Helper ristretti di pinned-dispatcher senza l'ampia superficie infra runtime | - | `plugin-sdk/ssrf-runtime` | Helper per pinned-dispatcher, fetch protetto da SSRF e policy SSRF | - | `plugin-sdk/secret-input` | Helper di parsing dell'input secret | - | `plugin-sdk/webhook-ingress` | Helper per richieste/target Webhook | - | `plugin-sdk/webhook-request-guards` | Helper per dimensione del body e timeout della richiesta | + | `plugin-sdk/ssrf-dispatcher` | Helper ristretti di dispatcher fissato senza la più ampia surface runtime dell'infrastruttura | + | `plugin-sdk/ssrf-runtime` | Helper per dispatcher fissato, fetch protetto da SSRF e policy SSRF | + | `plugin-sdk/secret-input` | Helper di parsing dell'input dei secret | + | `plugin-sdk/webhook-ingress` | Helper per richiesta/target Webhook | + | `plugin-sdk/webhook-request-guards` | Helper per dimensione del body della richiesta/timeout | - - | Subpath | Key exports | + + | Sottopercorso | Esportazioni chiave | | --- | --- | - | `plugin-sdk/runtime` | Helper ampi per runtime/logging/backup/installazione Plugin | + | `plugin-sdk/runtime` | Helper ampi per runtime/logging/backup/installazione plugin | | `plugin-sdk/runtime-env` | Helper ristretti per env runtime, logger, timeout, retry e backoff | | `plugin-sdk/channel-runtime-context` | Helper generici di registrazione e lookup del contesto runtime del canale | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Helper condivisi per comandi/hook/http/interattività del Plugin | - | `plugin-sdk/hook-runtime` | Helper condivisi per la pipeline di hook Webhook/interni | - | `plugin-sdk/lazy-runtime` | Helper di import/binding runtime lazy come `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helper exec di processo | + | `plugin-sdk/plugin-runtime` | Helper condivisi per comando/hook/http/interattività del plugin | + | `plugin-sdk/hook-runtime` | Helper condivisi della pipeline di hook Webhook/interni | + | `plugin-sdk/lazy-runtime` | Helper di importazione/binding runtime lazy come `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helper di esecuzione dei processi | | `plugin-sdk/cli-runtime` | Helper per formattazione CLI, attesa e versione | - | `plugin-sdk/gateway-runtime` | Helper per il client Gateway e patch dello stato del canale | - | `plugin-sdk/config-runtime` | Helper per caricamento/scrittura della configurazione | - | `plugin-sdk/telegram-command-config` | Normalizzazione di nome/descrizione dei comandi Telegram e controlli di duplicati/conflitti, anche quando la superficie del contratto Telegram bundled non è disponibile | - | `plugin-sdk/text-autolink-runtime` | Rilevamento autolink dei riferimenti ai file senza l'ampio barrel text-runtime | - | `plugin-sdk/approval-runtime` | Helper per approvazioni exec/plugin, builder di capacità di approvazione, helper auth/profilo, helper di routing/runtime nativi | - | `plugin-sdk/reply-runtime` | Helper condivisi di runtime inbound/risposta, chunking, dispatch, Heartbeat, reply planner | + | `plugin-sdk/gateway-runtime` | Helper per client Gateway e patch dello stato del canale | + | `plugin-sdk/config-runtime` | Helper di caricamento/scrittura della configurazione | + | `plugin-sdk/telegram-command-config` | Normalizzazione di nome/descrizione dei comandi Telegram e controlli di duplicati/conflitti, anche quando la surface del contratto Telegram incluso non è disponibile | + | `plugin-sdk/text-autolink-runtime` | Rilevamento dell'autolink di riferimenti a file senza il più ampio barrel text-runtime | + | `plugin-sdk/approval-runtime` | Helper per approvazione exec/plugin, builder di capability di approvazione, helper auth/profilo, helper di routing/runtime nativo | + | `plugin-sdk/reply-runtime` | Helper runtime condivisi per inbound/risposta, chunking, dispatch, Heartbeat, pianificatore di risposta | | `plugin-sdk/reply-dispatch-runtime` | Helper ristretti per dispatch/finalizzazione delle risposte | | `plugin-sdk/reply-history` | Helper condivisi per la cronologia delle risposte a finestra breve come `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helper ristretti per il chunking di testo/markdown | - | `plugin-sdk/session-store-runtime` | Helper per percorso dello store di sessione + updated-at | - | `plugin-sdk/state-paths` | Helper per i percorsi delle directory state/OAuth | - | `plugin-sdk/routing` | Helper per route/session-key/binding account come `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helper condivisi per riepilogo dello stato di canale/account, valori predefiniti dello stato runtime e helper per metadati dei problemi | - | `plugin-sdk/target-resolver-runtime` | Helper condivisi per la risoluzione dei target | - | `plugin-sdk/string-normalization-runtime` | Helper di normalizzazione slug/string | + | `plugin-sdk/reply-chunking` | Helper ristretti per chunking di testo/Markdown | + | `plugin-sdk/session-store-runtime` | Helper per percorso dello store delle sessioni + `updated-at` | + | `plugin-sdk/state-paths` | Helper di percorso per directory di stato/OAuth | + | `plugin-sdk/routing` | Helper per route/session-key/binding dell'account come `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Helper condivisi per riepilogo di stato canale/account, valori predefiniti dello stato runtime e helper di metadati dei problemi | + | `plugin-sdk/target-resolver-runtime` | Helper condivisi per resolver dei target | + | `plugin-sdk/string-normalization-runtime` | Helper di normalizzazione per slug/stringhe | | `plugin-sdk/request-url` | Estrae URL stringa da input simili a fetch/request | - | `plugin-sdk/run-command` | Runner di comandi temporizzato con risultati stdout/stderr normalizzati | - | `plugin-sdk/param-readers` | Lettori comuni di parametri tool/CLI | - | `plugin-sdk/tool-payload` | Estrae payload normalizzati dagli oggetti risultato tool | - | `plugin-sdk/tool-send` | Estrae campi target di invio canonici dagli argomenti del tool | - | `plugin-sdk/temp-path` | Helper condivisi per i percorsi di download temporanei | + | `plugin-sdk/run-command` | Esecutore di comandi temporizzato con risultati stdout/stderr normalizzati | + | `plugin-sdk/param-readers` | Lettori comuni di parametri per tool/CLI | + | `plugin-sdk/tool-payload` | Estrae payload normalizzati da oggetti risultato dei tool | + | `plugin-sdk/tool-send` | Estrae campi target di invio canonici dagli argomenti dei tool | + | `plugin-sdk/temp-path` | Helper condivisi per percorsi temporanei di download | | `plugin-sdk/logging-core` | Helper per logger di sottosistema e redazione | - | `plugin-sdk/markdown-table-runtime` | Helper per la modalità tabella Markdown | + | `plugin-sdk/markdown-table-runtime` | Helper per modalità tabella Markdown | | `plugin-sdk/json-store` | Piccoli helper di lettura/scrittura dello stato JSON | - | `plugin-sdk/file-lock` | Helper re-entrant per file-lock | - | `plugin-sdk/persistent-dedupe` | Helper per cache dedupe persistente su disco | - | `plugin-sdk/acp-runtime` | Helper per runtime/sessione ACP e reply-dispatch | - | `plugin-sdk/acp-binding-resolve-runtime` | Risoluzione read-only dei binding ACP senza import di avvio del ciclo di vita | - | `plugin-sdk/agent-config-primitives` | Primitive ristrette di schema config runtime dell'agente | + | `plugin-sdk/file-lock` | Helper di file-lock rientrante | + | `plugin-sdk/persistent-dedupe` | Helper di cache dedupe persistente su disco | + | `plugin-sdk/acp-runtime` | Helper ACP per runtime/sessione e dispatch delle risposte | + | `plugin-sdk/acp-binding-resolve-runtime` | Risoluzione read-only del binding ACP senza importazioni di avvio del lifecycle | + | `plugin-sdk/agent-config-primitives` | Primitive ristrette di schema configurazione runtime dell'agente | | `plugin-sdk/boolean-param` | Lettore permissivo di parametri booleani | | `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per matching di nomi pericolosi | | `plugin-sdk/device-bootstrap` | Helper per bootstrap del dispositivo e token di pairing | - | `plugin-sdk/extension-shared` | Primitive helper condivise per canale passivo, stato e proxy ambient | - | `plugin-sdk/models-provider-runtime` | Helper per le risposte del comando `/models` / provider | - | `plugin-sdk/skill-commands-runtime` | Helper per l'elenco dei comandi Skill | + | `plugin-sdk/extension-shared` | Primitive helper condivise per canali passivi, stato e proxy ambientale | + | `plugin-sdk/models-provider-runtime` | Helper di risposta per comando/provider `/models` | + | `plugin-sdk/skill-commands-runtime` | Helper di elenco dei comandi Skill | | `plugin-sdk/native-command-registry` | Helper per registro/build/serializzazione dei comandi nativi | - | `plugin-sdk/agent-harness` | Superficie sperimentale trusted-plugin per harness di agente di basso livello: tipi di harness, helper per steer/abort delle esecuzioni attive, helper per il bridge dei tool OpenClaw e utility per i risultati dei tentativi | - | `plugin-sdk/provider-zai-endpoint` | Helper di rilevamento degli endpoint Z.AI | + | `plugin-sdk/agent-harness` | Surface sperimentale per plugin attendibili per harness di agenti di basso livello: tipi di harness, helper di steering/abort dei run attivi, helper di bridge degli strumenti OpenClaw e utility per risultati dei tentativi | + | `plugin-sdk/provider-zai-endpoint` | Helper di rilevamento degli endpoint Z.A.I | | `plugin-sdk/infra-runtime` | Helper per eventi di sistema/Heartbeat | - | `plugin-sdk/collection-runtime` | Piccoli helper per cache bounded | + | `plugin-sdk/collection-runtime` | Piccoli helper di cache limitata | | `plugin-sdk/diagnostic-runtime` | Helper per flag ed eventi diagnostici | | `plugin-sdk/error-runtime` | Grafo degli errori, formattazione, helper condivisi di classificazione degli errori, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helper per fetch wrapped, proxy e lookup pinned | - | `plugin-sdk/runtime-fetch` | Fetch runtime consapevole del dispatcher senza import di proxy/fetch protetto | - | `plugin-sdk/response-limit-runtime` | Lettore bounded del body della risposta senza l'ampia superficie media runtime | - | `plugin-sdk/session-binding-runtime` | Stato corrente del binding della conversazione senza routing dei binding configurati o store di pairing | - | `plugin-sdk/session-store-runtime` | Helper di lettura dello session-store senza import ampi di scritture/manutenzione della configurazione | - | `plugin-sdk/context-visibility-runtime` | Risoluzione della visibilità del contesto e filtraggio del contesto supplementare senza import ampi di config/sicurezza | - | `plugin-sdk/string-coerce-runtime` | Helper ristretti di coercizione e normalizzazione di record/string primitive senza import markdown/logging | + | `plugin-sdk/fetch-runtime` | Helper per fetch wrapper, proxy e lookup fissato | + | `plugin-sdk/runtime-fetch` | Fetch runtime consapevole del dispatcher senza importazioni di proxy/fetch protetto | + | `plugin-sdk/response-limit-runtime` | Lettore limitato del body della risposta senza la più ampia surface runtime dei media | + | `plugin-sdk/session-binding-runtime` | Stato corrente del binding della conversazione senza routing di binding configurato o store di pairing | + | `plugin-sdk/session-store-runtime` | Helper di lettura dello store delle sessioni senza importazioni ampie di scritture/manutenzione della configurazione | + | `plugin-sdk/context-visibility-runtime` | Risoluzione della visibilità del contesto e filtro del contesto supplementare senza importazioni ampie di configurazione/sicurezza | + | `plugin-sdk/string-coerce-runtime` | Helper ristretti di coercizione e normalizzazione di record/stringhe primitive senza importazioni di markdown/logging | | `plugin-sdk/host-runtime` | Helper di normalizzazione per hostname e host SCP | - | `plugin-sdk/retry-runtime` | Helper per configurazione retry e runner retry | - | `plugin-sdk/agent-runtime` | Helper per dir/identità/workspace dell'agente | - | `plugin-sdk/directory-runtime` | Query/dedup di directory supportate da config | + | `plugin-sdk/retry-runtime` | Helper per configurazione ed esecuzione dei retry | + | `plugin-sdk/agent-runtime` | Helper per directory/identità/workspace dell'agente | + | `plugin-sdk/directory-runtime` | Query/dedup di directory supportata dalla configurazione | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Subpath | Key exports | + + | Sottopercorso | Esportazioni chiave | | --- | --- | - | `plugin-sdk/media-runtime` | Helper condivisi per fetch/transform/store dei media più builder di payload media | + | `plugin-sdk/media-runtime` | Helper condivisi per fetch/trasformazione/store dei media più builder del payload dei media | | `plugin-sdk/media-generation-runtime` | Helper condivisi per failover della generazione media, selezione dei candidati e messaggistica per modello mancante | - | `plugin-sdk/media-understanding` | Tipi di provider per media understanding più esportazioni helper lato provider per immagini/audio | - | `plugin-sdk/text-runtime` | Helper condivisi per testo/markdown/logging come rimozione del testo visibile all'assistant, helper per rendering/chunking/tabella Markdown, helper di redazione, helper per directive-tag e utility per testo sicuro | - | `plugin-sdk/text-chunking` | Helper per il chunking del testo outbound | - | `plugin-sdk/speech` | Tipi di provider speech più helper lato provider per directive, registry e validazione | - | `plugin-sdk/speech-core` | Tipi condivisi di provider speech, registry, directive e helper di normalizzazione | - | `plugin-sdk/realtime-transcription` | Tipi di provider per trascrizione realtime e helper di registry | - | `plugin-sdk/realtime-voice` | Tipi di provider per voce realtime e helper di registry | + | `plugin-sdk/media-understanding` | Tipi di provider per comprensione dei media più esportazioni helper lato provider per immagini/audio | + | `plugin-sdk/text-runtime` | Helper condivisi per testo/Markdown/logging come rimozione del testo visibile all'assistente, helper di render/chunking/tabella Markdown, helper di redazione, helper per tag di direttiva e utility di testo sicuro | + | `plugin-sdk/text-chunking` | Helper per chunking del testo outbound | + | `plugin-sdk/speech` | Tipi di provider speech più helper lato provider per direttive, registro e validazione | + | `plugin-sdk/speech-core` | Tipi condivisi di provider speech, helper per registro, direttive e normalizzazione | + | `plugin-sdk/realtime-transcription` | Tipi di provider per trascrizione in tempo reale e helper di registro | + | `plugin-sdk/realtime-voice` | Tipi di provider voce in tempo reale e helper di registro | | `plugin-sdk/image-generation` | Tipi di provider per generazione di immagini | - | `plugin-sdk/image-generation-core` | Tipi condivisi per generazione di immagini, helper per failover, auth e registry | - | `plugin-sdk/music-generation` | Tipi di provider/request/result per generazione musicale | - | `plugin-sdk/music-generation-core` | Tipi condivisi per generazione musicale, helper di failover, lookup provider e parsing di model-ref | - | `plugin-sdk/video-generation` | Tipi di provider/request/result per generazione video | - | `plugin-sdk/video-generation-core` | Tipi condivisi per generazione video, helper di failover, lookup provider e parsing di model-ref | - | `plugin-sdk/webhook-targets` | Registry dei target Webhook e helper di installazione delle route | + | `plugin-sdk/image-generation-core` | Tipi condivisi per generazione di immagini, helper per failover, autenticazione e registro | + | `plugin-sdk/music-generation` | Tipi provider/request/result per generazione musicale | + | `plugin-sdk/music-generation-core` | Tipi condivisi per generazione musicale, helper per failover, lookup del provider e parsing del riferimento modello | + | `plugin-sdk/video-generation` | Tipi provider/request/result per generazione video | + | `plugin-sdk/video-generation-core` | Tipi condivisi per generazione video, helper per failover, lookup del provider e parsing del riferimento modello | + | `plugin-sdk/webhook-targets` | Registro dei target Webhook e helper di installazione delle route | | `plugin-sdk/webhook-path` | Helper di normalizzazione del percorso Webhook | - | `plugin-sdk/web-media` | Helper condivisi per il caricamento di media remoti/locali | - | `plugin-sdk/zod` | `zod` riesportato per i consumer dell'SDK Plugin | + | `plugin-sdk/web-media` | Helper condivisi per caricamento di media remoti/locali | + | `plugin-sdk/zod` | `zod` riesportato per i consumer dell'SDK del Plugin | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - | Subpath | Key exports | + + | Sottopercorso | Esportazioni chiave | | --- | --- | - | `plugin-sdk/memory-core` | Superficie helper bundled memory-core per helper di manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Facade runtime per indice/ricerca Memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Esportazioni del foundation engine dell'host Memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Contratti embedding dell'host Memory, accesso al registry, provider locale e helper batch/remoti generici | - | `plugin-sdk/memory-core-host-engine-qmd` | Esportazioni del motore QMD dell'host Memory | - | `plugin-sdk/memory-core-host-engine-storage` | Esportazioni del motore di storage dell'host Memory | - | `plugin-sdk/memory-core-host-multimodal` | Helper multimodali dell'host Memory | - | `plugin-sdk/memory-core-host-query` | Helper di query dell'host Memory | - | `plugin-sdk/memory-core-host-secret` | Helper secret dell'host Memory | - | `plugin-sdk/memory-core-host-events` | Helper del journal eventi dell'host Memory | - | `plugin-sdk/memory-core-host-status` | Helper di stato dell'host Memory | - | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI dell'host Memory | - | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core dell'host Memory | - | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime dell'host Memory | - | `plugin-sdk/memory-host-core` | Alias neutrale rispetto al vendor per gli helper runtime core dell'host Memory | - | `plugin-sdk/memory-host-events` | Alias neutrale rispetto al vendor per gli helper del journal eventi dell'host Memory | - | `plugin-sdk/memory-host-files` | Alias neutrale rispetto al vendor per gli helper file/runtime dell'host Memory | - | `plugin-sdk/memory-host-markdown` | Helper condivisi di managed-markdown per Plugin adiacenti a Memory | + | `plugin-sdk/memory-core` | Surface helper `memory-core` inclusa per helper di manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Facade runtime per indice/ricerca della memoria | + | `plugin-sdk/memory-core-host-engine-foundation` | Esportazioni del motore foundation dell'host della memoria | + | `plugin-sdk/memory-core-host-engine-embeddings` | Contratti di embedding dell'host della memoria, accesso al registro, provider locale e helper generici batch/remoti | + | `plugin-sdk/memory-core-host-engine-qmd` | Esportazioni del motore QMD dell'host della memoria | + | `plugin-sdk/memory-core-host-engine-storage` | Esportazioni del motore di storage dell'host della memoria | + | `plugin-sdk/memory-core-host-multimodal` | Helper multimodali dell'host della memoria | + | `plugin-sdk/memory-core-host-query` | Helper di query dell'host della memoria | + | `plugin-sdk/memory-core-host-secret` | Helper dei secret dell'host della memoria | + | `plugin-sdk/memory-core-host-events` | Helper del journal eventi dell'host della memoria | + | `plugin-sdk/memory-core-host-status` | Helper di stato dell'host della memoria | + | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI dell'host della memoria | + | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core dell'host della memoria | + | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime dell'host della memoria | + | `plugin-sdk/memory-host-core` | Alias neutrale rispetto al vendor per gli helper runtime core dell'host della memoria | + | `plugin-sdk/memory-host-events` | Alias neutrale rispetto al vendor per gli helper del journal eventi dell'host della memoria | + | `plugin-sdk/memory-host-files` | Alias neutrale rispetto al vendor per gli helper file/runtime dell'host della memoria | + | `plugin-sdk/memory-host-markdown` | Helper condivisi di managed-markdown per plugin adiacenti alla memoria | | `plugin-sdk/memory-host-search` | Facade runtime di Active Memory per l'accesso al search-manager | - | `plugin-sdk/memory-host-status` | Alias neutrale rispetto al vendor per gli helper di stato dell'host Memory | - | `plugin-sdk/memory-lancedb` | Superficie helper bundled memory-lancedb | + | `plugin-sdk/memory-host-status` | Alias neutrale rispetto al vendor per gli helper di stato dell'host della memoria | + | `plugin-sdk/memory-lancedb` | Surface helper `memory-lancedb` inclusa | - - | Family | Current subpaths | Intended use | + + | Famiglia | Sottopercorsi attuali | Uso previsto | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper di supporto del Plugin browser bundled (`browser-support` resta il barrel di compatibilità) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/runtime Matrix bundled | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime LINE bundled | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper IRC bundled | - | Helper specifici del canale | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam di compatibilità/helper dei canali bundled | - | Helper specifici di auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper di funzionalità/plugin bundled; `plugin-sdk/github-copilot-token` esporta attualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper di supporto del Plugin browser incluso (`browser-support` resta il barrel di compatibilità) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Surface helper/runtime Matrix inclusa | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/runtime LINE inclusa | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Surface helper IRC inclusa | + | Helper specifici del canale | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam helper/di compatibilità dei canali inclusi | + | Helper specifici di auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper di feature/plugin inclusi; `plugin-sdk/github-copilot-token` attualmente esporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | @@ -323,59 +323,68 @@ non ne promuova esplicitamente uno come pubblico. La callback `register(api)` riceve un oggetto `OpenClawPluginApi` con questi metodi: -### Registrazione delle capacità +### Registrazione delle capability -| Method | What it registers | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Inferenza testuale (LLM) | -| `api.registerAgentHarness(...)` | Esecutore sperimentale di agente di basso livello | -| `api.registerCliBackend(...)` | Backend CLI locale per inferenza | -| `api.registerChannel(...)` | Canale di messaggistica | -| `api.registerSpeechProvider(...)` | Sintesi text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Trascrizione realtime in streaming | +| Metodo | Cosa registra | +| ------------------------------------------------ | -------------------------------------- | +| `api.registerProvider(...)` | Inferenza di testo (LLM) | +| `api.registerAgentHarness(...)` | Esecutore sperimentale di agenti di basso livello | +| `api.registerCliBackend(...)` | Backend di inferenza CLI locale | +| `api.registerChannel(...)` | Canale di messaggistica | +| `api.registerSpeechProvider(...)` | Sintesi text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Trascrizione realtime in streaming | | `api.registerRealtimeVoiceProvider(...)` | Sessioni vocali realtime duplex | -| `api.registerMediaUnderstandingProvider(...)` | Analisi di immagini/audio/video | -| `api.registerImageGenerationProvider(...)` | Generazione di immagini | -| `api.registerMusicGenerationProvider(...)` | Generazione musicale | +| `api.registerMediaUnderstandingProvider(...)` | Analisi di immagini/audio/video | +| `api.registerImageGenerationProvider(...)` | Generazione di immagini | +| `api.registerMusicGenerationProvider(...)` | Generazione musicale | | `api.registerVideoGenerationProvider(...)` | Generazione video | -| `api.registerWebFetchProvider(...)` | Provider di web fetch / scraping | +| `api.registerWebFetchProvider(...)` | Provider di web fetch / scraping | | `api.registerWebSearchProvider(...)` | Ricerca web | -### Tool e comandi +### Strumenti e comandi -| Method | What it registers | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Tool agente (obbligatorio oppure `{ optional: true }`) | -| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) | +| Metodo | Cosa registra | +| ------------------------------- | -------------------------------------------- | +| `api.registerTool(tool, opts?)` | Strumento agente (obbligatorio o `{ optional: true }`) | +| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) | ### Infrastruttura -| Method | What it registers | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook evento | -| `api.registerHttpRoute(params)` | Endpoint HTTP del Gateway | -| `api.registerGatewayMethod(name, handler)` | Metodo RPC del Gateway | -| `api.registerCli(registrar, opts?)` | Sottocomando CLI | -| `api.registerService(service)` | Servizio in background | -| `api.registerInteractiveHandler(registration)` | Handler interattivo | -| `api.registerMemoryPromptSupplement(builder)` | Sezione prompt additiva adiacente a Memory | -| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additivo per ricerca/lettura Memory | +| Metodo | Cosa registra | +| ----------------------------------------------- | ---------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook evento | +| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway | +| `api.registerGatewayMethod(name, handler)` | Metodo RPC Gateway | +| `api.registerCli(registrar, opts?)` | Sottocomando CLI | +| `api.registerService(service)` | Servizio in background | +| `api.registerInteractiveHandler(registration)` | Gestore interattivo | +| `api.registerEmbeddedExtensionFactory(factory)` | Factory di estensione embedded-runner Pi | +| `api.registerMemoryPromptSupplement(builder)` | Sezione di prompt additiva adiacente alla memoria | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additivo di ricerca/lettura della memoria | I namespace admin core riservati (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) restano sempre `operator.admin`, anche se un Plugin prova ad assegnare -uno scope più ristretto a un metodo gateway. Preferisci prefissi specifici del Plugin per -i metodi posseduti dal Plugin. +`update.*`) restano sempre `operator.admin`, anche se un plugin prova ad assegnare uno +scope di metodo gateway più ristretto. Preferisci prefissi specifici del plugin per +i metodi gestiti dal plugin. + +Usa `api.registerEmbeddedExtensionFactory(...)` quando un plugin richiede timing di eventi +nativo Pi durante esecuzioni embedded di OpenClaw, per esempio riscritture asincrone di +`tool_result` che devono avvenire prima che venga emesso il messaggio finale del risultato del tool. +Oggi questo è un seam dei plugin inclusi: solo i plugin inclusi possono registrarne uno, e +devono dichiarare `contracts.embeddedExtensionFactories: ["pi"]` in +`openclaw.plugin.json`. Mantieni i normali hook dei plugin OpenClaw per tutto ciò +che non richiede quel seam di livello più basso. ### Metadati di registrazione CLI `api.registerCli(registrar, opts?)` accetta due tipi di metadati di primo livello: -- `commands`: root di comandi espliciti posseduti dal registrar -- `descriptors`: descrittori di comandi a tempo di parsing usati per help della CLI root, - instradamento e registrazione CLI lazy del Plugin +- `commands`: root di comando esplicite gestite dal registrar +- `descriptors`: descrittori di comando a tempo di parsing usati per help della CLI root, + instradamento e registrazione lazy della CLI del plugin -Se vuoi che un comando Plugin resti caricato lazy nel normale percorso della CLI root, -fornisci `descriptors` che coprano ogni root di comando di primo livello esposto da quel +Se vuoi che un comando del plugin resti lazy-loaded nel normale percorso della CLI root, +fornisci `descriptors` che coprano ogni root di comando di primo livello esposta da quel registrar. ```typescript @@ -402,127 +411,127 @@ placeholder supportati da descriptor per il caricamento lazy a tempo di parsing. ### Registrazione del backend CLI -`api.registerCliBackend(...)` permette a un Plugin di possedere la configurazione predefinita per un +`api.registerCliBackend(...)` permette a un plugin di gestire la configurazione predefinita per un backend CLI AI locale come `codex-cli`. -- Il backend `id` diventa il prefisso provider nei riferimenti ai modelli come `codex-cli/gpt-5`. +- L'`id` del backend diventa il prefisso provider nei riferimenti modello come `codex-cli/gpt-5`. - La `config` del backend usa la stessa forma di `agents.defaults.cliBackends.`. -- La configurazione utente continua ad avere priorità. OpenClaw unisce `agents.defaults.cliBackends.` sopra il - valore predefinito del Plugin prima di eseguire la CLI. +- La configurazione utente continua ad avere la precedenza. OpenClaw unisce `agents.defaults.cliBackends.` sopra il + valore predefinito del plugin prima di eseguire la CLI. - Usa `normalizeConfig` quando un backend richiede riscritture di compatibilità dopo il merge - (per esempio la normalizzazione di vecchie forme di flag). + (per esempio per normalizzare vecchie forme di flag). ### Slot esclusivi -| Method | What it registers | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (uno attivo alla volta). La callback `assemble()` riceve `availableTools` e `citationsMode` così il motore può adattare le aggiunte al prompt. | -| `api.registerMemoryCapability(capability)` | Capacità Memory unificata | -| `api.registerMemoryPromptSection(builder)` | Builder della sezione prompt Memory | -| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush Memory | -| `api.registerMemoryRuntime(runtime)` | Adapter runtime Memory | +| Metodo | Cosa registra | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `api.registerContextEngine(id, factory)` | Motore di contesto (uno attivo alla volta). La callback `assemble()` riceve `availableTools` e `citationsMode` così il motore può adattare le aggiunte al prompt. | +| `api.registerMemoryCapability(capability)` | Capability di memoria unificata | +| `api.registerMemoryPromptSection(builder)` | Builder della sezione di prompt della memoria | +| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush della memoria | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime della memoria | -### Adapter di embedding Memory +### Adapter di embedding della memoria -| Method | What it registers | +| Metodo | Cosa registra | | ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding Memory per il Plugin attivo | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding della memoria per il plugin attivo | -- `registerMemoryCapability` è l'API preferita del Plugin Memory esclusivo. +- `registerMemoryCapability` è l'API preferita del plugin di memoria esclusivo. - `registerMemoryCapability` può anche esporre `publicArtifacts.listArtifacts(...)` - così i Plugin companion possono consumare artifact Memory esportati tramite + così i plugin companion possono consumare gli artifact di memoria esportati tramite `openclaw/plugin-sdk/memory-host-core` invece di entrare nel layout privato - di uno specifico Plugin Memory. + di uno specifico plugin di memoria. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` e - `registerMemoryRuntime` sono API legacy-compatibili del Plugin Memory esclusivo. -- `registerMemoryEmbeddingProvider` permette al Plugin Memory attivo di registrare uno - o più id di adapter embedding (per esempio `openai`, `gemini` o un id personalizzato definito dal Plugin). + `registerMemoryRuntime` sono API legacy-compatibili del plugin di memoria esclusivo. +- `registerMemoryEmbeddingProvider` permette al plugin di memoria attivo di registrare uno + o più id adapter di embedding (per esempio `openai`, `gemini` o un id personalizzato definito dal plugin). - La configurazione utente come `agents.defaults.memorySearch.provider` e - `agents.defaults.memorySearch.fallback` viene risolta rispetto a questi id di adapter registrati. + `agents.defaults.memorySearch.fallback` viene risolta rispetto a quegli id adapter registrati. -### Eventi e ciclo di vita +### Eventi e lifecycle -| Method | What it does | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Hook di ciclo di vita tipizzato | +| Metodo | Cosa fa | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Hook di lifecycle tipizzato | | `api.onConversationBindingResolved(handler)` | Callback di binding della conversazione | -### Semantica decisionale degli hook +### Semantica delle decisioni degli hook - `before_tool_call`: restituire `{ block: true }` è terminale. Una volta che un handler lo imposta, gli handler con priorità inferiore vengono saltati. -- `before_tool_call`: restituire `{ block: false }` viene trattato come nessuna decisione (uguale a omettere `block`), non come override. +- `before_tool_call`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override. - `before_install`: restituire `{ block: true }` è terminale. Una volta che un handler lo imposta, gli handler con priorità inferiore vengono saltati. -- `before_install`: restituire `{ block: false }` viene trattato come nessuna decisione (uguale a omettere `block`), non come override. +- `before_install`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override. - `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Una volta che un handler rivendica il dispatch, gli handler con priorità inferiore e il percorso predefinito di dispatch del modello vengono saltati. - `message_sending`: restituire `{ cancel: true }` è terminale. Una volta che un handler lo imposta, gli handler con priorità inferiore vengono saltati. -- `message_sending`: restituire `{ cancel: false }` viene trattato come nessuna decisione (uguale a omettere `cancel`), non come override. +- `message_sending`: restituire `{ cancel: false }` viene trattato come nessuna decisione (come omettere `cancel`), non come override. ### Campi dell'oggetto API -| Field | Type | Description | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID del Plugin | -| `api.name` | `string` | Nome visualizzato | -| `api.version` | `string?` | Versione del Plugin (facoltativa) | -| `api.description` | `string?` | Descrizione del Plugin (facoltativa) | -| `api.source` | `string` | Percorso sorgente del Plugin | -| `api.rootDir` | `string?` | Directory root del Plugin (facoltativa) | -| `api.config` | `OpenClawConfig` | Snapshot della configurazione corrente (snapshot runtime in-memory attivo quando disponibile) | -| `api.pluginConfig` | `Record` | Configurazione specifica del Plugin da `plugins.entries..config` | +| Campo | Tipo | Descrizione | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | +| `api.id` | `string` | Id del Plugin | +| `api.name` | `string` | Nome visualizzato | +| `api.version` | `string?` | Versione del Plugin (facoltativa) | +| `api.description` | `string?` | Descrizione del Plugin (facoltativa) | +| `api.source` | `string` | Percorso sorgente del Plugin | +| `api.rootDir` | `string?` | Directory radice del Plugin (facoltativa) | +| `api.config` | `OpenClawConfig` | Snapshot della configurazione corrente (snapshot runtime in memoria attivo quando disponibile) | +| `api.pluginConfig` | `Record` | Configurazione specifica del Plugin da `plugins.entries..config` | | `api.runtime` | `PluginRuntime` | [Helper runtime](/it/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger con ambito (`debug`, `info`, `warn`, `error`) | +| `api.logger` | `PluginLogger` | Logger con scope (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/setup pre-entry completa | -| `api.resolvePath(input)` | `(string) => string` | Risolve il percorso relativo alla root del Plugin | +| `api.resolvePath(input)` | `(string) => string` | Risolve un percorso relativo alla radice del Plugin | ## Convenzione dei moduli interni -All'interno del tuo Plugin, usa file barrel locali per gli import interni: +All'interno del tuo Plugin, usa file barrel locali per le importazioni interne: ``` my-plugin/ api.ts # Esportazioni pubbliche per consumer esterni runtime-api.ts # Esportazioni runtime solo interne - index.ts # Punto di ingresso del Plugin - setup-entry.ts # Entry leggera solo setup (facoltativa) + index.ts # Entry point del Plugin + setup-entry.ts # Entry leggera solo per setup (facoltativa) ``` Non importare mai il tuo stesso Plugin tramite `openclaw/plugin-sdk/` - dal codice di produzione. Instrada gli import interni tramite `./api.ts` oppure + dal codice di produzione. Instrada le importazioni interne tramite `./api.ts` o `./runtime-api.ts`. Il percorso SDK è solo il contratto esterno. -Le superfici pubbliche dei Plugin bundled caricate tramite facade (`api.ts`, `runtime-api.ts`, +Le surface pubbliche dei plugin inclusi caricate tramite facade (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` e file di entry pubblici simili) ora preferiscono lo snapshot della configurazione runtime attiva quando OpenClaw è già in esecuzione. Se non esiste ancora uno snapshot runtime, usano come fallback il file di configurazione risolto su disco. -I Plugin provider possono anche esporre un barrel di contratto locale al Plugin quando un -helper è intenzionalmente specifico del provider e non appartiene ancora a un subpath SDK generico. -Esempio bundled attuale: il provider Anthropic mantiene i suoi helper di stream Claude +I plugin provider possono anche esporre un barrel di contratto locale al plugin e ristretto quando un +helper è intenzionalmente specifico del provider e non appartiene ancora a un sottopercorso SDK +generico. Esempio incluso attuale: il provider Anthropic mantiene i propri helper di stream Claude nel proprio seam pubblico `api.ts` / `contract-api.ts` invece di -promuovere la logica Anthropic beta-header e `service_tier` in un contratto generico -`plugin-sdk/*`. +promuovere la logica di header beta Anthropic e `service_tier` in un contratto +generico `plugin-sdk/*`. -Altri esempi bundled attuali: +Altri esempi inclusi attuali: -- `@openclaw/openai-provider`: `api.ts` esporta builder di provider, - helper di modelli predefiniti e builder di provider realtime +- `@openclaw/openai-provider`: `api.ts` esporta builder del provider, + helper per modelli predefiniti e builder di provider realtime - `@openclaw/openrouter-provider`: `api.ts` esporta il builder del provider più helper di onboarding/configurazione - Il codice di produzione delle estensioni dovrebbe anche evitare import `openclaw/plugin-sdk/`. - Se un helper è davvero condiviso, promuovilo a un subpath SDK neutrale + Il codice di produzione delle estensioni dovrebbe evitare anche importazioni da `openclaw/plugin-sdk/`. + Se un helper è davvero condiviso, promuovilo a un sottopercorso SDK neutrale come `openclaw/plugin-sdk/speech`, `.../provider-model-shared` o un'altra - superficie orientata alla capacità invece di accoppiare due Plugin. + surface orientata alle capability invece di accoppiare due plugin tra loro. ## Correlati -- [Punti di ingresso](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry` e `defineChannelPluginEntry` -- [Helper runtime](/it/plugins/sdk-runtime) — riferimento completo dello spazio dei nomi `api.runtime` -- [Setup e configurazione](/it/plugins/sdk-setup) — packaging, manifest, schemi di configurazione -- [Testing](/it/plugins/sdk-testing) — utility di test e regole lint -- [Migrazione SDK](/it/plugins/sdk-migration) — migrazione dalle superfici deprecate -- [Interni del Plugin](/it/plugins/architecture) — architettura approfondita e modello di capacità +- [Entry Points](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry` e `defineChannelPluginEntry` +- [Runtime Helpers](/it/plugins/sdk-runtime) — riferimento completo del namespace `api.runtime` +- [Setup and Config](/it/plugins/sdk-setup) — packaging, manifest, schemi di configurazione +- [Testing](/it/plugins/sdk-testing) — utility di test e regole di lint +- [SDK Migration](/it/plugins/sdk-migration) — migrazione dalle surface deprecate +- [Plugin Internals](/it/plugins/architecture) — architettura approfondita e modello delle capability diff --git a/docs/it/providers/ollama.md b/docs/it/providers/ollama.md index 21f8f6740..e2cdc0dea 100644 --- a/docs/it/providers/ollama.md +++ b/docs/it/providers/ollama.md @@ -1,15 +1,15 @@ --- read_when: - Vuoi eseguire OpenClaw con modelli cloud o locali tramite Ollama - - Hai bisogno di indicazioni per la configurazione e il setup di Ollama - - Vuoi modelli Ollama con capacità visive per la comprensione delle immagini + - Hai bisogno di indicazioni per la configurazione e l'impostazione di Ollama + - Vuoi modelli vision di Ollama per la comprensione delle immagini summary: Esegui OpenClaw con Ollama (modelli cloud e locali) title: Ollama x-i18n: - generated_at: "2026-04-22T04:27:00Z" + generated_at: "2026-04-22T08:20:52Z" model: gpt-5.4 provider: openai - source_hash: 32623b6523f22930a5987fb22d2074f1e9bb274cc01ae1ad1837825cc04ec179 + source_hash: 704beed3bf988d6c2ad50b2a1533f6dcef655e44b34f23104827d2acb71b8655 source_path: providers/ollama.md workflow: 15 --- @@ -19,7 +19,7 @@ x-i18n: OpenClaw si integra con l'API nativa di Ollama (`/api/chat`) per modelli cloud ospitati e server Ollama locali/self-hosted. Puoi usare Ollama in tre modalità: `Cloud + Local` tramite un host Ollama raggiungibile, `Cloud only` contro `https://ollama.com`, oppure `Local only` contro un host Ollama raggiungibile. -**Utenti Ollama remoti**: non usare l'URL OpenAI-compatibile `/v1` (`http://host:11434/v1`) con OpenClaw. Questo interrompe il tool calling e i modelli potrebbero emettere JSON dei tool grezzi come testo semplice. Usa invece l'URL dell'API nativa di Ollama: `baseUrl: "http://host:11434"` (senza `/v1`). +**Utenti di Ollama remoto**: non usare l'URL compatibile OpenAI `/v1` (`http://host:11434/v1`) con OpenClaw. Questo interrompe la chiamata degli strumenti e i modelli potrebbero produrre JSON grezzo degli strumenti come testo normale. Usa invece l'URL dell'API nativa di Ollama: `baseUrl: "http://host:11434"` (senza `/v1`). ## Per iniziare @@ -44,7 +44,7 @@ Scegli il metodo e la modalità di configurazione che preferisci. - **Local only** — solo modelli locali - `Cloud only` richiede `OLLAMA_API_KEY` e suggerisce valori predefiniti cloud ospitati. `Cloud + Local` e `Local only` chiedono un URL base Ollama, rilevano i modelli disponibili e scaricano automaticamente il modello locale selezionato se non è ancora disponibile. `Cloud + Local` verifica anche se quell'host Ollama ha effettuato l'accesso per l'uso cloud. + `Cloud only` richiede `OLLAMA_API_KEY` e suggerisce impostazioni predefinite cloud ospitate. `Cloud + Local` e `Local only` richiedono un URL base Ollama, individuano i modelli disponibili e scaricano automaticamente il modello locale selezionato se non è ancora disponibile. `Cloud + Local` controlla anche se quell'host Ollama ha effettuato l'accesso per l'uso cloud. ```bash @@ -61,7 +61,7 @@ Scegli il metodo e la modalità di configurazione che preferisci. --accept-risk ``` - Facoltativamente specifica un URL base o un modello personalizzato: + Facoltativamente, specifica un URL base o un modello personalizzato: ```bash openclaw onboard --non-interactive \ @@ -74,12 +74,12 @@ Scegli il metodo e la modalità di configurazione che preferisci. - **Ideale per:** pieno controllo sulla configurazione cloud o locale. + **Ideale per:** controllo completo sulla configurazione cloud o locale. - **Cloud + Local**: installa Ollama, accedi con `ollama signin` e instrada le richieste cloud tramite quell'host - - **Cloud only**: usa `https://ollama.com` con `OLLAMA_API_KEY` + - **Cloud only**: usa `https://ollama.com` con un `OLLAMA_API_KEY` - **Local only**: installa Ollama da [ollama.com/download](https://ollama.com/download) @@ -105,7 +105,7 @@ Scegli il metodo e la modalità di configurazione che preferisci. openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY" ``` - + ```bash openclaw models list openclaw models set ollama/gemma4 @@ -134,9 +134,9 @@ Scegli il metodo e la modalità di configurazione che preferisci. `Cloud + Local` usa un host Ollama raggiungibile come punto di controllo sia per i modelli locali sia per quelli cloud. Questo è il flusso ibrido preferito da Ollama. - Usa **Cloud + Local** durante la configurazione. OpenClaw richiede l'URL base di Ollama, rileva i modelli locali da quell'host e verifica se l'host ha effettuato l'accesso per l'accesso cloud con `ollama signin`. Quando l'host ha effettuato l'accesso, OpenClaw suggerisce anche valori predefiniti cloud ospitati come `kimi-k2.5:cloud`, `minimax-m2.7:cloud` e `glm-5.1:cloud`. + Usa **Cloud + Local** durante la configurazione. OpenClaw richiede l'URL base di Ollama, individua i modelli locali da quell'host e controlla se l'host ha effettuato l'accesso per l'accesso cloud con `ollama signin`. Quando l'host ha effettuato l'accesso, OpenClaw suggerisce anche impostazioni predefinite cloud ospitate come `kimi-k2.5:cloud`, `minimax-m2.7:cloud` e `glm-5.1:cloud`. - Se l'host non ha ancora effettuato l'accesso, OpenClaw mantiene la configurazione solo locale finché non esegui `ollama signin`. + Se l'host non ha ancora effettuato l'accesso, OpenClaw mantiene la configurazione in modalità solo locale finché non esegui `ollama signin`. @@ -145,30 +145,30 @@ Scegli il metodo e la modalità di configurazione che preferisci. Usa **Cloud only** durante la configurazione. OpenClaw richiede `OLLAMA_API_KEY`, imposta `baseUrl: "https://ollama.com"` e inizializza l'elenco dei modelli cloud ospitati. Questo percorso **non** richiede un server Ollama locale né `ollama signin`. - L'elenco dei modelli cloud mostrato durante `openclaw onboard` viene popolato in tempo reale da `https://ollama.com/api/tags`, con limite di 500 voci, quindi il selettore riflette il catalogo ospitato corrente invece di un elenco statico. Se `ollama.com` non è raggiungibile o non restituisce modelli al momento della configurazione, OpenClaw torna ai precedenti suggerimenti hardcoded così che l'onboarding possa comunque completarsi. + L'elenco dei modelli cloud mostrato durante `openclaw onboard` viene popolato in tempo reale da `https://ollama.com/api/tags`, con un limite di 500 voci, in modo che il selettore rifletta il catalogo ospitato corrente anziché un seed statico. Se `ollama.com` non è raggiungibile o non restituisce modelli al momento della configurazione, OpenClaw torna ai suggerimenti hardcoded precedenti così l'onboarding può comunque completarsi. - In modalità solo locale, OpenClaw rileva i modelli dall'istanza Ollama configurata. Questo percorso è pensato per server Ollama locali o self-hosted. + In modalità solo locale, OpenClaw individua i modelli dall'istanza Ollama configurata. Questo percorso è pensato per server Ollama locali o self-hosted. - OpenClaw attualmente suggerisce `gemma4` come valore predefinito locale. + OpenClaw al momento suggerisce `gemma4` come valore predefinito locale. -## Rilevamento dei modelli (provider implicito) +## Individuazione dei modelli (provider implicito) -Quando imposti `OLLAMA_API_KEY` (o un profilo auth) e **non** definisci `models.providers.ollama`, OpenClaw rileva i modelli dall'istanza Ollama locale su `http://127.0.0.1:11434`. +Quando imposti `OLLAMA_API_KEY` (o un profilo di autenticazione) e **non** definisci `models.providers.ollama`, OpenClaw individua i modelli dall'istanza Ollama locale su `http://127.0.0.1:11434`. -| Comportamento | Dettaglio | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Query del catalogo | Interroga `/api/tags` | -| Rilevamento capacità | Usa lookup best-effort su `/api/show` per leggere `contextWindow` e rilevare le capacità (inclusa la visione) | -| Modelli visivi | I modelli con capacità `vision` riportata da `/api/show` vengono contrassegnati come compatibili con immagini (`input: ["text", "image"]`), quindi OpenClaw inietta automaticamente le immagini nel prompt | -| Rilevamento reasoning | Contrassegna `reasoning` con un'euristica basata sul nome del modello (`r1`, `reasoning`, `think`) | -| Limiti token | Imposta `maxTokens` al limite massimo di token predefinito di Ollama usato da OpenClaw | -| Costi | Imposta tutti i costi a `0` | +| Comportamento | Dettaglio | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Query del catalogo | Interroga `/api/tags` | +| Rilevamento capacità | Usa ricerche `/api/show` best-effort per leggere `contextWindow` e rilevare le capacità (inclusa la vision) | +| Modelli vision | I modelli con capacità `vision` riportata da `/api/show` sono contrassegnati come compatibili con immagini (`input: ["text", "image"]`), quindi OpenClaw inserisce automaticamente le immagini nel prompt | +| Rilevamento reasoning | Contrassegna `reasoning` con un'euristica sul nome del modello (`r1`, `reasoning`, `think`) | +| Limiti di token | Imposta `maxTokens` sul limite massimo di token predefinito di Ollama usato da OpenClaw | +| Costi | Imposta tutti i costi a `0` | Questo evita voci di modello manuali mantenendo il catalogo allineato con l'istanza Ollama locale. @@ -184,17 +184,17 @@ Per aggiungere un nuovo modello, basta scaricarlo con Ollama: ollama pull mistral ``` -Il nuovo modello verrà rilevato automaticamente e sarà disponibile per l'uso. +Il nuovo modello verrà individuato automaticamente e sarà disponibile per l'uso. -Se imposti esplicitamente `models.providers.ollama`, il rilevamento automatico viene saltato e devi definire manualmente i modelli. Vedi la sezione sulla configurazione esplicita qui sotto. +Se imposti esplicitamente `models.providers.ollama`, l'individuazione automatica viene saltata e devi definire i modelli manualmente. Vedi la sezione di configurazione esplicita qui sotto. -## Visione e descrizione delle immagini +## Vision e descrizione delle immagini -Il plugin Ollama incluso registra Ollama come provider di comprensione dei media con capacità immagine. Questo consente a OpenClaw di instradare richieste esplicite di descrizione delle immagini e valori predefiniti configurati del modello immagine tramite modelli visivi Ollama locali o ospitati. +Il plugin Ollama incluso registra Ollama come provider di comprensione dei media compatibile con le immagini. Questo permette a OpenClaw di instradare richieste esplicite di descrizione di immagini e i valori predefiniti configurati per i modelli di immagini tramite modelli vision Ollama locali o ospitati. -Per la visione locale, scarica un modello che supporti le immagini: +Per la vision locale, scarica un modello che supporti le immagini: ```bash ollama pull qwen2.5vl:7b @@ -210,7 +210,7 @@ openclaw infer image describe \ --json ``` -`--model` deve essere un riferimento completo ``. Quando è impostato, `openclaw infer image describe` esegue direttamente quel modello invece di saltare la descrizione perché il modello supporta la visione nativa. +`--model` deve essere un riferimento completo ``. Quando è impostato, `openclaw infer image describe` esegue direttamente quel modello invece di saltare la descrizione perché il modello supporta la vision nativa. Per rendere Ollama il modello predefinito di comprensione delle immagini per i media in ingresso, configura `agents.defaults.imageModel`: @@ -226,7 +226,7 @@ Per rendere Ollama il modello predefinito di comprensione delle immagini per i m } ``` -Se definisci manualmente `models.providers.ollama.models`, contrassegna i modelli visivi con supporto per input immagine: +Se definisci manualmente `models.providers.ollama.models`, contrassegna i modelli vision con il supporto per input immagine: ```json5 { @@ -238,26 +238,26 @@ Se definisci manualmente `models.providers.ollama.models`, contrassegna i modell } ``` -OpenClaw rifiuta richieste di descrizione delle immagini per modelli che non sono contrassegnati come compatibili con immagini. Con il rilevamento implicito, OpenClaw legge questa informazione da Ollama quando `/api/show` riporta una capacità vision. +OpenClaw rifiuta le richieste di descrizione delle immagini per i modelli che non sono contrassegnati come compatibili con le immagini. Con l'individuazione implicita, OpenClaw legge questa informazione da Ollama quando `/api/show` riporta una capacità vision. ## Configurazione - - Il percorso di abilitazione più semplice per solo locale avviene tramite variabile d'ambiente: + + Il percorso più semplice per abilitare la modalità solo locale è tramite variabile d'ambiente: ```bash export OLLAMA_API_KEY="ollama-local" ``` - Se `OLLAMA_API_KEY` è impostato, puoi omettere `apiKey` nella voce provider e OpenClaw lo compilerà per i controlli di disponibilità. + Se `OLLAMA_API_KEY` è impostato, puoi omettere `apiKey` nella voce del provider e OpenClaw lo compilerà per i controlli di disponibilità. - Usa la configurazione esplicita quando vuoi una configurazione cloud ospitata, Ollama viene eseguito su un altro host/porta, vuoi forzare specifiche finestre di contesto o elenchi di modelli, oppure vuoi definizioni di modelli completamente manuali. + Usa la configurazione esplicita quando vuoi una configurazione cloud ospitata, Ollama è in esecuzione su un altro host/porta, vuoi forzare specifiche finestre di contesto o elenchi di modelli, oppure vuoi definizioni dei modelli completamente manuali. ```json5 { @@ -287,7 +287,7 @@ OpenClaw rifiuta richieste di descrizione delle immagini per modelli che non son - Se Ollama è in esecuzione su un host o una porta diversi (la configurazione esplicita disabilita il rilevamento automatico, quindi definisci i modelli manualmente): + Se Ollama è in esecuzione su un host o una porta diversi (la configurazione esplicita disabilita l'individuazione automatica, quindi definisci i modelli manualmente): ```json5 { @@ -295,8 +295,8 @@ OpenClaw rifiuta richieste di descrizione delle immagini per modelli che non son providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // Nessun /v1 - usa l'URL dell'API nativa di Ollama - api: "ollama", // Impostalo esplicitamente per garantire il comportamento nativo di tool-calling + baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL + api: "ollama", // Set explicitly to guarantee native tool-calling behavior }, }, }, @@ -304,7 +304,7 @@ OpenClaw rifiuta richieste di descrizione delle immagini per modelli che non son ``` - Non aggiungere `/v1` all'URL. Il percorso `/v1` usa la modalità OpenAI-compatibile, in cui il tool calling non è affidabile. Usa l'URL base di Ollama senza suffisso di percorso. + Non aggiungere `/v1` all'URL. Il percorso `/v1` usa la modalità compatibile con OpenAI, in cui la chiamata degli strumenti non è affidabile. Usa l'URL base di Ollama senza un suffisso di percorso. @@ -327,15 +327,15 @@ Una volta configurato, tutti i tuoi modelli Ollama sono disponibili: } ``` -## Web Search di Ollama +## Ricerca Web Ollama OpenClaw supporta **Ollama Web Search** come provider `web_search` incluso. -| Proprietà | Dettaglio | -| ----------- | -------------------------------------------------------------------------------------------------------------------- | -| Host | Usa l'host Ollama configurato (`models.providers.ollama.baseUrl` se impostato, altrimenti `http://127.0.0.1:11434`) | -| Auth | Senza chiave | -| Requisito | Ollama deve essere in esecuzione e aver effettuato l'accesso con `ollama signin` | +| Proprietà | Dettaglio | +| ----------- | ---------------------------------------------------------------------------------------------------------------------- | +| Host | Usa l'host Ollama configurato (`models.providers.ollama.baseUrl` se impostato, altrimenti `http://127.0.0.1:11434`) | +| Auth | Senza chiave | +| Requisito | Ollama deve essere in esecuzione e con accesso effettuato tramite `ollama signin` | Scegli **Ollama Web Search** durante `openclaw onboard` o `openclaw configure --section web`, oppure imposta: @@ -360,10 +360,10 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear - **Il tool calling non è affidabile in modalità compatibile con OpenAI.** Usa questa modalità solo se ti serve il formato OpenAI per un proxy e non dipendi dal comportamento nativo del tool calling. + **La chiamata degli strumenti non è affidabile nella modalità compatibile con OpenAI.** Usa questa modalità solo se hai bisogno del formato OpenAI per un proxy e non dipendi dal comportamento nativo della chiamata degli strumenti. - Se invece hai bisogno di usare l'endpoint compatibile con OpenAI (per esempio dietro un proxy che supporta solo il formato OpenAI), imposta esplicitamente `api: "openai-completions"`: + Se invece hai bisogno di usare l'endpoint compatibile con OpenAI (per esempio, dietro un proxy che supporta solo il formato OpenAI), imposta esplicitamente `api: "openai-completions"`: ```json5 { @@ -372,7 +372,7 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear ollama: { baseUrl: "http://ollama-host:11434/v1", api: "openai-completions", - injectNumCtxForOpenAICompat: true, // predefinito: true + injectNumCtxForOpenAICompat: true, // default: true apiKey: "ollama-local", models: [...] } @@ -381,9 +381,9 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear } ``` - Questa modalità potrebbe non supportare contemporaneamente streaming e tool calling. Potresti dover disabilitare lo streaming con `params: { streaming: false }` nella configurazione del modello. + Questa modalità potrebbe non supportare contemporaneamente streaming e chiamata degli strumenti. Potrebbe essere necessario disabilitare lo streaming con `params: { streaming: false }` nella configurazione del modello. - Quando `api: "openai-completions"` viene usato con Ollama, OpenClaw inietta per impostazione predefinita `options.num_ctx` così Ollama non torna silenziosamente a una finestra di contesto di 4096. Se il tuo proxy/upstream rifiuta campi `options` sconosciuti, disabilita questo comportamento: + Quando `api: "openai-completions"` viene usato con Ollama, OpenClaw inserisce `options.num_ctx` per impostazione predefinita in modo che Ollama non ricada silenziosamente su una finestra di contesto di 4096. Se il tuo proxy/upstream rifiuta campi `options` sconosciuti, disabilita questo comportamento: ```json5 { @@ -404,7 +404,7 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear - Per i modelli rilevati automaticamente, OpenClaw usa la finestra di contesto riportata da Ollama quando disponibile, altrimenti torna alla finestra di contesto Ollama predefinita usata da OpenClaw. + Per i modelli individuati automaticamente, OpenClaw usa la finestra di contesto riportata da Ollama quando disponibile, altrimenti ricorre alla finestra di contesto predefinita di Ollama usata da OpenClaw. Puoi sovrascrivere `contextWindow` e `maxTokens` nella configurazione esplicita del provider: @@ -428,7 +428,7 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear - + OpenClaw tratta per impostazione predefinita come compatibili con il reasoning i modelli con nomi come `deepseek-r1`, `reasoning` o `think`. ```bash @@ -440,20 +440,20 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear - Ollama è gratuito e viene eseguito localmente, quindi tutti i costi dei modelli sono impostati a $0. Questo vale sia per i modelli rilevati automaticamente sia per quelli definiti manualmente. + Ollama è gratuito e viene eseguito in locale, quindi tutti i costi dei modelli sono impostati a $0. Questo vale sia per i modelli individuati automaticamente sia per quelli definiti manualmente. Il plugin Ollama incluso registra un provider di embedding della memoria per - la [ricerca in memoria](/it/concepts/memory). Usa l'URL base Ollama configurato - e la chiave API. + la [ricerca nella memoria](/it/concepts/memory). Usa l'URL base di Ollama + configurato e la chiave API. | Proprietà | Valore | | -------------- | ------------------- | | Modello predefinito | `nomic-embed-text` | - | Auto-pull | Sì — il modello di embedding viene scaricato automaticamente se non è presente localmente | + | Auto-pull | Sì — il modello di embedding viene scaricato automaticamente se non è presente in locale | - Per selezionare Ollama come provider di embedding per la ricerca in memoria: + Per selezionare Ollama come provider di embedding per la ricerca nella memoria: ```json5 { @@ -468,10 +468,12 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear - L'integrazione Ollama di OpenClaw usa per impostazione predefinita l'**API nativa di Ollama** (`/api/chat`), che supporta completamente streaming e tool calling contemporaneamente. Non è necessaria alcuna configurazione speciale. + L'integrazione Ollama di OpenClaw usa per impostazione predefinita l'**API nativa di Ollama** (`/api/chat`), che supporta pienamente contemporaneamente lo streaming e la chiamata degli strumenti. Non è necessaria alcuna configurazione speciale. + + Per le richieste native `/api/chat`, OpenClaw inoltra anche il controllo del thinking direttamente a Ollama: `/think off` e `openclaw agent --thinking off` inviano `think: false` al livello superiore, mentre i livelli di thinking diversi da `off` inviano `think: true`. - Se hai bisogno di usare l'endpoint compatibile con OpenAI, vedi la sezione "Modalità legacy compatibile con OpenAI" qui sopra. Streaming e tool calling potrebbero non funzionare contemporaneamente in quella modalità. + Se hai bisogno di usare l'endpoint compatibile con OpenAI, vedi la sezione "Modalità legacy compatibile con OpenAI" sopra. In quella modalità, streaming e chiamata degli strumenti potrebbero non funzionare contemporaneamente. @@ -481,7 +483,7 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear - Assicurati che Ollama sia in esecuzione, di aver impostato `OLLAMA_API_KEY` (o un profilo auth) e di **non** aver definito una voce esplicita `models.providers.ollama`: + Assicurati che Ollama sia in esecuzione, di aver impostato `OLLAMA_API_KEY` (o un profilo di autenticazione) e di **non** aver definito una voce esplicita `models.providers.ollama`: ```bash ollama serve @@ -511,10 +513,10 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear Controlla che Ollama sia in esecuzione sulla porta corretta: ```bash - # Controlla se Ollama è in esecuzione + # Check if Ollama is running ps aux | grep ollama - # Oppure riavvia Ollama + # Or restart Ollama ollama serve ``` @@ -522,20 +524,20 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear -Altri aiuti: [Risoluzione dei problemi](/it/help/troubleshooting) e [FAQ](/it/help/faq). +Più aiuto: [Risoluzione dei problemi](/it/help/troubleshooting) e [FAQ](/it/help/faq). ## Correlati - Panoramica di tutti i provider, riferimenti modello e comportamento di failover. + Panoramica di tutti i provider, riferimenti ai modelli e comportamento di failover. Come scegliere e configurare i modelli. - Dettagli completi su configurazione e comportamento della ricerca web basata su Ollama. + Dettagli completi su configurazione e comportamento per la ricerca web basata su Ollama. Riferimento completo della configurazione. diff --git a/docs/it/providers/tencent.md b/docs/it/providers/tencent.md new file mode 100644 index 000000000..182105081 --- /dev/null +++ b/docs/it/providers/tencent.md @@ -0,0 +1,64 @@ +--- +read_when: + - Vuoi usare i modelli Tencent Hy con OpenClaw + - Hai bisogno della configurazione della chiave API di TokenHub +summary: Configurazione di Tencent Cloud TokenHub +title: Tencent Cloud (TokenHub) +x-i18n: + generated_at: "2026-04-22T08:20:52Z" + model: gpt-5.4 + provider: openai + source_hash: 04da073973792c55dc0c2d287bfc51187bb2128bbbd5c4a483f850adeea50ab5 + source_path: providers/tencent.md + workflow: 15 +--- + +# Tencent Cloud (TokenHub) + +Il provider Tencent Cloud consente l'accesso ai modelli Tencent Hy tramite l'endpoint TokenHub (`tencent-tokenhub`). + +Il provider usa un'API compatibile con OpenAI. + +## Avvio rapido + +```bash +openclaw onboard --auth-choice tokenhub-api-key +``` + +## Esempio non interattivo + +```bash +openclaw onboard --non-interactive \ + --mode local \ + --auth-choice tokenhub-api-key \ + --tokenhub-api-key "$TOKENHUB_API_KEY" \ + --skip-health \ + --accept-risk +``` + +## Provider ed endpoint + +| Provider | Endpoint | Caso d'uso | +| ------------------ | ----------------------------- | ----------------------- | +| `tencent-tokenhub` | `tokenhub.tencentmaas.com/v1` | Hy tramite Tencent TokenHub | + +## Modelli disponibili + +### tencent-tokenhub + +- **hy3-preview** — Anteprima di Hy3 (contesto 256K, ragionamento, predefinito) + +## Note + +- I riferimenti modello TokenHub usano `tencent-tokenhub/`. +- Se necessario, sostituisci i metadati di prezzo e contesto in `models.providers`. + +## Nota sull'ambiente + +Se il Gateway è in esecuzione come demone (launchd/systemd), assicurati che `TOKENHUB_API_KEY` sia disponibile per quel processo (ad esempio in `~/.openclaw/.env` o tramite `env.shellEnv`). + +## Documentazione correlata + +- [Configurazione di OpenClaw](/it/gateway/configuration) +- [Provider di modelli](/it/concepts/model-providers) +- [Tencent TokenHub](https://cloud.tencent.com/document/product/1823/130050) diff --git a/docs/it/tools/index.md b/docs/it/tools/index.md index 122836b01..851d1d691 100644 --- a/docs/it/tools/index.md +++ b/docs/it/tools/index.md @@ -1,23 +1,23 @@ --- read_when: - Vuoi capire quali strumenti fornisce OpenClaw - - Devi configurare, consentire o negare strumenti + - Devi configurare, consentire o negare gli strumenti - Stai decidendo tra strumenti integrati, Skills e plugin -summary: 'Panoramica di strumenti e plugin di OpenClaw: cosa può fare l''agent e come estenderlo' -title: Strumenti e plugin +summary: 'Panoramica di strumenti e plugin di OpenClaw: cosa può fare l’agente e come estenderlo' +title: Strumenti e Plugin x-i18n: - generated_at: "2026-04-06T03:12:52Z" + generated_at: "2026-04-22T08:20:54Z" model: gpt-5.4 provider: openai - source_hash: b2371239316997b0fe389bfa2ec38404e1d3e177755ad81ff8035ac583d9adeb + source_hash: 6edb9e13b72e6345554f25c8d8413d167a69501e6626828d9aa3aac6907cd092 source_path: tools/index.md workflow: 15 --- -# Strumenti e plugin +# Strumenti e Plugin -Tutto ciò che l'agent fa oltre a generare testo avviene tramite gli **strumenti**. -Gli strumenti sono il modo in cui l'agent legge file, esegue comandi, naviga sul web, invia +Tutto ciò che l’agente fa oltre a generare testo avviene tramite gli **strumenti**. +Gli strumenti sono il modo in cui l’agente legge file, esegue comandi, naviga sul web, invia messaggi e interagisce con i dispositivi. ## Strumenti, Skills e plugin @@ -25,33 +25,33 @@ messaggi e interagisce con i dispositivi. OpenClaw ha tre livelli che lavorano insieme: - - Uno strumento è una funzione tipizzata che l'agent può invocare (ad esempio `exec`, `browser`, + + Uno strumento è una funzione tipizzata che l’agente può invocare (ad es. `exec`, `browser`, `web_search`, `message`). OpenClaw include un insieme di **strumenti integrati** e - i plugin possono registrarne altri. + i plugin possono registrarne di aggiuntivi. - L'agent vede gli strumenti come definizioni strutturate di funzione inviate all'API del modello. + L’agente vede gli strumenti come definizioni di funzione strutturate inviate all’API del modello. - - Una Skill è un file markdown (`SKILL.md`) iniettato nel prompt di sistema. - Le Skills forniscono all'agent contesto, vincoli e indicazioni passo passo per - usare gli strumenti in modo efficace. Le Skills si trovano nel tuo workspace, in cartelle condivise, - oppure vengono distribuite all'interno dei plugin. + + Una Skill è un file markdown (`SKILL.md`) iniettato nel system prompt. + Le Skills forniscono all’agente contesto, vincoli e una guida passo passo per + usare gli strumenti in modo efficace. Le Skills si trovano nel tuo workspace, in cartelle + condivise oppure possono essere incluse nei plugin. - [Riferimento Skills](/it/tools/skills) | [Creare Skills](/it/tools/creating-skills) + [Riferimento Skills](/it/tools/skills) | [Creazione di Skills](/it/tools/creating-skills) - - Un plugin è un pacchetto che può registrare qualsiasi combinazione di capability: - canali, provider di modelli, strumenti, Skills, speech, realtime transcription, - realtime voice, media understanding, image generation, video generation, - web fetch, web search e altro. Alcuni plugin sono **core** (distribuiti con + + Un plugin è un pacchetto che può registrare qualsiasi combinazione di capacità: + canali, provider di modelli, strumenti, Skills, voce, trascrizione in tempo reale, + voce in tempo reale, comprensione dei media, generazione di immagini, generazione di video, + recupero web, ricerca web e altro ancora. Alcuni plugin sono **core** (forniti con OpenClaw), altri sono **esterni** (pubblicati su npm dalla community). - [Installare e configurare plugin](/it/tools/plugin) | [Crea il tuo](/it/plugins/building-plugins) + [Installa e configura i plugin](/it/tools/plugin) | [Crea il tuo](/it/plugins/building-plugins) @@ -60,30 +60,30 @@ OpenClaw ha tre livelli che lavorano insieme: Questi strumenti sono inclusi in OpenClaw e sono disponibili senza installare alcun plugin: -| Strumento | Cosa fa | Pagina | -| ------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------- | -| `exec` / `process` | Esegue comandi shell, gestisce processi in background | [Exec](/it/tools/exec) | -| `code_execution` | Esegue analisi Python remote in sandbox | [Code Execution](/it/tools/code-execution) | -| `browser` | Controlla un browser Chromium (naviga, clicca, screenshot) | [Browser](/it/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Cerca nel web, cerca post su X, recupera contenuto di pagine | [Web](/it/tools/web) | -| `read` / `write` / `edit` | I/O di file nel workspace | | -| `apply_patch` | Patch di file multi-hunk | [Apply Patch](/it/tools/apply-patch) | -| `message` | Invia messaggi su tutti i canali | [Agent Send](/it/tools/agent-send) | -| `canvas` | Guida il Canvas a nodi (present, eval, snapshot) | | -| `nodes` | Rileva e seleziona dispositivi associati | | -| `cron` / `gateway` | Gestisce job pianificati; ispeziona, modifica, riavvia o aggiorna il gateway | | -| `image` / `image_generate` | Analizza o genera immagini | [Generazione di immagini](/it/tools/image-generation) | -| `music_generate` | Genera tracce musicali | [Generazione di musica](/tools/music-generation) | -| `video_generate` | Genera video | [Generazione di video](/tools/video-generation) | -| `tts` | Conversione text-to-speech singola | [TTS](/it/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Gestione sessioni, stato e orchestrazione di sub-agent | [Sub-agent](/it/tools/subagents) | -| `session_status` | Lettura leggera in stile `/status` e override del modello di sessione | [Strumenti di sessione](/it/concepts/session-tool) | +| Tool | Cosa fa | Pagina | +| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------- | +| `exec` / `process` | Esegue comandi shell, gestisce processi in background | [Exec](/it/tools/exec) | +| `code_execution` | Esegue analisi Python remota in sandbox | [Code Execution](/it/tools/code-execution) | +| `browser` | Controlla un browser Chromium (navigazione, clic, screenshot) | [Browser](/it/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Cerca nel web, cerca post su X, recupera il contenuto delle pagine | [Web](/it/tools/web) | +| `read` / `write` / `edit` | I/O dei file nel workspace | | +| `apply_patch` | Patch di file multi-hunk | [Apply Patch](/it/tools/apply-patch) | +| `message` | Invia messaggi su tutti i canali | [Agent Send](/it/tools/agent-send) | +| `canvas` | Controlla node Canvas (present, eval, snapshot) | | +| `nodes` | Individua e seleziona dispositivi associati | | +| `cron` / `gateway` | Gestisce job pianificati; ispeziona, corregge, riavvia o aggiorna il Gateway | | +| `image` / `image_generate` | Analizza o genera immagini | [Image Generation](/it/tools/image-generation) | +| `music_generate` | Genera tracce musicali | [Music Generation](/it/tools/music-generation) | +| `video_generate` | Genera video | [Video Generation](/it/tools/video-generation) | +| `tts` | Conversione text-to-speech one-shot | [TTS](/it/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Gestione delle sessioni, stato e orchestrazione di sotto-agenti | [Sub-agents](/it/tools/subagents) | +| `session_status` | Lettura leggera in stile `/status` e override del modello di sessione | [Session Tools](/it/concepts/session-tool) | -Per il lavoro sulle immagini, usa `image` per l'analisi e `image_generate` per la generazione o la modifica. Se scegli come target `openai/*`, `google/*`, `fal/*` o un altro provider image non predefinito, configura prima l'autenticazione/la chiave API di quel provider. +Per il lavoro con le immagini, usa `image` per l’analisi e `image_generate` per la generazione o la modifica. Se scegli `openai/*`, `google/*`, `fal/*` o un altro provider di immagini non predefinito, configura prima l’autenticazione/la chiave API di quel provider. -Per il lavoro sulla musica, usa `music_generate`. Se scegli come target `google/*`, `minimax/*` o un altro provider music non predefinito, configura prima l'autenticazione/la chiave API di quel provider. +Per il lavoro con la musica, usa `music_generate`. Se scegli `google/*`, `minimax/*` o un altro provider di musica non predefinito, configura prima l’autenticazione/la chiave API di quel provider. -Per il lavoro sui video, usa `video_generate`. Se scegli come target `qwen/*` o un altro provider video non predefinito, configura prima l'autenticazione/la chiave API di quel provider. +Per il lavoro con i video, usa `video_generate`. Se scegli `qwen/*` o un altro provider di video non predefinito, configura prima l’autenticazione/la chiave API di quel provider. Per la generazione audio guidata da workflow, usa `music_generate` quando un plugin come ComfyUI lo registra. Questo è separato da `tts`, che è text-to-speech. @@ -91,38 +91,39 @@ ComfyUI lo registra. Questo è separato da `tts`, che è text-to-speech. `session_status` è lo strumento leggero di stato/lettura nel gruppo sessions. Risponde a domande in stile `/status` sulla sessione corrente e può facoltativamente impostare un override del modello per sessione; `model=default` cancella tale -override. Come `/status`, può completare in retrospettiva contatori sparsi di token/cache e l'etichetta -del modello runtime attivo dall'ultima voce di utilizzo nella trascrizione. +override. Come `/status`, può ricostruire contatori sparsi di token/cache e l’etichetta del +modello runtime attivo a partire dall’ultima voce di utilizzo nella trascrizione. -`gateway` è lo strumento runtime riservato al proprietario per le operazioni del gateway: +`gateway` è lo strumento runtime solo per owner per le operazioni del Gateway: -- `config.schema.lookup` per un sottoalbero della configurazione limitato a un percorso prima delle modifiche -- `config.get` per lo snapshot + hash della configurazione corrente +- `config.schema.lookup` per un singolo sottoalbero di configurazione limitato a un percorso prima delle modifiche +- `config.get` per lo snapshot della configurazione corrente + hash - `config.patch` per aggiornamenti parziali della configurazione con riavvio - `config.apply` solo per la sostituzione completa della configurazione -- `update.run` per auto-aggiornamento esplicito + riavvio +- `update.run` per self-update esplicito + riavvio -Per le modifiche parziali, preferisci `config.schema.lookup` e poi `config.patch`. Usa -`config.apply` solo quando intendi sostituire l'intera configurazione. -Lo strumento rifiuta anche di modificare `tools.exec.ask` o `tools.exec.security`; -gli alias legacy `tools.bash.*` vengono normalizzati agli stessi percorsi exec protetti. +Per modifiche parziali, preferisci `config.schema.lookup` e poi `config.patch`. Usa +`config.apply` solo quando intendi sostituire l’intera configurazione. +Lo strumento si rifiuta anche di modificare `tools.exec.ask` o `tools.exec.security`; +i vecchi alias `tools.bash.*` vengono normalizzati agli stessi percorsi exec protetti. ### Strumenti forniti dai plugin I plugin possono registrare strumenti aggiuntivi. Alcuni esempi: -- [Lobster](/it/tools/lobster) — runtime di workflow tipizzato con approvazioni riprendibili -- [LLM Task](/it/tools/llm-task) — passaggio LLM solo JSON per output strutturato -- [Generazione di musica](/tools/music-generation) — strumento condiviso `music_generate` con provider supportati da workflow - [Diffs](/it/tools/diffs) — visualizzatore e renderer di diff +- [LLM Task](/it/tools/llm-task) — passaggio LLM solo JSON per output strutturato +- [Lobster](/it/tools/lobster) — runtime di workflow tipizzato con approvazioni riprendibili +- [Music Generation](/it/tools/music-generation) — strumento condiviso `music_generate` con provider basati su workflow - [OpenProse](/it/prose) — orchestrazione di workflow markdown-first +- [Tokenjuice](/it/tools/tokenjuice) — risultati compatti e meno rumorosi degli strumenti `exec` e `bash` ## Configurazione degli strumenti -### Liste di autorizzazione e negazione +### Liste di consentiti e negati -Controlla quali strumenti l'agent può richiamare tramite `tools.allow` / `tools.deny` nella -configurazione. La negazione ha sempre la precedenza sull'autorizzazione. +Controlla quali strumenti l’agente può richiamare tramite `tools.allow` / `tools.deny` nella +configurazione. I negati hanno sempre la precedenza sui consentiti. ```json5 { @@ -136,22 +137,22 @@ configurazione. La negazione ha sempre la precedenza sull'autorizzazione. ### Profili degli strumenti `tools.profile` imposta una allowlist di base prima che vengano applicati `allow`/`deny`. -Override per-agent: `agents.list[].tools.profile`. +Override per agente: `agents.list[].tools.profile`. -| Profilo | Cosa include | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Nessuna restrizione (uguale a non impostato) | +| Profilo | Cosa include | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `full` | Nessuna restrizione (uguale a non impostato) | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `minimal` | Solo `session_status` | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `minimal` | solo `session_status` | ### Gruppi di strumenti -Usa le abbreviazioni `group:*` nelle liste allow/deny: +Usa le abbreviazioni `group:*` nelle liste di consentiti/negati: | Gruppo | Strumenti | | ------------------ | ----------------------------------------------------------------------------------------------------------- | -| `group:runtime` | exec, process, code_execution (`bash` è accettato come alias di `exec`) | +| `group:runtime` | exec, process, code_execution (`bash` è accettato come alias per `exec`) | | `group:fs` | read, write, edit, apply_patch | | `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | | `group:memory` | memory_search, memory_get | @@ -162,17 +163,17 @@ Usa le abbreviazioni `group:*` nelle liste allow/deny: | `group:nodes` | nodes | | `group:agents` | agents_list | | `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | Tutti gli strumenti integrati di OpenClaw (esclude gli strumenti dei plugin) | +| `group:openclaw` | Tutti gli strumenti integrati di OpenClaw (esclude gli strumenti dei plugin) | `sessions_history` restituisce una vista di richiamo limitata e filtrata per sicurezza. Rimuove -tag di thinking, scaffolding ``, payload XML in testo semplice delle chiamate agli strumenti -(inclusi `...`, +tag di ragionamento, scaffolding ``, payload XML di chiamate agli strumenti in testo semplice +(compresi `...`, `...`, `...`, `...` e blocchi di chiamata agli strumenti troncati), -scaffolding degradato delle chiamate agli strumenti, token di controllo del modello ASCII/full-width trapelati -e XML malformato delle chiamate agli strumenti MiniMax dal testo dell'assistente, quindi applica -redazione/troncamento e possibili placeholder per righe troppo grandi invece di comportarsi -come dump grezzo della trascrizione. +scaffolding declassato di chiamata agli strumenti, token di controllo del modello ASCII/a larghezza piena fuoriusciti +e XML malformato di chiamata agli strumenti MiniMax dal testo dell’assistente, quindi applica +redazione/troncamento ed eventuali placeholder per righe troppo grandi invece di comportarsi +come un dump grezzo della trascrizione. ### Restrizioni specifiche del provider diff --git a/docs/it/tools/tokenjuice.md b/docs/it/tools/tokenjuice.md new file mode 100644 index 000000000..c6ef74357 --- /dev/null +++ b/docs/it/tools/tokenjuice.md @@ -0,0 +1,79 @@ +--- +read_when: + - Vuoi risultati degli strumenti `exec` o `bash` più brevi in OpenClaw + - Vuoi abilitare il plugin tokenjuice incluso nel pacchetto + - Hai bisogno di capire cosa modifica tokenjuice e cosa lascia grezzo +summary: Compatta i risultati rumorosi degli strumenti exec e bash con un plugin incluso facoltativo +title: Tokenjuice +x-i18n: + generated_at: "2026-04-22T08:21:03Z" + model: gpt-5.4 + provider: openai + source_hash: 9b9a1054c9b1cc62e43ac6d5904c7790f9b27d8e0d0700c9da6e287c00e91783 + source_path: tools/tokenjuice.md + workflow: 15 +--- + +# Tokenjuice + +`tokenjuice` è un plugin incluso facoltativo che compatta i risultati rumorosi degli strumenti `exec` e `bash` dopo che il comando è già stato eseguito. + +Modifica il `tool_result` restituito, non il comando stesso. Tokenjuice non riscrive l'input della shell, non riesegue i comandi e non cambia i codici di uscita. + +Attualmente questo si applica alle esecuzioni incorporate di Pi, in cui tokenjuice si aggancia al percorso incorporato di `tool_result` e riduce l'output che torna nella sessione. + +## Abilita il plugin + +Percorso rapido: + +```bash +openclaw config set plugins.entries.tokenjuice.enabled true +``` + +Equivalente: + +```bash +openclaw plugins enable tokenjuice +``` + +OpenClaw include già il plugin. Non esiste un passaggio separato `plugins install` o `tokenjuice install openclaw`. + +Se preferisci modificare direttamente la configurazione: + +```json5 +{ + plugins: { + entries: { + tokenjuice: { + enabled: true, + }, + }, + }, +} +``` + +## Cosa cambia tokenjuice + +- Compatta i risultati rumorosi di `exec` e `bash` prima che vengano reinseriti nella sessione. +- Lascia invariata l'esecuzione originale del comando. +- Preserva le letture esatte del contenuto dei file e gli altri comandi che tokenjuice deve lasciare grezzi. +- Resta su base opt-in: disabilita il plugin se vuoi output letterale ovunque. + +## Verifica che funzioni + +1. Abilita il plugin. +2. Avvia una sessione che possa chiamare `exec`. +3. Esegui un comando rumoroso come `git status`. +4. Verifica che il risultato dello strumento restituito sia più breve e più strutturato dell'output grezzo della shell. + +## Disabilita il plugin + +```bash +openclaw config set plugins.entries.tokenjuice.enabled false +``` + +Oppure: + +```bash +openclaw plugins disable tokenjuice +```