Puntos de entrada de Plugin

Cada plugin exporta un objeto de entrada predeterminado. El SDK proporciona una función auxiliar para cada forma de entrada: defineToolPlugin, definePluginEntry, defineChannelPluginEntry, defineSetupPluginEntry.

Entradas de paquetes

Los plugins instalados hacen que los campos package.json openclaw apunten tanto a las entradas de origen como a las compiladas:

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

• extensions y setupEntry son entradas de origen, utilizadas para el desarrollo en espacios de trabajo y checkouts de git.
• runtimeExtensions y runtimeSetupEntry son las opciones preferidas para los paquetes instalados: permiten que los paquetes npm omitan la compilación de TypeScript en tiempo de ejecución.
• runtimeExtensions, cuando está presente, debe coincidir con extensions en la longitud del arreglo (las entradas se emparejan por posición). runtimeSetupEntry requiere setupEntry.
• Si se declara un artefacto runtimeExtensions/runtimeSetupEntry pero no está presente, la instalación o detección falla con un error de empaquetado; OpenClaw no recurre silenciosamente al código fuente. La alternativa de código fuente (descrita más abajo) solo se aplica cuando no se declara ninguna entrada de tiempo de ejecución.
• Si un paquete instalado declara únicamente una entrada de código fuente TypeScript, OpenClaw busca una entrada compilada equivalente dist/*.js (o .mjs/.cjs) y la utiliza; de lo contrario, recurre al código fuente TypeScript.
• Todas las rutas de entrada deben permanecer dentro del directorio del paquete del plugin. Las entradas de tiempo de ejecución y las entradas equivalentes de JS compilado inferidas no hacen válida una ruta de código fuente extensions o setupEntry que se escape del directorio.

defineToolPlugin

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

Para plugins que solo añaden herramientas de agente. Mantiene el código fuente reducido, infiere los tipos de configuración y de parámetros de herramientas a partir de esquemas TypeBox, envuelve los valores de retorno simples en el formato de resultados de herramientas de OpenClaw y expone metadatos estáticos que openclaw plugins build escribe en el manifiesto del plugin (contracts.tools, configSchema).

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quotes.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "API key." })),  }),  tools: (tool) => [    tool({      name: "quote",      label: "Quote",      description: "Fetch a quote.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol." }),      }),      outputSchema: Type.Object(        {          symbol: Type.String(),          hasKey: Type.Boolean(),        },        { additionalProperties: false },      ),      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),    }),  ],});

• configSchema es opcional; si se omite, se utiliza un esquema estricto de objeto vacío (el manifiesto generado sigue incluyendo configSchema).
• execute devuelve una cadena simple o un valor serializable como JSON; la función auxiliar lo envuelve como un resultado de herramienta de texto con details establecido en el valor de retorno original (sin convertir en cadena).
• outputSchema describe opcionalmente ese valor details original para el modo de código y la búsqueda de herramientas. Las llamadas al catálogo rechazan un esquema no válido antes de la ejecución y validan el valor final antes de devolverlo.
• Para resultados de herramientas personalizados, openclaw/plugin-sdk/tool-results exporta textResult y jsonResult.
• Los nombres de las herramientas son estáticos, por lo que openclaw plugins build deriva contracts.tools de las herramientas declaradas sin duplicar manualmente los nombres.
• La carga en tiempo de ejecución sigue siendo estricta: los plugins instalados aún necesitan openclaw.plugin.json y package.json openclaw.extensions. OpenClaw nunca ejecuta código de plugins para inferir datos faltantes del manifiesto.

definePluginEntry

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

Para plugins de proveedores, plugins de herramientas avanzadas, plugins de hooks y cualquier elemento 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 el manifiesto openclaw.plugin.json.
• Los catálogos de sesiones externas utilizan openclaw/plugin-sdk/session-catalog y api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). El núcleo es propietario de los métodos del Gateway sessions.catalog.*; los proveedores devuelven proyecciones del host, de la sesión y de la transcripción normalizada sin registrar RPC. Un proveedor de listas debe invocar la función de devolución opcional onHost(host) a medida que se completa cada host; el arreglo de hosts devuelto sigue siendo obligatorio como instantánea final de compatibilidad.
• kind está obsoleto: declare un espacio exclusivo ("memory" o "context-engine") en el campo kind del manifiesto openclaw.plugin.json en su lugar. La entrada de tiempo de ejecución kind permanece únicamente como alternativa de compatibilidad para plugins antiguos.
• configSchema puede ser una función para su evaluación diferida. OpenClaw resuelve y memoriza el esquema durante el primer acceso, por lo que los generadores de esquemas costosos solo se ejecutan una vez.
• Un descriptor nodeHostCommands puede definir isAvailable({ config, env }). Devolver false omite ese comando y su capacidad de la declaración del Gateway del nodo sin interfaz gráfica. OpenClaw lo evalúa con respecto a la configuración de inicio local del nodo; los controladores de comandos deben seguir validando la disponibilidad al invocarse.

defineChannelPluginEntry

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

Envuelve definePluginEntry con conexiones específicas del canal: invoca automáticamente api.registerChannel({ plugin }), expone una interfaz opcional de metadatos de la CLI para la ayuda raíz y condiciona registerFull al 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(/* ... */);  },});

Las funciones de devolución se ejecutan según el modo de registro (tabla completa en Modo de registro):

• setRuntime se ejecuta en todos los modos excepto "cli-metadata" y "tool-discovery". Almacene aquí la referencia al entorno de ejecución, normalmente mediante createPluginRuntimeStore.
• registerCliMetadata se ejecuta para "cli-metadata", "discovery" y "full". Utilícelo como ubicación canónica para los descriptores de la CLI propiedad del canal, de modo que la ayuda raíz no provoque la activación, las instantáneas de detección incluyan metadatos estáticos de comandos y el registro normal de la CLI siga siendo compatible con las cargas completas de plugins.
• registerFull se ejecuta únicamente para "full" y "tool-discovery". Para "tool-discovery", se ejecuta en lugar del registro del canal: OpenClaw omite por completo registerChannel/setRuntime e invoca únicamente registerFull, por lo que cualquier registro de proveedores o herramientas que el canal necesite para la detección o ejecución independiente de herramientas debe residir allí, no detrás de la configuración normal del canal.
• El registro de detección no provoca la activación, pero sí puede realizar importaciones: OpenClaw puede evaluar la entrada del plugin de confianza y el módulo del plugin de canal para crear la instantánea. Mantenga las importaciones de nivel superior libres de efectos secundarios y coloque los sockets, clientes, procesos de trabajo y servicios detrás de rutas exclusivas de "full".
• Al igual que definePluginEntry, configSchema puede ser una fábrica diferida; OpenClaw memoriza el esquema resuelto durante el primer acceso.

Registro de la CLI:

• Use api.registerCli(..., { descriptors: [...] }) para los comandos raíz de la CLI propiedad del plugin que se quiera cargar de forma diferida sin que desaparezcan del árbol de análisis de la CLI raíz. Los nombres de los descriptores deben contener letras, números, guiones y guiones bajos, y comenzar con una letra o un número; OpenClaw rechaza otras formas y elimina las secuencias de control del terminal de las descripciones antes de mostrar la ayuda. Abarque cada raíz de comando de nivel superior que exponga el registrador. commands por sí solo permanece en la ruta de compatibilidad de carga inmediata.
• Use api.registerNodeCliFeature(...) para los comandos de funciones de nodos emparejados, de modo que queden bajo openclaw nodes (equivalente a registerCli(registrar, { parentPath: ["nodes"], ... })).
• Para otros comandos de plugins anidados, añada parentPath y registre los comandos en el objeto program pasado al registrador; OpenClaw lo resuelve como el comando principal antes de llamar al plugin.
• Para los plugins de canal, registre los descriptores de la CLI desde registerCliMetadata y mantenga registerFull centrado únicamente en el trabajo de tiempo de ejecución.
• Si registerFull también registra métodos RPC del Gateway, manténgalos bajo un prefijo específico del plugin. Los espacios de nombres administrativos reservados del núcleo (config.*, exec.approvals.*, wizard.*, update.*) siempre se convierten en operator.admin.

defineSetupPluginEntry

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

Para el archivo ligero setup-entry.ts. Devuelve únicamente { plugin }, sin conexiones de tiempo de ejecución ni de la CLI.

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw carga esto en lugar de la entrada completa cuando un canal está deshabilitado, no está configurado o cuando la carga diferida está habilitada. Consulte Configuración para saber cuándo es importante.

Combine defineSetupPluginEntry(...) con las familias específicas de asistentes de configuración:

Mantenga los SDK pesados, el registro de la CLI y los servicios de tiempo de ejecución de larga duración en la entrada completa.

Los canales incluidos en el espacio de trabajo que dividen las superficies de configuración y tiempo de ejecución pueden usar defineBundledChannelSetupEntry(...) de openclaw/plugin-sdk/channel-entry-contract en su lugar. Permite que la entrada de configuración conserve las exportaciones de plugins y secretos seguras para la configuración, a la vez que expone un definidor de tiempo de ejecución:

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },  registerSetupRuntime(api) {    api.registerHttpRoute({      path: "/my-channel/events",      auth: "plugin",      handler: async (req, res) => {        /* ruta segura para la configuración */      },    });  },});

Úselo solo cuando un flujo de configuración necesite realmente un definidor ligero de tiempo de ejecución o una superficie del Gateway segura para la configuración antes de que se cargue la entrada completa del canal. registerSetupRuntime se ejecuta solo para las cargas de "setup-runtime"; limítelo a rutas o métodos exclusivos de configuración que deban existir antes de la activación completa diferida.

Modo de registro

api.registrationMode indica al plugin cómo se cargó:

defineChannelPluginEntry gestiona esta división automáticamente. Si se usa definePluginEntry directamente para un canal, compruebe el modo y recuerde que "tool-discovery" omite el registro del canal:

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   if (api.registrationMode === "tool-discovery") {    // Registre superficies exclusivas de capacidades (proveedores/herramientas), sin canal.    return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // Registros pesados exclusivos del tiempo de ejecución  api.registerService(/* ... */);}

Los servicios de larga duración pueden emitir pequeños eventos de invalidación o del ciclo de vida mediante su contexto de servicio:

api.registerService({  id: "index-events",  start(ctx) {    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });  },});

OpenClaw aplica el espacio de nombres plugin.<plugin-id>.changed. Los nombres de los eventos constan de un segmento en minúsculas, las cargas útiles deben ser JSON acotado y el ámbito debe ser operator.read, operator.write o operator.admin. El emisor existe únicamente durante la vida útil del servicio y se revoca tras la detención o un inicio fallido. Prefiera cargas útiles de versión o invalidación en lugar de registros completos para que los clientes autorizados vuelvan a leer el estado canónico mediante los métodos de Gateway con ámbito del plugin.

El modo de detección crea una instantánea del registro sin activación. Aun así, puede evaluar la entrada del plugin y el objeto del plugin de canal para que OpenClaw pueda registrar las capacidades del canal y los descriptores estáticos de la CLI. Trate la evaluación del módulo durante la detección como fiable, pero ligera: sin clientes de red, subprocesos, escuchas, conexiones de bases de datos, procesos de trabajo en segundo plano, lecturas de credenciales ni otros efectos secundarios activos del tiempo de ejecución en el nivel superior.

Considere "setup-runtime" como la ventana en la que las superficies de inicio exclusivas de la configuración deben existir sin volver a entrar en el tiempo de ejecución completo del canal incluido. Las opciones adecuadas son el registro del canal, las rutas HTTP seguras para la configuración, los métodos del Gateway seguros para la configuración y los asistentes de configuración delegados. Los servicios pesados en segundo plano, los registradores de la CLI y las inicializaciones de SDK de proveedores/clientes siguen perteneciendo a "full".

Formas de plugins

OpenClaw clasifica los plugins cargados según su comportamiento de registro:

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

Contenido relacionado

• Descripción general del SDK - referencia de la API de registro y las subrutas
• Asistentes de tiempo de ejecución - api.runtime y createPluginRuntimeStore
• Configuración - manifiesto, entrada de configuración y carga diferida
• Plugins de canal - creación del objeto ChannelPlugin
• Plugins de proveedores - registro y enlaces de proveedores