Plugin-Runtime-Helfer

Agent-Identität, Verzeichnisse und Session-Verwaltung.

// 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(...) ist die neutrale Hilfsfunktion zum Starten eines normalen OpenClaw-Agent-Turns aus Plugin-Code. Sie verwendet dieselbe Provider-/Modell-Auflösung und Agent-Harness-Auswahl wie durch Channels ausgelöste Antworten.

runEmbeddedPiAgent(...) bleibt als veralteter Kompatibilitätsalias für bestehende Plugins erhalten. Neuer Code sollte runEmbeddedAgent(...) verwenden.

resolveThinkingPolicy(...) gibt die vom Provider/Modell unterstützten Denkstufen und optionalen Default zurück. Provider-Plugins besitzen das modellspezifische Profil über ihre Thinking-Hooks, daher sollten Tool-Plugins diese Runtime-Hilfsfunktion aufrufen, statt Provider-Listen zu importieren oder zu duplizieren.

normalizeThinkingLevel(...) konvertiert Benutzereingaben wie on, x-high oder extra high in die kanonisch gespeicherte Stufe, bevor sie gegen die aufgelöste Policy geprüft wird.

Session-Store-Hilfsfunktionen befinden sich unter 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.  },);

Bevorzugen Sie getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) oder upsertSessionEntry(...) für Session-Workflows. Diese Hilfsfunktionen adressieren Sessions über Agent-/Session-Identität, damit Plugins nicht von der alten sessions.json-Speicherform abhängen. Verwenden Sie preserveActivity: true für reine Metadaten-Patches, die die Session-Aktivität nicht aktualisieren sollen, und replaceEntry: true nur, wenn der Callback einen vollständigen Eintrag zurückgibt und gelöschte Felder gelöscht bleiben müssen.

Verwenden Sie runWithWorkAdmission(...), wenn ein Plugin Arbeit an einer persistierten Session startet. Der Callback weist archivierte oder gleichzeitig ersetzte Sessions zurück, hält Archiv-/Reset-/Löschmutationen bis zum Abschluss koordiniert und erhält ein AbortSignal, das an den Agent-Run weitergeleitet werden muss.

Importieren Sie für Transcript-Lese- und Schreibvorgänge openclaw/plugin-sdk/session-transcript-runtime und verwenden Sie resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) oder withSessionTranscriptWriteLock(...) mit { agentId, sessionKey, sessionId }. Diese APIs erlauben Plugins, ein Transcript zu identifizieren, seine Events zu lesen, Nachrichten anzuhängen, Updates zu veröffentlichen und zugehörige Operationen unter derselben Transcript-Schreibsperre auszuführen. Das Übergeben von sessionFile, die Verwendung von resolveSessionTranscriptLegacyFileTarget(...) oder das Importieren der Low-Level-Funktionen appendSessionTranscriptMessage(...) / emitSessionTranscriptUpdate(...) aus openclaw/plugin-sdk/agent-harness-runtime ist veraltet; diese Pfade existieren nur für Legacy-Code, der bereits ein aktives Transcript-Artefakt erhält.

loadSessionStore(...), saveSessionStore(...), updateSessionStore(...), resolveSessionFilePath(...) und resolveAndPersistSessionFile(...) sind veraltete Kompatibilitäts-Hilfsfunktionen für Plugins, die weiterhin absichtlich von der alten Whole-Store- oder Transcript-Dateiform abhängen. Neuer Plugin-Code darf diese Hilfsfunktionen nicht verwenden, und bestehende Aufrufer sollten zu Entry-Hilfsfunktionen und Transcript-Identity-Hilfsfunktionen migrieren.

Default-Modell- und Provider-Konstanten:

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

Führen Sie eine Host-eigene Textvervollständigung aus, ohne Provider-Interna zu importieren oder die OpenClaw-Vorbereitung für Modell/Auth/Basis-URL zu duplizieren.

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

Die Hilfsfunktion verwendet denselben einfachen Vervollständigungs-Vorbereitungspfad wie die integrierte Runtime von OpenClaw und den Host-eigenen Runtime-Konfigurations-Snapshot. Kontext-Engines erhalten eine sessiongebundene llm.complete-Capability, sodass Modellaufrufe den Agent der aktiven Session verwenden und nicht stillschweigend auf den Default-Agent zurückfallen. Das Ergebnis enthält Provider-/Modell-/Agent-Zuordnung plus normalisierte Token-, Cache- und geschätzte Kostennutzung, sofern verfügbar.

Starten und verwalten Sie Subagent-Ausführungen im Hintergrund.

// 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(...) kann Sitzungen löschen, die vom selben Plugin über api.runtime.subagent.run(...) erstellt wurden. Das Löschen beliebiger Benutzer- oder Operator-Sitzungen erfordert weiterhin eine admin-skopierte Gateway-Anforderung.

Listen Sie verbundene Nodes auf und rufen Sie einen Node-Host-Befehl aus vom Gateway geladenem Plugin-Code oder aus Plugin-CLI-Befehlen auf. Verwenden Sie dies, wenn ein Plugin lokale Arbeit auf einem gekoppelten Gerät besitzt, zum Beispiel eine Browser- oder Audio-Bridge auf einem anderen 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,});

Innerhalb des Gateway läuft diese Runtime im Prozess. In Plugin-CLI-Befehlen ruft sie das konfigurierte Gateway über RPC auf, sodass Befehle wie openclaw googlemeet recover-tab gekoppelte Nodes vom Terminal aus prüfen können. Node-Befehle durchlaufen weiterhin die normale Gateway-Node-Kopplung, Befehls-Allowlists, Plugin-Richtlinien für Node-Aufrufe und die node-lokale Befehlsverarbeitung.

Plugins, die gefährliche Node-Host-Befehle bereitstellen, sollten mit api.registerNodeInvokePolicy(...) eine Richtlinie für Node-Aufrufe registrieren. Die Richtlinie wird im Gateway nach den Befehls-Allowlist-Prüfungen und vor der Weiterleitung des Befehls an die Node ausgeführt, sodass direkte node.invoke-Aufrufe und höherwertige Plugin-Tools denselben Durchsetzungspfad nutzen.

Binden Sie eine Task Flow-Runtime an einen vorhandenen OpenClaw-Sitzungsschlüssel oder vertrauenswürdigen Tool-Kontext, und erstellen und verwalten Sie dann Task Flows, ohne bei jedem Aufruf einen Besitzer zu übergeben.

Task Flow verfolgt dauerhaften mehrstufigen Workflow-Zustand. Es ist kein Scheduler: Verwenden Sie Cron oder api.session.workflow.scheduleSessionTurn(...) für zukünftige Aktivierungen, und verwenden Sie anschließend managedFlows aus dem geplanten Turn, wenn diese Arbeit Flow-Zustand, untergeordnete Aufgaben, Wartevorgänge oder Abbruch benötigt.

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

Verwenden Sie bindSession({ sessionKey, requesterOrigin }), wenn Sie bereits einen vertrauenswürdigen OpenClaw-Sitzungsschlüssel aus Ihrer eigenen Bindungsschicht haben. Binden Sie nicht aus rohen Benutzereingaben.

Text-zu-Sprache-Synthese.

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

Verwendet die Kernkonfiguration messages.tts und Provider-Auswahl. Gibt PCM-Audiopuffer + Abtastrate zurück.

Bild-, Audio- und Videoanalyse.

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

Gibt { text: undefined } zurück, wenn keine Ausgabe erzeugt wird (z. B. bei übersprungener Eingabe).

Bilderzeugung.

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

Websuche.

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

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

Aktueller Runtime-Konfigurations-Snapshot und transaktionale Konfigurationsschreibvorgänge. Bevorzugen Sie Konfiguration, die bereits in den aktiven Aufrufpfad übergeben wurde; verwenden Sie current() nur, wenn der Handler den Prozess-Snapshot direkt benötigt.

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

mutateConfigFile(...) und replaceConfigFile(...) geben einen followUp- Wert zurück, zum Beispiel { mode: "restart", requiresRestart: true, reason }, der die Absicht des Schreibers festhält, ohne dem Gateway die Neustartsteuerung zu entziehen.

Hilfsfunktionen auf Systemebene.

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(...) gibt erfasste stdout und stderr, optionale Kürzungszähler, code, signal, killed, termination und noOutputTimedOut zurück. Timeout- und No-Output-Timeout-Ergebnisse melden code: 124, wenn der Child-Prozess keinen Exit-Code ungleich null bereitstellt. Signal-Exits ohne Timeout können weiterhin code: null zurückgeben; verwenden Sie daher termination und noOutputTimedOut, um Timeout-Gründe zu unterscheiden.

Ereignisabonnements.

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

Protokollierung.

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

Auflösung der Modell- und Provider-Authentifizierung.

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

Auflösung des Zustandsverzeichnisses und SQLite-gestützter 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();

Keyed Stores überstehen Neustarts und sind durch die runtime-gebundene Plugin-ID isoliert. Verwenden Sie registerIfAbsent(...) für atomare Deduplizierungs-Claims: Es gibt true zurück, wenn der Schlüssel fehlte oder abgelaufen war und registriert wurde, oder false, wenn bereits ein aktiver Wert vorhanden ist, ohne dessen Wert, Erstellungszeit oder TTL zu überschreiben. Limits: maxEntries pro Namespace, 6.000 aktive Zeilen pro Plugin, JSON-Werte unter 64 KB und optionaler TTL-Ablauf. Wenn ein Schreibvorgang das Zeilenlimit des Plugins überschreiten würde, kann die Runtime die ältesten aktiven Zeilen aus dem Namespace entfernen, in den geschrieben wird; benachbarte Namespaces werden für diesen Schreibvorgang nicht entfernt, und der Schreibvorgang schlägt dennoch fehl, wenn der Namespace nicht genügend Zeilen freigeben kann.

Factorys für Memory-Tools und CLI.

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

Channelspezifische Runtime-Hilfsfunktionen (verfügbar, wenn ein Channel-Plugin geladen ist).

api.runtime.channel.media ist die bevorzugte Oberfläche für Channel-Mediendownloads und -Speicherung:

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

Verwenden Sie saveRemoteMedia(...), wenn eine entfernte URL zu OpenClaw-Medien werden soll. Verwenden Sie saveResponseMedia(...), wenn das Plugin bereits eine Response mit plugin-eigener Authentifizierung, Weiterleitungs- oder Allowlist-Behandlung abgerufen hat. Verwenden Sie readRemoteMediaBuffer(...) nur, wenn das Plugin Rohbytes für Prüfung, Transformationen, Entschlüsselung oder erneutes Hochladen benötigt. fetchRemoteMedia(...) bleibt ein veralteter Kompatibilitätsalias für readRemoteMediaBuffer(...).

api.runtime.channel.mentions ist die gemeinsame eingehende Oberfläche für Erwähnungsrichtlinien für gebündelte Channel-Plugins, die Runtime-Injection verwenden:

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

Verfügbare Mention-Hilfsfunktionen:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions stellt die älteren resolveMentionGating*-Kompatibilitätshelfer absichtlich nicht bereit. Bevorzugen Sie den normalisierten { facts, policy }-Pfad.