Runtimehelpers voor Plugins

Agentidentiteit, mappen en sessiebeheer.

// De werkmap van de agent bepalen (agentId is vereist)const agentDir = api.runtime.agent.resolveAgentDir(cfg, agentId); // De agentwerkruimte bepalenconst workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId); // De agentidentiteit ophalenconst identity = api.runtime.agent.resolveAgentIdentity(cfg); // Het standaard denkniveau ophalenconst thinking = api.runtime.agent.resolveThinkingDefault({  cfg,  provider,  model,}); // Een door de gebruiker opgegeven denkniveau valideren aan de hand van het actieve providerprofielconst policy = api.runtime.agent.resolveThinkingPolicy({ provider, model });const level = api.runtime.agent.normalizeThinkingLevel("extra high");if (level && policy.levels.some((entry) => entry.id === level)) {  // niveau doorgeven aan een ingebedde uitvoering} // De time-out van de agent ophalenconst timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); // Controleren of de werkruimte bestaatawait api.runtime.agent.ensureAgentWorkspace(cfg); // Een ingebedde agentbeurt uitvoerenconst result = await api.runtime.agent.runEmbeddedAgent({  sessionId: "my-plugin:task-1",  runId: crypto.randomUUID(),  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId),  prompt: "Vat de meest recente wijzigingen samen",  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),});

runEmbeddedAgent(...) is de neutrale helper om vanuit plugincode een normale OpenClaw-agentbeurt te starten. Deze gebruikt dezelfde provider-/modelresolutie en selectie van de agentharness als antwoorden die door kanalen worden geactiveerd.

runEmbeddedPiAgent(...) blijft bestaan als verouderde compatibiliteitsalias voor bestaande plugins. Nieuwe code moet runEmbeddedAgent(...) gebruiken.

resolveCliBackendDispatchEligibility({ provider, model, agentId, authProfileId, config, agentDir, workspaceDir }) deelt de dispatchbeslissing van de CLI-backend van de ingebedde runner (route, de door de backend gedeclareerde subscriptionAuthDispatch-mogelijkheid, opgeslagen modus voor inloggegevens — met inachtneming van een expliciet vastgezette authProfileId) met aanroepers die ingebedde uitvoeringen aanmelden voor cliBackendDispatch: "subscription-auth". Het retourneert { provider } wanneer de uitvoering via de CLI-backend zou plaatsvinden en undefined wanneer deze op de rechtstreekse passthrough blijft, zodat aanroepers time-outs kunnen begroten voor de uitvoering die daadwerkelijk zal plaatsvinden.

resolveThinkingPolicy(...) retourneert de ondersteunde denkniveaus en optionele standaardwaarde van de provider/het model. Providerplugins beheren het modelspecifieke profiel via hun denkhooks, dus toolplugins moeten deze runtimehelper aanroepen in plaats van providerlijsten te importeren of dupliceren.

normalizeThinkingLevel(...) zet gebruikerstekst zoals on, x-high of extra high om naar het canonieke opgeslagen niveau voordat dit aan het opgeloste beleid wordt getoetst.

Helpers voor de sessieopslag staan onder api.runtime.agent.session:

const entry = api.runtime.agent.session.getSessionEntry({ agentId, sessionKey });for (const { sessionKey, entry } of api.runtime.agent.session.listSessionEntries({ agentId })) {  // Sessierijen doorlopen zonder afhankelijk te zijn van de verouderde sessions.json-structuur.}await api.runtime.agent.session.patchSessionEntry({  agentId,  sessionKey,  update: (entry) => ({ thinkingLevel: "high" }),}); const created = await api.runtime.agent.session.createSessionEntry({  cfg,  key: "agent:main:my-plugin:task-1",  initialEntry: {    agentHarnessId: "my-harness",    modelSelectionLocked: true,    pluginExtensions: { "my-plugin": { phase: "initializing" } },  },  afterCreate: async () => ({    pluginExtensions: { "my-plugin": { phase: "ready" } },  }),}); const storePath = api.runtime.agent.session.resolveStorePath(cfg.session?.store, { agentId });await api.runtime.agent.session.runWithWorkAdmission(  { storePath, sessionKey },  async (signal) => {    // De sessie maken of bijwerken en vervolgens signal doorgeven aan de toegelaten agentuitvoering.  },);

Geef voor sessieworkflows de voorkeur aan getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) of upsertSessionEntry(...). Deze helpers adresseren sessies op basis van de agent-/sessie-identiteit, zodat plugins niet afhankelijk zijn van de verouderde sessions.json-opslagstructuur. Gebruik preserveActivity: true voor patches die alleen metadata bevatten en de sessieactiviteit niet mogen vernieuwen, en replaceEntry: true alleen wanneer de callback een volledige entry retourneert en verwijderde velden verwijderd moeten blijven. Doctor- en migratiepaden kunnen fallbackEntry, skipMaintenance en requireWriteSuccess combineren voor één atomair herstel van de canonieke opslag.

createSessionEntry(...) maakt een nieuwe canonieke sessierij en transcriptie. Het vertrouwde initialEntry-oppervlak is bewust beperkt: een niet-lege agentHarnessId, optionele modelSelectionLocked: true en optionele pluginExtensions. De geïnjecteerde runtime accepteert via registerAgentHarness(...) alleen harness-id's die eigendom zijn van de aanroepende plugin; dit is een eigendomsinvariant, geen sandbox tussen plugins binnen hetzelfde proces. Een bestaande rij wordt geweigerd; label en spawnedCwd zijn afzonderlijke aanmaakvelden in plaats van patches voor vertrouwde entries.

Tijdens het aanmaken blijft de mutatiebarrière voor de sessielevenscyclus via afterCreate actief, zodat nieuw werk wacht tot de initialisatie door de plugin is voltooid en reeds toegelaten werk ertoe leidt dat het aanmaken mislukt. De callback ontvangt een kloon van de aangemaakte status. Als deze een patch retourneert, mag die patch alleen pluginExtensions bevatten en is de waarde daarvan het volledige definitieve pluginExtensions-veld. Bij een fout in de callback of de definitieve persistentie worden de ongewijzigde nieuwe rij en transcriptie teruggedraaid; beveiligd terugdraaien behoudt een rij die gelijktijdig is gewijzigd of geclaimd. recoverMatchingInitialEntry: true is alleen bedoeld om een onderbroken initialisatie opnieuw te proberen wanneer de opgeslagen vertrouwde velden exact overeenkomen, en herstel vereist dat afterCreate een definitieve patch retourneert.

Gebruik runWithWorkAdmission(...) wanneer een plugin werk start op een opgeslagen sessie. De callback weigert gearchiveerde of gelijktijdig vervangen sessies, houdt archiverings-, reset- en verwijderingsmutaties gecoördineerd tot voltooiing en ontvangt een AbortSignal die aan de agentuitvoering moet worden doorgegeven. Een harness kan via het experimentele registratieveld delegatedExecutionPluginIds expliciet vertrouwde uitvoeringsgedelegeerden benoemen. Gedelegeerden kunnen alleen een exact bestaande, modelvergrendelde sessie toelaten en uitvoeren; alle sessiemutaties blijven beperkt tot de eigenaar van de harness. Zie Agentharness-plugins.

Onderhouds- en reparatieplugins kunnen deleteSessionEntry(...) gebruiken voor één sessie-item binnen een bepaald bereik, cleanupSessionLifecycleArtifacts(...) voor door de levenscyclus beheerde tijdelijke sessies en resolveSessionStoreBackupPaths(...) voordat een opslag wordt gewijzigd. Geef expectedSessionId en expectedUpdatedAt door wanneer verwijdering niet mag conflicteren met een gelijktijdige sessie-update; gebruik expectedSessionId: null wanneer de eerdere momentopname geen sessie-id had. Deze helpers zijn beperkte oppervlakken voor reparatie en levenscyclusbeheer, geen algemene API voor het verwijderen uit een opslag.

resolveStorePath(...) en updateSessionStoreEntry(...) completeren de sessiehelpers: resolveStorePath bepaalt het pad naar de sessieopslag voor een bepaald bereik en updateSessionStoreEntry({ storePath, sessionKey, update }) past één item rechtstreeks aan via het opslagpad wanneer de aanroeper dit al kent.

loadTranscriptEventsSync(...) is beschikbaar voor synchrone doctor- en reparatiepaden die de asynchrone transcriptruntime niet kunnen gebruiken. Deze retourneert onbewerkte SessionStoreTranscriptEvent-records. Normale runtimecode van plugins hoort bij voorkeur openclaw/plugin-sdk/session-transcript-runtime te gebruiken.

formatSqliteSessionFileMarker(...), parseSqliteSessionFileMarker(...) en sqliteSessionFileMarkerMatchesSession(...) zijn overgangshelpers voor code die nog steeds een verouderd veld met de naam sessionFile ontvangt. Een geparseerde SQLite-markering identificeert een actief SQLite-transcriptdoel; het is geen bestandssysteempad. Nieuwe API's horen getypeerde sessie-identiteit te gebruiken in plaats van markeringsreeksen.

Importeer voor het lezen en schrijven van transcripties openclaw/plugin-sdk/session-transcript-runtime en gebruik resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), readSessionTranscriptRawDelta(...), readSessionTranscriptVisibleMessageDelta(...), readVisibleSessionTranscriptMessageEntries(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) of withSessionTranscriptWriteLock(...) met { agentId, sessionKey, sessionId }. Met deze API's kunnen plugins een transcript identificeren, onbewerkte gebeurtenissen of zichtbare vertakkingsveilige berichtitems lezen, berichten toevoegen, updates publiceren en gerelateerde bewerkingen uitvoeren onder dezelfde schrijfvergrendeling van het transcript, zonder afhankelijk te zijn van actieve transcriptbestandspaden. readVisibleSessionTranscriptMessageEntries(...) retourneert geordende leesmetagegevens; het veld seq daarvan is geen hervatbare cursor.

appendSessionTranscriptMessageByIdentity(...) is een low-level toevoeging van een reeds canoniek bericht. Plugins mogen geen gebruikersrijen met media samenstellen met MediaPath, MediaPaths, MediaUrl, MediaUrls, MediaType of MediaTypes op het hoogste niveau. Binnenkomende kanaalgegevens horen geordende feiten via MsgContext.media door te geven en de host de persistentie van gebruikersbeurten te laten beheren. Een door de host voorbereid persistent gebruikersbericht bevat canonieke geordende feiten onder message.__openclaw.media; de algemene toevoeg-API leidt verouderde parallelle arrays niet af en repareert ze niet.

readSessionTranscriptRawDelta(...) retourneert een begrensd resultaat van het type page, reset of missing. Geef de ondoorzichtige page.cursor door aan de volgende aanroep. Zuivere toevoegingen behouden de cursor, terwijl vervanging van het transcript reset retourneert met een nieuwe opstartcursor. Pagina's bevatten standaard 1,000 gebeurtenissen en 1,000,000 geserialiseerde bytes; aanroepers kunnen maximaal 10,000 gebeurtenissen en 64 MiB aanvragen. Wanneer alleen de volgende gebeurtenis al groter is dan maxBytes, is de pagina leeg en rapporteert deze requiredBytes; probeer het opnieuw met ten minste die bytelimiet wanneer deze niet groter is dan 64 MiB. Grotere afzonderlijke gebeurtenissen vereisen de API voor volledig lezen. Een cursor identificeert alleen een positie en verleent nooit toegang tot een andere sessie.

readSessionTranscriptVisibleMessageDelta(...) biedt dezelfde begrensde opstart-en-hervatstructuur voor de door de host beheerde actieve berichtprojectie. Deze retourneert berichten van oud naar nieuw, zodat contextengines de initiële geschiedenis kunnen verwerken en de ondoorzichtige cursor als hun watermerk kunnen opslaan. Sla de cursor ongewijzigd op en retourneer deze ongewijzigd; het is een aanwijzing om door te gaan, geen autorisatiereferentie. Lineaire toevoegingen worden hervat na het laatst geretourneerde bericht. Vervanging van het transcript, een cursor waarvan het anker de actieve vertakking heeft verlaten of daarbinnen is verplaatst, onjuist gevormde cursors en cursors van andere sessies retourneren reset met een nieuwe opstartcursor. De standaardwaarden en limieten voor aantal en bytes komen overeen met de onbewerkte delta-API. Terwijl de actieve projectie na een wijziging van vertakking opnieuw wordt opgebouwd, is het resultaat unavailable met reden projection_rebuilding; probeer het later opnieuw in plaats van terug te vallen op een actief transcriptbestand.

De verouderde helpers voor de volledige opslag en actieve transcriptbestanden worden niet meer geëxporteerd vanuit de plugin-SDK. Gebruik de helpers voor items binnen een bepaald bereik voor sessiemetagegevens en de helpers voor transcriptidentiteit voor bewerkingen op actieve transcripties. Archief- en ondersteuningsworkflows die bestandsartefacten nodig hebben, horen hun eigen archiefoppervlakken te gebruiken in plaats van runtime-API's voor actieve sessies.

Standaardconstanten voor model en provider:

const model = api.runtime.agent.defaults.model; // bijv. "gpt-5.6-sol"const provider = api.runtime.agent.defaults.provider; // bijv. "openai"

Voer een door de host beheerde tekstaanvulling uit zonder interne provideronderdelen te importeren of de voorbereiding van OpenClaw voor model, authenticatie en basis-URL te dupliceren.

const result = await api.runtime.llm.complete({  messages: [{ role: "user", content: "Vat dit transcript samen." }],  purpose: "my-plugin.summary",  maxTokens: 512,  temperature: 0.2,  reasoning: "high",});

Providerorkestratie kan ook de geconfigureerde levenscyclus van de lokale service verkrijgen voordat een HTTP-aanvraag wordt verzonden:

const lease = await api.runtime.llm.acquireLocalService(  {    providerId,    baseUrl,    headers,  },  signal,);try {  // Verzend en verwerk de provideraanvraag volledig.} finally {  await lease?.release();}

acquireLocalService(...) is een stabiel, algemeen SDK-contract voor providerservices. De host bepaalt de procesconfiguratie vanuit models.providers.<providerId>.localService; aanroepers kunnen geen opdracht, argumenten, omgeving of levenscyclusbeleid opgeven. Het starten van processen, gereedheidscontrole, diagnostiek en het beleid voor stoppen bij inactiviteit blijven intern voor de host.

Geef de exact geconfigureerde provider-id en de bepaalde basis-URL voor aanvragen door. Vervang aliassen niet door een adapter-id: afzonderlijke aliassen kunnen naar afzonderlijke lokale GPU-hosts verwijzen. De host weigert eindpunten die niet overeenkomen met de geconfigureerde basis-URL van de provider, afgezien van de normalisatie /v1 die door Ollama- en LM Studio-adapters wordt gebruikt. De host beheert serialisatie bij het opstarten, gereedheidscontroles, aanvraagleases, afbreekverwerking en afsluiting bij inactiviteit.

De helper gebruikt hetzelfde eenvoudige voorbereidingspad voor aanvullingen als de ingebouwde runtime van OpenClaw en de door de host beheerde momentopname van de runtimeconfiguratie. Contextengines ontvangen een aan een sessie gebonden llm.complete-mogelijkheid, zodat modelaanroepen de agent van de actieve sessie gebruiken en niet stilzwijgend terugvallen op de standaardagent. Het resultaat bevat toeschrijving aan provider, model en agent, plus genormaliseerd token-, cache- en geschat kostengebruik wanneer beschikbaar.

Stel reasoning in om een redeneerinspanning voor het geselecteerde model aan te vragen. De host normaliseert de canonieke denkniveaus (off, minimal, low, medium, high, xhigh, adaptive, max en ultra) voor de geselecteerde provider en het geselecteerde model voordat de aanvulling wordt verzonden. adaptive wordt medium; max en ultra worden max indien ondersteund, en anders xhigh.

Roep een andere Gateway-methode binnen hetzelfde proces aan met behoud van de vertrouwde runtime- identiteit van de huidige plugin. Dit is bedoeld voor gebundelde of vertrouwde officiële plugins die plugin-eigen Gateway-mogelijkheden combineren zonder een WebSocket-loopbackverbinding te openen.

if (await api.runtime.gateway.isAvailable()) {  const result = await api.runtime.gateway.request<{ callId: string }>(    "voicecall.start",    { to: "+15550001234", mode: "conversation" },    { timeoutMs: 60_000 },  );}

Aanvragen gebruiken het bereik operator.write en verlenen geen beheerdersbereik. Aanroepen van willekeurige externe plugins worden geweigerd. Mislukte methoden werpen een GatewayClientRequestError en behouden gestructureerde details, metagegevens voor opnieuw proberen en de Gateway-foutcode voor herstelworkflows. Gebruik isAvailable() voordat je dit pad kiest vanuit tools die ook in zelfstandige agentprocessen kunnen worden uitgevoerd.

Start en beheer subagentuitvoeringen op de achtergrond.

// Start een subagentuitvoeringconst { runId } = await api.runtime.subagent.run({  sessionKey: "agent:main:subagent:search-helper",  message: "Werk deze zoekopdracht uit tot gerichte vervolgzoekopdrachten.",  toolsAlsoAllow: ["my_plugin_progress"],  provider: "openai", // optionele overschrijving  model: "gpt-5.6-sol", // optionele overschrijving  deliver: false,}); // Wacht op voltooiingconst result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); // Lees sessieberichtenconst { messages } = await api.runtime.subagent.getSessionMessages({  sessionKey: "agent:main:subagent:search-helper",  limit: 10,}); // Verwijder een sessieawait api.runtime.subagent.deleteSession({  sessionKey: "agent:main:subagent:search-helper",});

toolsAlsoAllow voegt exacte, uniek beheerde tools die door de aanroepende plugin zijn geregistreerd toe aan het normale tooloppervlak van de worker. De runtime weigert kerntools en namen die met een andere plugin worden gedeeld. Profielen en toolbeleid van de operator blijven van toepassing, inclusief expliciete toelatingslijsten en weigeringen.

deleteSession(...) kan sessies verwijderen die door dezelfde plugin via api.runtime.subagent.run(...) zijn aangemaakt. Voor het verwijderen van willekeurige gebruikers- of operatorsessies blijft een Gateway-aanvraag met beheerdersbereik vereist.

Inspecteer de effectieve bevoegdheid voor de sandboxwerkruimte van een agentsessie.

const authority = api.runtime.sandbox.resolveWorkspaceAuthority({  config: cfg,  agentId,  sessionKey,}); const liveAuthority = await api.runtime.sandbox.prepareWorkspaceAuthority({  config: cfg,  agentId,  sessionKey,  workspaceDir,  confinedToolNames: ["my_plugin_safe_tool"],});

Het resultaat meldt of deze sessie in een sandbox wordt uitgevoerd, of de werkruimte niet beschikbaar, alleen-lezen of beschrijfbaar is, en een optionele confinementError wanneer het effectieve Docker-, tool-, sessie-, browser- of verhoogde beleid aan die werkruimte kan ontsnappen. Gebruik dit voor door de host beheerde delegatiebeslissingen die een worker niet meer bevoegdheden mogen verlenen dan de aanroeper heeft. Het is een attestatiehelper, geen vervanging voor het controleren van de eigen autorisatie van de aanroeper.

prepareWorkspaceAuthority(...) voert dezelfde beleidscontrole uit en bereidt ook de Docker-sandbox voor workspaceDir voor. Deze weigert een actieve container waarvan de hash van de actuele configuratie niet overeenkomt met de aangevraagde koppelingen of het beleid. Geef alleen exacte toolnamen door waarvan de aanroepende plugin de geregistreerde implementaties begrenst; jokertekenvoorvoegsels bewijzen geen eigendom van tools.

Geef verbonden Nodes weer en roep een opdracht voor een Node-host aan vanuit door de Gateway geladen plugincode of vanuit CLI-opdrachten van een plugin. Gebruik dit wanneer een plugin lokaal werk op een gekoppeld apparaat beheert, bijvoorbeeld een browser- of audiobrug op een andere 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,});

nodes.list(...) bevat de geadverteerde nodePluginTools-beschrijvingen van elke verbonden Node wanneer die Node door plugins of MCP ondersteunde tools beschikbaar stelt aan de agent. Deze beschrijvingen vertegenwoordigen de actuele verbindingsstatus: de Gateway verwijdert ze wanneer de verbinding met de Node wordt verbroken, en een Node kan ze vervangen door node.pluginTools.update nadat de lokale plugin-/MCP-inventaris is gewijzigd.

Binnen de Gateway draait deze runtime in hetzelfde proces. In CLI-opdrachten van plugins roept deze de geconfigureerde Gateway aan via RPC, zodat opdrachten zoals openclaw googlemeet recover-tab gekoppelde Nodes vanuit de terminal kunnen inspecteren. Node-opdrachten verlopen nog steeds via de normale Node-koppeling van de Gateway, lijsten met toegestane opdrachten, beleidsregels voor Node-aanroepen door plugins en de lokale opdrachtafhandeling van de Node.

Plugins die door Nodes gehoste agenttools beschikbaar stellen, kunnen agentTool.defaultPlatforms instellen voor ongevaarlijke opdrachten die standaard moeten worden toegestaan. Laat dit weg wanneer operators zich expliciet moeten aanmelden met gateway.nodes.commands.allow. Gevaarlijke opdrachten op Node-hosts moeten een beleid voor Node-aanroepen registreren met api.registerNodeInvokePolicy(...); dit beleid wordt uitgevoerd in de Gateway nadat de lijst met toegestane opdrachten is gecontroleerd en voordat de opdracht naar de Node wordt doorgestuurd, zodat rechtstreekse node.invoke-aanroepen, door Nodes gehoste plugintools en plugintools op hoger niveau hetzelfde handhavingstraject delen.

Koppel de status van Task Flow en Task Run aan een bestaande OpenClaw-sessiesleutel of vertrouwde toolcontext.

• api.runtime.tasks.managedFlows kan mutaties uitvoeren: Task Flows maken, voortzetten en annuleren.
• api.runtime.tasks.flows en api.runtime.tasks.runs zijn alleen-lezen DTO-weergaven voor lijsten en statuszoekopdrachten; beide stellen bindSession(...) / fromToolContext(...) beschikbaar, plus get, list, findLatest en resolve.

Task Flow houdt duurzame workflowstatus met meerdere stappen bij. Het is geen planner: gebruik Cron of api.session.workflow.scheduleSessionTurn(...) voor toekomstige activeringen en gebruik vervolgens managedFlows vanuit de geplande beurt wanneer dat werk flowstatus, onderliggende taken, wachttijden of annulering nodig heeft.

const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); const created = taskFlow.createManaged({  controllerId: "my-plugin/review-batch",  goal: "Nieuwe pull requests beoordelen",}); const child = taskFlow.runTask({  flowId: created.flowId,  runtime: "acp",  childSessionKey: "agent:main:subagent:reviewer",  task: "PR #123 beoordelen",  status: "running",  startedAt: Date.now(),}); const waiting = taskFlow.setWaiting({  flowId: created.flowId,  expectedRevision: created.revision,  currentStep: "await-human-reply",  waitJson: { kind: "reply", channel: "telegram" },});

Gebruik bindSession({ sessionKey, requesterOrigin }) wanneer je al een vertrouwde OpenClaw-sessiesleutel uit je eigen bindingslaag hebt. Koppel niet op basis van onbewerkte gebruikersinvoer.

Tekst-naar-spraaksynthese.

// Standaard-TTSconst clip = await api.runtime.tts.textToSpeech({  text: "Hallo vanuit OpenClaw",  cfg: api.config,}); // Voor telefonie geoptimaliseerde TTSconst telephonyClip = await api.runtime.tts.textToSpeechTelephony({  text: "Hallo vanuit OpenClaw",  cfg: api.config,}); // Beschikbare stemmen weergevenconst voices = await api.runtime.tts.listVoices({  provider: "elevenlabs",  cfg: api.config,});

Gebruikt de tts-configuratie en providerselectie van de kern. Retourneert een PCM-audiobuffer en samplefrequentie. textToSpeechStream is ook beschikbaar voor streamingsynthese.

Analyse van afbeeldingen, audio en video.

// Een afbeelding beschrijvenconst image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); // Audio transcriberenconst { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({  filePath: "/tmp/inbound-audio.ogg",  cfg: api.config,  mime: "audio/ogg", // optioneel, wanneer MIME niet kan worden afgeleid}); // Een video beschrijvenconst video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); // Algemene bestandsanalyseconst result = await api.runtime.mediaUnderstanding.runFile({  filePath: "/tmp/inbound-file.pdf",  cfg: api.config,}); // Gestructureerde afbeeldingsextractie via een specifieke provider/modelcombinatie.// Neem ten minste één afbeelding op; tekstinvoer dient als aanvullende context.const evidence = await api.runtime.mediaUnderstanding.extractStructuredWithModel({  provider: "codex",  model: "gpt-5.6-sol",  input: [    {      type: "image",      buffer: receiptImageBuffer,      fileName: "receipt.png",      mime: "image/png",    },    { type: "text", text: "Geef de voorkeur aan het afgedrukte totaal boven handgeschreven notities." },  ],  instructions: "Extraheer leverancier, totaal en doorzoekbare 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,});

Retourneert { text: undefined } wanneer geen uitvoer wordt geproduceerd (bijvoorbeeld bij overgeslagen invoer).

describeImageFileWithModel(...) beschrijft een reeds bekende afbeelding via een specifieke provider/modelcombinatie en omzeilt daarmee de standaardresolutie van het actieve model die describeImageFile(...) gebruikt.

Afbeeldingen genereren.

const result = await api.runtime.imageGeneration.generate({  prompt: "Een robot die een zonsondergang schildert",  cfg: api.config,}); const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });

Video's genereren, volgens dezelfde structuur als het genereren van afbeeldingen.

const result = await api.runtime.videoGeneration.generate({  prompt: "Een droneopname die bij zonsopgang over een kustlijn vliegt",  cfg: api.config,}); const providers = api.runtime.videoGeneration.listProviders({ cfg: api.config });

Muziek genereren, volgens dezelfde structuur als het genereren van afbeeldingen.

const result = await api.runtime.musicGeneration.generate({  prompt: "Een opgewekte lo-fi-track voor een programmeersessie",  cfg: api.config,}); const providers = api.runtime.musicGeneration.listProviders({ cfg: api.config });

Zoeken op het 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 },});

Mediahulpprogramma's op laag niveau.

const webMedia = await api.runtime.media.loadWebMedia(url);const mime = await api.runtime.media.detectMime(buffer);const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "afbeelding"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",});

Momentopname van de huidige runtimeconfiguratie en transactionele configuratieschrijfbewerkingen. Geef de voorkeur aan configuratie die al aan het actieve aanroeppad is doorgegeven; gebruik current() alleen wanneer de handler de momentopname van het proces rechtstreeks nodig heeft.

const cfg = api.runtime.config.current();await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

mutateConfigFile(...) en replaceConfigFile(...) retourneren een followUp- waarde, bijvoorbeeld { mode: "restart", requiresRestart: true, reason }, die de intentie van de schrijver vastlegt zonder de controle over opnieuw opstarten aan de Gateway te ontnemen.

Hulpprogramma's op systeemniveau.

await api.runtime.system.enqueueSystemEvent(event);api.runtime.system.requestHeartbeat({  source: "other",  intent: "event",  reason: "plugin-event",});api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // Verouderde compatibiliteitsalias.const heartbeatResult = await api.runtime.system.runHeartbeatOnce({  reason: "plugin-triggered-check",});const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);const hint = api.runtime.system.formatNativeDependencyHint(pkg);

runHeartbeatOnce(...) voert onmiddellijk één Heartbeat-cyclus uit en omzeilt daarbij de normale samenvoegtimer. Geef { heartbeat: { target: "last" } } door om aflevering naar het laatst actieve kanaal af te dwingen in plaats van de standaardonderdrukking via target: "none".

runCommandWithTimeout(...) retourneert vastgelegde stdout en stderr, optionele aantallen afkappingen, code, signal, killed, termination en noOutputTimedOut. Resultaten van een time-out en een time-out wegens ontbrekende uitvoer rapporteren code: 124 wanneer het onderliggende proces geen afsluitcode anders dan nul levert. Afsluitingen door een signaal zonder time-out kunnen nog steeds code: null retourneren, dus gebruik termination en noOutputTimedOut om de redenen voor time-outs te onderscheiden.

Abonnementen op gebeurtenissen.

api.runtime.events.onAgentEvent((event) => {  /* ... */});api.runtime.events.onSessionTranscriptUpdate((update) => {  /* ... */});

Logboekregistratie.

const verbose = api.runtime.logging.shouldLogVerbose();const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });

Resolutie van model- en providerauthenticatie.

const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); // Verificatiegegevens gereed voor aanvragen, inclusief runtime-uitwisselingen van providers (bijv. OAuth-vernieuwing)const runtimeAuth = await api.runtime.modelAuth.getRuntimeAuthForModel({ model, cfg }); const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({  provider: "openai",  cfg,});

Resolutie van de statusmap en door SQLite ondersteunde opslag met sleutels.

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.deleteIf?.("key-1", (current) => current.value === "hello");await store.consume("key-1");await store.clear(); const blobs = api.runtime.state.openBlobStore<MyBlobMetadata>({  namespace: "rendered-artifacts",  maxEntries: 100,  maxBytesPerEntry: 4 * 1024 * 1024,  maxBytesPerNamespace: 64 * 1024 * 1024,  defaultTtlMs: 15 * 60_000,});await blobs.register(  "artifact-1",  new TextEncoder().encode("binaire of tekstuele payload"),  { contentType: "text/plain" },);const blob = await blobs.lookup("artifact-1"); await api.runtime.state.withLease(  {    namespace: "my-feature",    key: "writer",    database: { scope: "agent", agentId },    leaseMs: 5 * 60_000,    waitMs: 30_000,  },  async ({ signal, assertOwned }) => {    await runExternalWriter({ signal });    assertOwned();  },);

Opslag met sleutels blijft na herstarts behouden en wordt geïsoleerd op basis van de aan de runtime gebonden Plugin-id. Gebruik registerIfAbsent(...) voor atomische deduplicatieclaims: dit retourneert true wanneer de sleutel ontbrak of verlopen was en is geregistreerd, of false wanneer er al een actieve waarde bestaat, zonder de waarde, aanmaaktijd of TTL ervan te overschrijven. Gebruik deleteIf(...) wanneer bij opschoning alleen de eerder waargenomen waarde mag worden verwijderd; het synchrone predicaat en de verwijdering worden in één SQLite-transactie uitgevoerd. Limieten: maxEntries per naamruimte, 50,000 actieve rijen per Plugin, JSON-waarden kleiner dan 64KB en optionele TTL-vervaltermijnen. Standaard verwijdert een schrijfbewerking bij het bereiken van een van beide rijlimieten de oudste actieve rijen uit de naamruimte waarnaar wordt geschreven; andere naamruimten worden voor die schrijfbewerking niet verwijderd en de schrijfbewerking mislukt alsnog als de naamruimte onvoldoende rijen kan vrijmaken. Stel overflowPolicy: "reject-new" in voor duurzame eigendomsrecords die nooit mogen worden verwijderd: nieuwe sleutels mislukken bij een van beide limieten, terwijl bestaande sleutels kunnen worden bijgewerkt.

openSyncKeyedStore<T>(...) retourneert dezelfde opslagvorm met synchrone methoden (register, registerIfAbsent, deleteIf, lookup, consume, clear retourneren allemaal rechtstreeks waarden in plaats van promises) voor aanroepers die niet kunnen wachten met await.

openBlobStore<TMetadata>(...) slaat begrensde binaire payloads op in gedeelde SQLite zonder base64 of begeleidende bestanden. Hiervoor zijn limieten vereist voor bytes per item, bytes per naamruimte en rijen; byte-arrays worden aan de API-grens gekopieerd; en metadata worden weergegeven zonder elke BLOB te laden. register(...) is een expliciete upsert, ook voor verlopen sleutels. registerIfAbsent(...) biedt botsingsveilige aanmaak: een verlopen sleutel blijft bezet totdat de eigenaar deze claimt met deleteExpiredKey(key) of deleteExpired(), waardoor de metadata behouden blijven die nodig zijn om gerelateerde benoemde artefacten na de SQLite-commit te verwijderen. Elke rij met een TTL is tijdelijk en wordt uitgesloten van back-ups en herstel, zelfs voordat deze verloopt; laat TTL weg voor duurzame, herstelbare status. Hostzekeringen beperken elke BLOB tot 100 MiB, elke Plugin tot 512 MiB aan fysiek opgeslagen BLOB's en elke Plugin tot 50,000 fysiek opgeslagen rijen, inclusief verlopen rijen die wachten op opschoning door de eigenaar. Gebruik registerIfAbsent(...) met overflowPolicy: "reject-new" wanneer externe materialisaties niet ongemerkt verweesd mogen raken door vervanging of verwijdering.

openChannelIngressQueue<TPayload>(...) opent een persistente ingangswachtrij met het bereik van de aanroepende Plugin, voor het bufferen van inkomende gebeurtenissen die minstens één keer moeten worden verwerkt, ook na herstarts. Wanneer voor herstel van verouderde claims shouldRecover wordt gebruikt, geef dan ook shouldRecoverCorrupt op als beschadigde geclaimde payloads in quarantaine moeten worden geplaatst: dankzij de claimidentiteit die onafhankelijk is van de payload kan de Plugin het actieve eigenaars- en rijstrookbeleid behouden voordat de wachtrij de rij met een tombstone markeert.

withLease(...) serialiseert samenwerkend Plugin-werk tussen OpenClaw-processen. Kies database: { scope: "shared" } voor één globale eigenaar of { scope: "agent", agentId } voor onafhankelijk eigendom per agent. Geef AbortSignal van de callback door aan elke bewerking die kan mislukken. assertOwned() is een controlepunt op een specifiek moment voordat een volgende belangrijke stap wordt gestart; de host verifieert het eigendom ook na de callback. Verlies van de lease of annulering door de aanroeper breekt het signaal af. Wachten op verkrijging en Heartbeats vinden buiten korte synchrone SQLite-transacties plaats; plugins ontvangen nooit databasepaden of -handles. Dit is coöperatieve annulering, geen fencing-token of autorisatie voor externe schrijfbewerkingen zonder fencing.

openChannelIngressDrain(...) opent de kanaalonafhankelijke kernworker boven die wachtrij (of maakt een wachtrij als er geen is opgegeven). Het leegloopproces beheert herstel van verouderde claims, serialisatie van claims per rijstrook, voltooiing bij overname of voltooiing bij terugkeer van de verzending, afhandeling voor opnieuw proberen/dode berichten, optionele vervanging vóór overname en een time-out voor stilstand tussen claim en overname. Verbind claimeigendom met het genereren van antwoorden via turnAdoptionLifecycle (via bindIngressLifecycleToReplyOptions uit plugin-sdk/channel-outbound). Kanaalplugins behouden het in de wachtrij plaatsen aan de acceptatiezijde, het afleiden van rijstroken, de classificatie als niet opnieuw uitvoerbaar en eventueel beleid voor autorisatie van vervanging.

Kanaalspecifieke runtimehelpers (beschikbaar wanneer een kanaalplugin is geladen). Gegroepeerd op aandachtspunt:

api.runtime.channel.media is het aanbevolen oppervlak voor het downloaden en opslaan van kanaalmedia:

const saved = await api.runtime.channel.media.saveRemoteMedia({  url,  subdir: "inbound",  maxBytes,  filePathHint: fileName,});

Gebruik saveRemoteMedia(...) wanneer een externe URL OpenClaw-media moet worden. Gebruik saveResponseMedia(...) wanneer de Plugin al een Response heeft opgehaald met door de Plugin beheerde verificatiegegevens, omleidingsafhandeling of toelatingslijstafhandeling. Gebruik readRemoteMediaBuffer(...) alleen wanneer de Plugin onbewerkte bytes nodig heeft voor inspectie, transformaties, ontsleuteling of opnieuw uploaden. fetchRemoteMedia(...) blijft een verouderde compatibiliteitsalias voor readRemoteMediaBuffer(...).

api.runtime.channel.mentions is het gedeelde oppervlak voor beleid rond inkomende vermeldingen voor gebundelde kanaalplugins die runtime-injectie gebruiken:

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,  },});

Beschikbare vermeldingshelpers:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

Gebruik het genormaliseerde { facts, policy }-pad voor beslissingen over vermeldingen.

Verschillende velden onder reply, session en inbound bevatten per veld @deprecated-notities die verwijzen naar de huidige kern voor kanaalbeurten of uitgaande kanaaladapters; controleer de inline-JSDoc van de specifieke helper voordat je er nieuwe code op bouwt.