Correcciones de validación de plugins

ClawHub valida los paquetes de plugins antes de publicarlos y también puede mostrar hallazgos de análisis automatizados de paquetes. Esta página trata los hallazgos dirigidos a los autores, es decir, aquellos que el autor del plugin puede corregir en los metadatos del paquete, el manifiesto, las importaciones del SDK o el artefacto publicado.

No trata los hallazgos de cobertura internos de Plugin Inspector. Si un informe completo contiene códigos de mantenimiento del analizador sin instrucciones de corrección para el autor, estos están destinados a los mantenedores de OpenClaw y no a los autores de plugins.

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

clawhub package validate <path-to-plugin>

Hallazgos dirigidos a los autores

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.

• Añada package.json con name, version y type.
• Añada un bloque openclaw cuando el paquete incluya un plugin de OpenClaw.
• Consulte Creación de plugins para ver un ejemplo mínimo de paquete y Manifiesto del plugin para conocer la separación entre el paquete y el manifiesto.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-openclaw-metadata-missing

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

• Añada package.json#openclaw.
• Incluya metadatos de puntos de entrada, como openclaw.extensions o openclaw.runtimeExtensions.
• Añada metadatos de compatibilidad e instalación cuando el paquete se vaya a publicar o instalar mediante ClawHub.
• Consulte Campos de package.json que afectan al descubrimiento.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-openclaw-entry-missing

Los metadatos del paquete existen, pero no declaran un punto de entrada del entorno de ejecución de OpenClaw.

• Añada openclaw.extensions para los puntos de entrada de plugins nativos.
• Añada openclaw.runtimeExtensions cuando el paquete publicado deba cargar JavaScript compilado.
• Mantenga todas las rutas de los puntos de entrada dentro del directorio del paquete.
• Consulte Puntos de entrada de plugins y Campos de package.json que afectan al descubrimiento.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-entrypoint-missing

El paquete declara un punto de entrada de OpenClaw, pero el archivo al que se hace referencia no está en el paquete que se está validando.

• Compruebe cada ruta de openclaw.extensions, openclaw.runtimeExtensions, openclaw.setupEntry y openclaw.runtimeSetupEntry.
• Compile el paquete si el punto de entrada se genera en dist.
• Actualice los metadatos si se movió el punto de entrada.
• Consulte Puntos de entrada de plugins.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-install-metadata-incomplete

ClawHub no puede determinar cómo se debe instalar o actualizar el paquete.

• Complete openclaw.install con la fuente de instalación compatible, como clawhubSpec, npmSpec o localPath.
• Defina openclaw.install.defaultChoice cuando haya más de una fuente de instalación disponible.
• Utilice openclaw.install.minHostVersion para la versión mínima del host de OpenClaw.
• Consulte Campos de package.json que afectan al descubrimiento.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-plugin-api-compat-missing

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

• Añada openclaw.compat.pluginApi a package.json.
• Utilice la versión de la API de plugins de OpenClaw o la versión mínima semántica con la que se haya compilado y probado el paquete.
• Mantenga este valor separado de la versión del paquete. La versión del paquete describe la versión del plugin; openclaw.compat.pluginApi describe el contrato de la API del host.
• Consulte Campos de package.json que afectan al descubrimiento.
• Vuelva 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 con los que se compiló el paquete.

• Compruebe openclaw.install.minHostVersion.
• Compruebe cualquier metadato de compilación de OpenClaw del paquete, como la versión de OpenClaw utilizada durante la publicación.
• Alinee la versión mínima del host con el intervalo de versiones del host que el paquete admite realmente.
• Consulte Campos de package.json que afectan al descubrimiento.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-manifest-version-drift

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

• Prefiera package.json#version como versión de publicación del paquete.
• Si openclaw.plugin.json también contiene version, actualícelo para que coincida o elimine los metadatos de versión obsoletos del manifiesto cuando los metadatos del paquete sean la fuente autoritativa.
• Publique una nueva versión del paquete después de cambiar los metadatos publicados.
• Consulte Manifiesto del plugin.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-openclaw-unsupported-metadata

El bloque package.json#openclaw contiene campos que no se admiten como metadatos de paquete de OpenClaw.

• Elimine los campos no compatibles, como openclaw.bundle.
• Mantenga los metadatos de plugins nativos en openclaw.plugin.json.
• Mantenga los puntos de entrada, la compatibilidad, la instalación, la configuración y los metadatos del catálogo del paquete en campos compatibles de package.json#openclaw.
• Consulte Campos de package.json que afectan al descubrimiento.
• Vuelva 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.

• Ejecute npm pack --dry-run desde la raíz del paquete.
• Corrija los metadatos del paquete no válidos, los scripts del ciclo de vida defectuosos o las entradas de archivos que impidan el empaquetado.
• Elimine private: true si este paquete está destinado a la publicación pública.
• Vuelva 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 puntos de entrada declarados en package.json#openclaw.

• Ejecute npm pack --dry-run e inspeccione los archivos que se incluirían.
• Compile los puntos de entrada generados antes de empaquetar.
• Actualice files, .npmignore o la salida de compilación para que se incluyan los puntos de entrada declarados.
• Consulte Puntos de entrada de plugins.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

package-npm-pack-metadata-missing

Al artefacto empaquetado le faltan metadatos de OpenClaw que existen en el paquete de origen.

• Ejecute npm pack --dry-run e inspeccione los archivos de metadatos incluidos.
• Asegúrese de que package.json incluya el bloque openclaw en el artefacto empaquetado.
• Asegúrese de que se incluya openclaw.plugin.json cuando el paquete sea un plugin nativo de OpenClaw.
• Actualice files o .npmignore para que no se excluyan los metadatos del paquete.
• Consulte Creación de plugins.
• Vuelva 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.

• Añada un campo name no vacío a openclaw.plugin.json.
• Mantenga name legible para las personas y id como identificador estable para la máquina.
• Consulte Manifiesto del plugin.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

manifest-unknown-fields

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

• Compare cada campo de nivel superior con la referencia de campos del manifiesto.
• Elimine los campos personalizados de openclaw.plugin.json.
• Traslade los metadatos del paquete o de instalación a campos package.json#openclaw compatibles en lugar de incluirlos en el manifiesto.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

manifest-unknown-contracts

El manifiesto declara claves no compatibles dentro de contracts.

• Compare cada clave de contracts con la referencia de contratos.
• Elimine las claves de contrato no compatibles.
• Traslade el comportamiento en tiempo de ejecución al código de registro del plugin y limite contracts a metadatos estáticos sobre la propiedad de las capacidades.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

Migración del SDK y de compatibilidad

legacy-root-sdk-import

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

• Sustituya las importaciones del barrel raíz por importaciones de subrutas públicas específicas.
• Use openclaw/plugin-sdk/plugin-entry para definePluginEntry.
• Use openclaw/plugin-sdk/channel-core para los auxiliares de puntos de entrada de canales.
• Use Convenciones de importación y Subrutas del SDK del plugin para encontrar la importación específica.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

reserved-sdk-import

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

• Sustituya las importaciones reservadas del SDK interno de OpenClaw por subrutas públicas documentadas de openclaw/plugin-sdk/*.
• Si el comportamiento no dispone de un SDK público, mantenga el auxiliar dentro del paquete o solicite una API pública de OpenClaw.
• Use Subrutas del SDK del plugin y Migración del SDK para elegir una importación compatible.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

sdk-load-session-store

El plugin todavía utiliza el auxiliar obsoleto para todo el almacén de sesiones loadSessionStore.

• Use getSessionEntry(...) o listSessionEntries(...) al leer el estado de la sesión.
• Use patchSessionEntry(...) o upsertSessionEntry(...) al escribir el estado de la sesión.
• Evite cargar, modificar y guardar el objeto completo del almacén de sesiones.
• Conserve loadSessionStore(...) solo mientras el intervalo de compatibilidad declarado siga admitiendo versiones anteriores de OpenClaw que lo requieran.
• Consulte API de tiempo de ejecución y Subrutas del SDK del plugin.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

sdk-session-store-write

El plugin todavía utiliza un auxiliar de escritura obsoleto para todo el almacén de sesiones, como saveSessionStore o updateSessionStore.

• Use patchSessionEntry(...) al actualizar campos de una entrada de sesión existente.
• Use upsertSessionEntry(...) al sustituir o crear una entrada de sesión.
• Evite cargar, modificar y guardar el objeto completo del almacén de sesiones.
• Conserve los auxiliares de escritura de todo el almacén solo mientras el intervalo de compatibilidad declarado siga admitiendo versiones anteriores de OpenClaw que los requieran.
• Consulte API de tiempo de ejecución y Subrutas del SDK del plugin.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

sdk-session-file-helper

El plugin todavía utiliza auxiliares obsoletos de rutas de archivos de sesión, como resolveSessionFilePath o resolveAndPersistSessionFile.

• Use getSessionEntry(...) para leer los metadatos de sesión según la identidad del agente y de la sesión.
• Use patchSessionEntry(...) o upsertSessionEntry(...) para conservar los metadatos de la sesión.
• Use la identidad de la transcripción o los auxiliares de destino cuando el código prepare una operación de transcripción.
• No conserve ni utilice rutas de archivos de transcripción heredadas.
• Consulte API de tiempo de ejecución y Subrutas del SDK del plugin.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

sdk-session-transcript-file-target

El plugin todavía utiliza el auxiliar obsoleto de destino de archivos de transcripción resolveSessionTranscriptLegacyFileTarget.

• Use resolveSessionTranscriptIdentity(...) cuando el código solo necesite la identidad pública de la sesión.
• Use resolveSessionTranscriptTarget(...) cuando el código necesite un destino estructurado para una operación de transcripción.
• Evite leer o construir directamente destinos de archivos de transcripción heredados.
• Conserve el auxiliar heredado solo mientras el intervalo de compatibilidad declarado siga admitiendo versiones anteriores de OpenClaw que lo requieran.
• Consulte API de tiempo de ejecución y Subrutas del SDK del plugin.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

sdk-session-transcript-low-level

El plugin todavía utiliza auxiliares obsoletos de transcripción de bajo nivel, como appendSessionTranscriptMessage o emitSessionTranscriptUpdate.

• Use appendSessionTranscriptMessageByIdentity(...) para añadir contenido a las transcripciones.
• Use publishSessionTranscriptUpdateByIdentity(...) para las notificaciones de actualización de transcripciones.
• Utilice preferentemente la interfaz estructurada de transcripciones en tiempo de ejecución para que OpenClaw pueda aplicar los límites de transacción y el tratamiento de identidades correctos.
• Conserve los auxiliares de transcripción de bajo nivel solo mientras el intervalo de compatibilidad declarado siga admitiendo versiones anteriores de OpenClaw que los requieran.
• Consulte API de tiempo de ejecución y Subrutas del SDK del plugin.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

legacy-before-agent-start

El plugin todavía utiliza el hook heredado before_agent_start.

• Traslade el trabajo de sustitución del modelo o proveedor a before_model_resolve.
• Traslade el trabajo de modificación del prompt o del contexto a before_prompt_build.
• Conserve before_agent_start solo mientras el intervalo de compatibilidad declarado siga admitiendo versiones anteriores de OpenClaw que lo requieran.
• Consulte Hooks y Compatibilidad de plugins.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

provider-auth-env-vars

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

• Duplique los metadatos de las variables de entorno del proveedor en setup.providers[].envVars.
• Conserve providerAuthEnvVars solo como metadatos de compatibilidad mientras el intervalo admitido de OpenClaw siga necesitándolos.
• Consulte la referencia de configuración y Migración del SDK.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

channel-env-vars

El manifiesto utiliza metadatos heredados o antiguos de variables de entorno del canal sin los metadatos actuales de configuración inicial o del canal que ClawHub espera.

• Mantenga declarativos los metadatos de las variables de entorno del canal para que OpenClaw pueda inspeccionar el estado de configuración sin cargar el tiempo de ejecución del canal.
• Duplique la configuración del canal basada en variables de entorno en los metadatos actuales de configuración inicial, configuración del canal o canal del paquete que utilice la estructura de su plugin.
• Conserve channelEnvVars solo como metadatos de compatibilidad mientras las versiones anteriores admitidas de OpenClaw sigan necesitándolos.
• Consulte Manifiesto del plugin y Plugins de canal.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

Manifiesto de seguridad

security-manifest-schema-unavailable

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

• Elimine la URL del esquema si solo tiene carácter informativo.
• Use un esquema versionado y documentado solo después de que OpenClaw publique uno.
• Vuelva a ejecutar clawhub package validate <path-to-plugin>.

unrecognized-security-manifest

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

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

Contenido relacionado

• CLI de ClawHub
• Publicación en ClawHub
• Creación de plugins
• Manifiesto del plugin
• Puntos de entrada del plugin
• Compatibilidad de plugins