openclaw/docs

Fork 0

openclaw-docs-i18n[bot] 41ae35e536 chore(i18n): refresh fr translations

2026-04-15 19:52:20 +00:00

14 KiB

Raw Blame History

read_when

sidebarTitle

summary

title

x-i18n

Vous devez appeler des assistants du cœur depuis un plugin (TTS, STT, génération d’images, recherche web, sous-agent)

Vous voulez comprendre ce que `api.runtime` expose

Vous accédez à des assistants de configuration, d’agent ou de média depuis le code du plugin

Runtime Helpers

api.runtime -- les assistants d’exécution injectés disponibles pour les plugins

Assistants d’exécution du Plugin

generated_at	model	provider	source_hash	source_path	workflow
2026-04-15T19:41:44Z	gpt-5.4	openai	c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8	plugins/sdk-runtime.md	15

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](/fr/plugins/sdk-channel-plugins) ou [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) 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..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 :

Champ	Type	Description
`api.id`	`string`	ID du Plugin
`api.name`	`string`	Nom d’affichage du Plugin
`api.config`	`OpenClawConfig`	Instantané actuel de la configuration (instantané actif du runtime en mémoire lorsqu’il est disponible)
`api.pluginConfig`	`Record<string, unknown>`	Configuration spécifique au Plugin provenant de `plugins.entries.<id>.config`
`api.logger`	`PluginLogger`	Logger à portée limitée (`debug`, `info`, `warn`, `error`)
`api.registrationMode`	`PluginRegistrationMode`	Mode 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) => string`	Résout un chemin relatif à la racine du Plugin

Lié

Vue d’ensemble du SDK -- référence des sous-chemins
Points d’entrée du SDK -- options de definePluginEntry
Composants internes du Plugin -- modèle de capacités et registre

14 KiB Raw Blame History Unescape Escape

Assistants d’exécution du Plugin

Espaces de noms d’exécution

api.runtime.agent

api.runtime.agent.defaults

api.runtime.subagent

api.runtime.taskFlow

api.runtime.tts

api.runtime.mediaUnderstanding

api.runtime.imageGeneration

api.runtime.webSearch

api.runtime.media

api.runtime.config

api.runtime.system

api.runtime.events

api.runtime.logging

api.runtime.modelAuth

api.runtime.state

api.runtime.tools

api.runtime.channel

Stockage des références de runtime

Autres champs api de niveau supérieur

Lié

14 KiB

Raw Blame History

`api.runtime.agent`

`api.runtime.agent.defaults`

`api.runtime.subagent`

`api.runtime.taskFlow`

`api.runtime.tts`

`api.runtime.mediaUnderstanding`

`api.runtime.imageGeneration`

`api.runtime.webSearch`

`api.runtime.media`

`api.runtime.config`

`api.runtime.system`

`api.runtime.events`

`api.runtime.logging`

`api.runtime.modelAuth`

`api.runtime.state`

`api.runtime.tools`

`api.runtime.channel`

Autres champs `api` de niveau supérieur