Puntos de entrada de Plugin

​

Entradas de paquete

{
  "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 código fuente, usadas para el desarrollo en espacios de trabajo y checkouts de git.
• runtimeExtensions y runtimeSetupEntry son preferidas para paquetes instalados: permiten que los paquetes de 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 falta, la instalación/detección falla con un error de empaquetado; OpenClaw no recurre silenciosamente al código fuente. La alternativa de código fuente (abajo) solo se aplica cuando no se declara ninguna entrada de tiempo de ejecución.
• Si un paquete instalado declara solo una entrada de código fuente TypeScript, OpenClaw busca un par dist/*.js (o .mjs/.cjs) compilado que coincida y lo usa; 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 los pares JS compilados inferidos no hacen válida una ruta de código fuente extensions o setupEntry que se escape.

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

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." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema es opcional; omitirlo usa un esquema estricto de objeto vacío (el manifiesto generado sigue incluyendo configSchema).
• execute devuelve una cadena simple o un valor serializable como JSON; el helper lo envuelve como un resultado de herramienta de texto con details establecido en el valor de retorno original (sin convertir a cadena).
• Para resultados de herramienta personalizados, openclaw/plugin-sdk/tool-results exporta textResult y jsonResult.
• Los nombres de herramientas son estáticos, por lo que openclaw plugins build deriva contracts.tools de las herramientas declaradas sin nombres duplicados a mano.
• La carga en tiempo de ejecución sigue siendo estricta: los plugins instalados aún necesitan openclaw.plugin.json y openclaw.extensions de package.json. OpenClaw nunca ejecuta código del Plugin para inferir datos de manifiesto faltantes.

​

definePluginEntry

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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 está obsoleto: declara un slot exclusivo ("memory" o "context-engine") en el campo kind del manifiesto openclaw.plugin.json en su lugar. El kind de la entrada de tiempo de ejecución permanece solo como alternativa de compatibilidad para plugins antiguos.
• configSchema puede ser una función para evaluación diferida. OpenClaw resuelve y memoiza el esquema en el primer acceso, por lo que los constructores de esquemas costosos solo se ejecutan una vez.

​

defineChannelPluginEntry

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

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 ejecuta en todos los modos excepto "cli-metadata" y "tool-discovery". Almacena aquí la referencia del runtime, normalmente mediante createPluginRuntimeStore.
• registerCliMetadata se ejecuta para "cli-metadata", "discovery" y "full". Úsalo como el lugar canónico para descriptores de CLI propiedad del canal de modo que la ayuda raíz siga sin activarse, las instantáneas de detección incluyan metadatos estáticos de comandos y el registro normal de CLI siga siendo compatible con cargas completas del Plugin.
• registerFull se ejecuta solo para "full" y "tool-discovery". Para "tool-discovery" se ejecuta en lugar de el registro del canal: OpenClaw omite registerChannel/setRuntime por completo y llama solo a registerFull, por lo que cualquier registro de proveedor/herramienta que tu canal necesite para la detección o ejecución independiente de herramientas debe estar allí, no detrás de la configuración normal del canal.
• El registro de detección no activa, pero no evita importaciones: OpenClaw puede evaluar la entrada del Plugin de confianza y el módulo del Plugin de canal para crear la instantánea. Mantén las importaciones de nivel superior libres de efectos secundarios y coloca sockets, clientes, workers y servicios detrás de rutas solo para "full".
• Al igual que definePluginEntry, configSchema puede ser una fábrica diferida; OpenClaw memoiza el esquema resuelto en el primer acceso.

• Usa api.registerCli(..., { descriptors: [...] }) para comandos CLI raíz propiedad del Plugin que quieres cargar de forma diferida sin que desaparezcan del árbol de análisis de la CLI raíz. Los nombres de descriptor deben coincidir con letras, números, guion y guion bajo, empezando por una letra o número; OpenClaw rechaza otras formas y elimina secuencias de control de terminal de las descripciones antes de renderizar la ayuda. Cubre cada raíz de comando de nivel superior que expone el registrador. commands por sí solo permanece en la ruta de compatibilidad eager.
• Usa api.registerNodeCliFeature(...) para comandos de función de nodo emparejado de modo que terminen bajo openclaw nodes (equivalente a registerCli(registrar, { parentPath: ["nodes"], ... })).
• Para otros comandos anidados de Plugin, agrega parentPath y registra comandos en el objeto program pasado al registrador; OpenClaw lo resuelve en el comando padre antes de llamar al Plugin.
• Para plugins de canal, registra descriptores de CLI desde registerCliMetadata y mantén registerFull enfocado en trabajo solo de runtime.
• Si registerFull también registra métodos RPC de Gateway, mantenlos en un prefijo específico del Plugin. Los espacios de nombres reservados de administración del núcleo (config.*, exec.approvals.*, wizard.*, update.*) siempre se fuerzan a operator.admin.

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

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) => {
        /* setup-safe route */
      },
    });
  },
});

​

Modo de registro

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") {
    // Register capability-only surfaces (providers/tools), no channel.
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

​

Formas de plugin

​

Relacionado

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