Helper di runtime Plugin

Identità dell’agente, directory e gestione delle sessioni.

// Resolve the agent's working directoryconst agentDir = api.runtime.agent.resolveAgentDir(cfg); // Resolve agent workspaceconst workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg); // Get agent identityconst identity = api.runtime.agent.resolveAgentIdentity(cfg); // Get default thinking levelconst thinking = api.runtime.agent.resolveThinkingDefault({  cfg,  provider,  model,}); // Validate a user-provided thinking level against the active provider profileconst 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 timeoutconst timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); // Ensure workspace existsawait api.runtime.agent.ensureAgentWorkspace(cfg); // Run an embedded agent turnconst 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.

Avvia e gestisci esecuzioni di subagenti in background.

// Start a subagent runconst { 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 completionconst result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); // Read session messagesconst { messages } = await api.runtime.subagent.getSessionMessages({  sessionKey: "agent:main:subagent:search-helper",  limit: 10,}); // Delete a sessionawait api.runtime.subagent.deleteSession({  sessionKey: "agent:main:subagent:search-helper",});

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.

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 TTSconst clip = await api.runtime.tts.textToSpeech({  text: "Hello from OpenClaw",  cfg: api.config,}); // Telephony-optimized TTSconst telephonyClip = await api.runtime.tts.textToSpeechTelephony({  text: "Hello from OpenClaw",  cfg: api.config,}); // List available voicesconst 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 imageconst image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); // Transcribe audioconst { 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 videoconst video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); // Generic file analysisconst 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).

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.

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 }.