Plugin Ecosystem

Plugin install, update, packaging, and SDK behavior are product behavior. Treat them as high-blast-radius surfaces.

Distribution Model

  • Some official plugins are externalized and distributed through npm or ClawHub.
  • npm is the default distribution path for official external plugins.
  • Missing externalized plugins should be auto-downloaded during update and during onboarding when selected.
  • Plugin publishes are separate from the core openclaw package publish.
  • Publishable plugin packages opt in through package metadata such as openclaw.release.publishToNpm: true.

Version Policy

  • Mixed core-plugin versions are not supported.
  • OpenClaw forcibly upgrades affected @openclaw/* plugins to match the installed core line.
  • Stable plugin versions publish to npm latest.
  • Beta plugin versions publish to npm beta.
  • If a selected version already exists on npm, the workflow should skip it instead of republishing.

Change Rules

  • Discuss meaningful install, uninstall, plugin update, and package upgrade behavior changes in #maintainers before merging.
  • Discuss adding, removing, or externalizing a plugin before writing the final shape.
  • Add deprecation tags for breaking SDK changes.
  • Add doctor notices or migrations when a breaking change needs operator visibility.
  • Check whether openclaw/plugin-inspector needs updates when the public SDK surface changes.
  • Keep peerDependencies.openclaw, install metadata, package names, and public extension metadata aligned before publishing external plugins.

Contract Testing

  • Use openclaw/plugin-inspector to test the last known public SDK surface.
  • Use openclaw/kitchen-sink to exercise every plugin SDK surface.
  • Use openclaw/crabpot to combine SDK checks with external plugin contracts.
  • Include externalized official plugins and high-signal community plugins when the change can affect loading, compatibility, packaging, installation, or update behavior.

Publish Rules

  • Do not publish plugins from a local shell.
  • Use the shared plugin npm release workflow.
  • Inspect the preview run before dispatching a real publish.
  • Use selected scope for exact package lists. Use all-publishable only when you intentionally want every publishable plugin package from that ref.
  • If publish auth fails, fix npm trusted publisher settings. Do not fall back to local credentials.