Correcciones de validación de plugins

ClawHub valida los paquetes de plugin antes de publicarlos y también puede mostrar hallazgos de escaneos automatizados de paquetes. Esta página cubre los hallazgos orientados al autor, es decir, hallazgos que el autor del plugin puede corregir en los metadatos del paquete, el manifiesto, las importaciones del SDK o el artefacto publicado.

No cubre hallazgos internos de cobertura de Plugin Inspector. Si un informe completo contiene códigos de mantenimiento del escáner sin orientación de remediación para el autor, esos son para mantenedores de OpenClaw, no para autores de plugins.

Después de aplicar cualquier corrección, vuelve a ejecutar:

clawhub package validate <path-to-plugin>

Hallazgos orientados al autor

Metadatos del paquete

package-json-missing

La raíz del paquete no incluye package.json, por lo que ClawHub no puede identificar el paquete npm, la versión, los puntos de entrada ni los metadatos de OpenClaw.

• Agrega package.json con name, version y type.
• Agrega un bloque openclaw cuando el paquete incluya un plugin de OpenClaw.
• Usa Crear plugins para ver un ejemplo mínimo de paquete y Manifiesto de plugin para la división entre paquete y manifiesto.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-openclaw-metadata-missing

El paquete tiene package.json, pero no declara metadatos de paquete de OpenClaw.

• Agrega package.json#openclaw.
• Incluye metadatos de punto de entrada como openclaw.extensions o openclaw.runtimeExtensions.
• Agrega metadatos de compatibilidad e instalación cuando el paquete vaya a publicarse o instalarse mediante ClawHub.
• Consulta campos de package.json que afectan el descubrimiento.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-openclaw-entry-missing

Los metadatos del paquete existen, pero no declaran un punto de entrada de runtime de OpenClaw.

• Agrega openclaw.extensions para puntos de entrada de plugins nativos.
• Agrega openclaw.runtimeExtensions cuando el paquete publicado deba cargar JavaScript compilado.
• Mantén todas las rutas de puntos de entrada dentro del directorio del paquete.
• Consulta Puntos de entrada de plugins y campos de package.json que afectan el descubrimiento.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-entrypoint-missing

El paquete declara un punto de entrada de OpenClaw, pero falta el archivo referenciado en el paquete que se está validando.

• Revisa cada ruta en openclaw.extensions, openclaw.runtimeExtensions, openclaw.setupEntry y openclaw.runtimeSetupEntry.
• Compila el paquete si el punto de entrada se genera en dist.
• Actualiza los metadatos si el punto de entrada se movió.
• Consulta Puntos de entrada de plugins.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-install-metadata-incomplete

ClawHub no puede determinar cómo debe instalarse o actualizarse el paquete.

• Completa openclaw.install con la fuente de instalación admitida, como clawhubSpec, npmSpec o localPath.
• Define openclaw.install.defaultChoice cuando haya más de una fuente de instalación disponible.
• Usa openclaw.install.minHostVersion para la versión mínima del host OpenClaw.
• Consulta campos de package.json que afectan el descubrimiento.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-plugin-api-compat-missing

El paquete no declara el rango de API de plugins de OpenClaw que admite.

• Agrega openclaw.compat.pluginApi a package.json.
• Usa la versión de la API de plugins de OpenClaw o el piso semver contra el que compilaste y probaste.
• Mantén esto separado de la versión del paquete. La versión del paquete describe el lanzamiento del plugin; openclaw.compat.pluginApi describe el contrato de API del host.
• Consulta campos de package.json que afectan el descubrimiento.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-min-host-version-drift

La versión mínima del host del paquete no coincide con los metadatos de versión de OpenClaw contra los que se compiló el paquete.

• Revisa openclaw.install.minHostVersion.
• Revisa cualquier metadato de compilación de OpenClaw en el paquete, como la versión de OpenClaw usada durante el lanzamiento.
• Alinea la versión mínima del host con el rango de versiones del host que el paquete realmente admite.
• Consulta campos de package.json que afectan el descubrimiento.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-manifest-version-drift

La versión del paquete y la versión del manifiesto del plugin no coinciden.

• Prefiere package.json#version como versión de lanzamiento del paquete.
• Si openclaw.plugin.json también tiene version, actualízalo para que coincida o elimina metadatos de versión de manifiesto obsoletos cuando los metadatos del paquete sean autoritativos.
• Publica una nueva versión del paquete después de cambiar metadatos publicados.
• Consulta Manifiesto de plugin.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-openclaw-unsupported-metadata

El bloque package.json#openclaw contiene campos que no son metadatos de paquete de OpenClaw admitidos.

• Elimina campos no admitidos como openclaw.bundle.
• Mantén los metadatos de plugins nativos en openclaw.plugin.json.
• Mantén los puntos de entrada del paquete, la compatibilidad, la instalación, la configuración y los metadatos de catálogo en campos admitidos de package.json#openclaw.
• Consulta campos de package.json que afectan el descubrimiento.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

Artefacto publicado

package-npm-pack-unavailable

El paquete no se puede empaquetar en el artefacto que ClawHub inspeccionaría o publicaría.

• Ejecuta npm pack --dry-run desde la raíz del paquete.
• Corrige metadatos de paquete no válidos, scripts de ciclo de vida rotos o entradas de archivos que hacen que el empaquetado falle.
• Elimina private: true si este paquete está destinado a publicación pública.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-npm-pack-entrypoint-missing

El paquete se puede empaquetar, pero el artefacto empaquetado no incluye los archivos de punto de entrada declarados en package.json#openclaw.

• Ejecuta npm pack --dry-run e inspecciona los archivos que se incluirían.
• Compila los puntos de entrada generados antes de empaquetar.
• Actualiza files, .npmignore o la salida de compilación para que se incluyan los puntos de entrada declarados.
• Consulta Puntos de entrada de plugins.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

package-npm-pack-metadata-missing

Al artefacto empaquetado le faltan metadatos de OpenClaw que existen en tu paquete fuente.

• Ejecuta npm pack --dry-run e inspecciona los archivos de metadatos incluidos.
• Asegúrate de que package.json incluya el bloque openclaw en el artefacto empaquetado.
• Asegúrate de que openclaw.plugin.json se incluya cuando el paquete sea un plugin nativo de OpenClaw.
• Actualiza files o .npmignore para que los metadatos del paquete no queden excluidos.
• Consulta Crear plugins.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

Metadatos del manifiesto

manifest-name-missing

El manifiesto del plugin nativo no incluye un nombre para mostrar.

• Agrega un campo name no vacío a openclaw.plugin.json.
• Mantén name legible para humanos y conserva id como el id estable de máquina.
• Consulta Manifiesto de plugin.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

manifest-unknown-fields

El manifiesto del plugin tiene campos de nivel superior que OpenClaw no admite.

• Compara cada campo de nivel superior con la referencia de campos del manifiesto.
• Elimina los campos personalizados de openclaw.plugin.json.
• Mueve los metadatos de paquete o instalación a campos compatibles de package.json#openclaw en lugar del manifiesto.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

manifest-unknown-contracts

El manifiesto declara claves no compatibles dentro de contracts.

• Compara cada clave bajo contracts con la referencia de contracts.
• Elimina las claves de contrato no compatibles.
• Mueve el comportamiento de runtime al código de registro del plugin y mantén contracts limitado a metadatos estáticos de propiedad de capacidades.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

Migración de SDK y compatibilidad

legacy-root-sdk-import

El plugin importa desde el barrel raíz obsoleto del SDK: openclaw/plugin-sdk.

• Sustituye las importaciones del barrel raíz por importaciones de subrutas públicas enfocadas.
• Usa openclaw/plugin-sdk/plugin-entry para definePluginEntry.
• Usa openclaw/plugin-sdk/channel-core para los helpers de entrada de canal.
• Usa Convenciones de importación y Subrutas del SDK de Plugin para encontrar la importación limitada.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

reserved-sdk-import

El plugin importa una ruta del SDK reservada para plugins incluidos o compatibilidad interna.

• Sustituye las importaciones reservadas del SDK interno de OpenClaw por subrutas públicas documentadas de openclaw/plugin-sdk/*.
• Si el comportamiento no tiene SDK público, mantén el helper dentro de tu paquete o solicita una API pública de OpenClaw.
• Usa Subrutas del SDK de Plugin y Migración del SDK para elegir una importación compatible.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

sdk-load-session-store

El plugin todavía usa el helper obsoleto de almacén de sesión completo loadSessionStore.

• Usa getSessionEntry(...) o listSessionEntries(...) al leer el estado de sesión.
• Usa patchSessionEntry(...) o upsertSessionEntry(...) al escribir el estado de sesión.
• Evita cargar, mutar y guardar todo el objeto del almacén de sesión.
• Mantén loadSessionStore(...) solo mientras tu rango de compatibilidad declarado todavía admita versiones anteriores de OpenClaw que lo requieran.
• Consulta API de runtime y Subrutas del SDK de Plugin.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

legacy-before-agent-start

El plugin todavía usa el hook heredado before_agent_start.

• Mueve el trabajo de sobrescritura de modelo o proveedor a before_model_resolve.
• Mueve el trabajo de mutación de prompt o contexto a before_prompt_build.
• Mantén before_agent_start solo mientras tu rango de compatibilidad declarado todavía admita versiones anteriores de OpenClaw que lo requieran.
• Consulta Hooks y Compatibilidad de Plugin.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

provider-auth-env-vars

El manifiesto todavía usa los metadatos heredados de autenticación de proveedor providerAuthEnvVars.

• Refleja los metadatos de variables de entorno del proveedor en setup.providers[].envVars.
• Mantén providerAuthEnvVars solo como metadatos de compatibilidad mientras tu rango compatible de OpenClaw todavía lo necesite.
• Consulta referencia de setup y Migración del SDK.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

channel-env-vars

El manifiesto usa metadatos heredados o anteriores de variables de entorno de canal sin los metadatos actuales de setup o configuración que ClawHub espera.

• Mantén declarativos los metadatos de variables de entorno de canal para que OpenClaw pueda inspeccionar el estado de setup sin cargar el runtime del canal.
• Refleja el setup de canal impulsado por variables de entorno en los metadatos actuales de setup, configuración de canal o paquete de canal usados por la forma de tu plugin.
• Mantén channelEnvVars solo como metadatos de compatibilidad mientras las versiones anteriores compatibles de OpenClaw todavía lo requieran.
• Consulta Manifiesto de Plugin y Plugins de canal.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

Manifiesto de seguridad

security-manifest-schema-unavailable

El paquete distribuye openclaw.security.json con una referencia de esquema que ClawHub no reconoce como disponible.

• Elimina la URL del esquema si es solo orientativa.
• Usa un esquema versionado documentado solo después de que OpenClaw publique uno.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

unrecognized-security-manifest

El paquete distribuye un archivo de manifiesto de seguridad no compatible.

• Elimina openclaw.security.json hasta que OpenClaw documente un esquema versionado de manifiesto de seguridad y el comportamiento de ClawHub.
• Mantén el comportamiento sensible a la seguridad documentado en la documentación pública de tu paquete o README hasta que exista el contrato del manifiesto.
• Vuelve a ejecutar clawhub package validate <path-to-plugin>.

Relacionado

• CLI de ClawHub
• Publicación de ClawHub
• Crear plugins
• Manifiesto de Plugin
• Puntos de entrada de Plugin
• Compatibilidad de Plugin