Instalación y configuración del Plugin

Referencia para empaquetado de plugins (metadatos de package.json), manifiestos (openclaw.plugin.json), entradas de configuración y esquemas de configuración.

Metadatos del paquete

Tu package.json necesita un campo openclaw que indique al sistema de plugins qué proporciona tu plugin:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

Campos de openclaw

openclaw.channel

openclaw.channel son metadatos de paquete ligeros para el descubrimiento de canales y las superficies de configuración antes de que se cargue el runtime.

Ejemplo:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure admite:

• configured: incluir el canal en superficies de listado configuradas/de estilo estado
• setup: incluir el canal en selectores interactivos de configuración
• docs: marcar el canal como público en superficies de documentación/navegación

openclaw.install

openclaw.install son metadatos de paquete, no metadatos de manifiesto.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Carga completa diferida

Los plugins de canal pueden optar por la carga diferida con:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Cuando está habilitado, OpenClaw carga solo setupEntry durante la fase de inicio previa a la escucha, incluso para canales ya configurados. La entrada completa se carga después de que el Gateway comience a escuchar.

Si tu entrada de configuración/completa registra métodos RPC del 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.*) siguen siendo propiedad del núcleo y siempre se resuelven a operator.admin.

Manifiesto del plugin

Cada plugin nativo debe incluir un openclaw.plugin.json en la raíz del paquete. OpenClaw lo usa para validar la configuración sin ejecutar código del plugin.

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Para plugins de canal, añade kind y channels:

{  "id": "my-channel",  "kind": "channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Incluso los plugins sin configuración deben incluir un esquema. Un esquema vacío es válido:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

Consulta Manifiesto del plugin para ver la referencia completa del esquema.

Publicación en ClawHub

Para paquetes de plugin, usa el comando de ClawHub específico del paquete:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Entrada de setup

El archivo setup-entry.ts es una alternativa ligera a index.ts que OpenClaw carga cuando solo necesita superficies de setup (incorporación, reparación de configuración, inspección de canales deshabilitados).

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

Esto evita cargar código de runtime pesado (bibliotecas criptográficas, registros de CLI, servicios en segundo plano) durante los flujos de setup.

Los canales incluidos en el workspace que mantienen exportaciones seguras para setup en módulos complementarios pueden usar defineBundledChannelSetupEntry(...) de openclaw/plugin-sdk/channel-entry-contract en lugar de defineSetupPluginEntry(...). Ese contrato incluido también admite una exportación runtime opcional para que el cableado de runtime en tiempo de setup siga siendo ligero y explícito.

Importaciones acotadas de helpers de setup

Para rutas activas solo de setup, prefiere las interfaces acotadas de helpers de setup en lugar del paraguas más amplio plugin-sdk/setup cuando solo necesites parte de la superficie de setup:

Usa la interfaz más amplia plugin-sdk/setup cuando quieras la caja de herramientas compartida completa de setup, incluidos helpers de parcheo de configuración como moveSingleAccountChannelSectionToDefaultAccount(...).

Los adaptadores de parche de setup siguen siendo seguros de importar en rutas activas. Su búsqueda incluida de superficie de contrato de promoción de cuenta única es diferida, por lo que importar plugin-sdk/setup-runtime no carga de forma anticipada el descubrimiento de superficies de contrato incluidas antes de que el adaptador se use realmente.

Promoción de cuenta única propiedad del canal

Cuando un canal se actualiza desde una configuración de nivel superior de cuenta única a channels.<id>.accounts.*, el comportamiento compartido predeterminado es mover los valores promovidos con ámbito de cuenta a accounts.default.

Los canales incluidos pueden acotar o sobrescribir esa promoción mediante su superficie de contrato de setup:

• singleAccountKeysToMove: claves adicionales de nivel superior que deben moverse a la cuenta promovida
• namedAccountPromotionKeys: cuando ya existen cuentas con nombre, solo estas claves se mueven a la cuenta promovida; las claves compartidas de política/entrega permanecen en la raíz del canal
• resolveSingleAccountPromotionTarget(...): elige qué cuenta existente recibe los valores promovidos

Esquema de configuración

La configuración del Plugin se valida contra el JSON Schema de tu manifiesto. Los usuarios configuran plugins mediante:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Tu Plugin recibe esta configuración como api.pluginConfig durante el registro.

Para configuración específica del canal, usa en su lugar la sección de configuración de canal:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

Crear esquemas de configuración de canal

Usa buildChannelConfigSchema para convertir un esquema de Zod en el contenedor ChannelConfigSchema usado por artefactos de configuración propiedad del Plugin:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

Si ya escribes el contrato como JSON Schema o TypeBox, usa el helper directo para que OpenClaw pueda omitir la conversión de Zod a JSON Schema en rutas de metadatos:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

Para plugins de terceros, el contrato de ruta fría sigue siendo el manifiesto del Plugin: replica el JSON Schema generado en openclaw.plugin.json#channelConfigs para que las superficies de esquema de configuración, setup y UI puedan inspeccionar channels.<id> sin cargar código de runtime.

Asistentes de setup

Los plugins de canal pueden proporcionar asistentes de setup interactivos para openclaw onboard. El asistente es un objeto ChannelSetupWizard en el ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

El tipo ChannelSetupWizard admite credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize y más. Consulta los paquetes de plugins incluidos (por ejemplo, el Plugin de Discord src/channel.setup.ts) para ver ejemplos completos.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

Publicación e instalación

Plugins externos: publica en ClawHub, luego instala:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Plugins dentro del repositorio: colócalos bajo el árbol del espacio de trabajo de plugins incluidos y se descubren automáticamente durante la compilación.

Los usuarios pueden instalar:

openclaw plugins install <package-name>

Los metadatos de los paquetes incluidos son explícitos, no se infieren del JavaScript compilado al iniciar el Gateway. Las dependencias de runtime pertenecen al paquete del plugin que las posee; el inicio de OpenClaw empaquetado nunca repara ni refleja dependencias de plugins.

Relacionado

• Crear plugins — guía paso a paso para empezar
• Manifiesto de Plugin — referencia completa del esquema del manifiesto
• Puntos de entrada del SDK — definePluginEntry y defineChannelPluginEntry