Install, configure, and manage OpenClaw plugins

Plugins add functionality to OpenClaw, including channels, model providers, agent harnesses, tools, skills, speech, realtime transcription, voice, media understanding, generation, web fetch, web search, and other runtime features.

This page covers installing a plugin, restarting the Gateway, confirming the runtime loaded it, and resolving typical setup issues. For command-only instructions, refer to Manage plugins. For a generated list of bundled, official external, and source-only plugins, see Plugin inventory.

Requirements

• an OpenClaw checkout or installation that includes the openclaw CLI
• network connectivity to the chosen source (ClawHub, npm, or a git host)
• any plugin-specific credentials, configuration keys, or operating system tools required by that plugin's documentation
• permission for the Gateway serving your channels to reload or restart

Quick start

Find the plugin

Browse ClawHub for publicly available plugin packages:

openclaw plugins search "calendar"

ClawHub serves as the main discovery platform for community plugins. During the launch transition, plain package names without a source prefix still install from npm unless they match an official plugin identifier. Raw @openclaw/* specifications that correspond to a bundled plugin resolve to that local copy. When you require a particular source, use an explicit source prefix.

Install the plugin

# From ClawHub.
openclaw plugins install clawhub:<package>

# From npm.
openclaw plugins install npm:<package>

# From git.
openclaw plugins install git:github.com/<owner>/<repo>@<ref>

# From a local development checkout.
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

Treat plugin installation like executing code. For reproducible production deployments, prefer pinned versions. ClawHub packages and OpenClaw's bundled or official catalog are considered trusted sources. New sources from npm, git, local paths or archives, npm-pack:, or marketplaces require --force in noninteractive mode after you have reviewed and trust the source.

Configure and enable it

Set plugin-specific options under plugins.entries.<id>.config. If the plugin is not already active, enable it:

openclaw plugins enable <plugin-id>

When plugins.allow is configured, the installed plugin identifier must appear in that list for the plugin to load. openclaw plugins install adds the installed identifier to an existing plugins.allow list and removes the same identifier from plugins.deny, allowing the explicit install to load after a restart.

Let the Gateway reload

Installing, updating, or removing plugin code requires restarting the Gateway. A managed Gateway with config reload enabled detects the updated plugin install record and restarts automatically. Otherwise, restart it manually:

openclaw gateway restart

Enable or disable configuration updates and the cold registry. A runtime inspection still provides the most definitive evidence of live runtime surfaces.

Verify runtime registration

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

Use --runtime to verify registered tools, hooks, services, Gateway methods, or plugin-owned CLI commands. Plain inspect only checks the cold manifest and registry.

Configuration

Choose an install source

Bare package specifications follow special compatibility rules: a bare name matching a bundled plugin identifier uses that bundled source; a bare name matching an official external plugin identifier uses the official package catalog; any other bare specification installs through npm during the launch transition. Raw @openclaw/* specifications that match bundled plugins also resolve to the local copy before falling back to npm. Use npm:@openclaw/<plugin>@<version> to intentionally install the external npm package rather than the bundled copy. For deterministic source selection, use clawhub:, npm:, git:, or npm-pack:. See openclaw plugins for the complete command contract.

For npm installations, unpinned specifications and @latest select the newest stable package that advertises compatibility with this OpenClaw build. If npm's current latest release declares a newer openclaw.compat.pluginApi or openclaw.install.minHostVersion than this build supports, OpenClaw searches older stable versions and installs the newest compatible one. Exact versions and explicit channel tags like @beta remain pinned to the chosen package and fail if incompatible.

Operator install policy

Configure security.installPolicy to execute a trusted local policy command before a plugin install or update proceeds. The policy receives metadata along with the staged source path and can either permit or deny the installation. This applies to both CLI and Gateway-backed install or update paths. Plugin before_install hooks run later, and only in OpenClaw processes where plugin hooks are loaded, so use security.installPolicy for operator-owned installation decisions instead. The deprecated --dangerously-force-unsafe-install flag is accepted for compatibility but does nothing: it does not bypass install policy or OpenClaw's built-in plugin dependency denylist.

See Skills config for the shared security.installPolicy execution schema used by both skills and plugins.

Configure plugin policy

The common plugin configuration structure is:

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    slots: { memory: "memory-core" },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

Key policy rules:

• plugins.enabled: false turns off every plugin and bypasses the discovery and loading process. While this flag is on, any leftover plugin references remain inactive; you must reactivate plugins before using doctor cleanup if you intend to remove those stale identifiers.
• plugins.deny overrides both allowlist settings and per-plugin activation.
• plugins.allow functions as an exclusive allowlist. Tools owned by a plugin that are not on this allowlist remain inaccessible, even when tools.allow contains "*".
• plugins.entries.<id>.enabled: false deactivates a single plugin while preserving its configuration.
• plugins.load.paths adds specific local plugin files or directories. Managed plugins install local paths must point to plugin directories or archives; for standalone plugin files, use plugins.load.paths.
• Plugins originating from the workspace are inactive by default; you must explicitly enable or allowlist them before using local workspace code.
• Bundled plugins follow their preconfigured default-on or default-off metadata unless the configuration explicitly overrides that setting.
• plugins.slots.<slot> (either memory or contextEngine) selects one plugin for an exclusive category. Slot selection counts as explicit activation and forces the chosen plugin to be enabled for that slot, even if it would normally be opt-in. However, plugins.deny and plugins.entries.<id>.enabled: false can still block it.
• Bundled opt-in plugins can activate automatically when the configuration names one of their owned surfaces, for example a provider or model reference, channel configuration, CLI backend, or agent harness runtime.
• OpenAI-family Codex routing keeps provider and runtime plugin boundaries separate: legacy Codex model references are legacy configuration that doctor repairs, while the bundled codex plugin owns the Codex app-server runtime for canonical openai/* agent references, explicit agentRuntime.id: "codex", and legacy codex/* references.

When plugins.allow is not set and non-bundled plugins are auto-discovered from the workspace or global plugin roots, the startup logs include plugins.allow is empty; discovered non-bundled plugins may auto-load: ... with the discovered plugin IDs and, for short lists, a minimal plugins.allow snippet. Run openclaw plugins list --enabled --verbose or openclaw plugins inspect <id> on the listed plugin ID before copying trusted plugins into openclaw.json. The same trust-pinning process applies when diagnostics indicate a plugin loaded without install/load-path provenance: inspect that plugin ID, then pin it in plugins.allow or reinstall from a trusted source so OpenClaw records install provenance.

Run openclaw doctor or openclaw doctor --fix when configuration validation reports stale plugin IDs, allowlist or tool mismatches, or legacy bundled plugin paths.

Understand plugin formats

OpenClaw supports two plugin formats:

Both formats appear in openclaw plugins list, openclaw plugins inspect, openclaw plugins enable, and openclaw plugins disable. See Plugin bundles for the bundle compatibility boundary and Building plugins for native plugin authoring.

Plugin hooks

Plugins can register hooks at runtime through two different APIs:

• api.on(...) typed hooks for runtime lifecycle events. This is the preferred surface for middleware, policy, message rewriting, prompt shaping, and tool control.
• api.registerHook(...) for the internal hook system described in Hooks. This is mainly for coarse command or lifecycle side effects and compatibility with existing HOOK-style automation.

Quick rule: if the handler needs priority, merge semantics, or block or cancel behavior, use typed hooks. If it only reacts to command:new, command:reset, message:sent, or similar coarse events, api.registerHook is sufficient.

Plugin-managed internal hooks appear in openclaw hooks list with plugin:<id>. You cannot enable or disable them through openclaw hooks; instead, enable or disable the plugin.

Verify the active Gateway

openclaw plugins list and plain openclaw plugins inspect read cold configuration, manifest, and registry state. They do not verify that an already-running Gateway has imported the same plugin code.

When a plugin appears installed but live chat traffic does not use it:

openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart

Managed Gateways restart automatically after plugin install, update, and uninstall changes that alter plugin source. On VPS or container installs, ensure any manual restart targets the actual openclaw gateway run child that serves your channels, not just a wrapper or supervisor.

Troubleshooting

When a managed plugin that is enabled fails payload verification at Gateway startup, OpenClaw quarantines that specific installed plugin root for that boot and keeps serving other plugins. openclaw status --all, openclaw health, and openclaw doctor report it as configured-unavailable. Repair or reinstall the plugin, then restart the Gateway. A healthy explicit plugins.load.paths override with the same plugin id is not affected by a stale broken install.

If stale plugin config still references a channel plugin that is no longer discoverable, config validation downgrades that channel key to a warning rather than a hard failure, so Gateway startup can continue serving every other channel. Execute openclaw doctor --fix to remove outdated plugin and channel entries. Unknown channel keys without evidence of stale plugins still cause validation to fail, so typos remain visible.

For intentional channel replacement, the preferred plugin should declare channelConfigs.<channel-id>.preferOver with the legacy or lower-priority plugin id. When both plugins are explicitly enabled, OpenClaw preserves that request and reports duplicate channel/tool diagnostics instead of silently picking one owner.

If an installed package reports that it requires compiled runtime output for TypeScript entry ..., the package was published without the JavaScript files OpenClaw needs at runtime. Update or reinstall after the publisher ships compiled JavaScript, or disable or uninstall the plugin until that happens.

Blocked plugin path ownership

When diagnostics say blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) and validation follows with plugin present but blocked, OpenClaw found plugin files owned by a different Unix user than the process loading them. Leave the plugin config in place; fix the filesystem ownership or run OpenClaw as the same user that owns the state directory.

For Docker installs, the official image runs as node (uid 1000), so the host bind-mounted OpenClaw config and workspace directories should normally be owned by uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

If you intentionally run OpenClaw as root, repair the managed plugin root to root ownership instead:

sudo chown -R root:root /path/to/openclaw-config/npm

After fixing ownership, run openclaw doctor --fix or openclaw plugins registry --refresh again so the persisted plugin registry matches the repaired files.

Slow plugin tool setup

If agent turns appear to stall while preparing tools, enable trace logging and check for plugin tool factory timing lines:

openclaw config set logging.level trace
openclaw logs --follow

Look for:

[trace:plugin-tools] factory timings ...

The summary shows total factory time and the slowest plugin tool factories, including plugin id, declared tool names, result shape, and whether the tool is optional. Slow lines are promoted to warnings when a single factory takes at least 1s or total plugin tool factory prep takes at least 5s.

OpenClaw caches successful plugin tool factory results for repeated resolutions with the same effective request context. The cache key includes the effective runtime config, workspace and agent id, sandbox policy, browser settings, delivery context, requester identity, and ownership state, so factories that depend on those trusted fields re-run when the context changes. If timings stay high, the plugin may be doing expensive work before returning its tool definitions.

If one plugin dominates the timing, inspect its runtime registrations:

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

Then update, reinstall, or disable that plugin. Plugin authors should move expensive dependency loading behind the tool execution path instead of doing it inside the tool factory.

For dependency roots, package metadata validation, registry records, startup reload behavior, and legacy cleanup, see Plugin dependency resolution.

Related

• Manage plugins - command examples for list, install, update, uninstall, and publish
• openclaw plugins - full CLI reference
• Plugin inventory - generated bundled and external plugin list
• Plugin reference - generated per-plugin reference pages
• Community plugins - ClawHub discovery and docs PR policy
• Plugin dependency resolution - install roots, registry records, and runtime boundaries
• Building plugins - native plugin authoring guide
• Plugin SDK overview - runtime registration, hooks, and API fields
• Plugin manifest - manifest and package metadata