Configuración del Plugin y ajustes

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

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

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: incluye el canal en interfaces de listado de canales configurados o de estado
• setup: incluye el canal en los selectores interactivos de configuración
• docs: marca el canal como público en las interfaces de documentación y navegación

openclaw.install

openclaw.install contiene metadatos del paquete, no 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 optar por la carga diferida mediante:

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

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

Si la entrada de configuración o la entrada completa 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.*) siguen siendo propiedad del núcleo y siempre se normalizan como operator.admin.

Manifiesto del plugin

Todo plugin nativo debe incluir un archivo 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": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Para los plugins de canal, añade channels (y, para los plugins de proveedor, añade 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  }}

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

Publicación en ClawHub

Los paquetes de Skills y plugins utilizan comandos de publicación de ClawHub distintos. Para los paquetes de plugins, utiliza 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 las superficies de configuración inicial (incorporación, reparación de la configuración e inspección de canales deshabilitados):

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

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

Los canales incluidos en el espacio de trabajo que mantienen exportaciones seguras para la configuración inicial en módulos auxiliares pueden utilizar defineBundledChannelSetupEntry(...) de openclaw/plugin-sdk/channel-entry-contract en lugar de defineSetupPluginEntry(...). Ese contrato para componentes incluidos también admite una exportación opcional runtime, de modo que la conexión del entorno de ejecución durante la configuración inicial pueda mantenerse ligera y explícita.

Importaciones específicas de ayudantes de configuración inicial

Para las rutas críticas exclusivas de configuración inicial, cuando solo necesites una parte de la superficie de configuración, prefiere los puntos de acceso específicos a los ayudantes de configuración en lugar del módulo general plugin-sdk/setup:

Utiliza el punto de acceso general plugin-sdk/setup cuando quieras el conjunto completo de herramientas compartidas de configuración inicial, incluidos los ayudantes para modificar la configuración, como moveSingleAccountChannelSectionToDefaultAccount(...).

Utiliza createSetupTranslator(...) para el texto fijo del asistente de configuración. Sigue la configuración regional del asistente de la CLI (OPENCLAW_LOCALE y, después, las variables de configuración regional del sistema) y utiliza el inglés como alternativa. Mantén el texto de configuración específico del plugin en el código propiedad del plugin y utiliza las claves del catálogo compartido solo para las etiquetas comunes de configuración, el texto de estado y el texto de configuración de los plugins oficiales incluidos.

Los adaptadores de modificación de la configuración siguen siendo seguros para las rutas críticas al importarlos. La búsqueda de la superficie del contrato para la promoción de cuentas únicas incluidas es diferida, por lo que importar plugin-sdk/setup-runtime no carga anticipadamente el descubrimiento de superficies de contrato incluidas antes de que se utilice realmente el adaptador.

Promoción de cuentas únicas propiedad del canal

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

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

• singleAccountKeysToMove: claves adicionales de nivel superior que deben trasladarse a la cuenta promocionada
• namedAccountPromotionKeys: cuando ya existen cuentas con nombre, solo estas claves se trasladan a la cuenta promocionada; las claves compartidas de políticas y 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 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, utiliza 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

Utiliza buildChannelConfigSchema para convertir un esquema de Zod en el contenedor ChannelConfigSchema que emplean 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 defines el contrato como esquema JSON o TypeBox, utiliza el ayudante 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 la ruta no crítica sigue siendo el manifiesto del plugin: refleja el esquema JSON generado en openclaw.plugin.json#channelConfigs para que las superficies de esquema de configuración, configuración inicial e interfaz de usuario puedan inspeccionar channels.<id> sin cargar código del entorno de ejecución.

Asistentes de configuración

Los plugins de canal pueden proporcionar asistentes interactivos de configuración 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 opciones. Consulta 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, después, 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 durante el inicio del Gateway. Las dependencias de ejecución deben pertenecer al paquete del Plugin que las gestiona; el inicio de OpenClaw empaquetado nunca repara ni replica las dependencias de los Plugins.

Contenido 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