Passer au contenu principal

​
Assistants d’exécution du Plugin

Référence pour l’objet api.runtime injecté dans chaque plugin pendant l’enregistrement. Utilisez ces assistants au lieu d’importer directement les composants internes de l’hôte.
Vous cherchez un guide pas à pas ? Consultez Plugins de canal ou Plugins de fournisseur pour des guides étape par étape qui montrent ces assistants dans leur contexte.
register(api) {
  const runtime = api.runtime;
}

​
Espaces de noms d’exécution

​
api.runtime.agent

Identité de l’agent, répertoires et gestion des sessions. 
// Resolve the agent's working directory
const agentDir = api.runtime.agent.resolveAgentDir(cfg);

// Resolve agent workspace
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);

// Get agent identity
const identity = api.runtime.agent.resolveAgentIdentity(cfg);

// Get default thinking level
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);

// Get agent timeout
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);

// Ensure workspace exists
await api.runtime.agent.ensureAgentWorkspace(cfg);

// Run an embedded agent turn
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedAgent({
  sessionId: "my-plugin:task-1",
  runId: crypto.randomUUID(),
  sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
  prompt: "Summarize the latest changes",
  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
});
runEmbeddedAgent(...) est l’assistant neutre pour démarrer un tour d’agent OpenClaw normal depuis le code du plugin. Il utilise la même résolution de fournisseur/modèle et la même sélection du harnais d’agent que les réponses déclenchées par un canal. runEmbeddedPiAgent(...) reste un alias de compatibilité. Les assistants du magasin de sessions se trouvent sous api.runtime.agent.session : 
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
const store = api.runtime.agent.session.loadSessionStore(cfg);
await api.runtime.agent.session.saveSessionStore(cfg, store);
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);

​
api.runtime.agent.defaults

Constantes de modèle et de fournisseur par défaut : 
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"

​
api.runtime.subagent

Lancer et gérer des exécutions de sous-agent en arrière-plan. 
// Start a subagent run
const { 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 completion
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

// Read session messages
const { messages } = await api.runtime.subagent.getSessionMessages({
  sessionKey: "agent:main:subagent:search-helper",
  limit: 10,
});

// Delete a session
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});
Les remplacements de modèle (provider/model) nécessitent un opt-in de l’opérateur via plugins.entries.<id>.subagent.allowModelOverride: true dans la configuration. Les plugins non fiables peuvent toujours exécuter des sous-agents, mais les demandes de remplacement sont rejetées.

​
api.runtime.taskFlow

Lier un runtime TaskFlow à une clé de session OpenClaw existante ou à un contexte d’outil de confiance, puis créer et gérer des TaskFlow sans transmettre un propriétaire à chaque appel. 
const taskFlow = api.runtime.taskFlow.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 de liaison. N’effectuez pas de liaison à partir d’une entrée utilisateur brute.

​
api.runtime.tts

Synthèse vocale. 
// Standard TTS
const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

// Telephony-optimized TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

// List available voices
const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});
Utilise la configuration centrale messages.tts et la sélection de fournisseur. Renvoie un tampon audio PCM + une fréquence d’échantillonnage.

​
api.runtime.mediaUnderstanding

Analyse d’images, d’audio et de vidéos. 
// Describe an image
const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

// Transcribe audio
const { 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 video
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

// Generic file analysis
const result = await api.runtime.mediaUnderstanding.runFile({
  filePath: "/tmp/inbound-file.pdf",
  cfg: api.config,
});
Renvoie { text: undefined } lorsqu’aucune sortie n’est produite (par exemple, entrée ignorée).
api.runtime.stt.transcribeAudioFile(...) reste un alias de compatibilité pour api.runtime.mediaUnderstanding.transcribeAudioFile(...).

​
api.runtime.imageGeneration

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

​
api.runtime.webSearch

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

​
api.runtime.media

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

​
api.runtime.config

Chargement et écriture de la configuration. 
const cfg = await api.runtime.config.loadConfig();
await api.runtime.config.writeConfigFile(cfg);

​
api.runtime.system

Utilitaires au niveau système. 
await api.runtime.system.enqueueSystemEvent(event);
api.runtime.system.requestHeartbeatNow();
const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
const hint = api.runtime.system.formatNativeDependencyHint(pkg);

​
api.runtime.events

Abonnements aux événements. 
api.runtime.events.onAgentEvent((event) => {
  /* ... */
});
api.runtime.events.onSessionTranscriptUpdate((update) => {
  /* ... */
});

​
api.runtime.logging

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

​
api.runtime.modelAuth

Résolution de l’authentification des modèles et des fournisseurs. 
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
  provider: "openai",
  cfg,
});

​
api.runtime.state

Résolution du répertoire d’état. 
const stateDir = api.runtime.state.resolveStateDir();

​
api.runtime.tools

Fabriques d’outils de mémoire et CLI. 
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);

​
api.runtime.channel

Assistants d’exécution spécifiques au canal (disponibles lorsqu’un plugin de canal est chargé). api.runtime.channel.mentions est la surface partagée de stratégie de mention entrante pour les plugins de canal intégrés qui utilisent l’injection du 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 }.

​
Stockage des références de runtime

Utilisez createPluginRuntimeStore pour stocker la référence du runtime en vue d’une utilisation en dehors du callback register : 
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "my-plugin",
  errorMessage: "my-plugin runtime not initialized",
});

// In your entry point
export default defineChannelPluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Example",
  plugin: myPlugin,
  setRuntime: store.setRuntime,
});

// In other files
export function getRuntime() {
  return store.getRuntime(); // throws if not initialized
}

export function tryGetRuntime() {
  return store.tryGetRuntime(); // returns null if not initialized
}
Préférez pluginId pour l’identité du runtime-store. La forme de niveau inférieur key est destinée aux cas peu courants où un plugin a intentionnellement besoin de plus d’un emplacement de runtime.

​
Autres champs api de niveau supérieur

Au-delà de api.runtime, l’objet API fournit aussi :
ChampTypeDescription
api.idstringID du Plugin
api.namestringNom d’affichage du Plugin
api.configOpenClawConfigInstantané actuel de la configuration (instantané actif du runtime en mémoire lorsqu’il est disponible)
api.pluginConfigRecord<string, unknown>Configuration spécifique au Plugin provenant de plugins.entries.<id>.config
api.loggerPluginLoggerLogger à portée limitée (debug, info, warn, error)
api.registrationModePluginRegistrationModeMode de chargement actuel ; "setup-runtime" est la fenêtre légère de démarrage/configuration avant l’entrée complète
api.resolvePath(input)(string) => stringRésout un chemin relatif à la racine du Plugin

​
Lié