Funciones auxiliares de tiempo de ejecución del Plugin

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

// Resolve the agent's working directoryconst agentDir = api.runtime.agent.resolveAgentDir(cfg); // Resolve agent workspaceconst workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg); // Get agent identityconst identity = api.runtime.agent.resolveAgentIdentity(cfg); // Get default thinking levelconst thinking = api.runtime.agent.resolveThinkingDefault({  cfg,  provider,  model,}); // Validate a user-provided thinking level against the active provider profileconst policy = api.runtime.agent.resolveThinkingPolicy({ provider, model });const level = api.runtime.agent.normalizeThinkingLevel("extra high");if (level && policy.levels.some((entry) => entry.id === level)) {  // pass level to an embedded run} // Get agent timeoutconst timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); // Ensure workspace existsawait api.runtime.agent.ensureAgentWorkspace(cfg); // Run an embedded agent turnconst result = await api.runtime.agent.runEmbeddedAgent({  sessionId: "my-plugin:task-1",  runId: crypto.randomUUID(),  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),  prompt: "Summarize the latest changes",  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),});

runEmbeddedAgent(...) es el helper neutral para iniciar un turno normal de agente de OpenClaw desde código de plugin. Usa la misma resolución de proveedor/modelo y selección de arnés de agente que las respuestas activadas por canales.

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

resolveThinkingPolicy(...) devuelve los niveles de pensamiento admitidos del proveedor/modelo y el valor predeterminado opcional. Los plugins de proveedor controlan el perfil específico del modelo mediante sus hooks de pensamiento, por lo que los plugins de herramientas deben llamar a este helper de runtime en lugar de importar o duplicar listas de proveedores.

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

Los helpers de almacén de sesiones están bajo api.runtime.agent.session:

const entry = api.runtime.agent.session.getSessionEntry({ agentId, sessionKey });for (const { sessionKey, entry } of api.runtime.agent.session.listSessionEntries({ agentId })) {  // Iterate session rows without depending on the legacy sessions.json shape.}await api.runtime.agent.session.patchSessionEntry({  agentId,  sessionKey,  update: (entry) => ({ thinkingLevel: "high" }),}); const storePath = api.runtime.agent.session.resolveStorePath(cfg.session?.store, { agentId });await api.runtime.agent.session.runWithWorkAdmission(  { storePath, sessionKey },  async (signal) => {    // Create or update the session, then pass signal to the admitted agent run.  },);

Prefiere getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) o upsertSessionEntry(...) para flujos de trabajo de sesión. Estos helpers dirigen las sesiones por identidad de agente/sesión para que los plugins no dependan de la forma de almacenamiento heredada sessions.json. Usa preserveActivity: true para parches solo de metadatos que no deban actualizar la actividad de la sesión, y replaceEntry: true solo cuando el callback devuelve una entrada completa y los campos eliminados deben permanecer eliminados.

Usa runWithWorkAdmission(...) cuando un plugin inicia trabajo en una sesión persistida. El callback rechaza sesiones archivadas o reemplazadas concurrentemente, mantiene coordinadas las mutaciones de archivo/restablecimiento/eliminación hasta la finalización y recibe un AbortSignal que debe reenviarse a la ejecución del agente.

Para lecturas y escrituras de transcripciones, importa openclaw/plugin-sdk/session-transcript-runtime y usa resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) o withSessionTranscriptWriteLock(...) con { agentId, sessionKey, sessionId }. Estas API permiten que los plugins identifiquen una transcripción, lean sus eventos, agreguen mensajes, publiquen actualizaciones y ejecuten operaciones relacionadas bajo el mismo bloqueo de escritura de transcripción. Pasar sessionFile, usar resolveSessionTranscriptLegacyFileTarget(...) o importar appendSessionTranscriptMessage(...) / emitSessionTranscriptUpdate(...) de bajo nivel desde openclaw/plugin-sdk/agent-harness-runtime está obsoleto; esas rutas existen solo para código heredado que ya recibe un artefacto de transcripción activo.

loadSessionStore(...), saveSessionStore(...), updateSessionStore(...), resolveSessionFilePath(...) y resolveAndPersistSessionFile(...) son helpers de compatibilidad obsoletos para plugins que todavía dependen intencionalmente de la forma heredada de almacén completo o archivo de transcripción. El código nuevo de plugins no debe usar esos helpers, y los llamadores existentes deben migrar a helpers de entrada y helpers de identidad de transcripción.

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"

Ejecuta una finalización de texto propiedad del host sin importar componentes internos del proveedor ni duplicar la preparación de modelo/autenticación/URL base de OpenClaw.

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

El helper usa la misma ruta de preparación de finalización simple que el runtime integrado de OpenClaw y la instantánea de configuración de runtime propiedad del host. Los motores de contexto reciben una capacidad llm.complete vinculada a la sesión, por lo que las llamadas de modelo usan el agente de la sesión activa y no recurren silenciosamente al agente predeterminado. El resultado incluye atribución de proveedor/modelo/agente más uso normalizado de tokens, caché y coste estimado cuando está disponible.

Inicia y administra ejecuciones de subagentes en segundo plano.

// Start a subagent runconst { 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 completionconst result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); // Read session messagesconst { messages } = await api.runtime.subagent.getSessionMessages({  sessionKey: "agent:main:subagent:search-helper",  limit: 10,}); // Delete a sessionawait api.runtime.subagent.deleteSession({  sessionKey: "agent:main:subagent:search-helper",});

deleteSession(...) puede eliminar sesiones creadas por el mismo plugin mediante api.runtime.subagent.run(...). Eliminar sesiones arbitrarias de usuarios u operadores todavía requiere una solicitud Gateway con alcance de administrador.

Enumera los nodos conectados e invoca un comando de host de nodo desde código de plugin cargado por Gateway o desde comandos CLI del plugin. Usa esto cuando un plugin posee trabajo local en un dispositivo emparejado, por ejemplo, un navegador o puente de 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,});

Dentro del Gateway, este runtime está en proceso. En comandos CLI de plugins, llama al Gateway configurado mediante RPC, por lo que comandos como openclaw googlemeet recover-tab pueden inspeccionar nodos emparejados desde la terminal. Los comandos Node aún pasan por el emparejamiento normal de nodos de Gateway, listas de permisos de comandos, políticas de invocación de nodos del plugin y manejo de comandos local del nodo.

Los plugins que exponen comandos de host de nodo peligrosos deben registrar una política de invocación de nodos con api.registerNodeInvokePolicy(...). La política se ejecuta en el Gateway después de las comprobaciones de la lista de permisos de comandos y antes de que el comando se reenvíe al nodo, por lo que las llamadas directas a node.invoke y las herramientas de plugin de nivel superior comparten la misma ruta de aplicación.

Vincula un runtime de flujo de tareas a una clave de sesión existente de OpenClaw o a un contexto de herramienta de confianza, y luego crea y administra flujos de tareas sin pasar un propietario en cada llamada.

El flujo de tareas rastrea el estado duradero de flujos de trabajo de varios pasos. No es un programador: usa Cron o api.session.workflow.scheduleSessionTurn(...) para activaciones futuras, y luego usa managedFlows desde el turno programado cuando ese trabajo necesite estado de 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: "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" },});

Usa bindSession({ sessionKey, requesterOrigin }) cuando ya tengas una clave de sesión de OpenClaw de confianza desde tu propia capa de vinculación. No vincules desde entrada de usuario sin procesar.

Síntesis de texto a voz.

// Standard TTSconst clip = await api.runtime.tts.textToSpeech({  text: "Hello from OpenClaw",  cfg: api.config,}); // Telephony-optimized TTSconst telephonyClip = await api.runtime.tts.textToSpeechTelephony({  text: "Hello from OpenClaw",  cfg: api.config,}); // List available voicesconst 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 búfer de audio PCM + frecuencia de muestreo.

Análisis de imágenes, audio y video.

// Describe an imageconst image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); // Transcribe audioconst { 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 videoconst video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); // Generic file analysisconst result = await api.runtime.mediaUnderstanding.runFile({  filePath: "/tmp/inbound-file.pdf",  cfg: api.config,}); // Structured image extraction through a specific provider/model.// Include at least one image; text inputs are supplemental context.const evidence = await api.runtime.mediaUnderstanding.extractStructuredWithModel({  provider: "codex",  model: "gpt-5.5",  input: [    {      type: "image",      buffer: receiptImageBuffer,      fileName: "receipt.png",      mime: "image/png",    },    { type: "text", text: "Prefer the printed total over handwritten notes." },  ],  instructions: "Extract vendor, total, and searchable tags.",  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, entrada omitida).

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

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

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 });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 configuración del runtime actual y escrituras de configuración transaccionales. Prefiere la configuración que ya se pasó a la ruta de llamada activa; usa current() solo cuando el manejador 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 quitarle el control de reinicio al gateway.

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" }); // Deprecated compatibility alias.const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);const hint = api.runtime.system.formatNativeDependencyHint(pkg);

runCommandWithTimeout(...) devuelve stdout y stderr capturados, conteos opcionales de truncamiento, code, signal, killed, termination y noOutputTimedOut. Los resultados de tiempo de espera y de tiempo de espera sin salida informan code: 124 cuando el proceso hijo no proporciona un código de salida distinto de cero. Las salidas por señal sin tiempo de espera aún pueden devolver code: null, así que usa termination y noOutputTimedOut para distinguir los motivos del tiempo de espera.

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 });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 id del plugin vinculado al runtime. Usa registerIfAbsent(...) para reclamos atómicos de deduplicación: devuelve true cuando la clave faltaba o había expirado y se registró, o false cuando ya existe un valor activo sin sobrescribir su valor, hora de creación ni TTL. Límites: maxEntries por espacio de nombres, 6000 filas activas por plugin, valores JSON de menos de 64 KB y expiración TTL opcional. Cuando una escritura superaría el límite de filas del plugin, el runtime puede expulsar las filas activas más antiguas del espacio de nombres que se está escribiendo; los espacios de nombres hermanos no se expulsan para esa escritura, y la escritura sigue fallando si el espacio de nombres no puede liberar suficientes filas.

Fábricas de herramientas de memoria y CLI.

const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);api.runtime.tools.registerMemoryCli(/* ... */);

Ayudantes de runtime específicos de canal (disponibles cuando se carga un plugin de canal).

api.runtime.channel.media es la superficie preferida para descargas y almacenamiento de medios del canal:

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

Usa saveRemoteMedia(...) cuando una URL remota deba convertirse en medios de OpenClaw. Usa saveResponseMedia(...) cuando el plugin ya haya obtenido una Response con manejo de autenticación, redirecciones o listas de permitidos propiedad del plugin. Usa readRemoteMediaBuffer(...) solo cuando el plugin necesite bytes sin procesar para inspección, transformaciones, descifrado o recarga. 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 plugins de canal incluidos que usan inyección de 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,  },});

Ayudantes de menciones disponibles:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions no expone intencionalmente los antiguos ayudantes de compatibilidad resolveMentionGating*. Prefiere la ruta normalizada { facts, policy }.