Configuración y ajustes del Plugin

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

Metadatos del paquete

Su package.json necesita un campo openclaw que indique al sistema de plugins qué proporciona su 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": "Mi canal",      "blurb": "Descripción breve del canal."    }  }}

{  "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 contiene metadatos ligeros del paquete para el descubrimiento de canales y las superficies de configuración inicial antes de cargar el entorno de ejecución.

Ejemplo:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "Mi canal",      "selectionLabel": "Mi canal (autoalojado)",      "detailLabel": "Bot de mi canal",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Integración de chat autoalojada basada en Webhook.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guía:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure admite:

• configured: incluye el canal en superficies de listas configuradas o de estado
• setup: incluye el canal en selectores interactivos de configuración inicial
• docs: marca el canal como público en las superficies de documentación y navegación

openclaw.install

openclaw.install son metadatos del paquete, no metadatos del 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 habilitar la carga diferida con:

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

Cuando se habilita, OpenClaw carga únicamente 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 comienza a escuchar.

Si su entrada de configuración/completa registra métodos RPC del Gateway, manténgalos en un prefijo específico del plugin. Los espacios de nombres administrativos reservados del núcleo (config.*, exec.approvals.*, wizard.*, update.*) siguen siendo propiedad del núcleo y siempre se normalizan a operator.admin.

Manifiesto del plugin

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

{  "id": "my-plugin",  "name": "Mi plugin",  "description": "Añade las capacidades de Mi plugin a OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Secreto de verificación del Webhook"      }    }  }}

Para los plugins de canal, añada channels (y, para los plugins de proveedor, añada providers):

{  "id": "my-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  }}

Consulte Manifiesto del plugin para obtener la referencia completa del esquema.

Publicación en ClawHub

Las Skills y los paquetes de plugins utilizan comandos de publicación de ClawHub distintos. Para los paquetes de plugins, utilice el comando específico para paquetes:

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

Entrada de configuración

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 la configuración, inspección de canales deshabilitados):

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

Esto evita cargar código pesado del entorno de ejecución (bibliotecas criptográficas, registros de la CLI, servicios en segundo plano) durante los flujos de configuración.

Los canales incluidos en el espacio de trabajo que mantienen exportaciones seguras para la configuración en módulos auxiliares pueden utilizar 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 del entorno de ejecución durante la configuración pueda seguir siendo ligero y explícito.

Importaciones específicas de auxiliares de configuración

Para las rutas activas exclusivas de configuración, prefiera las interfaces específicas de auxiliares de configuración en lugar del módulo general plugin-sdk/setup cuando solo necesite una parte de la superficie de configuración:

Utilice la interfaz más amplia plugin-sdk/setup cuando necesite el conjunto completo de herramientas compartidas de configuración, incluidos los auxiliares de modificación de la configuración, como moveSingleAccountChannelSectionToDefaultAccount(...).

Utilice createSetupTranslator(...) para el texto fijo del asistente de configuración. Usa el primer valor no vacío de OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES y LANG, en ese orden, y después recurre al inglés. Establezca OPENCLAW_LOCALE=en para una sustitución explícita en inglés. Mantenga el texto de configuración específico del plugin en código propiedad del plugin y utilice las claves del catálogo compartido solo para etiquetas de configuración comunes, texto de estado y texto de configuración de plugins oficiales incluidos.

Los adaptadores de modificación de la configuración siguen siendo seguros al importarlos en rutas activas. La búsqueda de su superficie de contrato incluida para promover configuraciones de una sola cuenta 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 se utilice realmente el adaptador.

Campos de entrada de configuración propiedad del canal

ChannelSetupInput es un contenedor genérico compartido por los invocadores de configuración y los plugins de canal. Sus campos tipados permanentemente son name, token, tokenFile, useEnv, allowFrom y defaultTo. Pueden seguir existiendo claves adicionales propiedad del plugin en el objeto de entrada del entorno de ejecución, pero el tipo compartido no declara una firma de índice. Cada plugin debe declarar y restringir sus propios campos de configuración o validarlos con un esquema propiedad del plugin en el límite del adaptador:

 type AcmeSetupInput = ChannelSetupInput & {  workspaceId?: string;  webhookUrl?: string;}; export const acmeSetupAdapter: ChannelSetupAdapter = {  applyAccountConfig: ({ cfg, input }) => {    const setupInput = input as AcmeSetupInput;    return {      ...cfg,      channels: {        ...cfg.channels,        acme: {          token: setupInput.token,          workspaceId: setupInput.workspaceId,          webhookUrl: setupInput.webhookUrl,        },      },    };  },};

Los campos específicos del canal que anteriormente se declaraban directamente en ChannelSetupInput siguen tipados temporalmente para mantener la compatibilidad con código fuente externo. Están obsoletos. Una revisión del registro realizada el 2026-07-22 sobre 426 plugins de canal publicados y externos al árbol eliminó 21 campos sin lectores y conservó 22 con lectores conocidos. Cada campo conservado se elimina en cuanto ningún plugin publicado lo lee; no se requiere ningún límite de versión. Los plugins nuevos e incluidos no deben depender de este nivel; deben declarar localmente los campos que poseen.

Promoción de una sola cuenta propiedad del canal

Cuando un canal actualiza una configuración de nivel superior para una sola cuenta a channels.<id>.accounts.*, el comportamiento compartido predeterminado mueve los valores promovidos específicos de la cuenta a accounts.default.

Cada plugin de canal puede ampliar o restringir esa promoción mediante su adaptador de configuración:

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

La presencia de singleAccountKeysToMove indica que el contrato de promoción está completo. Declare el campo incluso cuando sea una matriz vacía para excluirse de la promoción de claves heredadas. Los adaptadores que omiten el campo conservan un nivel de promoción anterior a la declaración, respaldado por lectores, para los plugins ya publicados. La revisión del registro del 2026-07-22 eliminó 23 claves sin dependientes publicados y conservó seis claves comunes, además de la clave exclusiva de configuración rooms. Cada clave conservada se elimina en cuanto sus lectores publicados migran a las declaraciones; no se requiere ningún límite de versión.

Declare openclaw.setupFeatures.configPromotion: true en el manifiesto del paquete del plugin cuando el doctor deba cargar estas declaraciones desde el artefacto ligero de configuración incluido. La superficie del plugin exclusiva de configuración y el plugin de canal completo deben exponer las mismas declaraciones.

Al invocar moveSingleAccountChannelSectionToDefaultAccount(...) con un plugin ya resuelto, pase su adaptador de configuración como setupSurface. Las superficies de configuración proporcionadas por el invocador tienen prioridad sobre las búsquedas cargadas e incluidas, lo que mantiene a los plugins con alcance limitado o exclusivos de configuración independientes del registro global.

Esquema de configuración

La configuración del plugin se valida con el esquema JSON del manifiesto. Los usuarios configuran los plugins mediante:

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

El plugin recibe esta configuración como api.pluginConfig durante el registro.

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

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

Creación de esquemas de configuración de canales

Utilice buildChannelConfigSchema para convertir un esquema de Zod en el contenedor ChannelConfigSchema utilizado por los 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 crea el contrato como esquema JSON o TypeBox, utilice el auxiliar directo para que OpenClaw pueda omitir la conversión de Zod a esquema JSON en las rutas de metadatos:

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

Para los plugins de terceros, el contrato de ruta inactiva sigue siendo el manifiesto del plugin: replique el esquema JSON generado en openclaw.plugin.json#channelConfigs para que las superficies de esquema de configuración, configuración e interfaz de usuario puedan inspeccionar channels.<id> sin cargar el código del entorno de ejecución.

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 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),        };      },    },  ],};

ChannelSetupWizard también admite textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize y más. Consulte src/setup-core.ts del plugin de Discord para ver un ejemplo completo incluido.

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: publíquelos en ClawHub y, a continuación, instálelos:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Plugins del repositorio: colóquelos en el árbol del espacio de trabajo de plugins incluidos; se detectan automáticamente durante la compilación.

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

Temas relacionados

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