Manage plugins

The Control UI covers discovery, installation, schema-backed configuration, effective access, enablement, reload, and removal. The CLI adds update, advanced maintenance, and explicit install-source controls. For its full command contract, flags, source-selection rules, and edge cases, see openclaw plugins.

Typical workflow: find a package, install it, enable it, then verify the plugin's runtime registrations. Control UI actions apply to the running Gateway without restarting it. CLI installs also use the running local Gateway for npm, Git, local paths and archives, npm-pack tarballs, and marketplace sources. See Apply changes and inspect for those paths.

Use the Control UI

Open Plugins in the Control UI, or use /plugins relative to the configured Control UI base path. For example, a base path of /openclaw uses /openclaw/plugins.

Installed plugins shows up to 12 installed plugins, prioritizing enabled plugins, plugins that need setup, and plugins that need attention. Use search to filter the full inventory or choose Show all to browse every installed plugin. Each card shows the plugin description. Choose a card to open its settings, where administrators can enable or disable it and read-only operators can inspect it.

A package installed from another ClawHub registry stays manageable under Installed plugins. It does not mark a same-name package in the current catalog as installed.

Choose a card to open /settings/plugins/<plugin-id>. That routed page uses the plugin's declared schema for configuration, explains effective access in plain language, and keeps raw capability declarations and grants under Advanced. Its Lifecycle section shows source and version details and lets administrators Reload a plugin or uninstall removable plugins after confirmation. Open /settings/plugins for the searchable installed inventory. Its Advanced tab owns global plugin loading policy, allow and deny lists, load paths, and capability slots.

Included plugins do not need a package install. Workboard, for example, is included with OpenClaw and disabled by default. Bundled plugins can be disabled or reloaded but not removed.

Inventory, configuration, and access inspection require operator.read. Configuration, enable, disable, reload, install, and uninstall changes require operator.admin. Enabling an installed plugin as an administrator also records that explicit trust by adding the selected plugin to an existing restrictive plugins.allow list. An explicit plugins.deny entry remains authoritative and must be removed before enabling the plugin.

Install, enable, disable, remove, and reload actions wait for the running Gateway to apply the change. The page and plugin-provided tabs refresh on the existing connection. If application fails, the error distinguishes a rejected replacement from a change that was published before a later runtime failure. An install can remain saved even if its runtime fails to start. The page refreshes that installed entry and keeps the failure visible. Fix the reported problem, then choose Reload in its Lifecycle settings or run openclaw plugins reload <plugin-id>; repeating installation is unnecessary.

Reload refreshes the backend plugin and its package entries while preserving enablement and the current browser connection. Discovered plugins selected through plugins.load.paths and bundled plugins use the same action. Changed declared capabilities may require review before it proceeds. The success message reports the applied Gateway generation; a failure keeps its reported application state and phase visible. Reload does not rebuild compiled bundled code; see CLI reload for that boundary. The separate Reload plugin UI action only refreshes browser UI modules.

Administrators can reload with externally managed or Nix config when no new capability consent needs to be recorded. Config and installation changes stay unavailable. If a reload requires new capability consent, manage that acceptance through the deployment owner before retrying.

The Control UI does not install from arbitrary npm, git, or local-path sources, or update plugin packages. Use the CLI workflows below for those operations.

List and search plugins

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search "calendar"

--json for scripts:

openclaw plugins list --json \  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'

plugins list is a cold inventory check: what OpenClaw can discover from config, manifests, and the persisted plugin registry. It does not prove an already-running Gateway imported the plugin runtime. JSON output includes registry diagnostics and each plugin's dependencyStatus (whether declared dependencies/optionalDependencies resolve on disk).

plugins search queries ClawHub for installable plugin packages and prints an install hint (openclaw plugins install clawhub:<package>) per result.

Enable and disable plugins

openclaw plugins enable <plugin-id>openclaw plugins disable <plugin-id>

Toggles a plugin's config entry without touching installed files. Some bundled plugins (bundled model/speech providers, the bundled browser plugin) are enabled by default; others require enable after install.

Capability consent

OpenClaw asks you to review a third-party plugin's declared capabilities before installing or enabling it. The consent screen identifies the plugin, its version and source, artifact integrity, and available trust information. It also lists declared channels, providers, tools, hooks, MCP servers, CLI commands and backends, skills, and dangerous configuration flags, along with the operator grants that apply to hooks, model access, and subagents.

Bundled plugins and verified first-party plugins from OpenClaw's official catalog do not require this capability review during setup, install, enable, update, or Doctor repair. For separately installed first-party plugins, OpenClaw checks the actual package identity against its catalog and verified npm source record or official-channel record from https://clawhub.ai. A matching plugin id or package name alone is insufficient: local copies, archives, git installs, custom ClawHub registries, and conflicting source records still require review. This exemption does not grant OAuth access, operating-system permissions, or runtime tool approvals, and does not create an operator acceptance record.

The review token hashes the exact declared capability surface, not the plugin's executable files. Acceptance separately records installer-provided artifact integrity when available. Re-enabling an installed plugin reuses acceptance when its declared surface and recorded integrity are unchanged. Updates of enabled plugins require fresh consent when the new artifact declares additional capabilities; unchanged or narrower surfaces can refresh an existing valid acceptance. Updating a disabled plugin preserves disablement and defers any required consent until enablement. Reinstalling through plugins install also preserves an authored enabled: false, but requires consent before committing the install when no valid acceptance can be reused. Run openclaw plugins enable <plugin-id> to activate it afterward.

Already-enabled third-party legacy installations remain usable without an initial review; disabling and re-enabling them requires consent. Setup rechecks consent when saving its final config, so a plugin update during login cannot activate a replacement with unaccepted capabilities.

Declining an update's capability review leaves the previous plugin enabled and unchanged. Repairing a missing or damaged artifact requires a fresh review; OpenClaw cannot carry acceptance forward from an artifact it cannot verify.

Carrying an earlier acceptance forward requires the install record to pin artifact integrity, which registry and ClawHub installs provide. Sources without recorded integrity — notably local paths — cannot prove the new bytes are the artifact you approved before, so they ask for consent on every install rather than inheriting it.

Interactive CLI commands, onboarding, and provider, search, or channel setup prompt when consent is required, including automatic installs of required runtime plugins. Noninteractive or silent setup cannot approve new capabilities. Review and preinstall or enable the plugin with --accept-capabilities, then retry setup. Noninteractive plugin install, update, and enable commands also require the explicit flag when consent is needed:

openclaw plugins install clawhub:<package> --accept-capabilitiesopenclaw plugins update <plugin-id> --accept-capabilitiesopenclaw plugins enable <plugin-id> --accept-capabilities

Doctor uses the same source checks and review before installing or adopting a replacement plugin. doctor --fix and --yes do not approve capabilities automatically. For noninteractive repair, review and install the plugin with the explicit flag above, then rerun doctor.

Chat installs and enablement use the same capability consent. When consent is required, review the capabilities in the reply, then rerun the same command with --accept-capabilities:

/plugins install clawhub:<package> --accept-capabilities/plugins install npm:<package> --force --accept-capabilities/plugins enable <plugin-id> --accept-capabilities

Plugins discovered directly in a workspace or through plugins.load.paths, without a managed install record, cannot persist capability acceptance. Their details in the Control UI still show declared capabilities.

openclaw plugins install --link <path> creates a managed install record and requires capability consent even though it loads the plugin from its source directory. It is not the same as adding a bare plugins.load.paths entry.

Install plugins

# Search ClawHub for plugin packages.openclaw plugins search "calendar" # Install from ClawHub.openclaw plugins install clawhub:<package>openclaw plugins install clawhub:<package>@1.2.3openclaw plugins install clawhub:<package>@beta # Install from npm.openclaw plugins install npm:<package>openclaw plugins install npm:@scope/openclaw-plugin@1.2.3openclaw plugins install npm:@openclaw/codex # Install from a local npm-pack artifact.openclaw plugins install npm-pack:<path.tgz> # Install from git or a local development checkout.openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

Bare package specs install from npm, unless the name matches a bundled or official plugin id, in which case OpenClaw uses that local/official copy instead. Use clawhub:, npm:, git:, or npm-pack: for deterministic source selection. OpenClaw's bundled and official catalog packages are trusted alongside ClawHub packages. New arbitrary npm, git, local path/archive, npm-pack:, or marketplace sources require --force in noninteractive installs after you review and trust the source.

--force confirms a non-ClawHub source without prompting and overwrites an existing install target when needed. For routine upgrades of a tracked npm, ClawHub, or hook-pack install, use openclaw plugins update instead. With --link, --force only confirms the source; the linked directory is not copied or overwritten.

If a newly installed plugin requires configuration that is not present yet, OpenClaw records the install but leaves the plugin disabled. Configure plugins.entries.<id>.config, then run openclaw plugins enable <id>. If an existing config entry is present but invalid, install fails without rewriting it.

A plugin package can expose multiple child entries. Installation tracks that package once, enables each ready child entry, and preserves any child that you explicitly disabled. Runtime policy remains child-addressable through plugins.entries.<child-id>, allow/deny lists, channel config, exact child load paths, and the memory and contextEngine slots.

Apply changes and inspect

Control UI actions and the Gateway plugin-management RPCs apply plugin changes without restarting the Gateway. Ordinary CLI install, enable, disable, and uninstall commands use the running local Gateway when available; updates refresh it after the local package operation finishes. Without a running Gateway, those commands update the local installation for its next startup.

In the default hybrid reload mode, saving plugin configuration in the Control UI, through openclaw config, or in openclaw.json also applies automatically. By default, changes under plugins.entries.<id> replace that plugin's runtime instance, so registration, tools, hooks, and services receive its new configuration. Unchanged plugins keep their instances. A plugin can declare a narrower policy that retains its instance or requires a restart; see Config hot reload.

CLI installation supports npm, Git, local paths and archives, npm-pack tarballs, marketplace sources, and official or ClawHub packages through that same owner. See Install for source selection and capability consent. After an offline installation, start the Gateway to use the installed runtime surfaces. To inspect their registration:

openclaw plugins inspect <plugin-id> --runtime --json

The Gateway reuses its current plugin inventory until startup or an explicit owner update. Run openclaw plugins reload <plugin-id> after source or manifest edits. For API clients, plugins.reload takes plugins: [{ pluginId }] to reload one installed plugin, or multiple targets in the same request, and plugins.refresh refreshes the inventory. Both wait for runtime application and return restartRequired: false with a generation receipt. Explicit actions also work with gateway.reload.mode: "off". See Plugin management RPCs.

Cleanup is best effort: disabling removes the plugin's registered capabilities and attempts to stop its services and cleanup hooks. A successful change can include warnings about unfinished cleanup. Cached modules, native libraries, or other process state may remain until the Gateway exits. Restart is a recovery option when those leftovers cause problems.

inspect --runtime loads the plugin module and proves it registered runtime surfaces (tools, hooks, services, Gateway methods, HTTP routes, plugin-owned CLI commands). Plain inspect and list are cold manifest/config/registry checks only.

Manage plugins from an agent conversation

The owner-only plugins tool can list, inspect, search, install, enable, disable, uninstall, and reload plugins through the running Gateway. Agent installs accept official catalog plugin IDs or ClawHub package names. The version option applies only to ClawHub installs; official installs use the catalog selection. To activate edits to an already-installed local TypeScript plugin, use reload with its plugin ID. Installing new local, npm, Git, or archive sources still uses the CLI workflow above.

In the embedded agent runtime, an applied change refreshes tools before the next model request after running code programs have settled. A parked program may need further model steps to wait for completion; completed actions and accepted steering remain in the transcript and are not replayed. Finish a running program before asking it to use changed tools.

Managed Codex sessions continue in the same OpenClaw conversation after stopping the current native turn and its background terminals, then creating a thread with updated tools. Completed tool results, accepted follow-up messages, and ordinary question answers carry into that thread as bounded conversation context. If native cleanup or thread release fails, the attempt reports the failure and preserves the binding for recovery instead of replaying completed work.

Imported or supervised native sessions keep their original ownership and tool definitions. They report the backend change but require a new managed conversation to use changed tools. Other runtimes without a refresh consumer do the same.

Inventory and result output are bounded. Narrow list with query, inspect a specific plugin, or use the Control UI Plugins page for omitted details and capability reviews. A saved install can outlive a failed runtime activation: inspect that result before retrying activation, rather than reinstalling it.

Update plugins

openclaw plugins update <plugin-id>openclaw plugins update <npm-package-or-spec>openclaw plugins update --allopenclaw plugins update <plugin-id> --dry-run

Passing a plugin id reuses its tracked install spec: stored dist-tags (@beta) and exact pinned versions carry over to later update <plugin-id> runs. For a multi-entry package, any child id resolves to the one tracked package install, so all siblings update together. Removed or renamed children have their stale entries, allow/deny policy, exact load paths, channel config, and memory/context slot selections reconciled before the new package/index state commits; retained/new children and unrelated plugins are preserved.

If OpenClaw cannot prove exactly one package owner and a complete child list, update and uninstall fail closed without changing package files, config, or the installed index. Run openclaw plugins registry --refresh, inspect openclaw plugins doctor, and use openclaw doctor --fix for repairable legacy index state. If the ambiguity remains, reinstall the package before retrying.

openclaw plugins update --all is the bulk maintenance path. It preserves exact version pins and explicit tags, including trusted official OpenClaw plugin records, because older automatic pins cannot be distinguished from an operator's intentional pin. When a newer default-line release exists, OpenClaw reports it and prints the explicit command that replaces the pin. Floating official records still follow the canonical channel resolver, which uses both update.channel and the installed core version.

For an exact-pinned ClawHub record, deliberately return to the default release line with the command printed by the updater:

openclaw plugins install clawhub:<package> --force

For npm installs, pass an explicit package spec to switch the tracked record:

openclaw plugins update @scope/openclaw-plugin@betaopenclaw plugins update @scope/openclaw-plugin

The second command moves a plugin back to the registry's default release line when it was previously pinned to an exact version or tag.

See openclaw plugins for the exact fallback and pinning rules.

Uninstall plugins

openclaw plugins uninstall <plugin-id> --dry-runopenclaw plugins uninstall <plugin-id>openclaw plugins uninstall <plugin-id> --keep-files

Uninstall removes the package's persisted install record and every owned child's settings from plugin config, allow/deny lists, memory/context slots, exact linked plugins.load.paths, and channel config entries when applicable. It retains only an exact enabled: false marker for each removed child so remaining model, provider, or channel selections cannot automatically reinstall the package during startup repair. Reinstalling does not silently re-enable it; enabling the plugin again replaces the marker. You may address a multi-entry package by any child id; the preview names the package owner and all siblings that will be removed. The managed install directory is removed once unless you pass --keep-files. With a running Gateway, ordinary uninstall waits for the package's runtime owners to stop before removing files and returns after the new inventory is applied.

If an installed Claw references the plugin, preview and uninstall print the affected Claw package names. Ordinary plugin uninstall can still proceed and may break those Claws; use openclaw claws status to review ownership first. Removing a Claw releases its plugin reference but retains the process-wide plugin by default.

In Nix mode (OPENCLAW_NIX_MODE=1), plugin install, update, uninstall, enable, and disable are all disabled; manage those choices in the Nix source for the install instead.

Choose a source

Managed local path installs must be plugin directories or archives. Put standalone plugin files in plugins.load.paths instead of installing them with plugins install.

Publish plugins

ClawHub is the primary public discovery surface for OpenClaw plugins. Publish there when you want users to find plugin metadata, version history, registry scan results, and install hints before they install.

npm i -g clawhubclawhub loginclawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-pluginclawhub package publish your-org/your-plugin@v1.0.0

Native npm plugins must ship a plugin manifest (openclaw.plugin.json) plus package.json metadata before publishing:

{  "name": "@acme/openclaw-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

npm publish --access publicopenclaw plugins install npm:@acme/openclaw-pluginopenclaw plugins install npm:@acme/openclaw-plugin@betaopenclaw plugins install npm:@acme/openclaw-plugin@1.0.0

Use these pages for the full publishing contract instead of treating this page as the publishing reference:

• ClawHub publishing explains owners, scopes, releases, review, package validation, and package transfer.
• Building plugins shows the full plugin package shape (including openclaw.plugin.json) and first publish workflow.
• Plugin manifest defines native plugin manifest fields.

If the same package is available on both ClawHub and npm, use the explicit clawhub: or npm: prefix to force one source.

Related

• Plugins - install, configure, reload, and troubleshoot
• openclaw plugins - full CLI reference
• Community plugins - public discovery and ClawHub publishing
• ClawHub - registry CLI operations
• Building plugins - create a plugin package
• Plugin manifest - manifest and package metadata