Puntos de entrada del Plugin

Cada plugin exporta un objeto de entrada predeterminado. El SDK proporciona tres helpers para crearlos.

Para los plugins instalados, package.json debe dirigir la carga en tiempo de ejecución a JavaScript compilado cuando esté disponible:

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

extensions y setupEntry siguen siendo entradas de código fuente válidas para desarrollo en workspace y checkout de git. runtimeExtensions y runtimeSetupEntry son preferidas cuando OpenClaw carga un paquete instalado y permiten que los paquetes npm eviten la compilación de TypeScript en tiempo de ejecución. Las entradas runtime explícitas son obligatorias: runtimeSetupEntry requiere setupEntry, y los artefactos runtimeExtensions o runtimeSetupEntry faltantes hacen fallar la instalación/detección en lugar de recurrir silenciosamente al código fuente. Si un paquete instalado solo declara una entrada de código fuente TypeScript, OpenClaw usará un par compilado dist/*.js coincidente cuando exista, y luego recurrirá al código fuente TypeScript.

Todas las rutas de entrada deben permanecer dentro del directorio del paquete del plugin. Las entradas runtime y los pares JavaScript compilados inferidos no hacen válida una ruta de código fuente extensions o setupEntry que escape del paquete.

definePluginEntry

Importación: openclaw/plugin-sdk/plugin-entry

Para plugins de proveedor, plugins de herramientas, plugins de hooks y cualquier cosa que no sea un canal de mensajería.

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({      /* ... */    });    api.registerTool({      /* ... */    });  },});

• id debe coincidir con tu manifiesto openclaw.plugin.json.
• kind es para slots exclusivos: "memory" o "context-engine".
• configSchema puede ser una función para evaluación diferida.
• OpenClaw resuelve y memoiza ese esquema en el primer acceso, por lo que los constructores de esquemas costosos solo se ejecutan una vez.

defineChannelPluginEntry

Importación: openclaw/plugin-sdk/channel-core

Envuelve definePluginEntry con cableado específico de canal. Llama automáticamente a api.registerChannel({ plugin }), expone una costura opcional de metadatos CLI de ayuda raíz y restringe registerFull según el modo de registro.

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

• setRuntime se llama durante el registro para que puedas almacenar la referencia runtime (normalmente mediante createPluginRuntimeStore). Se omite durante la captura de metadatos CLI.
• registerCliMetadata se ejecuta durante api.registrationMode === "cli-metadata", api.registrationMode === "discovery" y api.registrationMode === "full". Úsalo como el lugar canónico para descriptores CLI propiedad del canal, de modo que la ayuda raíz no active el canal, las instantáneas de detección incluyan metadatos estáticos de comandos y el registro normal de comandos CLI siga siendo compatible con cargas completas del plugin.
• El registro de detección no activa el plugin, pero no está libre de importaciones. OpenClaw puede evaluar la entrada del plugin confiable y el módulo del plugin de canal para construir la instantánea, así que mantén las importaciones de nivel superior sin efectos secundarios y pon sockets, clientes, workers y servicios detrás de rutas solo para "full".
• registerFull solo se ejecuta cuando api.registrationMode === "full". Se omite durante la carga solo de setup.
• Igual que definePluginEntry, configSchema puede ser una fábrica diferida y OpenClaw memoiza el esquema resuelto en el primer acceso.
• Para comandos CLI raíz propiedad de plugins, prefiere api.registerCli(..., { descriptors: [...] }) cuando quieras que el comando permanezca con carga diferida sin desaparecer del árbol de análisis de la CLI raíz. Para comandos de función de nodo emparejado, prefiere api.registerNodeCliFeature(...) para que el comando quede bajo openclaw nodes. Para otros comandos de plugin anidados, agrega parentPath y registra comandos en el objeto program pasado al registrador; OpenClaw lo resuelve al comando padre antes de llamar al plugin. Para plugins de canal, prefiere registrar esos descriptores desde registerCliMetadata(...) y mantener registerFull(...) enfocado en trabajo solo de runtime.
• Si registerFull(...) también registra métodos RPC del Gateway, mantenlos en un prefijo específico del plugin. Los namespaces reservados de administración del núcleo (config.*, exec.approvals.*, wizard.*, update.*) siempre se fuerzan a operator.admin.

defineSetupPluginEntry

Importación: openclaw/plugin-sdk/channel-core

Para el archivo ligero setup-entry.ts. Devuelve solo { plugin }, sin cableado runtime ni CLI.

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw carga esto en lugar de la entrada completa cuando un canal está deshabilitado, sin configurar o cuando la carga diferida está habilitada. Consulta Setup y configuración para saber cuándo importa esto.

En la práctica, combina defineSetupPluginEntry(...) con las familias estrechas de helpers de setup:

• openclaw/plugin-sdk/setup-runtime para helpers de setup seguros para runtime, como adaptadores de parches de setup seguros para importación, salida de notas de búsqueda, promptResolvedAllowFrom, splitSetupEntries y proxies de setup delegados
• openclaw/plugin-sdk/channel-setup para superficies de setup de instalación opcional
• openclaw/plugin-sdk/setup-tools para helpers CLI/de archivo/de documentación de setup/instalación

Mantén SDKs pesados, registro CLI y servicios runtime de larga duración en la entrada completa.

Los canales de workspace incluidos que dividen superficies de setup y runtime pueden usar defineBundledChannelSetupEntry(...) desde openclaw/plugin-sdk/channel-entry-contract en su lugar. Ese contrato permite que la entrada de setup conserve exportaciones de plugin/secretos seguras para setup y, a la vez, exponga un setter runtime:

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },});

Usa ese contrato incluido solo cuando los flujos de setup realmente necesiten un setter runtime ligero antes de que cargue la entrada completa del canal.

Modo de registro

api.registrationMode le indica a tu plugin cómo se cargó:

defineChannelPluginEntry gestiona esta división automáticamente. Si usas definePluginEntry directamente para un canal, comprueba el modo tú mismo:

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // Heavy runtime-only registrations  api.registerService(/* ... */);}

El modo de detección construye una instantánea de registro que no activa el plugin. Aun así, puede evaluar la entrada del plugin y el objeto del plugin de canal para que OpenClaw pueda registrar capacidades de canal y descriptores CLI estáticos. Trata la evaluación de módulos en detección como confiable pero ligera: sin clientes de red, subprocesos, listeners, conexiones a bases de datos, workers en segundo plano, lecturas de credenciales ni otros efectos secundarios runtime activos en el nivel superior.

Trata "setup-runtime" como la ventana donde las superficies de inicio solo de setup deben existir sin volver a entrar en el runtime completo del canal incluido. Encajan bien el registro de canal, rutas HTTP seguras para setup, métodos Gateway seguros para setup y helpers de setup delegados. Los servicios pesados en segundo plano, registradores CLI e inicializaciones de SDK de proveedores/clientes siguen perteneciendo a "full".

Para registradores CLI específicamente:

• usa descriptors cuando el registrador posee uno o más comandos raíz y quieres que OpenClaw cargue de forma diferida el módulo real de la CLI en la primera invocación
• asegúrate de que esos descriptores cubran cada raíz de comando de nivel superior expuesta por el registrador
• limita los nombres de comandos de descriptor a letras, números, guion y guion bajo, empezando por una letra o un número; OpenClaw rechaza los nombres de descriptor fuera de esa forma y elimina las secuencias de control de terminal de las descripciones antes de renderizar la ayuda
• usa solo commands únicamente para rutas de compatibilidad de carga inmediata

Formas de Plugin

OpenClaw clasifica los plugins cargados por su comportamiento de registro:

Usa openclaw plugins inspect <id> para ver la forma de un plugin.

Relacionado

• Resumen del SDK - API de registro y referencia de subrutas
• Ayudantes de runtime - api.runtime y createPluginRuntimeStore
• Configuración y ajustes - manifiesto, entrada de configuración, carga diferida
• Plugins de canal - creación del objeto ChannelPlugin
• Plugins de proveedor - registro de proveedores y hooks