Manage OpenClaw Plugins via Control UI or CLI

The Control UI handles the typical workflow of discovering, installing, enabling, and disabling plugins. For updates, uninstalls, advanced configuration, and explicit source selection, use the CLI. Refer to openclaw plugins for the full command contract, flags, source-selection rules, and edge cases.

A standard CLI workflow looks like this: locate a package, install it from ClawHub, npm, git, or a local path, allow the managed Gateway to restart automatically (or restart it manually), and then confirm the plugin's runtime registrations.

Use the Control UI

Navigate to Plugins in the Control UI, or use /settings/plugins relative to your configured Control UI base path. For instance, with a base path of /openclaw, the URL becomes /openclaw/settings/plugins. This page contains two tabs:

• Installed displays all local plugins grouped by category (channels, model providers, memory, tools). Clicking a row opens a detail panel; the overflow (…) menu lets you enable or disable the plugin and, for externally installed ones, provides a Remove option. This tab also shows configured MCP servers with the same menu for enabling, disabling, and removing them, which edits mcp.servers in the Gateway configuration.
• Discover acts as a storefront: featured plugins shipped with OpenClaw, official external plugins, and a curated connector section. Connector cards either add a hosted MCP server in a single click (GitHub, Notion, Linear, Sentry, Home Assistant) or open a prefilled ClawHub search. Typing in the search box queries ClawHub live and adds a From ClawHub section showing download counts and source-verification badges.

Bundled plugins do not require a package installation. Their menu shows Enable or Disable. For example, Workboard ships with OpenClaw but starts disabled, so click Enable to activate it. You cannot remove bundled plugins, only disable them.

Accessing the catalog and search requires operator.read. Installing, enabling, disabling, removing, and modifying MCP servers require operator.admin. The Gateway performs a ClawHub installation and enforces its trust, integrity, and plugin-install policy checks. When an administrator enables an installed plugin, that action also records 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 the plugin can be enabled.

Installing or removing plugin code requires a Gateway restart. Changes to enablement can take effect without a restart if both the installed plugin and the current Gateway runtime support it; otherwise the UI indicates a restart is needed. OAuth-backed MCP connectors still require a one-time openclaw mcp login <name> from the CLI after they are added.

The Control UI cannot install from arbitrary npm, git, or local-path sources, update plugins, or expose detailed plugin configuration. Use the CLI workflows described below for those tasks.

List and search plugins

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search "calendar"

--json for scripts:

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

plugins list performs a cold inventory check: it shows what OpenClaw can detect from configuration, manifests, and the persisted plugin registry. It does not verify that an already-running Gateway loaded the plugin runtime. JSON output includes registry diagnostics and each plugin's dependencyStatus (whether declared dependencies/optionalDependencies exist on disk).

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

Enable and disable plugins

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

This toggles a plugin's config entry without modifying installed files. Some bundled plugins (bundled model/speech providers, the bundled browser plugin) are enabled by default; others need enable after installation.

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.3
openclaw plugins install clawhub:<package>@beta

# Install from npm.
openclaw plugins install npm:<package>
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw 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.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

Bare package specs install from npm during the launch cutover, unless the name matches a bundled or official plugin id, in which case OpenClaw uses that local or 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 or 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 needs configuration that does not exist 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, the install fails without rewriting it.

Restart and inspect

A running managed Gateway with config reload enabled restarts automatically after installing, updating, or uninstalling plugin code. If the Gateway is unmanaged or reload is disabled, restart it manually before checking live runtime surfaces:

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

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

Update plugins

openclaw plugins update <plugin-id>
openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
openclaw 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.

openclaw plugins update --all is the bulk maintenance path. It still respects ordinary tracked install specs, but trusted official OpenClaw plugin records sync to the current official catalog target instead of staying pinned to a stale exact official package; when update.channel is beta, that sync prefers the beta release line. Use a targeted update <plugin-id> to keep an exact or tagged official spec untouched.

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

openclaw plugins update @scope/openclaw-plugin@beta
openclaw 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-run
openclaw plugins uninstall <plugin-id>
openclaw plugins uninstall <plugin-id> --keep-files

When you uninstall a plugin, its configuration entry, persisted index record, allow/deny list entries, and any linked plugins.load.paths entries are removed where relevant. The managed installation directory is deleted unless you supply --keep-files. If the uninstallation modifies the plugin source, a running managed Gateway restarts on its own.

Under Nix mode (OPENCLAW_NIX_MODE=1), you cannot install, update, uninstall, enable, or disable plugins; instead, handle those settings within the Nix source for the installation.

Choose a source

Managed local path installs must be plugin directories or archives. Place standalone plugin files in plugins.load.paths rather than installing them with plugins install.

Publish plugins

ClawHub serves as the primary public discovery platform for OpenClaw plugins. Publish there if you want users to find plugin metadata, version history, registry scan results, and install hints prior to installation.

npm i -g clawhub
clawhub login
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0

Native npm plugins must include a plugin manifest (openclaw.plugin.json) along with package.json metadata before publishing:

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

npm publish --access public
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0

For the complete publishing contract, refer to these pages instead of using this one as the publishing reference:

• ClawHub publishing covers owners, scopes, releases, review, package validation, and package transfer.
• Building plugins describes the full plugin package structure (including openclaw.plugin.json) and the first publish workflow.
• Plugin manifest defines the fields for a native plugin manifest.

When the same package exists on both ClawHub and npm, use the explicit clawhub: or npm: prefix to force a specific source.

Related

• Plugins - install, configure, restart, 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