On this page
On this page
Building plugins
Plugin runtime compatibility
OpenClaw reports runtime compatibility hazards after a code plugin's production dependencies have been materialized and before activation. The same static inspection is available to plugin authors without importing or running their plugin:
Install the plugin's dependencies first. The inspection follows materialized
production, optional, and peer dependencies, excluding the host's openclaw
peer and development dependencies. Each warning identifies its package name,
version, source file, line, and rule. Tests, fixtures, declarations, and nested
node_modules directories are not scanned as package source; each resolved
runtime dependency is inspected under its own package identity.
In JSON output, complete describes coverage of the selected materialized
package manifests and source files. It does not say that the plugin is compatible
with the host. scannedPackages and scannedFiles are inspection counts.
Missing required dependencies or peers and malformed dependency metadata make
coverage incomplete. Optional dependencies and peers explicitly marked optional
can be absent. An absent openclaw dependency does not produce a missing-dependency
warning: the host-link owner supplies it after install checks. Existing
OpenClaw dependency directories still undergo the normal admission checks.
What the warnings mean
| Rule | Hazard | Prefer |
|---|---|---|
builtin-patch |
Replacing or deleting an existing built-in member, or changing a protected prototype | Owned wrappers, subclasses, and instance metadata |
host-patch |
Changing process-wide functions or Node module exports | api.logger, local fetch wrappers, provider transport hooks, and diagnostic events |
loader-patch |
Replacing module loaders or module-resolution hooks | The host plugin loader and documented SDK entrypoints |
runtime-code-generation |
Calling eval, Function, or Node VM compilation APIs |
Emitted JavaScript or parsing the relevant language |
scan-incomplete |
A read, parse, symlink, or inspection limit prevented complete source coverage | Inspect the named files or package separately |
The analyzer resolves lexical receivers and simple constant aliases. A plugin's
own class named Array, a read of Array.prototype.push, and an instance's
url property are different from replacing a host built-in. Ordinary new
properties on extensible built-ins are not treated as immutable-member writes.
Warnings and host qualification
Warnings do not block installation, require approval, or change
security.installPolicy. They are compatibility diagnostics, separate from
operator security policy and the optional before_install hook. Static source
inspection cannot establish whether an optional branch executes, whether a
browser-side function is serialized into another realm, or what code a string
will produce. Blocking on these observations would reject working plugins.
Process-wide patches can conflict on Node and Bun when multiple owners install and restore wrappers. In a compiled host, immutable built-in writes can fail, and other global writes depend on which writers the actual host retained. Runtime module hooks do not intercept imports resolved during compilation. Code loaded after compilation is not made native by the host's build mode.
Qualify activation, SDK calls, transitive imports, disablement, and the supported reload lifecycle against each actual host runtime. A warning-free report is not a compatibility certificate: computed aliases, generated strings, native addons, dormant branches, and host-image requirements need behavioral proof. The inspection does not install packages, fetch code, execute lifecycle scripts, or run an activation test.
