OpenClaw Plugins: Install, Configure, and Manage

Plugins bring additional functionality to OpenClaw, covering areas such as channels, model providers, agent harnesses, tools, skills, speech, realtime transcription, voice, media understanding, generation, web fetch, web search, and other runtime capabilities.

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

Requirements

• an OpenClaw checkout or installation with the openclaw CLI available
• network access to the chosen source (ClawHub, npm, or a git host)
• any plugin-specific credentials, config keys, or OS tools named by that plugin's setup docs
• permission for the Gateway serving your channels to reload or restart

Quick start

Find the plugin

Look for public plugin packages on ClawHub:

openclaw plugins search "calendar"

ClawHub serves as the main place to find community plugins. During the launch cutover, plain bare package specs still come from npm unless they correspond to an official plugin id. Raw @openclaw/* specs that match a bundled plugin point to that bundled copy. When a specific source is required, add 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 installs like executing code. For reproducible production installs, prefer pinned versions. ClawHub packages and OpenClaw's bundled/official catalog are considered trustworthy. New arbitrary npm, git, local path/archive, npm-pack:, or marketplace sources need --force in noninteractive installs after you review and trust the source.

Configure and enable it

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

openclaw plugins enable <plugin-id>

When plugins.allow is set, the installed plugin id must appear in that list before the plugin can load. openclaw plugins install adds the installed id to an existing plugins.allow list and removes the same id from plugins.deny so the explicit install can load after restart.

Let the Gateway reload

A Gateway restart is needed after installing, updating, or uninstalling plugin code. A managed Gateway with config reload enabled notices the changed plugin install record and restarts on its own. Otherwise, restart it manually:

openclaw gateway restart

Enable/disable update config and the cold registry. Inspect registration next, then confirm the running Gateway with an actual hook event or tool call.

Verify runtime registration

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

--runtime loads the plugin in the inspecting CLI process and reports registered tools, hooks, services, Gateway methods, and plugin-owned CLI commands. Plain inspect is a cold manifest and registry check only. Neither proves an already-running Gateway has loaded the same code. After restarting it, trigger the hook or capability and verify its actual effect.

Configuration

Choose an install source

Bare package specs behave in a special way for compatibility: a bare name matching a bundled plugin id uses that bundled source; a bare name matching an official external plugin id uses the official package catalog; any other bare spec installs through npm during the launch cutover. Raw @openclaw/* specs that match bundled plugins also resolve to the bundled copy before npm fallback. Use npm:@openclaw/<plugin>@<version> to deliberately install the external npm package instead of the bundled copy. Use clawhub:, npm:, git:, or npm-pack: for deterministic source selection. See openclaw plugins for the full command contract.

For npm installs, unpinned specs and @latest choose 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 scans older stable versions and installs the newest one that fits. Exact versions and explicit channel tags such as @beta stay pinned to the selected package and fail when incompatible.

Operator install policy

Configure security.installPolicy to run a trusted local policy command before a plugin install or update proceeds. The policy receives metadata plus the staged source path and can allow, warn, or block the install. It covers both CLI and Gateway-backed install/update paths. CLI plugin and skill commands can acknowledge a warning interactively by typing the target name with the same copy as suspicious ClawHub releases; policy is then re-evaluated. Reviewed non-interactive direct CLI commands can use --acknowledge-install-policy-warning. That flag approves every warning for the command invocation; each warning is still re-evaluated before the install continues. The Control UI shows the structured warning and offers Install anyway. That action resends the same plugin request with acknowledgeInstallPolicyWarning: true, approving every warning encountered during that install invocation; each warning is still re-evaluated before installation continues. Other Gateway-backed and automatic installs remain blocked when they have no operator-confirmation flow. When an equivalent direct plugin or skill command exists, use that command to review and approve the warning. Otherwise, change security.installPolicy to return allow for the reviewed request, then retry the managed flow. Neither --force nor the deprecated plugin install/update flag --dangerously-force-unsafe-install approves a policy warning. Plugin before_install hooks run later, and only in OpenClaw processes where plugin hooks are loaded, so use security.installPolicy for operator-owned install decisions instead. The flag does not override a block or policy failure. It also does not bypass before_install hook blocks.

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

Configure plugin policy

The common plugin config shape 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:

• Setting plugins.enabled: false turns off every plugin and bypasses the discovery and loading steps. While it remains on, any stale plugin references stay dormant; turn plugins back on before running doctor cleanup if you want those stale ids cleared out.
• plugins.deny takes precedence over both allow and per-plugin enablement.
• plugins.allow acts as a strict allowlist. Plugin-owned tools that fall outside the allowlist remain inaccessible even when tools.allow includes "*".
• plugins.entries.<id>.enabled: false turns off a single plugin while preserving its configuration.
• plugins.load.paths adds specific local plugin files or directories. Managed plugins install local paths have to be plugin directories or archives; for standalone plugin files, use plugins.load.paths.
• Plugins originating from the workspace are off by default; you must explicitly enable or allowlist them before relying on local workspace code.
• Bundled plugins stick to their built-in default-on or default-off metadata unless configuration explicitly overrides that.
• plugins.slots.<slot> (memory or contextEngine) selects one plugin for an exclusive category. Choosing a slot counts as explicit activation and force-enables the picked plugin for that slot, even if it would normally be opt-in. plugins.deny and plugins.entries.<id>.enabled: false can still block it.
• Bundled opt-in plugins can activate on their own when config names one of their owned surfaces, for example a provider or model ref, channel config, CLI backend, or agent harness runtime.
• OpenAI-family Codex routing keeps provider and runtime plugin boundaries separate: legacy Codex model refs are legacy config that doctor fixes, while the bundled codex plugin owns Codex app-server runtime for canonical openai/* agent refs, explicit agentRuntime.id: "codex", and legacy codex/* refs.

When plugins.allow is unset and non-bundled plugins are auto-discovered from the workspace or global plugin roots, startup logs 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 applies when diagnostics say 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 config validation reports stale plugin ids, allowlist or tool mismatches, or legacy bundled plugin paths.

Understand plugin formats

OpenClaw recognizes 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 just reacts to command:new, command:reset, message:sent, or similar coarse events, api.registerHook is fine.

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

Hook registration also depends on Gateway startup selection. For a hook-only plugin, declare activation.onCapabilities: ["hook"] in openclaw.plugin.json, then enable the plugin and include it in plugins.allow when that allowlist is configured. The manifest hint does not bypass global disable, deny, or per-plugin enablement policy.

An explicit hook policy is also startup intent. For example, plugins.entries.<id>.hooks.allowConversationAccess: true both authorizes non-bundled conversation hooks and selects that configured plugin for Gateway startup; normal plugin policy still applies. After changing manifest or hook policy, inspect registration with openclaw plugins inspect <id> --runtime --json, restart the Gateway, and trigger an event to verify the running process. See Plugin hooks for a complete example.

Verify the active Gateway

openclaw plugins list and plain openclaw plugins inspect read cold config, manifest, and registry state. They do not prove 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, make sure any manual restart targets the actual openclaw gateway run child that serves your channels, not only a wrapper or supervisor.

Troubleshooting

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

When stale plugin config still names a no-longer-discoverable channel plugin, config validation downgrades that channel key to a warning instead of a hard failure, so Gateway startup can still serve every other channel. Run openclaw doctor --fix to remove stale plugin and channel entries. Unknown channel keys without stale-plugin evidence still fail validation so typos stay visible.

For intentional channel replacement, the preferred plugin should declare channelConfigs.<channel-id>.preferOver with the legacy or lower-priority plugin id. If both plugins are explicitly enabled, OpenClaw keeps that request and reports duplicate channel/tool diagnostics instead of silently choosing 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/uninstall the plugin until then.

Blocked plugin path ownership

If 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. Keep 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, rerun openclaw doctor --fix or openclaw plugins registry --refresh 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 lists 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