Funciones auxiliares del entorno de ejecución del Plugin

Identidad del agente, directorios y gestión de sesiones.

// Resolver el directorio de trabajo del agente (agentId es obligatorio)const agentDir = api.runtime.agent.resolveAgentDir(cfg, agentId); // Resolver el espacio de trabajo del agenteconst workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId); // Obtener la identidad del agenteconst identity = api.runtime.agent.resolveAgentIdentity(cfg); // Obtener el nivel de razonamiento predeterminadoconst thinking = api.runtime.agent.resolveThinkingDefault({  cfg,  provider,  model,}); // Validar un nivel de razonamiento proporcionado por el usuario con el perfil activo del proveedorconst policy = api.runtime.agent.resolveThinkingPolicy({ provider, model });const level = api.runtime.agent.normalizeThinkingLevel("extra high");if (level && policy.levels.some((entry) => entry.id === level)) {  // pasar el nivel a una ejecución integrada} // Obtener el tiempo de espera del agenteconst timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); // Asegurarse de que exista el espacio de trabajoawait api.runtime.agent.ensureAgentWorkspace(cfg); // Ejecutar un turno integrado del agenteconst result = await api.runtime.agent.runEmbeddedAgent({  sessionId: "my-plugin:task-1",  runId: crypto.randomUUID(),  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId),  prompt: "Resume los cambios más recientes",  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),});

runEmbeddedAgent(...) es el asistente neutral para iniciar un turno normal de un agente de OpenClaw desde el código de un plugin. Utiliza la misma resolución de proveedor y modelo, así como la misma selección del entorno del agente, que las respuestas activadas por canales.

runEmbeddedPiAgent(...) permanece como alias de compatibilidad obsoleto para los plugins existentes. El código nuevo debe utilizar runEmbeddedAgent(...).

resolveThinkingPolicy(...) devuelve los niveles de razonamiento admitidos por el proveedor o modelo y el valor predeterminado opcional. Los plugins de proveedor controlan el perfil específico del modelo mediante sus enlaces de razonamiento, por lo que los plugins de herramientas deben llamar a este asistente del entorno de ejecución en lugar de importar o duplicar listas de proveedores.

normalizeThinkingLevel(...) convierte texto del usuario como on, x-high o extra high al nivel canónico almacenado antes de comprobarlo con la política resuelta.

Los asistentes del almacén de sesiones se encuentran en api.runtime.agent.session:

const entry = api.runtime.agent.session.getSessionEntry({ agentId, sessionKey });for (const { sessionKey, entry } of api.runtime.agent.session.listSessionEntries({ agentId })) {  // Iterar por las filas de sesiones sin depender de la estructura heredada de sessions.json.}await api.runtime.agent.session.patchSessionEntry({  agentId,  sessionKey,  update: (entry) => ({ thinkingLevel: "high" }),}); const created = await api.runtime.agent.session.createSessionEntry({  cfg,  key: "agent:main:my-plugin:task-1",  initialEntry: {    agentHarnessId: "my-harness",    modelSelectionLocked: true,    pluginExtensions: { "my-plugin": { phase: "initializing" } },  },  afterCreate: async () => ({    pluginExtensions: { "my-plugin": { phase: "ready" } },  }),}); const storePath = api.runtime.agent.session.resolveStorePath(cfg.session?.store, { agentId });await api.runtime.agent.session.runWithWorkAdmission(  { storePath, sessionKey },  async (signal) => {    // Crear o actualizar la sesión y, a continuación, pasar signal a la ejecución admitida del agente.  },);

Utilice preferentemente getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) o upsertSessionEntry(...) para los flujos de trabajo de sesiones. Estos asistentes identifican las sesiones mediante la identidad del agente y de la sesión para que los plugins no dependan de la estructura de almacenamiento heredada sessions.json. Utilice preserveActivity: true para modificaciones exclusivamente de metadatos que no deban actualizar la actividad de la sesión y replaceEntry: true solo cuando la devolución de llamada devuelva una entrada completa y los campos eliminados deban permanecer eliminados. Las rutas de diagnóstico y migración pueden combinar fallbackEntry, skipMaintenance y requireWriteSuccess para realizar una única reparación atómica del almacén canónico.

createSessionEntry(...) crea una nueva fila de sesión canónica y una transcripción. Su superficie de confianza initialEntry es deliberadamente limitada: un agentHarnessId no vacío, un modelSelectionLocked: true opcional y un pluginExtensions opcional. El entorno de ejecución inyectado solo acepta identificadores de entornos que pertenezcan al plugin que realiza la llamada mediante registerAgentHarness(...); se trata de una invariante de propiedad, no de un entorno aislado entre plugins dentro del proceso. Rechaza una fila existente; label y spawnedCwd son campos de creación independientes, no modificaciones de entradas de confianza.

La creación mantiene el bloqueo de mutación del ciclo de vida de la sesión mediante afterCreate, de modo que el trabajo nuevo espera a que finalice la inicialización controlada por el plugin y el trabajo admitido previamente hace que la creación falle. La devolución de llamada recibe un clon del estado creado. Si devuelve una modificación, esta solo puede contener pluginExtensions, y su valor es el campo final completo pluginExtensions. Un fallo de la devolución de llamada o de la persistencia final revierte la nueva fila sin cambios y la transcripción; la reversión protegida conserva una fila modificada o reclamada simultáneamente. recoverMatchingInitialEntry: true sirve únicamente para reintentar una inicialización interrumpida cuando los campos de confianza conservados coinciden exactamente, y la recuperación requiere que afterCreate devuelva una modificación final.

Utilice runWithWorkAdmission(...) cuando un plugin inicie trabajo en una sesión persistida. La devolución de llamada rechaza las sesiones archivadas o sustituidas simultáneamente, mantiene coordinadas hasta su finalización las mutaciones de archivado, restablecimiento o eliminación y recibe un AbortSignal que debe reenviarse a la ejecución del agente. Un entorno puede nombrar explícitamente delegados de ejecución de confianza mediante su campo de registro experimental delegatedExecutionPluginIds. Los delegados solo pueden admitir y ejecutar una sesión existente exacta con el modelo bloqueado; todas las mutaciones de la sesión permanecen restringidas al propietario del entorno. Consulte Plugins de entornos de agentes.

Los plugins de mantenimiento y reparación pueden utilizar deleteSessionEntry(...) para una entrada de sesión específica, cleanupSessionLifecycleArtifacts(...) para sesiones temporales gestionadas por el ciclo de vida y resolveSessionStoreBackupPaths(...) antes de modificar un almacén. Estos asistentes son superficies limitadas de reparación y ciclo de vida, no una API general para eliminar almacenes.

resolveStorePath(...) y updateSessionStoreEntry(...) completan los auxiliares de sesión: resolveStorePath resuelve la ruta del almacén de sesiones para un ámbito determinado, y updateSessionStoreEntry({ storePath, sessionKey, update }) modifica directamente una entrada mediante la ruta del almacén cuando el invocador ya la conoce.

loadTranscriptEventsSync(...) está disponible para las rutas síncronas de diagnóstico y reparación que no pueden usar el entorno de ejecución asíncrono de transcripciones. Devuelve registros SessionStoreTranscriptEvent sin procesar. El código normal del entorno de ejecución de plugins debería preferir openclaw/plugin-sdk/session-transcript-runtime.

formatSqliteSessionFileMarker(...), parseSqliteSessionFileMarker(...) y sqliteSessionFileMarkerMatchesSession(...) son auxiliares transitorios para el código que aún recibe un campo heredado denominado sessionFile. Un marcador de SQLite analizado identifica un destino activo de transcripción en SQLite; no es una ruta del sistema de archivos. Las API nuevas deberían transmitir una identidad de sesión tipada en lugar de cadenas de marcadores.

Para leer y escribir transcripciones, importe openclaw/plugin-sdk/session-transcript-runtime y use resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), readVisibleSessionTranscriptMessageEntries(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) o withSessionTranscriptWriteLock(...) con { agentId, sessionKey, sessionId }. Estas API permiten que los plugins identifiquen una transcripción, lean eventos sin procesar o entradas de mensajes visibles y seguras para ramas, añadan mensajes, publiquen actualizaciones y ejecuten operaciones relacionadas con el mismo bloqueo de escritura de la transcripción sin depender de las rutas de archivos de transcripciones activas. readVisibleSessionTranscriptMessageEntries(...) devuelve metadatos de lectura ordenados; su campo seq no es un cursor reanudable.

Los auxiliares heredados para el almacén completo y los archivos de transcripciones activas ya no se exportan desde el SDK de plugins. Use los auxiliares de entradas con ámbito para los metadatos de sesión y los auxiliares de identidad de transcripción para las operaciones de transcripciones activas. Los flujos de trabajo de archivado y asistencia que necesiten artefactos de archivos deberían usar sus superficies de archivado específicas en lugar de las API del entorno de ejecución de sesiones activas.

Constantes predeterminadas del modelo y el proveedor:

const model = api.runtime.agent.defaults.model; // p. ej., "gpt-5.6-sol"const provider = api.runtime.agent.defaults.provider; // p. ej., "openai"

Ejecute una finalización de texto administrada por el host sin importar elementos internos del proveedor ni duplicar la preparación del modelo, la autenticación y la URL base de OpenClaw.

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

La orquestación del proveedor también puede adquirir el ciclo de vida configurado del servicio local antes de emitir una solicitud HTTP:

const lease = await api.runtime.llm.acquireLocalService(  {    providerId,    baseUrl,    headers,  },  signal,);try {  // Envía y consume por completo la solicitud del proveedor.} finally {  await lease?.release();}

acquireLocalService(...) es un contrato estable y genérico del SDK para servicios de proveedores. El host resuelve la configuración del proceso desde models.providers.<providerId>.localService; los invocadores no pueden proporcionar un comando, argumentos, entorno ni política de ciclo de vida. La creación de procesos, la disponibilidad, los diagnósticos y la política de detención por inactividad permanecen como elementos internos del host.

Pase el identificador exacto del proveedor configurado y la URL base resuelta de la solicitud. No sustituya los alias por un identificador de adaptador: distintos alias pueden apuntar a distintos hosts de GPU locales. El host rechaza los endpoints que no coincidan con la URL base configurada del proveedor, salvo por la normalización /v1 que usan los adaptadores de Ollama y LM Studio. El host se encarga de la serialización del inicio, las pruebas de disponibilidad, las concesiones de solicitudes, la gestión de cancelaciones y el apagado por inactividad.

El auxiliar usa la misma ruta de preparación de finalizaciones sencillas que el entorno de ejecución integrado de OpenClaw y la instantánea de configuración del entorno de ejecución administrada por el host. Los motores de contexto reciben una capacidad llm.complete vinculada a la sesión, de modo que las llamadas al modelo usan el agente de la sesión activa y no recurren silenciosamente al agente predeterminado. El resultado incluye la atribución de proveedor, modelo y agente, además del uso normalizado de tokens, caché y coste estimado cuando está disponible.

Llame a otro método del Gateway dentro del proceso conservando la identidad de confianza del entorno de ejecución del plugin actual. Está destinado a plugins integrados u oficiales de confianza que componen capacidades del Gateway propias del plugin sin abrir una conexión WebSocket de bucle invertido.

if (await api.runtime.gateway.isAvailable()) {  const result = await api.runtime.gateway.request<{ callId: string }>(    "voicecall.start",    { to: "+15550001234", mode: "conversation" },    { timeoutMs: 60_000 },  );}

Las solicitudes usan el ámbito operator.write y no conceden ámbito de administración. Se rechazan las llamadas de plugins externos arbitrarios. Los métodos que fallan generan un GatewayClientRequestError y conservan details estructurado, los metadatos de reintento y el código de error del Gateway para los flujos de recuperación. Use isAvailable() antes de elegir esta ruta desde herramientas que también puedan ejecutarse en procesos de agente independientes.

Inicie y gestione ejecuciones de subagentes en segundo plano.

// Inicia una ejecución de subagenteconst { runId } = await api.runtime.subagent.run({  sessionKey: "agent:main:subagent:search-helper",  message: "Amplía esta consulta para convertirla en búsquedas de seguimiento específicas.",  toolsAlsoAllow: ["my_plugin_progress"],  provider: "openai", // sustitución opcional  model: "gpt-5.6-sol", // sustitución opcional  deliver: false,}); // Espera a que finaliceconst result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); // Lee los mensajes de la sesiónconst { messages } = await api.runtime.subagent.getSessionMessages({  sessionKey: "agent:main:subagent:search-helper",  limit: 10,}); // Elimina una sesiónawait api.runtime.subagent.deleteSession({  sessionKey: "agent:main:subagent:search-helper",});

toolsAlsoAllow añade a la superficie normal de herramientas del trabajador las herramientas exactas y de propiedad exclusiva registradas por el plugin invocador. El entorno de ejecución rechaza las herramientas del núcleo y los nombres compartidos con otro plugin. Los perfiles y las políticas de herramientas del operador siguen aplicándose, incluidas las listas explícitas de permitidos y las denegaciones.

deleteSession(...) puede eliminar sesiones creadas por el mismo plugin mediante api.runtime.subagent.run(...). La eliminación de sesiones arbitrarias de usuarios u operadores sigue requiriendo una solicitud al Gateway con ámbito de administración.

Inspeccione la autoridad efectiva del espacio de trabajo aislado para una sesión de agente.

const authority = api.runtime.sandbox.resolveWorkspaceAuthority({  config: cfg,  agentId,  sessionKey,}); const liveAuthority = await api.runtime.sandbox.prepareWorkspaceAuthority({  config: cfg,  agentId,  sessionKey,  workspaceDir,  confinedToolNames: ["my_plugin_safe_tool"],});

El resultado indica si esta sesión está aislada, si su espacio de trabajo no está disponible, es de solo lectura o permite escritura, y proporciona un confinementError opcional cuando la política efectiva de Docker, herramientas, sesión, navegador o elevación puede escapar de ese espacio de trabajo. Use esto para las decisiones de delegación administradas por el host que no deben conceder a un trabajador más autoridad que a su invocador. Es un auxiliar de certificación, no un sustituto de comprobar la autorización del propio invocador.

prepareWorkspaceAuthority(...) realiza la misma comprobación de políticas y también prepara el entorno aislado de Docker para workspaceDir. Rechaza un contenedor activo cuyo hash de configuración en ejecución no coincida con los montajes o la política solicitados. Pase únicamente nombres exactos de herramientas cuyas implementaciones registradas estén restringidas por el plugin invocador; los prefijos con comodines no demuestran la propiedad de la herramienta.

Enumere los nodos conectados e invoque un comando del host de un nodo desde el código de un plugin cargado por el Gateway o desde comandos de la CLI del plugin. Use esto cuando un plugin sea responsable de trabajo local en un dispositivo emparejado, por ejemplo un puente de navegador o audio en otro 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,});

nodes.list(...) incluye los descriptores nodePluginTools anunciados por cada nodo conectado cuando ese nodo expone al agente herramientas respaldadas por plugins o MCP. Esos descriptores representan el estado de la conexión activa: el Gateway los descarta cuando el nodo se desconecta, y un nodo puede sustituirlos por node.pluginTools.update después de que cambie el inventario local de plugins o MCP.

Dentro del Gateway, este entorno de ejecución funciona en el proceso. En los comandos de la CLI del plugin, llama al Gateway configurado mediante RPC, por lo que comandos como openclaw googlemeet recover-tab pueden inspeccionar los nodos emparejados desde el terminal. Los comandos de nodo siguen pasando por el emparejamiento normal de nodos del Gateway, las listas de comandos permitidos, las políticas de invocación de nodos de los plugins y la gestión local de comandos del nodo.

Los plugins que exponen herramientas de agente alojadas en nodos pueden establecer agentTool.defaultPlatforms para comandos no peligrosos que deban permitirse de forma predeterminada. Omítalo cuando los operadores deban habilitarlos mediante gateway.nodes.allowCommands. Los comandos peligrosos alojados en nodos deberían registrar una política de invocación de nodos con api.registerNodeInvokePolicy(...); la política se ejecuta en el Gateway después de comprobar la lista de comandos permitidos y antes de reenviar el comando al nodo, por lo que las llamadas directas a node.invoke, las herramientas de plugins alojadas en nodos y las herramientas de plugins de nivel superior comparten la misma ruta de aplicación.

Vincule el estado de Task Flow y Task Run a una clave de sesión existente de OpenClaw o a un contexto de herramienta de confianza.

• api.runtime.tasks.managedFlows admite mutaciones: crear, avanzar y cancelar flujos de tareas.
• api.runtime.tasks.flows y api.runtime.tasks.runs son vistas DTO de solo lectura para enumeraciones y consultas de estado; ambas exponen bindSession(...) / fromToolContext(...), además de get, list, findLatest y resolve.
• api.runtime.tasks.flow es un alias obsoleto de managedFlows.

Task Flow realiza el seguimiento del estado duradero de los flujos de trabajo de varios pasos. No es un planificador: use Cron o api.session.workflow.scheduleSessionTurn(...) para futuras activaciones y, después, use managedFlows desde el turno programado cuando ese trabajo necesite estado del flujo, tareas secundarias, esperas o cancelación.

const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); const created = taskFlow.createManaged({  controllerId: "my-plugin/review-batch",  goal: "Revisar nuevas solicitudes de incorporación de cambios",}); const child = taskFlow.runTask({  flowId: created.flowId,  runtime: "acp",  childSessionKey: "agent:main:subagent:reviewer",  task: "Revisar la solicitud de incorporación de cambios n.º 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 se disponga de una clave de sesión de OpenClaw de confianza procedente de la propia capa de vinculación. No se debe vincular a partir de entradas de usuario sin procesar.

Síntesis de texto a voz.

// TTS estándarconst clip = await api.runtime.tts.textToSpeech({  text: "Hola desde OpenClaw",  cfg: api.config,}); // TTS optimizado para telefoníaconst telephonyClip = await api.runtime.tts.textToSpeechTelephony({  text: "Hola desde OpenClaw",  cfg: api.config,}); // Enumerar las voces disponiblesconst voices = await api.runtime.tts.listVoices({  provider: "elevenlabs",  cfg: api.config,});

Utiliza la configuración principal messages.tts y la selección de proveedor. Devuelve un búfer de audio PCM y la frecuencia de muestreo. textToSpeechStream también está disponible para la síntesis en streaming.

Análisis de imágenes, audio y vídeo.

// Describir una imagenconst image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); // Transcribir audioconst { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({  filePath: "/tmp/inbound-audio.ogg",  cfg: api.config,  mime: "audio/ogg", // opcional, para cuando no se pueda inferir el tipo MIME}); // Describir un vídeoconst video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); // Análisis genérico de archivosconst result = await api.runtime.mediaUnderstanding.runFile({  filePath: "/tmp/inbound-file.pdf",  cfg: api.config,}); // Extracción estructurada de imágenes mediante un proveedor/modelo específico.// Incluya al menos una imagen; las entradas de texto son contexto complementario.const evidence = await api.runtime.mediaUnderstanding.extractStructuredWithModel({  provider: "codex",  model: "gpt-5.6-sol",  input: [    {      type: "image",      buffer: receiptImageBuffer,      fileName: "receipt.png",      mime: "image/png",    },    { type: "text", text: "Dar preferencia al total impreso frente a las notas manuscritas." },  ],  instructions: "Extraer el proveedor, el total y las etiquetas de búsqueda.",  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,});

Devuelve { text: undefined } cuando no se produce ninguna salida (por ejemplo, si se omite la entrada).

describeImageFileWithModel(...) describe una imagen ya conocida mediante un proveedor/modelo específico, omitiendo la resolución predeterminada del modelo activo que utiliza describeImageFile(...).

Generación de imágenes.

const result = await api.runtime.imageGeneration.generate({  prompt: "Un robot pintando una puesta de sol",  cfg: api.config,}); const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });

Generación de vídeo, con la misma estructura que la generación de imágenes.

const result = await api.runtime.videoGeneration.generate({  prompt: "Una toma de dron que sobrevuela una costa al amanecer",  cfg: api.config,}); const providers = api.runtime.videoGeneration.listProviders({ cfg: api.config });

Generación de música, con la misma estructura que la generación de imágenes.

const result = await api.runtime.musicGeneration.generate({  prompt: "Una pista lo-fi animada para una sesión de programación",  cfg: api.config,}); const providers = api.runtime.musicGeneration.listProviders({ cfg: api.config });

Búsqueda web.

const providers = api.runtime.webSearch.listProviders({ config: api.config }); const result = await api.runtime.webSearch.search({  config: api.config,  args: { query: "SDK de plugins de OpenClaw", count: 5 },});

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

Instantánea de la configuración actual del entorno de ejecución y escrituras transaccionales de configuración. Se debe preferir la configuración que ya se haya pasado a la ruta de llamada activa; se debe usar current() solo cuando el controlador necesite directamente la instantánea del proceso.

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

mutateConfigFile(...) y replaceConfigFile(...) devuelven un valor followUp, por ejemplo { mode: "restart", requiresRestart: true, reason }, que registra la intención del escritor sin retirar al Gateway el control del reinicio.

Utilidades de nivel de sistema.

await api.runtime.system.enqueueSystemEvent(event);api.runtime.system.requestHeartbeat({  source: "other",  intent: "event",  reason: "plugin-event",});api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // Alias de compatibilidad obsoleto.const heartbeatResult = await api.runtime.system.runHeartbeatOnce({  reason: "plugin-triggered-check",});const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);const hint = api.runtime.system.formatNativeDependencyHint(pkg);

runHeartbeatOnce(...) ejecuta inmediatamente un único ciclo de Heartbeat, omitiendo el temporizador de agrupación normal. Se debe pasar { heartbeat: { target: "last" } } para forzar la entrega al último canal activo en lugar de la supresión predeterminada target: "none".

runCommandWithTimeout(...) devuelve los valores capturados stdout y stderr, recuentos opcionales de truncamiento, code, signal, killed, termination y noOutputTimedOut. Los resultados de tiempo de espera agotado y de tiempo de espera sin salida agotado indican code: 124 cuando el proceso secundario no proporciona un código de salida distinto de cero. Las salidas por señal sin tiempo de espera agotado aún pueden devolver code: null, por lo que se deben usar termination y noOutputTimedOut para distinguir los motivos del tiempo de espera agotado.

Suscripciones a eventos.

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

Registro.

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

Resolución de autenticación de modelos y proveedores.

const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); // Autenticación lista para solicitudes, incluidos los intercambios del entorno de ejecución del proveedor (por ejemplo, la renovación de OAuth)const runtimeAuth = await api.runtime.modelAuth.getRuntimeAuthForModel({ model, cfg }); const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({  provider: "openai",  cfg,});

Resolución del directorio de estado y almacenamiento con claves respaldado por 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();

Los almacenes con claves sobreviven a los reinicios y están aislados por el identificador del plugin vinculado al entorno de ejecución. Se debe usar registerIfAbsent(...) para las reservas atómicas de deduplicación: devuelve true cuando la clave no existía o había caducado y se registró, o false cuando ya existe un valor vigente, sin sobrescribir su valor, hora de creación ni TTL. Límites: maxEntries por espacio de nombres, 50,000 filas vigentes por plugin, valores JSON inferiores a 64KB y caducidad TTL opcional. De forma predeterminada, una escritura que alcance cualquiera de los límites de filas descarta las filas vigentes más antiguas del espacio de nombres en el que se escribe; no se expulsan espacios de nombres hermanos para esa escritura, y la escritura sigue fallando si el espacio de nombres no puede liberar suficientes filas. Se debe establecer overflowPolicy: "reject-new" para los registros de propiedad duraderos que nunca deban expulsarse: las claves nuevas fallan al alcanzar cualquiera de los límites, mientras que las existentes se pueden seguir actualizando.

openSyncKeyedStore<T>(...) devuelve la misma estructura de almacén con métodos síncronos (register, registerIfAbsent, lookup, consume y clear devuelven valores directamente en lugar de promesas) para los llamadores que no puedan esperar.

openChannelIngressQueue<TPayload>(...) abre una cola de entrada persistente limitada al plugin que realiza la llamada, para almacenar en búfer eventos entrantes que necesiten procesamiento al menos una vez entre reinicios. Cuando la recuperación de reservas obsoletas utiliza shouldRecover, también se debe proporcionar shouldRecoverCorrupt si las cargas útiles reservadas dañadas deben ponerse en cuarentena: su identidad de reserva independiente de la carga útil permite que el plugin conserve la política vigente del propietario y del carril antes de que la cola marque la fila como eliminada.

Ayudantes de tiempo de ejecución específicos del canal (disponibles cuando se carga un plugin de canal). Agrupados por función:

api.runtime.channel.media es la superficie recomendada para descargar y almacenar medios de canales:

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

Use saveRemoteMedia(...) cuando una URL remota deba convertirse en un medio de OpenClaw. Use saveResponseMedia(...) cuando el plugin ya haya obtenido un Response con autenticación, gestión de redirecciones o listas de permitidos propias del plugin. Use readRemoteMediaBuffer(...) únicamente cuando el plugin necesite los bytes sin procesar para inspeccionarlos, transformarlos, descifrarlos o volver a cargarlos. fetchRemoteMedia(...) sigue siendo un alias de compatibilidad obsoleto de readRemoteMediaBuffer(...).

api.runtime.channel.mentions es la superficie compartida de políticas de menciones entrantes para los plugins de canal incluidos que utilizan 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 menciones disponibles:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions no expone intencionadamente los antiguos ayudantes de compatibilidad resolveMentionGating*. Es preferible usar la ruta normalizada { facts, policy }.

Varios campos de reply, session y inbound contienen notas @deprecated por campo que apuntan al núcleo actual de turnos de canal o a los adaptadores de salida del canal; consulte el JSDoc integrado del ayudante específico antes de basar código nuevo en él.