Plugin-runtimehelpers

Agentidentiteit, mappen en sessiebeheer.

// 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(...) is de neutrale helper om een normale OpenClaw-agentbeurt te starten vanuit plugincode. Deze gebruikt dezelfde provider-/modeloplossing en agent-harnessselectie als door kanalen geactiveerde antwoorden.

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

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

normalizeThinkingLevel(...) converteert gebruikerstekst zoals on, x-high of extra high naar het canonieke opgeslagen niveau voordat het wordt gecontroleerd tegen het opgeloste beleid.

Sessiestorehelpers 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 })) {  // Iterate session rows without depending on the legacy sessions.json shape.}await api.runtime.agent.session.patchSessionEntry({  agentId,  sessionKey,  update: (entry) => ({ thinkingLevel: "high" }),});

Geef voor sessieworkflows de voorkeur aan getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) of upsertSessionEntry(...). Deze helpers adresseren sessies via agent-/sessie-identiteit, zodat plugins niet afhankelijk zijn van de legacy sessions.json-opslagvorm. Gebruik preserveActivity: true voor patches met alleen metadata die sessieactiviteit niet moeten verversen, en replaceEntry: true alleen wanneer de callback een volledige entry retourneert en verwijderde velden verwijderd moeten blijven.

Importeer voor transcriptlezingen en -schrijfoperaties openclaw/plugin-sdk/session-transcript-runtime en gebruik resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) of withSessionTranscriptWriteLock(...) met { agentId, sessionKey, sessionId }. Met deze API's kunnen plugins een transcript identificeren, de events ervan lezen, berichten toevoegen, updates publiceren en gerelateerde bewerkingen uitvoeren onder dezelfde transcript-write lock. Het doorgeven van sessionFile, het gebruiken van resolveSessionTranscriptLegacyFileTarget(...), of het importeren van low-level appendSessionTranscriptMessage(...) / emitSessionTranscriptUpdate(...) uit openclaw/plugin-sdk/agent-harness-runtime is verouderd; die paden bestaan alleen voor legacycode die al een actief transcriptartefact ontvangt.

loadSessionStore(...), saveSessionStore(...), updateSessionStore(...), resolveSessionFilePath(...) en resolveAndPersistSessionFile(...) zijn verouderde compatibiliteitshelpers voor plugins die nog steeds bewust afhankelijk zijn van de legacy whole-store- of transcriptbestandvorm. Nieuwe plugincode mag die helpers niet gebruiken, en bestaande aanroepers moeten migreren naar entryhelpers en transcriptidentiteithelpers.

Standaardmodel- en providerconstanten:

const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"

Voer een door de host beheerde tekstaanvulling uit zonder provider-internals te importeren of OpenClaw-model-/auth-/basis-URL-voorbereiding te dupliceren.

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

De helper gebruikt hetzelfde eenvoudige completion-voorbereidingspad als de ingebouwde runtime van OpenClaw en de host-eigen runtime-configuratiesnapshot. Context engines ontvangen een sessiegebonden llm.complete-capability, zodat modelaanroepen de agent van de actieve sessie gebruiken en niet stil terugvallen op de standaardagent. Het resultaat bevat provider-/model-/agenttoeschrijving plus genormaliseerd token-, cache- en geschat kostengebruik wanneer beschikbaar.

Start en beheer subagent-runs op de achtergrond.

// 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(...) kan sessies verwijderen die door dezelfde plugin zijn gemaakt via api.runtime.subagent.run(...). Voor het verwijderen van willekeurige gebruikers- of operatorsessies is nog steeds een Gateway-verzoek met admin-scope vereist.

Geef verbonden nodes weer en roep een node-hostcommando aan vanuit door Gateway geladen plugincode of vanuit plugin-CLI-commando's. Gebruik dit wanneer een plugin lokaal werk op een gekoppeld apparaat beheert, bijvoorbeeld een browser- of audiobridge 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,});

Binnen de Gateway draait deze runtime in-process. In plugin-CLI-commando's roept deze de geconfigureerde Gateway via RPC aan, zodat commando's zoals openclaw googlemeet recover-tab gekoppelde nodes vanuit de terminal kunnen inspecteren. Node-commando's lopen nog steeds via de normale Gateway-nodekoppeling, command allowlists, plugin node-invoke-beleid en node-lokale commandafhandeling.

Plugins die gevaarlijke node-hostcommando's beschikbaar maken, moeten een node-invoke-beleid registreren met api.registerNodeInvokePolicy(...). Het beleid draait in de Gateway na command allowlist-controles en voordat het commando naar de node wordt doorgestuurd, zodat directe node.invoke-aanroepen en hogere plugin-tools hetzelfde afdwingingspad delen.

Koppel een Task Flow-runtime aan een bestaande OpenClaw-sessiesleutel of vertrouwde toolcontext, en maak en beheer vervolgens Task Flows zonder bij elke aanroep een eigenaar door te geven.

Task Flow houdt duurzame workflowstatus met meerdere stappen bij. Het is geen scheduler: gebruik Cron of api.session.workflow.scheduleSessionTurn(...) voor toekomstige wake-ups, en gebruik daarna managedFlows vanuit de geplande turn wanneer dat werk flowstatus, child tasks, waits of annulering nodig heeft.

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

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

Tekst-naar-spraaksynthese.

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

Gebruikt de coreconfiguratie messages.tts en providerselectie. Retourneert PCM-audiobuffer + samplefrequentie.

Analyse van afbeeldingen, audio en 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,});

Retourneert { text: undefined } wanneer er geen output wordt geproduceerd, bijvoorbeeld bij overgeslagen invoer.

Afbeeldingen genereren.

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

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

Low-level mediahulpprogramma's.

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

Huidige snapshot van runtimeconfiguratie en transactionele configuratieschrijfacties. Geef de voorkeur aan configuratie die al aan het actieve aanroeppad is doorgegeven; gebruik current() alleen wanneer de handler de processnapshot direct 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 restartcontrole bij de Gateway weg te nemen.

Systeemhulpprogramma's.

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(...) retourneert vastgelegde stdout en stderr, optionele truncatietellingen, code, signal, killed, termination en noOutputTimedOut. Resultaten voor timeout en no-output-timeout rapporteren code: 124 wanneer het childproces geen niet-nul exitcode levert. Signaalafsluitingen zonder timeout kunnen nog steeds code: null retourneren, dus gebruik termination en noOutputTimedOut om timeoutredenen te onderscheiden.

Eventabonnementen.

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

Resolutie van model- en providerauthenticatie.

const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({  provider: "openai",  cfg,});

Resolutie van statusdirectory en SQLite-ondersteunde keyed storage.

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();

Stores met sleutels overleven herstarts en worden geïsoleerd door de runtime-gebonden Plugin-id. Gebruik registerIfAbsent(...) voor atomische dedupe-claims: dit retourneert true wanneer de sleutel ontbrak of verlopen was en is geregistreerd, of false wanneer er al een livewaarde bestaat zonder de waarde, aanmaaktijd of TTL te overschrijven. Limieten: maxEntries per namespace, 6.000 live rijen per Plugin, JSON-waarden onder 64 KB en optionele TTL-verval. Wanneer een schrijfactie de rijlimiet van de Plugin zou overschrijden, kan de runtime de oudste live rijen uit de namespace die wordt beschreven verwijderen; zuster-namespaces worden niet voor die schrijfactie verwijderd, en de schrijfactie mislukt alsnog als de namespace niet genoeg rijen kan vrijmaken.

Fabrieken voor geheugentools en CLI.

const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);api.runtime.tools.registerMemoryCli(/* ... */);

Kanaalspecifieke runtime-helpers (beschikbaar wanneer een kanaal-Plugin is geladen).

api.runtime.channel.media is het voorkeursoppervlak voor downloads en opslag 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 auth-, redirect- of allowlist-afhandeling. Gebruik readRemoteMediaBuffer(...) alleen wanneer de Plugin ruwe bytes nodig heeft voor inspectie, transformaties, decryptie of opnieuw uploaden. fetchRemoteMedia(...) blijft een verouderde compatibiliteitsalias voor readRemoteMediaBuffer(...).

api.runtime.channel.mentions is het gedeelde oppervlak voor inbound vermeldingsbeleid voor gebundelde kanaal-Plugins 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

api.runtime.channel.mentions stelt de oudere compatibiliteitshelpers resolveMentionGating* bewust niet beschikbaar. Geef de voorkeur aan het genormaliseerde pad { facts, policy }.