---

id: plugin-lifecycle-management title: Plugin Lifecycle Management type: plugin-lifecycle ownedPaths:

• electron/gateway/config-sync.ts
• electron/utils/openclaw-auth.ts
• electron/utils/channel-config.ts
• electron/utils/plugin-install.ts
• electron/gateway/skills-symlink-cleanup.ts
• electron/api/routes/skills.ts
• src/stores/skills.ts
• resources/skills/**
• tests/unit/openclaw-auth.test.ts
• tests/unit/channel-config.test.ts
• tests/unit/plugin-install.test.ts
• tests/unit/harness-specs.test.ts
• harness/src/cli.mjs
• harness/src/rules.mjs
• harness/src/specs.mjs
• harness/specs/scenarios/gateway-backend-communication.md
• harness/specs/scenarios/plugin-lifecycle-management.md
• harness/specs/rules/**
• harness/specs/tasks/** requiredProfiles:
• fast conditionalProfiles: comms: when:
  • plugin activation changes Gateway startup or runtime message delivery
  • channel/provider plugin ownership changes OpenClaw runtime config e2e: when:
  • plugin status, install, recovery, or diagnostics behavior is visible in the UI requiredRules:
• channel-plugin-migration-guards
• capability-owner-resolution
• active-config-guards
• packaged-runtime-pruning-guards

---

Plugin lifecycle management covers bundled and external plugins as one system with different source types. The core model has two layers:

• PluginPackage: a discoverable, installable, upgradable, and recoverable package with identity, version, source, manifest, install location, and validation state.
• PluginCapability: an integration surface declared by a package, such as a channel, provider, skill, or runtime extension.

Lifecycle stages:

• Declare: plugin manifests describe package identity, source expectations, compatibility, and provided capabilities.
• Discover: ClawX scans bundled and external sources and produces a factual inventory. Discovery does not choose active owners.
• Resolve: ClawX chooses canonical package/capability owners, applies migration rules, and marks conflicts before config activation.
• Materialize: ClawX installs, upgrades, copies, links, or verifies the physical package selected by resolution.
• Validate: ClawX verifies package manifests, dependencies, capability config, ownership uniqueness, and startup requirements.
• Activate: only resolved and validated capabilities enter final OpenClaw runtime config.
• Recover: failed upgrades, stale registrations, conflicts, and removed channels converge to a single diagnosable state with rollback or cleanup paths.
• Package: cleanup and pruning keep packaged artifacts small without deleting target runtime assets; macOS universal packages keep both x64 and arm64 native payloads.

First-stage priority is integration safety: single-owner capability resolution, active config guards, direct regression tests for migration cases, and explicit task specs for resolution, validation, and recovery work.