Configuración e instalación de Plugin

Referencia para el 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",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "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 tipo 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/wecom-openclaw-plugin@1.2.3",      "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 empieza a escuchar.

Si tu entrada de configuración/completa registra métodos RPC del Gateway, mantenlos con 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 como operator.admin.

Manifiesto del Plugin

Todo 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 de 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 configuración

El archivo setup-entry.ts es una alternativa ligera a index.ts que OpenClaw carga cuando solo necesita superficies de configuración (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 configuración.

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

Importaciones estrechas de helpers de configuración

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

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

Usa createSetupTranslator(...) para texto fijo del asistente de configuración. Sigue la configuración regional del asistente de CLI (OPENCLAW_LOCALE, luego las variables de configuración regional del sistema) y recurre al inglés. Mantén el texto de configuración específico del plugin en código propiedad del plugin y usa claves de catálogo compartidas solo para etiquetas comunes de configuración, texto de estado y texto de configuración de plugins oficiales incluidos.

Los adaptadores de parches de configuración siguen siendo seguros para rutas activas al importarse. Su búsqueda de superficie de contrato de promoción de cuenta única incluida es perezosa, 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 actualiza una configuración de nivel superior de cuenta única a channels.<id>.accounts.*, el comportamiento compartido predeterminado es mover los valores promocionados con alcance de cuenta a accounts.default.

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

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

Esquema de configuración

La configuración del Plugin se valida contra el esquema JSON 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 de canal, usa en su lugar la sección de configuración del 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: refleja el JSON Schema generado en openclaw.plugin.json#channelConfigs para que las superficies de esquema de configuración, configuración y UI puedan inspeccionar channels.<id> sin cargar código de runtime.

Asistentes de configuración

Los plugins de canal pueden proporcionar asistentes de configuración 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 y 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 de espacio de trabajo de plugins incluidos y se detectarán automáticamente durante la compilación.

Los usuarios pueden instalar:

openclaw plugins install <package-name>

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

Relacionado

• Creación de plugins — guía de introducción paso a paso
• Manifiesto de Plugin — referencia completa del esquema del manifiesto
• Puntos de entrada del SDK — definePluginEntry y defineChannelPluginEntry