chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8f8d9aad4b
commit
ec28b59a53
@ -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
|
||||
```
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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.<id>` 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).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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 | <id canale> (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 | <id canale> (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.<channel>.heartbeat` sovrascrive i valori predefiniti del canale.
|
||||
- `channels.<channel>.accounts.<id>.heartbeat` (canali multi-account) sovrascrive per canale.
|
||||
- `channels.<channel>.accounts.<id>.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 `<chatId>:topic:<messageThreadId>`.
|
||||
- `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 `<chatId>:topic:<messageThreadId>`.
|
||||
- `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:<id>:<mainKey>`),
|
||||
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:<id>:<mainKey>`),
|
||||
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
|
||||
|
||||
@ -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 <package-name>`. 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.
|
||||
<Card title="Plugin provider" icon="cpu" href="/it/plugins/sdk-provider-plugins">
|
||||
Aggiungi un provider di modelli (LLM, proxy o endpoint personalizzato)
|
||||
</Card>
|
||||
<Card title="Plugin tool / hook" icon="wrench">
|
||||
Registra strumenti agente, hook di eventi o servizi — continua sotto
|
||||
<Card title="Plugin di strumento / hook" icon="wrench">
|
||||
Registra strumenti per agenti, hook di evento o servizi — continua sotto
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
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.
|
||||
|
||||
<Steps>
|
||||
@ -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).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Testa e pubblica">
|
||||
|
||||
**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 -- <bundled-plugin-root>/my-plugin/
|
||||
@ -151,56 +151,62 @@ e provider hanno guide dedicate collegate sopra.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 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/<bundled-id>` 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/<bundled-id>` 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
|
||||
|
||||
<Check>**package.json** ha metadati `openclaw` corretti</Check>
|
||||
<Check>**package.json** ha i metadati `openclaw` corretti</Check>
|
||||
<Check>Il manifest **openclaw.plugin.json** è presente e valido</Check>
|
||||
<Check>Il punto di ingresso usa `defineChannelPluginEntry` o `definePluginEntry`</Check>
|
||||
<Check>Tutte le importazioni usano percorsi mirati `plugin-sdk/<subpath>`</Check>
|
||||
@ -286,14 +292,14 @@ non come il modello predefinito per nuovi plugin di terze parti.
|
||||
<Check>I test passano (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>`pnpm check` passa (plugin nel repository)</Check>
|
||||
|
||||
## 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: <plugin-name> - <summary>` e applica l'etichetta `beta-blocker`. Inserisci il link dell'issue nel tuo thread.
|
||||
5. Apri una PR verso `main` con titolo `fix(<plugin-id>): beta blocker - <summary>` 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: <plugin-name> - <summary>` e applica l'etichetta `beta-blocker`. Inserisci il link dell'issue nel tuo thread.
|
||||
5. Apri una PR verso `main` intitolata `fix(<plugin-id>): beta blocker - <summary>` 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
|
||||
</Card>
|
||||
<Card title="Helper di runtime" icon="settings" href="/it/plugins/sdk-runtime">
|
||||
TTS, ricerca, sottoagente tramite api.runtime
|
||||
TTS, ricerca, subagent tramite api.runtime
|
||||
</Card>
|
||||
<Card title="Testing" icon="test-tubes" href="/it/plugins/sdk-testing">
|
||||
Utilità e pattern di test
|
||||
<Card title="Test" icon="test-tubes" href="/it/plugins/sdk-testing">
|
||||
Utility e modelli di test
|
||||
</Card>
|
||||
<Card title="Manifest del plugin" icon="file-json" href="/it/plugins/manifest">
|
||||
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
|
||||
|
||||
@ -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/<model>` 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/<model>` 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 <thread-id>` 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)
|
||||
|
||||
@ -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.<id>`. |
|
||||
| `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<string, string[]>` | Metadati env a basso costo per l'autenticazione del provider che OpenClaw può ispezionare senza caricare il codice del Plugin. |
|
||||
| `providerAuthAliases` | No | `Record<string, string>` | 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<string, string[]>` | 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<string, object>` | 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<string, object>` | 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.<id>`. |
|
||||
| `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<string, string[]>` | Metadati leggeri delle variabili d'ambiente di auth del provider che OpenClaw può ispezionare senza caricare il codice del plugin. |
|
||||
| `providerAuthAliases` | No | `Record<string, string>` | 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<string, string[]>` | 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<string, object>` | Valori predefiniti leggeri di comprensione dei media per ID provider dichiarati in `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | No | `Record<string, object>` | 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<string, object>` | 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 <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 <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<string, string>` | Valori predefiniti capacità-modello usati quando la configurazione non specifica un modello. |
|
||||
| `autoPriority` | `Record<string, number>` | 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.<id>`. Obbligatorio per ogni voce di configurazione canale dichiarata. |
|
||||
| `uiHints` | `Record<string, object>` | 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.<id>`. Obbligatorio per ogni voce dichiarata di configurazione del canale. |
|
||||
| `uiHints` | `Record<string, object>` | 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.<id>` 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.<id>` 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.<id>`
|
||||
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.<id>` 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.<id>` 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.<id>`, `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 <package>`).
|
||||
|
||||
## 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
|
||||
|
||||
@ -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=<id>` 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=<id>` 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)
|
||||
|
||||
@ -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.
|
||||
|
||||
<Info>
|
||||
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.
|
||||
</Info>
|
||||
|
||||
## 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.<channel>.accounts.<id>.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.<channel>.accounts.<id>.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
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Pacchetto e manifest">
|
||||
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):
|
||||
|
||||
<CodeGroup>
|
||||
```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 })`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Crea l'oggetto Plugin di canale">
|
||||
L'interfaccia `ChannelPlugin` ha molte superfici adapter opzionali. Inizia con
|
||||
il minimo — `id` e `setup` — e aggiungi adapter secondo necessità.
|
||||
<Step title="Crea l'oggetto plugin di canale">
|
||||
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 })`.
|
||||
```
|
||||
|
||||
<Accordion title="Cosa fa per te createChatChannelPlugin">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Collega l'entrypoint">
|
||||
<Step title="Collega l'entry point">
|
||||
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.
|
||||
|
||||
</Step>
|
||||
@ -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.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Gestisci i messaggi inbound">
|
||||
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:
|
||||
<Step title="Gestisci i messaggi in ingresso">
|
||||
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 })`.
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -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`:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Opzioni di threading" icon="git-branch" href="/it/plugins/sdk-entrypoints#registration-mode">
|
||||
Modalità reply fisse, con scope per account o personalizzate
|
||||
Modalità di risposta fisse, con ambito account o personalizzate
|
||||
</Card>
|
||||
<Card title="Integrazione dello strumento message" icon="puzzle" href="/it/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool e rilevamento delle azioni
|
||||
describeMessageTool e discovery delle azioni
|
||||
</Card>
|
||||
<Card title="Risoluzione del target" icon="crosshair" href="/it/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Helper runtime" icon="settings" href="/it/plugins/sdk-runtime">
|
||||
TTS, STT, contenuti multimediali, sottoagente tramite api.runtime
|
||||
TTS, STT, media, subagent tramite api.runtime
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
@ -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**.
|
||||
|
||||
<Tip>
|
||||
**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)
|
||||
</Tip>
|
||||
|
||||
## 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` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Subpath dei canali">
|
||||
| Subpath | Key exports |
|
||||
<Accordion title="Sottopercorsi dei canali">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpath dei provider">
|
||||
| Subpath | Key exports |
|
||||
<Accordion title="Sottopercorsi dei provider">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpath di auth e sicurezza">
|
||||
| Subpath | Key exports |
|
||||
<Accordion title="Sottopercorsi di autenticazione e sicurezza">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpath di runtime e storage">
|
||||
| Subpath | Key exports |
|
||||
<Accordion title="Sottopercorsi di runtime e storage">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpath di capacità e test">
|
||||
| Subpath | Key exports |
|
||||
<Accordion title="Sottopercorsi di capability e testing">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpath Memory">
|
||||
| Subpath | Key exports |
|
||||
<Accordion title="Sottopercorsi della memoria">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpath helper bundled riservati">
|
||||
| Family | Current subpaths | Intended use |
|
||||
<Accordion title="Sottopercorsi helper inclusi riservati">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -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.<id>`.
|
||||
- La configurazione utente continua ad avere priorità. OpenClaw unisce `agents.defaults.cliBackends.<id>` sopra il
|
||||
valore predefinito del Plugin prima di eseguire la CLI.
|
||||
- La configurazione utente continua ad avere la precedenza. OpenClaw unisce `agents.defaults.cliBackends.<id>` 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<string, unknown>` | Configurazione specifica del Plugin da `plugins.entries.<id>.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<string, unknown>` | Configurazione specifica del Plugin da `plugins.entries.<id>.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)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Non importare mai il tuo stesso Plugin tramite `openclaw/plugin-sdk/<your-plugin>`
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
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
|
||||
|
||||
<Warning>
|
||||
Il codice di produzione delle estensioni dovrebbe anche evitare import `openclaw/plugin-sdk/<other-plugin>`.
|
||||
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/<other-plugin>`.
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
## 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
|
||||
|
||||
@ -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.
|
||||
|
||||
<Warning>
|
||||
**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`).
|
||||
</Warning>
|
||||
|
||||
## Per iniziare
|
||||
@ -44,7 +44,7 @@ Scegli il metodo e la modalità di configurazione che preferisci.
|
||||
- **Local only** — solo modelli locali
|
||||
</Step>
|
||||
<Step title="Seleziona un modello">
|
||||
`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.
|
||||
</Step>
|
||||
<Step title="Verifica che il modello sia disponibile">
|
||||
```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.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Configurazione manuale">
|
||||
**Ideale per:** pieno controllo sulla configurazione cloud o locale.
|
||||
**Ideale per:** controllo completo sulla configurazione cloud o locale.
|
||||
|
||||
<Steps>
|
||||
<Step title="Scegli 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)
|
||||
</Step>
|
||||
<Step title="Scarica un modello locale (solo locale)">
|
||||
@ -105,7 +105,7 @@ Scegli il metodo e la modalità di configurazione che preferisci.
|
||||
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Ispeziona e imposta il modello">
|
||||
<Step title="Esamina e imposta il modello">
|
||||
```bash
|
||||
openclaw models list
|
||||
openclaw models set ollama/gemma4
|
||||
@ -134,9 +134,9 @@ Scegli il metodo e la modalità di configurazione che preferisci.
|
||||
<Tab title="Cloud + Local">
|
||||
`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`.
|
||||
|
||||
</Tab>
|
||||
|
||||
@ -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.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Local only">
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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 `<provider/model>`. 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 `<provider/model>`. 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
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Base (rilevamento implicito)">
|
||||
Il percorso di abilitazione più semplice per solo locale avviene tramite variabile d'ambiente:
|
||||
<Tab title="Base (individuazione implicita)">
|
||||
Il percorso più semplice per abilitare la modalità solo locale è tramite variabile d'ambiente:
|
||||
|
||||
```bash
|
||||
export OLLAMA_API_KEY="ollama-local"
|
||||
```
|
||||
|
||||
<Tip>
|
||||
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à.
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Esplicita (modelli manuali)">
|
||||
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
|
||||
</Tab>
|
||||
|
||||
<Tab title="URL base personalizzato">
|
||||
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
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -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
|
||||
<AccordionGroup>
|
||||
<Accordion title="Modalità legacy compatibile con OpenAI">
|
||||
<Warning>
|
||||
**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.
|
||||
</Warning>
|
||||
|
||||
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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Finestre di contesto">
|
||||
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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Modelli di reasoning">
|
||||
<Accordion title="Modelli reasoning">
|
||||
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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Costi dei modelli">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Embedding della memoria">
|
||||
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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configurazione dello streaming">
|
||||
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`.
|
||||
|
||||
<Tip>
|
||||
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.
|
||||
</Tip>
|
||||
|
||||
</Accordion>
|
||||
@ -481,7 +483,7 @@ Per i dettagli completi su configurazione e comportamento, vedi [Ollama Web Sear
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ollama non rilevato">
|
||||
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
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
## Correlati
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Provider di modelli" href="/it/concepts/model-providers" icon="layers">
|
||||
Panoramica di tutti i provider, riferimenti modello e comportamento di failover.
|
||||
Panoramica di tutti i provider, riferimenti ai modelli e comportamento di failover.
|
||||
</Card>
|
||||
<Card title="Selezione del modello" href="/it/concepts/models" icon="brain">
|
||||
Come scegliere e configurare i modelli.
|
||||
</Card>
|
||||
<Card title="Ollama Web Search" href="/it/tools/ollama-search" icon="magnifying-glass">
|
||||
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.
|
||||
</Card>
|
||||
<Card title="Configurazione" href="/it/gateway/configuration" icon="gear">
|
||||
Riferimento completo della configurazione.
|
||||
|
||||
64
docs/it/providers/tencent.md
Normal file
64
docs/it/providers/tencent.md
Normal file
@ -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/<modelId>`.
|
||||
- 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)
|
||||
@ -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:
|
||||
|
||||
<Steps>
|
||||
<Step title="Gli strumenti sono ciò che l'agent richiama">
|
||||
Uno strumento è una funzione tipizzata che l'agent può invocare (ad esempio `exec`, `browser`,
|
||||
<Step title="Gli strumenti sono ciò che l’agente richiama">
|
||||
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.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Le Skills insegnano all'agent quando e come">
|
||||
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.
|
||||
<Step title="Le Skills insegnano all’agente quando e come">
|
||||
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)
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="I plugin impacchettano tutto insieme">
|
||||
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
|
||||
<Step title="I plugin riuniscono tutto insieme">
|
||||
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)
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -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 `<relevant-memories>`, payload XML in testo semplice delle chiamate agli strumenti
|
||||
(inclusi `<tool_call>...</tool_call>`,
|
||||
tag di ragionamento, scaffolding `<relevant-memories>`, payload XML di chiamate agli strumenti in testo semplice
|
||||
(compresi `<tool_call>...</tool_call>`,
|
||||
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
|
||||
`<function_calls>...</function_calls>` 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
|
||||
|
||||
|
||||
79
docs/it/tools/tokenjuice.md
Normal file
79
docs/it/tools/tokenjuice.md
Normal file
@ -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
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user