Puntos de entrada de Plugin

​

Entradas de paquetes

{
  "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

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." }),
      }),
      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

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 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

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". 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.

• 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

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) => {
        /* ruta segura para la configuración */
      },
    });
  },
});

​

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") {
    // 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(/* ... */);
}

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

​

Formas de plugins

​

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