Saltar al contenido principal

​
Ayudantes de tiempo de ejecución del Plugin

Referencia del objeto api.runtime inyectado en cada plugin durante el registro. Use estos ayudantes en lugar de importar directamente elementos internos del host.
¿Busca una guía paso a paso? Consulte Plugins de canal o Plugins de proveedor para ver guías paso a paso que muestran estos ayudantes en contexto.
register(api) {
  const runtime = api.runtime;
}

​
Espacios de nombres de tiempo de ejecución

​
api.runtime.agent

Identidad del agente, directorios y gestión de sesiones. 
// 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(...) es el ayudante neutral para iniciar un turno normal de agente de OpenClaw desde el código de un plugin. Usa la misma resolución de proveedor/modelo y selección del arnés del agente que las respuestas activadas por canales. runEmbeddedPiAgent(...) se mantiene como alias de compatibilidad. Los ayudantes de almacenamiento de sesiones están en 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 predeterminadas de modelo y proveedor: 
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

Inicie y gestione ejecuciones de subagentes en segundo plano. 
// 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",
});
Las anulaciones de modelo (provider/model) requieren consentimiento explícito del operador mediante plugins.entries.<id>.subagent.allowModelOverride: true en la configuración. Los plugins no confiables aún pueden ejecutar subagentes, pero las solicitudes de anulación se rechazan.

​
api.runtime.taskFlow

Vincule un tiempo de ejecución de TaskFlow a una clave de sesión de OpenClaw existente o a un contexto de herramienta confiable y, después, cree y gestione Task Flows sin pasar un propietario en cada llamada. 
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" },
});
Use bindSession({ sessionKey, requesterOrigin }) cuando ya tenga una clave de sesión de OpenClaw confiable de su propia capa de vinculación. No vincule a partir de entrada sin procesar del usuario.

​
api.runtime.tts

Síntesis de texto a voz. 
// 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,
});
Usa la configuración central messages.tts y la selección de proveedor. Devuelve un búfer de audio PCM + tasa de muestreo.

​
api.runtime.mediaUnderstanding

Análisis de imágenes, audio y video. 
// 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,
});
Devuelve { text: undefined } cuando no se produce salida (por ejemplo, si la entrada se omite).
api.runtime.stt.transcribeAudioFile(...) se mantiene como alias de compatibilidad de api.runtime.mediaUnderstanding.transcribeAudioFile(...).

​
api.runtime.imageGeneration

Generación de imágenes. 
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

Búsqueda 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

Utilidades multimedia de bajo nivel. 
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

Carga y escritura de configuración. 
const cfg = await api.runtime.config.loadConfig();
await api.runtime.config.writeConfigFile(cfg);

​
api.runtime.system

Utilidades a nivel del sistema. 
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

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

​
api.runtime.logging

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

​
api.runtime.modelAuth

Resolución de autenticación de modelos y proveedores. 
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
  provider: "openai",
  cfg,
});

​
api.runtime.state

Resolución del directorio de estado. 
const stateDir = api.runtime.state.resolveStateDir();

​
api.runtime.tools

Fábricas de herramientas de memoria y CLI. 
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);

​
api.runtime.channel

Ayudantes de tiempo de ejecución específicos del canal (disponibles cuando se carga un plugin de canal). api.runtime.channel.mentions es la superficie compartida de la política de menciones entrantes para los plugins de canal incluidos que usan inyección en tiempo de ejecución: 
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,
  },
});
Ayudantes de mención disponibles:
  • buildMentionRegexes
  • matchesMentionPatterns
  • matchesMentionWithExplicit
  • implicitMentionKindWhen
  • resolveInboundMentionDecision
api.runtime.channel.mentions intencionalmente no expone los ayudantes de compatibilidad anteriores resolveMentionGating*. Prefiera la ruta normalizada { facts, policy }.

​
Almacenamiento de referencias de tiempo de ejecución

Use createPluginRuntimeStore para almacenar la referencia de tiempo de ejecución y usarla fuera del 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
}
Prefiera pluginId para la identidad del runtime-store. La forma de nivel inferior key es para casos poco comunes en los que un plugin intencionalmente necesita más de una ranura de tiempo de ejecución.

​
Otros campos de nivel superior de api

Además de api.runtime, el objeto API también proporciona:
CampoTipoDescripción
api.idstringId del Plugin
api.namestringNombre para mostrar del Plugin
api.configOpenClawConfigInstantánea actual de la configuración (instantánea activa en memoria del tiempo de ejecución cuando está disponible)
api.pluginConfigRecord<string, unknown>Configuración específica del Plugin de plugins.entries.<id>.config
api.loggerPluginLoggerRegistrador con ámbito (debug, info, warn, error)
api.registrationModePluginRegistrationModeModo de carga actual; "setup-runtime" es la ventana ligera de inicio/configuración previa a la entrada completa
api.resolvePath(input)(string) => stringResuelve una ruta relativa a la raíz del Plugin

​
Relacionado