Vai al contenuto principale
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.

Channel plugins

Guida passo per passo che usa questi helper nel contesto dei Plugin di canale.

Provider plugins

Guida passo per passo che usa questi helper nel contesto dei Plugin provider.
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: 
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: 
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.
// 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:
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:
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.
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.<id>.llm.allowModelOverride: true nella configurazione. Usa plugins.entries.<id>.llm.allowedModels per limitare i plugin attendibili a specifici target canonici provider/model. I completamenti tra agenti richiedono plugins.entries.<id>.llm.allowAgentIdOverride: true.
Avvia e gestisci esecuzioni di subagenti in background.
// 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.<id>.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.
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.
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.
// 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.
// 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.
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.
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.
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.
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.
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.
api.runtime.events.onAgentEvent((event) => {
  /* ... */
});
api.runtime.events.onSessionTranscriptUpdate((update) => {
  /* ... */
});
Logging.
const verbose = api.runtime.logging.shouldLogVerbose();
const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });
Risoluzione dell’autenticazione di modello e provider.
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.
const stateDir = api.runtime.state.resolveStateDir(process.env);
const store = api.runtime.state.openKeyedStore<MyRecord>({
  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.
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:
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:
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:
1

Crea lo store

import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "my-plugin",
  errorMessage: "my-plugin runtime not initialized",
});
2

Collega all'entry point

export default defineChannelPluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Example",
  plugin: myPlugin,
  setRuntime: store.setRuntime,
});
3

Accedi da altri file

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:
​
api.id
string
Id del Plugin.
​
api.name
string
Nome visualizzato del Plugin.
​
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.logger
PluginLogger
Logger con ambito (debug, info, warn, error).
​
api.registrationMode
PluginRegistrationMode
Modalità di caricamento corrente; "setup-runtime" è la finestra leggera di avvio/configurazione precedente all’entry completa.
​
api.resolvePath(input)
(string) => string
Risolve un percorso relativo alla radice del Plugin.

​
Correlati