Migración del SDK de Plugin

OpenClaw ha pasado de una amplia capa de compatibilidad con versiones anteriores a una arquitectura moderna de plugins con importaciones enfocadas y documentadas. Si tu plugin se creó antes de la nueva arquitectura, esta guía te ayuda a migrar.

# Qué está cambiando

El sistema antiguo de plugins proporcionaba dos superficies muy abiertas que permitían a los plugins importar todo lo que necesitaban desde un único punto de entrada:

• openclaw/plugin-sdk/compat - una única importación que reexportaba decenas de ayudantes. Se introdujo para mantener funcionando los plugins antiguos basados en hooks mientras se construía la nueva arquitectura de plugins.
• openclaw/plugin-sdk/infra-runtime - un amplio barrel de ayudantes de runtime que mezclaba eventos del sistema, estado de heartbeat, colas de entrega, ayudantes de fetch/proxy, ayudantes de archivos, tipos de aprobación y utilidades no relacionadas.
• openclaw/plugin-sdk/config-runtime - un amplio barrel de compatibilidad de configuración que todavía contiene ayudantes directos de carga/escritura obsoletos durante la ventana de migración.
• openclaw/extension-api - un puente que daba a los plugins acceso directo a ayudantes del lado del host, como el ejecutor de agentes integrado.
• api.registerEmbeddedExtensionFactory(...) - un hook eliminado de extensión empaquetada exclusivo de Pi que podía observar eventos del ejecutor integrado como tool_result.

Las superficies amplias de importación ahora están obsoletas. Todavía funcionan en runtime, pero los plugins nuevos no deben usarlas, y los plugins existentes deben migrar antes de que la próxima versión mayor las elimine. La API de registro de fábrica de extensión integrada exclusiva de Pi se eliminó; usa middleware de resultados de herramientas en su lugar.

OpenClaw no elimina ni reinterpreta comportamiento documentado de plugins en el mismo cambio que introduce un reemplazo. Los cambios incompatibles de contrato primero deben pasar por un adaptador de compatibilidad, diagnósticos, documentación y una ventana de obsolescencia. Eso aplica a importaciones del SDK, campos de manifiesto, APIs de configuración, hooks y comportamiento de registro en runtime.

# Por qué cambió esto

El enfoque anterior causaba problemas:

• Inicio lento - importar un ayudante cargaba decenas de módulos no relacionados
• Dependencias circulares - las reexportaciones amplias facilitaban crear ciclos de importación
• Superficie de API poco clara - no había forma de saber qué exportaciones eran estables frente a internas

El SDK de plugins moderno corrige esto: cada ruta de importación (openclaw/plugin-sdk/\<subpath\>) es un módulo pequeño y autónomo con un propósito claro y un contrato documentado.

Las costuras de conveniencia heredadas de proveedores para canales empaquetados también desaparecieron. Las costuras auxiliares con marca de canal eran atajos privados del monorepo, no contratos estables de plugins. Usa subrutas genéricas estrechas del SDK en su lugar. Dentro del espacio de trabajo de plugins empaquetados, mantén los ayudantes propiedad del proveedor en el propio api.ts o runtime-api.ts de ese plugin.

Ejemplos actuales de proveedores empaquetados:

• Anthropic mantiene ayudantes de stream específicos de Claude en su propia costura api.ts / contract-api.ts
• OpenAI mantiene constructores de proveedor, ayudantes de modelo predeterminado y constructores de proveedor realtime en su propio api.ts
• OpenRouter mantiene constructor de proveedor y ayudantes de onboarding/configuración en su propio api.ts

# Plan de migración de Talk y voz realtime

El código de voz realtime, telefonía, reuniones y Talk de navegador se está moviendo de contabilidad de turnos local a la superficie a un controlador compartido de sesiones Talk exportado por openclaw/plugin-sdk/realtime-voice. El nuevo controlador posee el sobre común de eventos Talk, el estado de turno activo, el estado de captura, el estado de audio de salida, el historial reciente de eventos y el rechazo de turnos obsoletos. Los plugins de proveedor deben seguir siendo dueños de las sesiones realtime específicas del proveedor; los plugins de superficie deben seguir siendo dueños de captura, reproducción, telefonía y particularidades de reuniones.

Esta migración de Talk rompe limpiamente de forma intencional:

1. Mantén el controlador compartido y las primitivas de runtime en plugin-sdk/realtime-voice.
2. Mueve las superficies empaquetadas al controlador compartido: relé de navegador, traspaso de sala gestionada, realtime de llamada de voz, STT en streaming de llamada de voz, Google Meet realtime y push-to-talk nativo.
3. Reemplaza las familias antiguas de RPC de Talk por la API final talk.session.* y talk.client.*.
4. Anuncia un canal vivo de eventos Talk en Gateway hello-ok.features.events: talk.event.
5. Elimina el antiguo endpoint HTTP realtime y cualquier ruta de sobrescritura de instrucciones en tiempo de solicitud.

El código nuevo no debe llamar directamente a createTalkEventSequencer(...) salvo que esté implementando un adaptador de bajo nivel o fixture de prueba. Prefiere el controlador compartido para que los eventos con alcance de turno no puedan emitirse sin un id de turno, las llamadas obsoletas a turnEnd / turnCancel no puedan borrar un turno activo más nuevo y los eventos del ciclo de vida del audio de salida permanezcan coherentes entre telefonía, reuniones, relé de navegador, traspaso de sala gestionada y clientes Talk nativos.

La forma objetivo de la API pública es:

// Gateway-owned Talk session API.
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 });
await gateway.request("talk.session.close", { sessionId });

// Client-owned provider session API.
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 });

Las sesiones WebRTC/websocket de proveedor propiedad del navegador usan talk.client.create, porque el navegador posee la negociación con el proveedor y el transporte de medios, mientras el Gateway posee credenciales, instrucciones y política de herramientas. talk.session.* es la superficie común gestionada por Gateway para realtime por gateway-relay, transcripción por gateway-relay y sesiones STT/TTS nativas de sala gestionada.

Las configuraciones heredadas que ubicaban selectores realtime junto a talk.provider / talk.providers deben repararse con openclaw doctor --fix; Talk en runtime no reinterpreta la configuración de proveedores de voz/TTS como configuración de proveedor realtime.

Las combinaciones admitidas de talk.session.create son deliberadamente pequeñas:

Mapa de métodos eliminados:

El vocabulario unificado de control también es deliberadamente estrecho:

No introduzcas casos especiales de proveedor o plataforma en core para hacer que esto funcione. Core posee la semántica de sesiones Talk. Los plugins de proveedor poseen la configuración de sesión del proveedor. Voice-call y Google Meet poseen adaptadores de telefonía/reunión. Las aplicaciones de navegador y nativas poseen la experiencia de usuario de captura/reproducción del dispositivo.

# Política de compatibilidad

Para plugins externos, el trabajo de compatibilidad sigue este orden:

1. añade el nuevo contrato
2. mantén el comportamiento antiguo cableado mediante un adaptador de compatibilidad
3. emite un diagnóstico o advertencia que nombre la ruta antigua y su reemplazo
4. cubre ambas rutas en pruebas
5. documenta la obsolescencia y la ruta de migración
6. elimina solo después de la ventana de migración anunciada, normalmente en una versión mayor

Los mantenedores pueden auditar la cola de migración actual con pnpm plugins:boundary-report. Usa pnpm plugins:boundary-report:summary para conteos compactos, --owner <id> para un Plugin o propietario de compatibilidad, y pnpm plugins:boundary-report:ci cuando una compuerta de CI deba fallar por registros de compatibilidad vencidos, importaciones de SDK reservadas entre propietarios o subrutas de SDK reservadas sin usar. El informe agrupa los registros de compatibilidad obsoletos por fecha de eliminación, cuenta las referencias locales de código y documentación, muestra importaciones de SDK reservadas entre propietarios y resume el puente privado del SDK de host de memoria para que la limpieza de compatibilidad siga siendo explícita en lugar de depender de búsquedas ad hoc. Las subrutas de SDK reservadas deben tener uso de propietario registrado; las exportaciones de helpers reservados sin usar deben eliminarse del SDK público.

Si un campo de manifiesto todavía se acepta, los autores de plugins pueden seguir usándolo hasta que la documentación y los diagnósticos indiquen lo contrario. El código nuevo debe preferir el reemplazo documentado, pero los plugins existentes no deben romperse durante versiones menores ordinarias.

# Cómo migrar

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

// Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

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

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

// After
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Only set this for trusted compatibility callers that intentionally
  // accept shell-mediated fallback.
  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/

// Before (deprecated backwards-compatibility layer)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// After (modern focused imports)
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";

// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

# Referencia de rutas de importación

Esta tabla es intencionalmente el subconjunto común de migración, no toda la superficie del SDK. La lista completa de más de 200 puntos de entrada está en scripts/lib/plugin-sdk-entrypoints.json.

Las interfaces auxiliares reservadas para plugins incluidos se retiraron del mapa de exportaciones del SDK público, salvo las fachadas de compatibilidad documentadas explícitamente, como el shim obsoleto plugin-sdk/discord conservado para el paquete publicado @openclaw/[email protected]. Los auxiliares específicos de propietario viven dentro del paquete del plugin propietario; el comportamiento compartido del host debe pasar por contratos genéricos del SDK como plugin-sdk/gateway-runtime, plugin-sdk/security-runtime y plugin-sdk/plugin-config-runtime.

Usa la importación más estrecha que coincida con el trabajo. Si no puedes encontrar una exportación, revisa el código fuente en src/plugin-sdk/ o pregunta a los mantenedores qué contrato genérico debe poseerla.

# Obsolescencias activas

Obsolescencias más acotadas que se aplican al SDK de plugins, el contrato de proveedores, la superficie de runtime y el manifiesto. Cada una aún funciona hoy, pero se eliminará en una versión mayor futura. La entrada debajo de cada elemento asigna la API antigua a su reemplazo canónico.

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

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

# Cronograma de eliminación

Todos los plugins principales ya se migraron. Los plugins externos deben migrar antes de la próxima versión mayor.

# Suprimir las advertencias temporalmente

Define estas variables de entorno mientras trabajas en la migración:

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

Esto es una vía de escape temporal, no una solución permanente.

# Relacionado

• Primeros pasos - crea tu primer plugin
• Resumen del SDK - referencia completa de importaciones por subruta
• Plugins de canal - crear plugins de canal
• Plugins de proveedor - crear plugins de proveedor
• Internals de plugins - análisis profundo de la arquitectura
• Manifiesto de plugin - referencia del esquema del manifiesto