Utilitaires d’exécution du Plugin

Identité de l'agent, répertoires et gestion des sessions.

// 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(...) est le helper neutre pour démarrer un tour d'agent OpenClaw normal depuis du code de plugin. Il utilise la même résolution fournisseur/modèle et la même sélection du harnais d'agent que les réponses déclenchées par les canaux.

runEmbeddedPiAgent(...) reste un alias de compatibilité obsolète pour les plugins existants. Le nouveau code doit utiliser runEmbeddedAgent(...).

resolveThinkingPolicy(...) renvoie les niveaux de raisonnement pris en charge par le fournisseur/modèle et le défaut facultatif. Les Plugins de fournisseur possèdent le profil propre au modèle via leurs hooks de raisonnement ; les Plugins d'outils doivent donc appeler ce helper d'exécution plutôt que d'importer ou de dupliquer les listes de fournisseurs.

normalizeThinkingLevel(...) convertit le texte utilisateur tel que on, x-high ou extra high en niveau stocké canonique avant de le vérifier par rapport à la politique résolue.

Les helpers de magasin de sessions se trouvent sous 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.  },);

Préférez getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) ou upsertSessionEntry(...) pour les workflows de session. Ces helpers adressent les sessions par identité d'agent/session afin que les plugins ne dépendent pas de la forme de stockage héritée sessions.json. Utilisez preserveActivity: true pour les patchs qui ne concernent que les métadonnées et ne doivent pas actualiser l'activité de session, et replaceEntry: true uniquement lorsque le callback renvoie une entrée complète et que les champs supprimés doivent rester supprimés.

Utilisez runWithWorkAdmission(...) lorsqu'un plugin démarre un travail sur une session persistée. Le callback rejette les sessions archivées ou remplacées simultanément, maintient les mutations d'archive/réinitialisation/suppression coordonnées jusqu'à l'achèvement, et reçoit un AbortSignal qui doit être transmis à l'exécution de l'agent.

Pour les lectures et écritures de transcription, importez openclaw/plugin-sdk/session-transcript-runtime et utilisez resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) ou withSessionTranscriptWriteLock(...) avec { agentId, sessionKey, sessionId }. Ces API permettent aux plugins d'identifier une transcription, de lire ses événements, d'ajouter des messages, de publier des mises à jour et d'exécuter les opérations liées sous le même verrou d'écriture de transcription. Passer sessionFile, utiliser resolveSessionTranscriptLegacyFileTarget(...) ou importer les bas niveaux appendSessionTranscriptMessage(...) / emitSessionTranscriptUpdate(...) depuis openclaw/plugin-sdk/agent-harness-runtime est obsolète ; ces chemins existent uniquement pour le code hérité qui reçoit déjà un artefact de transcription actif.

loadSessionStore(...), saveSessionStore(...), updateSessionStore(...), resolveSessionFilePath(...) et resolveAndPersistSessionFile(...) sont des helpers de compatibilité obsolètes pour les plugins qui dépendent encore intentionnellement de l'ancienne forme de magasin complet ou de fichier de transcription. Le nouveau code de plugin ne doit pas utiliser ces helpers, et les appelants existants doivent migrer vers les helpers d'entrée et les helpers d'identité de transcription.

Constantes par défaut de modèle et de fournisseur :

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

Exécutez une complétion de texte détenue par l'hôte sans importer les éléments internes du fournisseur ni dupliquer la préparation de modèle/authentification/URL de base d'OpenClaw.

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

Le helper utilise le même chemin de préparation de complétion simple que l'exécution intégrée d'OpenClaw et l'instantané de configuration d'exécution détenu par l'hôte. Les moteurs de contexte reçoivent une capacité llm.complete liée à la session, de sorte que les appels de modèle utilisent l'agent de la session active et ne reviennent pas silencieusement à l'agent par défaut. Le résultat inclut l'attribution fournisseur/modèle/agent ainsi que l'utilisation normalisée des tokens, du cache et du coût estimé lorsqu'elle est disponible.

Lancez et gérez des exécutions de sous-agents en arrière-plan.

// 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(...) peut supprimer les sessions créées par le même plugin via api.runtime.subagent.run(...). La suppression de sessions utilisateur ou opérateur arbitraires nécessite toujours une requête Gateway avec portée administrateur.

Listez les nœuds connectés et invoquez une commande hébergée sur un nœud depuis du code de plugin chargé par le Gateway ou depuis des commandes CLI de plugin. Utilisez ceci lorsqu’un plugin possède du travail local sur un appareil appairé, par exemple un pont de navigateur ou audio sur un autre 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,});

Dans le Gateway, ce runtime est intégré au processus. Dans les commandes CLI de plugin, il appelle le Gateway configuré via RPC, afin que des commandes comme openclaw googlemeet recover-tab puissent inspecter les nœuds appairés depuis le terminal. Les commandes de nœud passent toujours par l’appairage normal des nœuds du Gateway, les listes d’autorisations de commandes, les politiques d’invocation de nœud des plugins et le traitement local des commandes sur le nœud.

Les plugins qui exposent des commandes dangereuses hébergées sur un nœud doivent enregistrer une politique d’invocation de nœud avec api.registerNodeInvokePolicy(...). La politique s’exécute dans le Gateway après les vérifications de liste d’autorisations de commandes et avant le transfert de la commande au nœud, de sorte que les appels directs node.invoke et les outils de plugin de plus haut niveau partagent le même chemin d’application.

Associez un runtime de flux de tâches à une clé de session OpenClaw existante ou à un contexte d’outil de confiance, puis créez et gérez des flux de tâches sans transmettre de propriétaire à chaque appel.

Le flux de tâches suit un état durable de workflow à plusieurs étapes. Ce n’est pas un planificateur : utilisez Cron ou api.session.workflow.scheduleSessionTurn(...) pour les réveils futurs, puis utilisez managedFlows depuis le tour planifié lorsque ce travail a besoin d’un état de flux, de tâches enfants, d’attentes ou d’une annulation.

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

Utilisez bindSession({ sessionKey, requesterOrigin }) lorsque vous disposez déjà d’une clé de session OpenClaw de confiance provenant de votre propre couche d’association. Ne l’associez pas à partir d’une entrée utilisateur brute.

Synthèse vocale.

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

Utilise la configuration principale messages.tts et la sélection de fournisseur. Renvoie un tampon audio PCM + le taux d’échantillonnage.

Analyse d’images, d’audio et de vidéos.

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

Renvoie { text: undefined } lorsqu’aucune sortie n’est produite (par exemple, entrée ignorée).

Génération d’images.

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

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

Utilitaires média de bas 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"); // "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",});

Instantané de configuration du runtime actuel et écritures transactionnelles de configuration. Préférez la configuration déjà transmise au chemin d’appel actif ; utilisez current() uniquement lorsque le gestionnaire a directement besoin de l’instantané du processus.

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

mutateConfigFile(...) et replaceConfigFile(...) renvoient une valeur followUp, par exemple { mode: "restart", requiresRestart: true, reason }, qui enregistre l’intention de l’auteur de l’écriture sans retirer le contrôle du redémarrage au Gateway.

Utilitaires au niveau système.

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(...) renvoie les stdout et stderr capturés, les nombres facultatifs de troncature, code, signal, killed, termination et noOutputTimedOut. Les résultats d’expiration de délai et d’expiration pour absence de sortie signalent code: 124 lorsque le processus enfant ne fournit pas de code de sortie non nul. Les sorties par signal hors expiration peuvent toujours renvoyer code: null; utilisez donc termination et noOutputTimedOut pour distinguer les raisons d’expiration.

Abonnements aux événements.

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

Journalisation.

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

Résolution de l’authentification du modèle et du fournisseur.

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

Résolution du répertoire d’état et stockage clé-valeur adossé à 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();

Les magasins clé-valeur survivent aux redémarrages et sont isolés par l’id du Plugin lié au runtime. Utilisez registerIfAbsent(...) pour des revendications de déduplication atomiques : la fonction renvoie true lorsque la clé était absente ou expirée et a été enregistrée, ou false lorsqu’une valeur active existe déjà, sans écraser sa valeur, son heure de création ni sa durée de vie. Limites : maxEntries par espace de noms, 6 000 lignes actives par Plugin, valeurs JSON inférieures à 64 Ko et expiration TTL facultative. Lorsqu’une écriture dépasserait le plafond de lignes du Plugin, le runtime peut évincer les lignes actives les plus anciennes de l’espace de noms en cours d’écriture ; les espaces de noms voisins ne sont pas évincés pour cette écriture, et l’écriture échoue quand même si l’espace de noms ne peut pas libérer suffisamment de lignes.

Fabriques d’outils de mémoire et CLI.

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

Assistants de runtime propres aux canaux (disponibles lorsqu’un Plugin de canal est chargé).

api.runtime.channel.media est la surface privilégiée pour les téléchargements et le stockage des médias de canal :

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

Utilisez saveRemoteMedia(...) lorsqu’une URL distante doit devenir un média OpenClaw. Utilisez saveResponseMedia(...) lorsque le Plugin a déjà récupéré une Response avec une authentification, des redirections ou une gestion de liste d’autorisation qui lui appartiennent. Utilisez readRemoteMediaBuffer(...) uniquement lorsque le Plugin a besoin d’octets bruts pour inspection, transformations, déchiffrement ou téléversement. fetchRemoteMedia(...) reste un alias de compatibilité obsolète pour readRemoteMediaBuffer(...).

api.runtime.channel.mentions est la surface partagée de politique de mentions entrantes pour les Plugins de canal groupés qui utilisent l’injection de 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,  },});

Assistants de mention disponibles :

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions n’expose volontairement pas les anciens assistants de compatibilité resolveMentionGating*. Préférez le chemin normalisé { facts, policy }.