| read_when |
sidebarTitle |
summary |
title |
x-i18n |
| 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 |
|
SDK Overview |
Mappa di importazione, riferimento API di registrazione e architettura dell'SDK |
Panoramica dell'SDK per Plugin |
| generated_at |
model |
provider |
source_hash |
source_path |
workflow |
| 2026-04-19T01:11:24Z |
gpt-5.4 |
openai |
522c2c542bc0ea4793541fda18931b963ad71f07e9c83e4f22f05184eb1ba91a |
plugins/sdk-overview.md |
15 |
|
Panoramica dell'SDK per Plugin
L'SDK per plugin è il contratto tipizzato tra i plugin e il core. Questa pagina è il
riferimento per cosa importare e cosa puoi registrare.
**Cerchi una guida pratica?**
- Primo plugin? Inizia con [Getting Started](/it/plugins/building-plugins)
- Plugin di canale? Vedi [Channel Plugins](/it/plugins/sdk-channel-plugins)
- Plugin provider? Vedi [Provider Plugins](/it/plugins/sdk-provider-plugins)
Convenzione di importazione
Importa sempre da un sottopercorso specifico:
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Ogni sottopercorso è un modulo piccolo e autosufficiente. Questo mantiene l'avvio rapido 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 ombrello più ampia e per gli helper condivisi come
buildChannelConfigSchema.
Non aggiungere né dipendere da seam di convenienza con nomi di provider come
openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord,
openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp, o
seam di helper con branding di 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 quei barrel locali del plugin oppure aggiungere un contratto SDK generico e ristretto
quando l'esigenza è davvero trasversale ai canali.
La mappa delle esportazioni generata contiene ancora un piccolo insieme di seam helper di plugin inclusi
come plugin-sdk/feishu, plugin-sdk/feishu-setup,
plugin-sdk/zalo, plugin-sdk/zalo-setup e plugin-sdk/matrix*. Questi
sottopercorsi esistono solo per manutenzione e compatibilità dei plugin inclusi; sono
intenzionalmente omessi dalla tabella comune qui sotto e non sono il percorso di importazione
consigliato per nuovi plugin di terze parti.
Riferimento dei sottopercorsi
I sottopercorsi più usati, raggruppati per scopo. L'elenco completo generato di
oltre 200 sottopercorsi si trova in scripts/lib/plugin-sdk-entrypoints.json.
I sottopercorsi helper riservati ai plugin inclusi compaiono ancora in quell'elenco generato.
Trattali come superfici di dettaglio implementativo/compatibilità, a meno che una pagina della documentazione
non ne promuova esplicitamente uno come pubblico.
Entry del plugin
| 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 |
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `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 il wizard di configurazione, prompt allowlist, builder dello stato di configurazione |
| `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/gate di azione multi-account e helper di fallback dell'account predefinito |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper di normalizzazione dell'account ID |
| `plugin-sdk/account-resolution` | Helper di ricerca account + fallback predefinito |
| `plugin-sdk/account-helpers` | Helper ristretti per elenco account/azioni 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 di configurazione del canale |
| `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati di Telegram con fallback al contratto incluso |
| `plugin-sdk/command-gating` | Helper ristretti per gate di autorizzazione dei comandi |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helper condivisi per route inbound + builder di envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper condivisi per registrazione e dispatch inbound |
| `plugin-sdk/messaging-targets` | Helper per parsing/matching dei target |
| `plugin-sdk/outbound-media` | Helper condivisi per il caricamento dei contenuti multimediali outbound |
| `plugin-sdk/outbound-runtime` | Helper outbound per identità/delega di invio |
| `plugin-sdk/poll-runtime` | Helper ristretti per la normalizzazione dei sondaggi |
| `plugin-sdk/thread-bindings-runtime` | Helper per lifecycle e adapter dei binding dei thread |
| `plugin-sdk/agent-media-payload` | Builder legacy del payload multimediale dell'agente |
| `plugin-sdk/conversation-runtime` | Helper per binding conversazione/thread, pairing e binding configurati |
| `plugin-sdk/runtime-config-snapshot` | Helper per snapshot di configurazione runtime |
| `plugin-sdk/runtime-group-policy` | Helper runtime per la risoluzione delle policy di gruppo |
| `plugin-sdk/channel-status` | Helper condivisi per snapshot/riepilogo dello stato del canale |
| `plugin-sdk/channel-config-primitives` | Primitive ristrette dello schema di configurazione del canale |
| `plugin-sdk/channel-config-writes` | Helper di autorizzazione per scritture della configurazione del canale |
| `plugin-sdk/channel-plugin-common` | Esportazioni di prelude condivise per plugin di canale |
| `plugin-sdk/allowlist-config-edit` | Helper di modifica/lettura 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 normalizzazione/riduzione del payload di risposta interattiva |
| `plugin-sdk/channel-inbound` | Barrel di compatibilità per inbound debounce, matching delle menzioni, helper per le policy di menzione e helper di envelope |
| `plugin-sdk/channel-mention-gating` | Helper ristretti per le policy di menzione senza la più ampia superficie runtime inbound |
| `plugin-sdk/channel-location` | Helper per contesto e formattazione della posizione del canale |
| `plugin-sdk/channel-logging` | Helper di logging del canale per scarti inbound e errori di digitazione/ack |
| `plugin-sdk/channel-send-result` | Tipi di risultato della risposta |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | Helper per parsing/matching dei target |
| `plugin-sdk/channel-contract` | Tipi di contratto del canale |
| `plugin-sdk/channel-feedback` | Wiring di feedback/reazioni |
| `plugin-sdk/channel-secret-runtime` | Helper ristretti per il contratto dei secret come `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipi di target dei secret |
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Helper curati per la configurazione di provider locali/self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper mirati per la configurazione di provider self-hosted compatibili con 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 per onboarding/scrittura del profilo delle 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 per la ricerca delle variabili d'ambiente auth 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 del provider e helper di normalizzazione del model ID come `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Helper generici per capacità HTTP/endpoint del provider |
| `plugin-sdk/provider-web-fetch-contract` | Helper ristretti per contratto di configurazione/selezione web-fetch come `enablePluginInConfig` e `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helper per registrazione/cache dei provider web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helper ristretti per configurazione/credenziali web-search per provider che non necessitano del wiring di abilitazione plugin |
| `plugin-sdk/provider-web-search-contract` | Helper ristretti per contratto di configurazione/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con ambito |
| `plugin-sdk/provider-web-search` | Helper per registrazione/cache/runtime dei provider web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia + diagnostica dello schema Gemini e helper compat xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` e simili |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di wrapper di 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 per patch di configurazione dell'onboarding |
| `plugin-sdk/global-singleton` | Helper per singleton/map/cache locali al processo |
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper del registro dei comandi, helper di autorizzazione del mittente |
| `plugin-sdk/command-status` | Builder di messaggi di comando/aiuto come `buildCommandsMessagePaginated` e `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Risoluzione degli approvatori e helper di autenticazione delle azioni nella stessa chat |
| `plugin-sdk/approval-client-runtime` | Helper di profilo/filtro di approvazione per exec nativo |
| `plugin-sdk/approval-delivery-runtime` | Adapter condivisi per capacità/consegna delle approvazioni native |
| `plugin-sdk/approval-gateway-runtime` | Helper condiviso per la risoluzione del Gateway delle approvazioni |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper leggeri di caricamento degli adapter di approvazione nativi per entrypoint hot dei canali |
| `plugin-sdk/approval-handler-runtime` | Helper runtime più ampi per il gestore delle approvazioni; preferisci i seam adapter/gateway più ristretti 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 approvazioni exec/plugin |
| `plugin-sdk/command-auth-native` | Helper nativi per auth dei comandi + target di sessione nativa |
| `plugin-sdk/command-detection` | Helper condivisi per il rilevamento dei comandi |
| `plugin-sdk/command-surface` | Helper per normalizzazione del corpo del comando e command-surface |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Helper ristretti di raccolta del contratto dei secret per superfici secret di canali/plugin |
| `plugin-sdk/secret-ref-runtime` | Helper ristretti `coerceSecretRef` e di tipizzazione SecretRef per il parsing del contratto dei secret/della configurazione |
| `plugin-sdk/security-runtime` | Helper condivisi per trust, gate DM, contenuti esterni e raccolta dei secret |
| `plugin-sdk/ssrf-policy` | Helper per policy SSRF di allowlist host e rete privata |
| `plugin-sdk/ssrf-dispatcher` | Helper ristretti per pinned-dispatcher senza l'ampia superficie runtime infra |
| `plugin-sdk/ssrf-runtime` | Helper per pinned-dispatcher, 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 |
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/runtime` | Ampi helper 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 per registrazione e lookup del contesto runtime del canale |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Helper condivisi per comandi/hook/http/interattività dei plugin |
| `plugin-sdk/hook-runtime` | Helper condivisi per pipeline di hook webhook/interni |
| `plugin-sdk/lazy-runtime` | Helper per import/binding lazy del runtime come `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper per esecuzione di processi |
| `plugin-sdk/cli-runtime` | Helper per formattazione CLI, attesa e versione |
| `plugin-sdk/gateway-runtime` | Helper per 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 nomi/descrizioni dei comandi Telegram e controlli di duplicati/conflitti, anche quando la superficie del contratto Telegram incluso non è disponibile |
| `plugin-sdk/text-autolink-runtime` | Rilevamento di autolink per riferimenti a file senza l'ampio barrel `text-runtime` |
| `plugin-sdk/approval-runtime` | Helper per approvazioni exec/plugin, builder di capacità di approvazione, helper auth/profili, helper nativi di routing/runtime |
| `plugin-sdk/reply-runtime` | Helper condivisi per runtime inbound/risposta, chunking, dispatch, Heartbeat, pianificatore di risposta |
| `plugin-sdk/reply-dispatch-runtime` | Helper ristretti per dispatch/finalizzazione della risposta |
| `plugin-sdk/reply-history` | Helper condivisi per la reply-history a breve finestra 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 percorsi di directory state/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 dello stato di canali/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 per normalizzazione di slug/stringhe |
| `plugin-sdk/request-url` | Estrai URL stringa da input simili a fetch/richiesta |
| `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` | Estrai payload normalizzati da oggetti risultato dei tool |
| `plugin-sdk/tool-send` | Estrai 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 modalità tabelle Markdown |
| `plugin-sdk/json-store` | Piccoli helper per lettura/scrittura di stato JSON |
| `plugin-sdk/file-lock` | Helper per file-lock rientrante |
| `plugin-sdk/persistent-dedupe` | Helper per cache di deduplica persistente su disco |
| `plugin-sdk/acp-runtime` | Helper per runtime/sessione ACP e reply-dispatch |
| `plugin-sdk/acp-binding-resolve-runtime` | Risoluzione in sola lettura dei binding ACP senza import di avvio del lifecycle |
| `plugin-sdk/agent-config-primitives` | Primitive ristrette dello schema di configurazione runtime dell'agente |
| `plugin-sdk/boolean-param` | Lettore permissivo di parametri booleani |
| `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per il 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 canali passivi, stato e proxy ambient |
| `plugin-sdk/models-provider-runtime` | Helper per il comando `/models` e per le risposte dei provider |
| `plugin-sdk/skill-commands-runtime` | Helper per l'elenco dei comandi Skills |
| `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 a basso livello: tipi di harness, helper per steer/abort di esecuzioni attive, helper per il bridge degli strumenti OpenClaw e utility per i risultati dei tentativi |
| `plugin-sdk/provider-zai-endpoint` | Helper per il rilevamento degli endpoint Z.A.I |
| `plugin-sdk/infra-runtime` | Helper per eventi di sistema/Heartbeat |
| `plugin-sdk/collection-runtime` | Piccoli helper per cache limitate |
| `plugin-sdk/diagnostic-runtime` | Helper per flag ed eventi diagnostici |
| `plugin-sdk/error-runtime` | Grafo degli errori, formattazione, helper condivisi per classificazione degli errori, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper per fetch con wrapper, 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 limitato del body della risposta senza l'ampia superficie runtime dei media |
| `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 store di sessione senza ampi import di scrittura/manutenzione della configurazione |
| `plugin-sdk/context-visibility-runtime` | Risoluzione della visibilità del contesto e filtro del contesto supplementare senza ampi import di configurazione/sicurezza |
| `plugin-sdk/string-coerce-runtime` | Helper ristretti per coercizione e normalizzazione di record/stringhe primitive senza import di markdown/logging |
| `plugin-sdk/host-runtime` | Helper per normalizzazione di hostname e host SCP |
| `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/deduplica di directory supportate dalla configurazione |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/media-runtime` | Helper condivisi per fetch/trasformazione/store dei media più builder di payload media |
| `plugin-sdk/media-generation-runtime` | Helper condivisi per failover della generazione media, selezione dei candidati e messaggistica per modelli mancanti |
| `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 per rendering/chunking/tabelle Markdown, helper di redazione, helper per tag di direttiva e utility per testo sicuro |
| `plugin-sdk/text-chunking` | Helper per chunking del testo in uscita |
| `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 per 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, failover, auth e helper di registro |
| `plugin-sdk/music-generation` | Tipi di provider/richiesta/risultato per generazione musicale |
| `plugin-sdk/music-generation-core` | Tipi condivisi per generazione musicale, helper di failover, lookup del provider e parsing di model-ref |
| `plugin-sdk/video-generation` | Tipi di provider/richiesta/risultato per generazione video |
| `plugin-sdk/video-generation-core` | Tipi condivisi per generazione video, helper di failover, lookup del provider e parsing di model-ref |
| `plugin-sdk/webhook-targets` | Registro dei target Webhook e helper di installazione delle route |
| `plugin-sdk/webhook-path` | Helper per normalizzazione dei percorsi Webhook |
| `plugin-sdk/web-media` | Helper condivisi per caricamento di media remoti/locali |
| `plugin-sdk/zod` | `zod` riesportato per i consumer dell'SDK per plugin |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/memory-core` | Superficie helper `memory-core` inclusa per helper di manager/config/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Facciata 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 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 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 per markdown gestito per plugin adiacenti alla memoria |
| `plugin-sdk/memory-host-search` | Facciata runtime di Active Memory per l'accesso al gestore di ricerca |
| `plugin-sdk/memory-host-status` | Alias neutrale rispetto al vendor per gli helper di stato dell'host della memoria |
| `plugin-sdk/memory-lancedb` | Superficie helper `memory-lancedb` inclusa |
| 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 per il 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` | Superficie helper/runtime Matrix inclusa |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime LINE inclusa |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie 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 funzionalità/plugin inclusi; `plugin-sdk/github-copilot-token` attualmente esporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` |
API di registrazione
La callback register(api) riceve un oggetto OpenClawPluginApi con questi
metodi:
Registrazione delle capacità
| Metodo |
Cosa registra |
api.registerProvider(...) |
Inferenza testuale (LLM) |
api.registerAgentHarness(...) |
Esecutore sperimentale di agente a 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 |
api.registerRealtimeVoiceProvider(...) |
Sessioni vocali realtime duplex |
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.registerWebSearchProvider(...) |
Ricerca web |
Strumenti e comandi
| Metodo |
Cosa registra |
api.registerTool(tool, opts?) |
Strumento agente (obbligatorio o { optional: true }) |
api.registerCommand(def) |
Comando personalizzato (bypassa l'LLM) |
Infrastruttura
| Metodo |
Cosa registra |
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) |
Gestore interattivo |
api.registerMemoryPromptSupplement(builder) |
Sezione di prompt additiva adiacente alla memoria |
api.registerMemoryCorpusSupplement(adapter) |
Corpus additivo per ricerca/lettura della memoria |
Gli spazi dei nomi di amministrazione core riservati (config.*, exec.approvals.*, wizard.*,
update.*) restano sempre operator.admin, anche se un plugin prova ad assegnare uno
scope del metodo Gateway più ristretto. Preferisci prefissi specifici del plugin per
i metodi di proprietà del plugin.
Metadati di registrazione CLI
api.registerCli(registrar, opts?) accetta due tipi di metadati di livello superiore:
commands: radici di comando esplicite di proprietà del registrardescriptors: descrittori di comando a tempo di parsing usati per l'help della CLI root,
il routing e la registrazione lazy della CLI del plugin
Se vuoi che un comando del plugin rimanga caricato lazy nel normale percorso della CLI root,
fornisci descriptors che coprano ogni radice di comando di livello superiore esposta da quel
registrar.
api.registerCli(
async ({ program }) => {
const { registerMatrixCli } = await import("./src/cli.js");
registerMatrixCli({ program });
},
{
descriptors: [
{
name: "matrix",
description: "Gestisci account Matrix, verifica, dispositivi e stato del profilo",
hasSubcommands: true,
},
],
},
);
Usa commands da solo solo quando non hai bisogno della registrazione lazy della CLI root.
Quel percorso di compatibilità eager resta supportato, ma non installa
placeholder supportati da descrittori per il caricamento lazy a tempo di parsing.
Registrazione del backend CLI
api.registerCliBackend(...) consente a un plugin di possedere la configurazione predefinita per un
backend CLI AI locale come codex-cli.
- L'
id del backend diventa il prefisso del provider nei model ref come codex-cli/gpt-5.
- La
config del backend usa la stessa forma di agents.defaults.cliBackends.<id>.
- La configurazione utente continua ad avere precedenza. OpenClaw unisce
agents.defaults.cliBackends.<id> sulla
configurazione predefinita del plugin prima di eseguire la CLI.
- Usa
normalizeConfig quando un backend necessita di riscritture di compatibilità dopo il merge
(per esempio per normalizzare vecchie forme di flag).
Slot esclusivi
| 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) |
Capacità 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 embedding della memoria
| Metodo |
Cosa registra |
api.registerMemoryEmbeddingProvider(adapter) |
Adapter embedding della memoria per il plugin attivo |
registerMemoryCapability è l'API esclusiva preferita del plugin di memoria.registerMemoryCapability può anche esporre publicArtifacts.listArtifacts(...)
così i plugin companion possono consumare artefatti di memoria esportati tramite
openclaw/plugin-sdk/memory-host-core invece di accedere al layout privato di uno specifico
plugin di memoria.registerMemoryPromptSection, registerMemoryFlushPlan e
registerMemoryRuntime sono API esclusive legacy-compatibili del plugin di memoria.registerMemoryEmbeddingProvider consente al plugin di memoria attivo di registrare uno
o più ID di adapter 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 quegli ID di adapter
registrati.
Eventi e ciclo di vita
| Metodo |
Cosa fa |
api.on(hookName, handler, opts?) |
Hook di ciclo di vita tipizzato |
api.onConversationBindingResolved(handler) |
Callback di binding della conversazione |
Semantica di decisione degli hook
before_tool_call: restituire { block: true } è terminale. Una volta che un gestore lo imposta, i gestori con priorità inferiore vengono saltati.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 gestore lo imposta, i gestori con priorità inferiore vengono saltati.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 gestore rivendica il dispatch, i gestori con priorità inferiore e il percorso predefinito di dispatch del modello vengono saltati.message_sending: restituire { cancel: true } è terminale. Una volta che un gestore lo imposta, i gestori con priorità inferiore vengono saltati.message_sending: restituire { cancel: false } viene trattato come nessuna decisione (come omettere cancel), non come override.
Campi dell'oggetto API
| 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 attivo in memoria quando disponibile) |
api.pluginConfig |
Record<string, unknown> |
Configurazione specifica del plugin da plugins.entries.<id>.config |
api.runtime |
PluginRuntime |
Helper runtime |
api.logger |
PluginLogger |
Logger con ambito (debug, info, warn, error) |
api.registrationMode |
PluginRegistrationMode |
Modalità di caricamento corrente; "setup-runtime" è la finestra leggera di avvio/configurazione prima dell'entry completa |
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 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 per la configurazione (facoltativa)
Non importare mai il tuo stesso plugin tramite `openclaw/plugin-sdk/`
dal codice di produzione. Instrada le importazioni interne tramite `./api.ts` o
`./runtime-api.ts`. Il percorso SDK è solo il contratto esterno.
Le superfici pubbliche dei plugin 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 sottopercorso SDK
generico. Esempio attuale incluso: il provider Anthropic mantiene i suoi helper di stream Claude
nel proprio seam pubblico api.ts / contract-api.ts invece di
promuovere la logica di header beta Anthropic e service_tier in un contratto
generico plugin-sdk/*.
Altri esempi attuali inclusi:
@openclaw/openai-provider: api.ts esporta builder del provider,
helper per modelli predefiniti e builder del provider realtime@openclaw/openrouter-provider: api.ts esporta il builder del provider più
helper di onboarding/configurazione
Il codice di produzione delle estensioni dovrebbe anche evitare importazioni
`openclaw/plugin-sdk/`. Se un helper è davvero condiviso, promuovilo a un sottopercorso SDK neutrale
come `openclaw/plugin-sdk/speech`, `.../provider-model-shared` o un'altra
superficie orientata alle capacità invece di accoppiare due plugin tra loro.
Correlati
