---
read_when:
- Devi chiamare gli helper del core da un Plugin (TTS, STT, generazione di immagini, ricerca web, sottoagente, nodi)
- Vuoi capire cosa espone api.runtime
- Stai accedendo agli helper di configurazione, agent o media dal codice del plugin
sidebarTitle: Runtime helpers
summary: api.runtime -- gli helper di runtime iniettati disponibili per i plugin
title: Helper di runtime Plugin
x-i18n:
generated_at: "2026-07-04T20:33:54Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: 22448865af70eedb71180ab88946a88d7eb59c43f09fc1a819d43263b4c4223c
source_path: plugins/sdk-runtime.md
workflow: 16
---
Riferimento per l’oggetto `api.runtime` iniettato in ogni plugin durante la registrazione. Usa questi helper invece di importare direttamente gli elementi interni dell’host.
Guida passo per passo che usa questi helper nel contesto dei Plugin di canale.
Guida passo per passo che usa questi helper nel contesto dei Plugin provider.
```typescript
register(api) {
const runtime = api.runtime;
}
```
## Caricamento e scritture della configurazione
Preferisci la configurazione già passata nel percorso di chiamata attivo, per esempio `api.config` durante la registrazione o un argomento `cfg` nelle callback di canale/provider. Questo mantiene uno snapshot di processo che scorre nel lavoro invece di rianalizzare la configurazione nei percorsi critici.
Usa `api.runtime.config.current()` solo quando un gestore a lunga durata necessita dello snapshot di processo corrente e nessuna configurazione è stata passata a quella funzione. Il valore restituito è di sola lettura; clonalo o usa un helper di mutazione prima di modificarlo.
Le factory degli strumenti ricevono `ctx.runtimeConfig` più `ctx.getRuntimeConfig()`. Usa il getter dentro la callback `execute` di uno strumento a lunga durata quando la configurazione può cambiare dopo la creazione della definizione dello strumento.
Persiste le modifiche con `api.runtime.config.mutateConfigFile(...)` o `api.runtime.config.replaceConfigFile(...)`. Ogni scrittura deve scegliere una policy `afterWrite` esplicita:
- `afterWrite: { mode: "auto" }` lascia decidere al Gateway il ricaricamento del planner.
- `afterWrite: { mode: "restart", reason: "..." }` forza un riavvio pulito quando chi scrive sa che il ricaricamento a caldo non è sicuro.
- `afterWrite: { mode: "none", reason: "..." }` sopprime il ricaricamento/riavvio automatico solo quando il chiamante possiede il seguito.
Gli helper di mutazione restituiscono `afterWrite` più un riepilogo `followUp` tipizzato, così i chiamanti possono registrare nei log o testare se hanno richiesto un riavvio. Il Gateway resta comunque responsabile di quando quel riavvio avviene effettivamente.
`api.runtime.config.loadConfig()` e `api.runtime.config.writeConfigFile(...)` sono helper di compatibilità deprecati sotto `runtime-config-load-write`. Emettono un avviso una volta a runtime e restano disponibili per i vecchi Plugin esterni durante la finestra di migrazione. I Plugin in bundle non devono usarli; le guardie del confine di configurazione falliscono se il codice del Plugin li chiama o importa questi helper dai sottopercorsi dell’SDK Plugin.
Per le importazioni dirette dell’SDK, usa i sottopercorsi di configurazione mirati invece del barrel di compatibilità ampio
`openclaw/plugin-sdk/config-runtime`: `config-contracts` per i
tipi, `plugin-config-runtime` per le asserzioni sulla configurazione già caricata e la ricerca della voce del Plugin, `runtime-config-snapshot` per gli snapshot del processo corrente, e
`config-mutation` per le scritture. I test dei Plugin in bundle dovrebbero simulare direttamente questi sottopercorsi mirati invece di simulare il barrel di compatibilità ampio.
Il codice runtime interno di OpenClaw segue la stessa direzione: carica la configurazione una volta al confine CLI, Gateway o processo, poi passa quel valore lungo il flusso. Le scritture di mutazione riuscite aggiornano lo snapshot runtime del processo e avanzano la sua revisione interna; le cache a lunga durata dovrebbero basarsi sulla chiave di cache posseduta dal runtime invece di serializzare localmente la configurazione. I moduli runtime a lunga durata hanno uno scanner a tolleranza zero per le chiamate ambientali a `loadConfig()`; usa un `cfg` passato, un `context.getRuntimeConfig()` della richiesta, oppure `getRuntimeConfig()` a un confine di processo esplicito.
I percorsi di esecuzione provider e canale devono usare lo snapshot della configurazione runtime attiva, non uno snapshot del file restituito per la rilettura o la modifica della configurazione. Gli snapshot dei file preservano valori sorgente come i marker SecretRef per UI e scritture; le callback provider richiedono la vista runtime risolta. Quando un helper può essere chiamato con lo snapshot sorgente attivo o con lo snapshot runtime attivo, passa tramite `selectApplicableRuntimeConfig()` prima di leggere le credenziali.
## Utilità runtime riutilizzabili
Usa i fatti `botLoopProtection` in ingresso per i messaggi in ingresso creati da bot. Il core applica la guardia condivisa in memoria a finestra scorrevole prima della registrazione e dell’invio della sessione, senza legare la policy a un singolo canale. La guardia traccia chiavi `(scopeId, conversationId, participant pair)`, conta insieme entrambe le direzioni di una coppia, applica un periodo di raffreddamento quando il budget della finestra viene superato, e pota opportunisticamente le voci inattive.
I Plugin di canale che espongono questo comportamento agli operatori dovrebbero preferire la forma condivisa `channels.defaults.botLoopProtection` per i budget di base, poi sovrapporre override specifici per canale/provider. La configurazione condivisa usa i secondi perché è visibile all’utente:
```typescript
type ChannelBotLoopProtectionConfig = {
enabled?: boolean;
maxEventsPerWindow?: number;
windowSeconds?: number;
cooldownSeconds?: number;
};
```
Passa i fatti normalizzati della coppia di bot con il turno risolto. Il core risolve predefiniti, conversione delle unità e semantica di `enabled`:
```typescript
return {
channel: "example",
routeSessionKey,
storePath,
ctxPayload,
recordInboundSession,
runDispatch,
botLoopProtection: {
scopeId: "account-1",
conversationId: "channel-1",
senderId: "bot-a",
receiverId: "bot-b",
config: channelConfig.botLoopProtection,
defaultsConfig: runtimeConfig.channels?.defaults?.botLoopProtection,
defaultEnabled: allowBotsMode !== "off",
},
};
```
Usa direttamente `openclaw/plugin-sdk/pair-loop-guard-runtime` solo per loop di eventi personalizzati a due parti che non passano dal runner condiviso delle risposte in ingresso.
## Spazi dei nomi runtime
Identità dell’agente, directory e gestione delle sessioni.
```typescript
// Resolve the agent's working directory
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
// Resolve agent workspace
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
// Get agent identity
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
// Get default thinking level
const thinking = api.runtime.agent.resolveThinkingDefault({
cfg,
provider,
model,
});
// Validate a user-provided thinking level against the active provider profile
const policy = api.runtime.agent.resolveThinkingPolicy({ provider, model });
const level = api.runtime.agent.normalizeThinkingLevel("extra high");
if (level && policy.levels.some((entry) => entry.id === level)) {
// pass level to an embedded run
}
// Get agent timeout
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
// Ensure workspace exists
await api.runtime.agent.ensureAgentWorkspace(cfg);
// Run an embedded agent turn
const result = await api.runtime.agent.runEmbeddedAgent({
sessionId: "my-plugin:task-1",
runId: crypto.randomUUID(),
workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
prompt: "Summarize the latest changes",
timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
});
```
`runEmbeddedAgent(...)` è l’helper neutro per avviare un normale turno agente OpenClaw dal codice del Plugin. Usa la stessa risoluzione provider/modello e la stessa selezione dell’harness agente delle risposte attivate dai canali.
`runEmbeddedPiAgent(...)` resta un alias di compatibilità deprecato per i Plugin esistenti. Il nuovo codice dovrebbe usare `runEmbeddedAgent(...)`.
`resolveThinkingPolicy(...)` restituisce i livelli di ragionamento supportati dal provider/modello e il valore predefinito opzionale. I Plugin provider possiedono il profilo specifico del modello tramite i loro hook di ragionamento, quindi i Plugin strumento dovrebbero chiamare questo helper runtime invece di importare o duplicare elenchi di provider.
`normalizeThinkingLevel(...)` converte testo utente come `on`, `x-high` o `extra high` nel livello canonico memorizzato prima di verificarlo rispetto alla policy risolta.
Gli **helper dell’archivio sessioni** sono sotto `api.runtime.agent.session`:
```typescript
const entry = api.runtime.agent.session.getSessionEntry({ agentId, sessionKey });
for (const { sessionKey, entry } of api.runtime.agent.session.listSessionEntries({ agentId })) {
// Iterate session rows without depending on the legacy sessions.json shape.
}
await api.runtime.agent.session.patchSessionEntry({
agentId,
sessionKey,
update: (entry) => ({ thinkingLevel: "high" }),
});
const storePath = api.runtime.agent.session.resolveStorePath(cfg.session?.store, { agentId });
await api.runtime.agent.session.runWithWorkAdmission(
{ storePath, sessionKey },
async (signal) => {
// Create or update the session, then pass signal to the admitted agent run.
},
);
```
Preferisci `getSessionEntry(...)`, `listSessionEntries(...)`, `patchSessionEntry(...)` o `upsertSessionEntry(...)` per i workflow di sessione. Questi helper indirizzano le sessioni per identità agente/sessione, così i Plugin non dipendono dalla forma di archiviazione legacy `sessions.json`. Usa `preserveActivity: true` per patch di soli metadati che non devono aggiornare l’attività della sessione, e `replaceEntry: true` solo quando la callback restituisce una voce completa e i campi eliminati devono restare eliminati.
Usa `runWithWorkAdmission(...)` quando un Plugin avvia lavoro su una sessione persistente. La callback rifiuta sessioni archiviate o sostituite simultaneamente, mantiene coordinate le mutazioni di archiviazione/reimpostazione/eliminazione fino al completamento e riceve un `AbortSignal` che deve essere inoltrato all’esecuzione dell’agente.
Per letture e scritture della trascrizione, importa `openclaw/plugin-sdk/session-transcript-runtime` e usa `resolveSessionTranscriptIdentity(...)`, `resolveSessionTranscriptTarget(...)`, `readSessionTranscriptEvents(...)`, `appendSessionTranscriptMessageByIdentity(...)`, `publishSessionTranscriptUpdateByIdentity(...)` o `withSessionTranscriptWriteLock(...)` con `{ agentId, sessionKey, sessionId }`. Queste API permettono ai Plugin di identificare una trascrizione, leggerne gli eventi, aggiungere messaggi, pubblicare aggiornamenti ed eseguire operazioni correlate sotto lo stesso lock di scrittura della trascrizione. Passare `sessionFile`, usare `resolveSessionTranscriptLegacyFileTarget(...)` o importare `appendSessionTranscriptMessage(...)` / `emitSessionTranscriptUpdate(...)` di basso livello da `openclaw/plugin-sdk/agent-harness-runtime` è deprecato; quei percorsi esistono solo per codice legacy che riceve già un artefatto di trascrizione attivo.
`loadSessionStore(...)`, `saveSessionStore(...)`, `updateSessionStore(...)`, `resolveSessionFilePath(...)` e `resolveAndPersistSessionFile(...)` sono helper di compatibilità deprecati per Plugin che dipendono ancora intenzionalmente dalla forma legacy dell’intero archivio o del file di trascrizione. Il nuovo codice Plugin non deve usare questi helper, e i chiamanti esistenti dovrebbero migrare agli helper di voce e agli helper di identità della trascrizione.
Costanti predefinite di modello e provider:
```typescript
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"
```
Esegui un completamento testuale posseduto dall’host senza importare elementi interni del provider né duplicare la preparazione di modello/autenticazione/URL di base di OpenClaw.
```typescript
const result = await api.runtime.llm.complete({
messages: [{ role: "user", content: "Summarize this transcript." }],
purpose: "my-plugin.summary",
maxTokens: 512,
temperature: 0.2,
});
```
L’helper usa lo stesso percorso di preparazione dei completamenti semplici del runtime integrato di OpenClaw e lo snapshot della configurazione runtime posseduto dall’host. I motori di contesto ricevono una capacità `llm.complete` vincolata alla sessione, quindi le chiamate al modello usano l’agente della sessione attiva e non ricadono silenziosamente sull’agente predefinito. Il risultato include attribuzione provider/modello/agente più utilizzo normalizzato di token, cache e costo stimato quando disponibile.
Le sostituzioni del modello richiedono l'opt-in dell'operatore tramite `plugins.entries..llm.allowModelOverride: true` nella configurazione. Usa `plugins.entries..llm.allowedModels` per limitare i plugin attendibili a specifici target canonici `provider/model`. I completamenti tra agenti richiedono `plugins.entries..llm.allowAgentIdOverride: true`.
Avvia e gestisci esecuzioni di subagenti in background.
```typescript
// Start a subagent run
const { runId } = await api.runtime.subagent.run({
sessionKey: "agent:main:subagent:search-helper",
message: "Expand this query into focused follow-up searches.",
provider: "openai", // optional override
model: "gpt-4.1-mini", // optional override
deliver: false,
});
// Wait for completion
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });
// Read session messages
const { messages } = await api.runtime.subagent.getSessionMessages({
sessionKey: "agent:main:subagent:search-helper",
limit: 10,
});
// Delete a session
await api.runtime.subagent.deleteSession({
sessionKey: "agent:main:subagent:search-helper",
});
```
Le sostituzioni del modello (`provider`/`model`) richiedono l'opt-in dell'operatore tramite `plugins.entries..subagent.allowModelOverride: true` nella configurazione. I plugin non attendibili possono comunque eseguire subagenti, ma le richieste di sostituzione vengono rifiutate.
`deleteSession(...)` può eliminare sessioni create dallo stesso plugin tramite `api.runtime.subagent.run(...)`. L'eliminazione di sessioni utente o operatore arbitrarie richiede comunque una richiesta Gateway con ambito amministratore.
Elenca i nodi connessi e invoca un comando ospitato su un nodo dal codice del plugin caricato dal Gateway o dai comandi CLI del plugin. Usa questa opzione quando un plugin gestisce lavoro locale su un dispositivo associato, ad esempio un bridge browser o audio su un altro Mac.
```typescript
const { nodes } = await api.runtime.nodes.list({ connected: true });
const result = await api.runtime.nodes.invoke({
nodeId: "mac-studio",
command: "my-plugin.command",
params: { action: "start" },
timeoutMs: 30000,
});
```
Dentro il Gateway questo runtime è in-process. Nei comandi CLI del plugin chiama il Gateway configurato tramite RPC, quindi comandi come `openclaw googlemeet recover-tab` possono ispezionare i nodi associati dal terminale. I comandi dei nodi passano comunque attraverso il normale abbinamento dei nodi del Gateway, le allowlist dei comandi, le policy di invocazione dei nodi dei plugin e la gestione dei comandi locale al nodo.
I plugin che espongono comandi per host di nodo pericolosi dovrebbero registrare una policy di invocazione dei nodi con `api.registerNodeInvokePolicy(...)`. La policy viene eseguita nel Gateway dopo i controlli della allowlist dei comandi e prima che il comando venga inoltrato al nodo, quindi le chiamate dirette `node.invoke` e gli strumenti plugin di livello superiore condividono lo stesso percorso di applicazione.
Il campo opzionale `scopes` richiede ambiti operatore del Gateway per l'invocazione. OpenClaw lo rispetta solo per i plugin in bundle e per le installazioni attendibili di plugin ufficiali; le richieste da altri plugin non elevano la chiamata. Usalo solo quando un plugin attendibile deve invocare un comando di nodo con un ambito Gateway più rigoroso, come `operator.admin`.
Associa un runtime Task Flow a una chiave di sessione OpenClaw esistente o a un contesto di strumento attendibile, quindi crea e gestisci Task Flow senza passare un proprietario a ogni chiamata.
Task Flow tiene traccia dello stato durevole di workflow in più passaggi. Non è uno scheduler:
usa Cron o `api.session.workflow.scheduleSessionTurn(...)` per risvegli futuri,
quindi usa `managedFlows` dal turno pianificato quando quel lavoro
richiede stato del flow, attività figlie, attese o annullamento.
```typescript
const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
const created = taskFlow.createManaged({
controllerId: "my-plugin/review-batch",
goal: "Review new pull requests",
});
const child = taskFlow.runTask({
flowId: created.flowId,
runtime: "acp",
childSessionKey: "agent:main:subagent:reviewer",
task: "Review PR #123",
status: "running",
startedAt: Date.now(),
});
const waiting = taskFlow.setWaiting({
flowId: created.flowId,
expectedRevision: created.revision,
currentStep: "await-human-reply",
waitJson: { kind: "reply", channel: "telegram" },
});
```
Usa `bindSession({ sessionKey, requesterOrigin })` quando hai già una chiave di sessione OpenClaw attendibile dal tuo livello di binding. Non eseguire il binding da input utente grezzo.
Sintesi text-to-speech.
```typescript
// Standard TTS
const clip = await api.runtime.tts.textToSpeech({
text: "Hello from OpenClaw",
cfg: api.config,
});
// Telephony-optimized TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
text: "Hello from OpenClaw",
cfg: api.config,
});
// List available voices
const voices = await api.runtime.tts.listVoices({
provider: "elevenlabs",
cfg: api.config,
});
```
Usa la configurazione core `messages.tts` e la selezione del provider. Restituisce buffer audio PCM + frequenza di campionamento.
Analisi di immagini, audio e video.
```typescript
// Describe an image
const image = await api.runtime.mediaUnderstanding.describeImageFile({
filePath: "/tmp/inbound-photo.jpg",
cfg: api.config,
agentDir: "/tmp/agent",
});
// Transcribe audio
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
filePath: "/tmp/inbound-audio.ogg",
cfg: api.config,
mime: "audio/ogg", // optional, for when MIME cannot be inferred
});
// Describe a video
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
filePath: "/tmp/inbound-video.mp4",
cfg: api.config,
});
// Generic file analysis
const result = await api.runtime.mediaUnderstanding.runFile({
filePath: "/tmp/inbound-file.pdf",
cfg: api.config,
});
// Structured image extraction through a specific provider/model.
// Include at least one image; text inputs are supplemental context.
const evidence = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
provider: "codex",
model: "gpt-5.5",
input: [
{
type: "image",
buffer: receiptImageBuffer,
fileName: "receipt.png",
mime: "image/png",
},
{ type: "text", text: "Prefer the printed total over handwritten notes." },
],
instructions: "Extract vendor, total, and searchable tags.",
schemaName: "receipt.evidence",
jsonSchema: {
type: "object",
properties: {
vendor: { type: "string" },
total: { type: "number" },
tags: { type: "array", items: { type: "string" } },
},
required: ["vendor", "total"],
},
cfg: api.config,
});
```
Restituisce `{ text: undefined }` quando non viene prodotto alcun output (ad esempio input saltato).
`api.runtime.stt.transcribeAudioFile(...)` rimane un alias di compatibilità per `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
Generazione di immagini.
```typescript
const result = await api.runtime.imageGeneration.generate({
prompt: "A robot painting a sunset",
cfg: api.config,
});
const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });
```
Ricerca web.
```typescript
const providers = api.runtime.webSearch.listProviders({ config: api.config });
const result = await api.runtime.webSearch.search({
config: api.config,
args: { query: "OpenClaw plugin SDK", count: 5 },
});
```
Utility multimediali di basso livello.
```typescript
const webMedia = await api.runtime.media.loadWebMedia(url);
const mime = await api.runtime.media.detectMime(buffer);
const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "image"
const isVoice = api.runtime.media.isVoiceCompatibleAudio(filePath);
const metadata = await api.runtime.media.getImageMetadata(filePath);
const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });
const terminalQr = await api.runtime.media.renderQrTerminal("https://openclaw.ai");
const pngQr = await api.runtime.media.renderQrPngBase64("https://openclaw.ai", {
scale: 6, // 1-12
marginModules: 4, // 0-16
});
const pngQrDataUrl = await api.runtime.media.renderQrPngDataUrl("https://openclaw.ai");
const tmpRoot = resolvePreferredOpenClawTmpDir();
const pngQrFile = await api.runtime.media.writeQrPngTempFile("https://openclaw.ai", {
tmpRoot,
dirPrefix: "my-plugin-qr-",
fileName: "qr.png",
});
```
Snapshot della configurazione runtime corrente e scritture transazionali della configurazione. Preferisci
la configurazione che era già stata passata nel percorso di chiamata attivo; usa
`current()` solo quando il gestore ha bisogno direttamente dello snapshot del processo.
```typescript
const cfg = api.runtime.config.current();
await api.runtime.config.mutateConfigFile({
afterWrite: { mode: "auto" },
mutate(draft) {
draft.plugins ??= {};
},
});
```
`mutateConfigFile(...)` e `replaceConfigFile(...)` restituiscono un valore `followUp`,
ad esempio `{ mode: "restart", requiresRestart: true, reason }`,
che registra l'intento dell'autore della scrittura senza sottrarre il controllo del riavvio al
gateway.
Utility a livello di sistema.
```typescript
await api.runtime.system.enqueueSystemEvent(event);
api.runtime.system.requestHeartbeat({
source: "other",
intent: "event",
reason: "plugin-event",
});
api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // Deprecated compatibility alias.
const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
const hint = api.runtime.system.formatNativeDependencyHint(pkg);
```
`runCommandWithTimeout(...)` restituisce `stdout` e `stderr` catturati, conteggi opzionali
di troncamento, `code`, `signal`, `killed`, `termination` e
`noOutputTimedOut`. I risultati di timeout e timeout per assenza di output riportano `code: 124`
quando il processo figlio non fornisce un codice di uscita diverso da zero. Le uscite per segnale
non dovute a timeout possono comunque restituire `code: null`, quindi usa `termination` e
`noOutputTimedOut` per distinguere i motivi del timeout.
Sottoscrizioni agli eventi.
```typescript
api.runtime.events.onAgentEvent((event) => {
/* ... */
});
api.runtime.events.onSessionTranscriptUpdate((update) => {
/* ... */
});
```
Logging.
```typescript
const verbose = api.runtime.logging.shouldLogVerbose();
const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });
```
Risoluzione dell'autenticazione di modello e provider.
```typescript
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
provider: "openai",
cfg,
});
```
Risoluzione della directory di stato e archiviazione a chiave basata su SQLite.
```typescript
const stateDir = api.runtime.state.resolveStateDir(process.env);
const store = api.runtime.state.openKeyedStore({
namespace: "my-feature",
maxEntries: 200,
defaultTtlMs: 15 * 60_000,
});
await store.register("key-1", { value: "hello" });
const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" });
const value = await store.lookup("key-1");
await store.consume("key-1");
await store.clear();
```
Gli store a chiave sopravvivono ai riavvii e sono isolati dall'id del Plugin vincolato al runtime. Usa `registerIfAbsent(...)` per rivendicazioni atomiche di deduplicazione: restituisce `true` quando la chiave era assente o scaduta ed è stata registrata, oppure `false` quando esiste già un valore attivo senza sovrascriverne valore, ora di creazione o TTL. Limiti: `maxEntries` per namespace, 6.000 righe attive per Plugin, valori JSON inferiori a 64 KB e scadenza TTL opzionale. Quando una scrittura supererebbe il limite di righe del Plugin, il runtime può espellere le righe attive meno recenti dal namespace in scrittura; i namespace fratelli non vengono espulsi per quella scrittura, e la scrittura fallisce comunque se il namespace non può liberare abbastanza righe.
Solo Plugin inclusi in questa release.
Factory degli strumenti di memoria e CLI.
```typescript
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);
```
Helper runtime specifici del canale (disponibili quando viene caricato un Plugin di canale).
`api.runtime.channel.media` è la superficie preferita per download e archiviazione dei media del canale:
```typescript
const saved = await api.runtime.channel.media.saveRemoteMedia({
url,
subdir: "inbound",
maxBytes,
filePathHint: fileName,
});
```
Usa `saveRemoteMedia(...)` quando un URL remoto deve diventare un media OpenClaw. Usa `saveResponseMedia(...)` quando il Plugin ha già recuperato una `Response` con gestione dell'autenticazione, dei reindirizzamenti o dell'allowlist di proprietà del Plugin. Usa `readRemoteMediaBuffer(...)` solo quando il Plugin ha bisogno dei byte grezzi per ispezione, trasformazioni, decrittazione o ricaricamento. `fetchRemoteMedia(...)` rimane un alias di compatibilità deprecato per `readRemoteMediaBuffer(...)`.
`api.runtime.channel.mentions` è la superficie condivisa per le policy di menzione in ingresso per i Plugin di canale inclusi che usano l'iniezione runtime:
```typescript
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
mentionRegexes,
mentionPatterns,
});
const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
facts: {
canDetectMention: true,
wasMentioned: mentionMatch.matched,
implicitMentionKinds: api.runtime.channel.mentions.implicitMentionKindWhen(
"reply_to_bot",
isReplyToBot,
),
},
policy: {
isGroup,
requireMention,
allowTextCommands,
hasControlCommand,
commandAuthorized,
},
});
```
Helper di menzione disponibili:
- `buildMentionRegexes`
- `matchesMentionPatterns`
- `matchesMentionWithExplicit`
- `implicitMentionKindWhen`
- `resolveInboundMentionDecision`
`api.runtime.channel.mentions` intenzionalmente non espone i vecchi helper di compatibilità `resolveMentionGating*`. Preferisci il percorso normalizzato `{ facts, policy }`.
## Archiviazione dei riferimenti runtime
Usa `createPluginRuntimeStore` per archiviare il riferimento runtime da usare al di fuori della callback `register`:
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
const store = createPluginRuntimeStore({
pluginId: "my-plugin",
errorMessage: "my-plugin runtime not initialized",
});
```
```typescript
export default defineChannelPluginEntry({
id: "my-plugin",
name: "My Plugin",
description: "Example",
plugin: myPlugin,
setRuntime: store.setRuntime,
});
```
```typescript
export function getRuntime() {
return store.getRuntime(); // throws if not initialized
}
export function tryGetRuntime() {
return store.tryGetRuntime(); // returns null if not initialized
}
```
Preferisci `pluginId` per l'identità dello store runtime. La forma di livello inferiore `key` è destinata ai casi non comuni in cui un Plugin necessita intenzionalmente di più di uno slot runtime.
## Altri campi `api` di livello superiore
Oltre a `api.runtime`, l'oggetto API fornisce anche:
Id del Plugin.
Nome visualizzato del Plugin.
Snapshot della configurazione corrente (snapshot runtime attivo in memoria quando disponibile).
Configurazione specifica del Plugin da `plugins.entries..config`.
Logger con ambito (`debug`, `info`, `warn`, `error`).
Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/configurazione precedente all'entry completa.
Risolve un percorso relativo alla radice del Plugin.
## Correlati
- [Interni dei Plugin](/it/plugins/architecture) — modello di capability e registro
- [Entry point SDK](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry`
- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento ai subpath