Migración del SDK de plugins

​

Qué cambió

• openclaw/plugin-sdk y openclaw/plugin-sdk/compat: reexportaban decenas de auxiliares mientras se desarrollaba el SDK específico. Ambas raíces se han eliminado; importe en su lugar una subruta documentada.
• openclaw/plugin-sdk/infra-runtime: un barrel amplio que mezclaba eventos del sistema, estado de Heartbeat, colas de entrega, auxiliares de obtención/proxy, auxiliares de archivos, tipos de aprobación y utilidades no relacionadas.
• openclaw/plugin-sdk/config-runtime: un barrel de configuración amplio conservado únicamente durante su ventana de compatibilidad posterior; se han eliminado los auxiliares directos de carga/escritura en tiempo de ejecución.
• openclaw/extension-api: un puente eliminado que proporcionaba a los plugins acceso directo a auxiliares del lado del host, como el ejecutor de agentes integrado.
• api.registerEmbeddedExtensionFactory(...): un hook eliminado exclusivo del ejecutor integrado que observaba eventos de dicho ejecutor, como tool_result. Use en su lugar middleware de resultados de herramientas del agente (consulte Migrar extensiones de resultados de herramientas integradas a middleware).

​

Motivos

• Inicio lento: importar un auxiliar cargaba decenas de módulos no relacionados.
• Dependencias circulares: las reexportaciones amplias facilitaban la creación de ciclos de importación.
• Superficie de API poco clara: no había forma de distinguir las exportaciones estables de las internas.

• Anthropic mantiene los auxiliares de flujos específicos de Claude en su propia interfaz api.ts / contract-api.ts.
• OpenAI mantiene los constructores de proveedores, los auxiliares de modelos predeterminados y los constructores de proveedores en tiempo real en su propio api.ts.
• OpenRouter mantiene el constructor de proveedores y los auxiliares de incorporación/configuración en su propio api.ts.

​

Política de compatibilidad

1. Añadir el nuevo contrato.
2. Mantener el comportamiento anterior conectado mediante un adaptador de compatibilidad.
3. Emitir un diagnóstico o una advertencia que indique la ruta anterior y su reemplazo.
4. Cubrir ambas rutas en las pruebas.
5. Documentar la obsolescencia y la ruta de migración.
6. Eliminar únicamente después del periodo de migración anunciado, normalmente en una versión principal.

​

Compatibilidad de la configuración de canales publicados

​

Compatibilidad de campos de entrada de configuración de canales

​

Verificación de lectores

1. Recorra por páginas https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 con cada nextCursor y conserve los paquetes cuyos categories incluyan channels.
2. Añada candidatos de npm desde npm search --json --searchlimit=1000 "openclaw channel plugin". Añada candidatos disponibles solo como código fuente a partir de búsquedas de código de GitHub para openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup y openclaw/plugin-sdk/core.
3. Determine la última versión publicada de cada candidato. Ejecute npm pack <package>@<version> --json --pack-destination <temp-dir>, desempaquétela e inspeccione el JavaScript y las declaraciones distribuidos en dist para detectar lecturas directas o desestructuradas de campos. Descargue el artefacto de ClawHub cuando un paquete no tenga una versión en npm.
4. Registre el paquete, la versión, el campo o la clave de promoción y el archivo coincidente. Un campo o una clave solo puede eliminarse cuando ningún artefacto publicado de un plugin lo lea. Mantenga sincronizados con el análisis los nombres de los lectores en los comentarios del código junto a las listas de campos y claves conservados.

​

Proyección heredada de medios

import { toInboundMediaFacts } from "openclaw/plugin-sdk/channel-inbound";

const media = toInboundMediaFacts([
  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },
]);

const ctx = finalizeInboundContext({ Body: caption, media });

​

Cómo migrar

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

// Herramientas del entorno de ejecución de OpenClaw y herramientas dinámicas del entorno de ejecución de Codex (el resultado puede
// transformarse). Los resultados de herramientas nativas de Codex también se retransmiten para su observación,
// pero su salida transformada nunca llega al modelo: el contrato del hook
// PostToolUse de Codex no puede reemplazar una respuesta de herramienta nativa.
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"]
  }
}

// Antes
const program = applyWindowsSpawnProgramPolicy({ candidate });

// Después
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Establezca esto únicamente para llamadores de compatibilidad de confianza que acepten
  // deliberadamente el respaldo mediado por el shell.
  allowShellFallback: true,
});

grep -r "plugin-sdk/compat" my-plugin/
grep -r "plugin-sdk/infra-runtime" my-plugin/
grep -r "plugin-sdk/config-runtime" my-plugin/
grep -r "openclaw/extension-api" my-plugin/

// Antes (capa obsoleta de retrocompatibilidad)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// Después (importaciones modernas específicas)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// Antes (puente extension-api obsoleto)
import { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// Después (entorno de ejecución inyectado)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test my-plugin/

​

Referencia de rutas de importación

​

Superficies de compatibilidad eliminadas

​

Publicación global del proceso de proveedores de API

​

Barrel privado de pruebas

​

Referencia de migración

// Antes
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// Después
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Antes
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Después
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Antes
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// Después
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}

// Antes
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// Después
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Antes
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// Después
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

​

Migración de Talk y voz en tiempo real

// API de sesiones de Talk gestionada por el Gateway.
await gateway.request("talk.session.create", {
  mode: "realtime",
  transport: "gateway-relay",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });
await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "working" },
  options: { willContinue: true },
});
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "already_delivered" },
  options: { suppressResponse: true },
});
await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });
await gateway.request("talk.session.close", { sessionId });

// API de sesiones de proveedor gestionada por el cliente.
await gateway.request("talk.client.create", {
  mode: "realtime",
  transport: "webrtc",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

​

Cronología de eliminación

​

Supresión temporal de las advertencias

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

​

Contenido relacionado

• Primeros pasos - cree su primer plugin
• Descripción general del SDK - referencia completa de importación de subrutas
• Plugins de canal - creación de plugins de canal
• Plugins de proveedor - creación de plugins de proveedor
• Aspectos internos de los plugins - análisis detallado de la arquitectura
• Manifiesto del plugin - referencia del esquema del manifiesto