Install, Configure, and Manage OpenClaw Plugins

Plugins add runtime capabilities to OpenClaw: channels, model providers, agent harnesses, tools, skills, speech, realtime transcription, voice, media understanding, generation, web fetch, web search, and more.

This page covers installing a plugin, applying its configuration, confirming the runtime loaded it, and diagnosing frequent setup failures. Command-only examples live in Manage plugins. For the generated inventory of bundled, official external, and source-only plugins, see Plugin inventory.

Requirements

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

Quick start

Find the plugin

Search ClawHub for public plugin packages:

openclaw plugins search "calendar"

ClawHub serves as the default install source and the main place to discover community plugins. Unless a spec is a bare bundled or official plugin id with no version or tag, ordinary package specs install from ClawHub. Scoped package names, @openclaw/* included, always select ClawHub by default. When you need one particular source, use an explicit source prefix.

Install the plugin

# From ClawHub.
openclaw plugins install <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 running code. Prefer pinned versions for reproducible production installs. ClawHub packages and OpenClaw's bundled/official catalog are trusted sources. New arbitrary npm, git, local path/archive, npm-pack:, or marketplace sources require --force in noninteractive installs after you review and trust the source.

Configure and enable it

Configure plugin-specific settings under plugins.entries.<id>.config. Enable the plugin if it is not already enabled:

openclaw plugins enable <plugin-id>

If plugins.allow is set, the installed plugin id must be 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.

Apply the changes

Plugin-management commands apply changes to a running local Gateway without restarting it. If the Gateway is stopped, start it to load the saved changes. See Apply changes and inspect.

With the default hybrid reload mode, ordinary plugin config edits also apply automatically. By default, the Gateway replaces the affected plugin instance; a plugin's explicit restart policy can still require a Gateway restart. Inspect registration next, then verify 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. Trigger the hook or capability and verify its actual effect.

Configuration

Choose an install source

Bare plugin ids with no version or tag act as shortcuts: an id matching a bundled plugin uses that bundled source, while an official external plugin id uses the official package catalog. Every package name, @openclaw/* included, plus versioned or tagged specs, installs through ClawHub with no automatic npm fallback. To install straight from npm, use npm:@openclaw/<plugin>@<version>. To pick the source explicitly, use clawhub:, npm:, git:, or npm-pack:. The full command contract is documented in openclaw plugins.

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: ["~/path/to/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 skips discovery and load work. While it is active, stale plugin references remain inert; if you want stale ids removed, re-enable plugins before running doctor cleanup.
• plugins.deny takes precedence over allow and per-plugin enablement.
• plugins.allow is an exclusive allowlist. Tools owned by a plugin that fall outside the allowlist stay unavailable, even when tools.allow includes "*".
• plugins.entries.<id>.enabled: false turns off a single plugin but keeps its config.
• plugins.load.paths adds explicit local plugin files or directories. Managed plugins install local paths must be plugin directories or archives; standalone plugin files belong in plugins.load.paths.
• Plugins from the workspace origin are disabled by default; before using local workspace code, enable or allowlist them explicitly.
• Bundled plugins follow their built-in default-on/default-off metadata, unless config overrides it explicitly.
• plugins.slots.<slot> (memory or contextEngine) picks one plugin for an exclusive category. Choosing a slot counts as explicit activation and force-enables the selected plugin for that slot, even if it would otherwise be opt-in. plugins.deny and plugins.entries.<id>.enabled: false still block it.
• When config names one of their owned surfaces, such as a provider/model ref, channel config, CLI backend, or agent harness runtime, bundled opt-in plugins can auto-activate.
• OpenAI-family Codex routing keeps provider and runtime plugin boundaries separate: legacy Codex model refs are legacy config that doctor repairs, while the bundled codex plugin owns Codex app-server runtime for current 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. Before copying trusted plugins into openclaw.json, run openclaw plugins list --enabled --verbose or openclaw plugins inspect <id> on the listed plugin id. 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/tool mismatches, or legacy bundled plugin paths. If removing stale ids empties a restrictive plugins.allow list, Doctor retains already enabled channels and selected plugins as explicit allowed IDs. It disables plugins only when none remain. Review the retained list when changing channels or plugin slots. Legacy ID collisions require an explicit policy choice; see config migrations.

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. For middleware, policy, message rewriting, prompt shaping, and tool control, this is the preferred surface.
• api.registerHook(...) for the internal hook system described in Hooks. Its main uses are coarse command/lifecycle side effects and compatibility with existing HOOK-style automation.

Quick rule: use typed hooks when the handler needs priority, merge semantics, or block/cancel behavior. If it only 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. Run openclaw plugins reload <id> after changing the plugin manifest or source. With the default hybrid reload mode, hook policy changes hot-reload the plugin runtime. Inspect registration with openclaw plugins inspect <id> --runtime --json, then 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 only read config, manifest, and registry state from cold storage. Neither proves that a Gateway already running has imported the same plugin code.

If a plugin looks installed yet live chat traffic never reaches it:

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

Plugin Reload re-imports the chosen plugin into the running Gateway. Reach for it after editing source or manifest files, or once a failed activation has been corrected. Install, update, enable, disable, and uninstall already apply their own changes on success, so no extra reload is needed for them. Compiled bundled code and cleanup limits are covered in Reload.

Troubleshooting

Should an enabled managed plugin fail payload verification while the Gateway starts, OpenClaw quarantines that precise installed plugin root for the current boot and keeps serving the remaining plugins. openclaw status --all, openclaw health, and openclaw doctor surface it as configured-unavailable. Repair or reinstall the plugin, then restart the Gateway. A healthy explicit plugins.load.paths override carrying the same plugin id is not quarantined because of a stale broken install.

When stale plugin config still references a channel plugin that can no longer be discovered, config validation downgrades that channel key to a warning rather than a hard failure, letting Gateway startup serve all other channels. Run openclaw doctor --fix to clear stale plugin and channel entries. Unknown channel keys with no stale-plugin evidence still fail validation, which keeps typos visible.

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

If an installed package reports that it requires compiled runtime output for TypeScript entry ..., the package shipped without the JavaScript files OpenClaw requires at runtime. Update or reinstall once the publisher provides compiled JavaScript, or disable/uninstall the plugin in the meantime.

Plugin runtime trust refused

Each loaded plugin may use its own keyed and blob state plus channel ingress queues, local paths and linked installs included. Hook agent turns and Gateway scope elevation still demand trust. Provenance warnings and plugins inspect continue to flag unverified sources; neither blocks plugin-scoped storage or queues.

When a plugin fails with dispatchHookAgentTurn is only available for trusted plugins, compare the error's registryPath against the plugin.trust.registryPath obtained from:

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

Inspection and the Gateway both report the trust decision made at plugin load time, covering reason, origin, installSource, and installSpec. Identical executable versions and config files do not mean identical registry databases. Inspection loads into the CLI process, so compare both paths. Where a local Gateway cannot be reached, Doctor also inspects the installed service environment, and states so when that environment cannot be verified.

If the plugin requires a trust-gated capability, apply the matching remedy below. --link and --force grant no trust for those capabilities.

bundled and trusted-official mark accepted sources. Legacy npm records whose official package spec is consistent stay valid without extra resolution fields. Doctor repairs provenance in the existing install ledger; at runtime there is no fallback to trusting package-authored metadata.

Blocked plugin path ownership

When diagnostics report blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) and validation then returns plugin present but blocked, OpenClaw has detected plugin files owned by a Unix user other than the one loading them. Leave the plugin config as is; correct the filesystem ownership, or run OpenClaw under the same user that owns the state directory.

In 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 deliberately run OpenClaw as root, repair the managed plugin root to root ownership instead:

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

Once ownership is fixed, 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 seem to stall while tools are being prepared, turn on trace logging and look for plugin tool factory timing lines:

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

Look for:

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

The summary reports overall factory time along with the plugin tool factories that took longest, showing plugin id, declared tool names, result shape, and whether each tool is optional. A line becomes a warning once a single factory reaches 1s or more, or when total plugin tool factory prep reaches 5s or more.

When the same effective request context resolves repeatedly, OpenClaw caches the results of successful plugin tool factories. The effective runtime config, workspace and agent id, sandbox policy, browser settings, delivery context, requester identity, and ownership state all feed into the cache key, which means any factory relying on those trusted fields runs again whenever the context changes. Should timings remain high, the plugin may be performing costly work before it returns its tool definitions.

When a single plugin accounts for most of the timing, check its runtime registrations:

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

After that, update, reinstall, or disable the plugin in question. Plugin authors ought to defer expensive dependency loading until the tool execution path runs, rather than performing it inside the tool factory.

Dependency roots, package metadata validation, registry records, startup reload behavior, and legacy cleanup are covered in 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
• Context engines - pluggable context assembly plugins
• Diffs - read-only diff viewer and file renderer (optional plugin tool)
• ACP agents, setup - configuring a plugin-provided ACP agent