Assistants d'exécution de plugin

Assistants d’exécution de plugin

Référence de l’objet api.runtime injecté dans chaque plugin lors de l’enregistrement. Utilisez ces assistants au lieu d’importer directement les éléments internes de l’hôte.

Tip

Vous cherchez un guide pas à pas ?

Voir

Channel Plugins

ou

Provider Plugins

pour des guides étape par étape qui présentent ces aides 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 de session.

// 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 Pi agent
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedPiAgent({
  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),
});

Les assistants de magasin de session 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 model et de provider 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

Lancez et gérez les exécutions de sous-agents 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",
});

Warning

Les substitutions de model (provider/model) nécessitent l’accord explicite de l’opérateur via `plugins.entries.

.subagent.allowModelOverride: true` dans la configuration. Les plugins non fiables peuvent toujours exécuter des sous-agents, mais les demandes de substitution sont rejetées.

api.runtime.tts

Synthèse vocale (texte-vers-parole).

// 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 messages.tts principale et la sélection de provider. Renvoie le tampon audio PCM + la fréquence d’échantillonnage.

api.runtime.mediaUnderstanding

Analyse d’image, d’audio et de vidéo.

// 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 } lorsque aucune sortie n’est produite (ex. entrée ignorée).

Info

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 multimédias 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 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 d’authentification pour les models et providers.

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

Assistances d’exécution spécifiques au canal (disponibles lorsqu’un plugin de canal est chargé).

Stockage des références d’exécution

Utilisez createPluginRuntimeStore pour stocker la référence d’exécution pour une utilisation en dehors de la fonction de rappel register :

import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>("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
}

Autres champs api de niveau supérieur

Au-delà de api.runtime, l’objet API fournit également :

Champ	Type	Description
api.id	string	ID du plugin
api.name	string	Nom d’affichage du plugin
api.config	OpenClawConfig	Instantané de la configuration actuelle
api.pluginConfig	Record<string, unknown>	Configuration spécifique au plugin provenant de plugins.entries.<id>.config
api.logger	PluginLogger	Enregistreur avec portée (debug, info, warn, error)
api.registrationMode	PluginRegistrationMode	"full", "setup-only", "setup-runtime", ou "cli-metadata"
api.resolvePath(input)	(string) => string	Résout un chemin relatif à la racine du plugin

Connexes

• Aperçu du SDK — référence de sous-chemin
• Points d’entrée du SDK — options definePluginEntry
• Fonctionnement interne des plugins — model de capacité et registre