Configuración y ajustes del 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

El package.json necesita un campo openclaw que indique al sistema de plugins qué proporciona el 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 son metadatos de paquete ligeros para el descubrimiento de canales y las superficies de configuración antes de cargar el entorno de ejecución.

Campos de configuración propiedad del canal

Los plugins de canal deben definir los campos de configuración una sola vez en el código del entorno de ejecución mediante defineChannelSetupContract(...) y publicar la proyección serializable correspondiente en openclaw.channel.setup.fields. La definición del entorno de ejecución infiere el tipo de entrada local del plugin, analiza tanto los valores guiados como los no interactivos y mantiene las claves específicas del canal fuera de los tipos del núcleo. Los metadatos del paquete permiten que openclaw channels add <channel-id> --help y openclaw channels add --channel <channel-id> --help descubran únicamente las opciones del canal seleccionado sin cargar el plugin.

 export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "Punto de conexión del servicio" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "Propietario del transporte" },    },  },  adapter: {    applyAccountConfig: ({ cfg, input }) => ({      ...cfg,      channels: { ...cfg.channels, example: input },    }),  },});

{  "openclaw": {    "channel": {      "id": "example",      "setup": {        "fields": [          {            "key": "endpoint",            "kind": "string",            "cli": { "flags": "--endpoint <url>", "description": "Punto de conexión del servicio" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "Propietario del transporte" }          }        ]      }    }  }}

Los tipos de campo admitidos son string, boolean, integer, string-list y choice. Utilice sensitive: true para las credenciales. Cada clave de campo debe ser igual al nombre de atributo en camelCase de su opción larga de la CLI, incluida cualquier forma negada, como apiToken para --api-token. Los campos booleanos pueden añadir cli.negatedFlags cuando se necesiten tanto las formas positivas como las formas --no-*. channel, account y el name de visualización de la cuenta siguen formando la envoltura de control compartida.

El adaptador publicado setup/ChannelSetupInput continúa disponible para los plugins externos existentes. Los plugins nuevos deben exponer setupContract; OpenClaw siempre lo prefiere cuando ambos están presentes.

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 las superficies de listado de configuración/estado
• setup: incluye el canal en los selectores interactivos de configuración
• docs: marca el canal como visible públicamente en las superficies de documentación/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 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/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 a operator.admin.

Manifiesto del plugin

Cada 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": "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ñ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 ver 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 e 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 CLI y 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 opcional runtime para que el cableado del entorno de ejecución durante la configuración pueda seguir siendo ligero y explícito.

Importaciones limitadas de asistentes de configuración

Para las rutas críticas exclusivas de configuración, prefiera las interfaces limitadas de asistentes 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 asistentes para aplicar parches a la configuración, como moveSingleAccountChannelSectionToDefaultAccount(...).

Utilice createSetupTranslator(...) para el texto fijo del asistente de configuración. Utiliza 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 indicar 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 únicamente 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 al importarse en rutas críticas. La consulta de la superficie del contrato de promoción de cuentas únicas incluidas es diferida, por lo que importar plugin-sdk/setup-runtime no carga anticipadamente el descubrimiento de superficies de contratos incluidos 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 con tipado permanente son name, token, tokenFile, useEnv, allowFrom y defaultTo. Aun pueden existir 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 delimitar sus propios campos de configuración o validarlos mediante 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 permanecen tipados temporalmente para mantener la compatibilidad con fuentes externas. Están obsoletos. Una revisión del registro del 2026-07-22 de 426 plugins de canal publicados fuera del á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 cuenta única propiedad del canal

Cuando un canal pasa de una configuración de nivel superior de una sola cuenta a channels.<id>.accounts.*, el comportamiento compartido predeterminado mueve los valores promovidos con ámbito de 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íticas 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 aunque 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 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 llamar a moveSingleAccountChannelSectionToDefaultAccount(...) con un plugin ya resuelto, pase su adaptador de configuración como setupSurface. Las superficies de configuración proporcionadas por el llamador tienen prioridad sobre la búsqueda cargada e incluida, lo que mantiene los plugins con ámbito 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 asistente 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 en frío sigue siendo el manifiesto del plugin: replique el esquema JSON generado en openclaw.plugin.json#channelConfigs para que las superficies del esquema de configuración, de configuración y de la interfaz de usuario puedan inspeccionar channels.<id> sin cargar código 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 incluido completo.

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 bajo 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 deducen del JavaScript compilado durante el inicio del Gateway. Las dependencias de ejecución pertenecen al paquete del plugin que las posee; 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 del plugin — referencia completa del esquema del manifiesto
• Puntos de entrada del SDK — definePluginEntry y defineChannelPluginEntry