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 tiempo 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: 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 arranque previa a escuchar, 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 en un prefijo específico del Plugin. Los espacios de nombres de administración central reservados (config.*, exec.approvals.*, wizard.*, update.*) siguen siendo propiedad del núcleo y siempre se resuelven a operator.admin.

# Manifiesto de 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 Plugins, usa el comando de ClawHub específico del paquete:

clawhub package publish your-org/your-plugin --dry-run
clawhub 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 ejecución pesado (bibliotecas criptográficas, registros de CLI, servicios en segundo plano) durante los flujos de configuración.

Los canales del espacio de trabajo incluidos que mantienen exportaciones seguras para la configuración en módulos complementarios 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 ejecución en tiempo de configuración pueda mantenerse ligero y explícito.

# Importaciones acotadas de auxiliares de configuración

Para rutas activas solo de configuración, prefiere las costuras acotadas de auxiliares de configuración frente al paraguas más amplio plugin-sdk/setup cuando solo necesitas parte de la superficie de configuración:

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

Los adaptadores de parche de configuración 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 con anticipación el descubrimiento incluido de superficie de contrato antes de que el adaptador se use realmente.

# Promoción de cuenta única propiedad del canal

Cuando un canal se actualiza de 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 acotar o reemplazar esa promoción mediante su superficie de contrato de configuración:

• singleAccountKeysToMove: claves adicionales de nivel superior 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 de Plugin se valida frente al 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 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 defines el contrato como JSON Schema o TypeBox, usa el auxiliar 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 el esquema de configuración, la configuración y las superficies de UI 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),
        };
      },
    },
  ],
};

El tipo ChannelSetupWizard admite credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize y más. Consulta los paquetes de Plugin 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 en el repositorio: colócalos bajo el árbol del 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 inferidos del JavaScript compilado al iniciar el Gateway. Las dependencias de tiempo de ejecución pertenecen al paquete del Plugin que las posee; el inicio de OpenClaw empaquetado nunca repara ni replica dependencias de plugins.

# Relacionado

• Crear 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