OpenClaw Plugins - Installing and Managing Extensions for AI Agent Gateways

OpenClaw's plugin system is one of those features that separates it from simpler AI agent frameworks. Instead of building everything from scratch, you can extend your gateway with pre-built plugins for model providers, speech processing, browser automation, and more. The plugin architecture supports native OpenClaw plugins, Codex-compatible bundles, Claude-compatible bundles, and Cursor-compatible bundles - which means the ecosystem is broader than any single platform's marketplace.

We've been working with OpenClaw across several AI agent projects, and the plugin system is where a lot of the practical value lives. Let me walk through how it works and what to watch out for.

Plugin Basics

OpenClaw ships with bundled plugins out of the box. Some are enabled by default - model providers, speech providers, and the built-in browser plugin. Others exist in the installation but need you to explicitly enable them.

The distinction matters. Bundled plugins have been vetted and tested against your OpenClaw version. Third-party plugins from npm or ClawHub haven't necessarily been through the same process. Treat plugin installation the same way you'd treat installing any third-party code - because that's exactly what it is.

Every native OpenClaw plugin must include an openclaw.plugin.json file with an inline JSON Schema for configuration (even if the config is empty). This manifest tells OpenClaw what the plugin does, how to configure it, and what capabilities it exposes. Compatible bundles from other ecosystems use their own manifest formats, which OpenClaw auto-detects.

You can see what you've got installed with:

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose

The verbose output shows the format (native OpenClaw vs bundle), the bundle subtype for compatible packages, and detected capabilities. This is worth running periodically - it's easy to accumulate plugins you're not actually using.

Installing Plugins

The install command is where most of the complexity lives, and honestly where most of the gotchas are too.

openclaw plugins install <package>

A bare package name gets checked against ClawHub first, then npm. This ordering is intentional - ClawHub packages have been submitted specifically for the OpenClaw ecosystem, while npm packages might just happen to have compatible naming.

For explicit source control:

openclaw plugins install clawhub:my-plugin          # ClawHub only
openclaw plugins install clawhub:[email protected]    # Specific version

You can also install from local paths and archives (.zip, .tgz, .tar.gz, .tar), which is useful for development and testing before publishing.

Version Pinning

If you're installing from npm, the --pin flag locks to a specific version. This is good practice for production deployments. Without pinning, updates can introduce breaking changes at inconvenient times.

openclaw plugins install my-plugin --pin

Note that --pin doesn't work with marketplace installs because those track marketplace source metadata instead of npm version specs.

The Force Flag

If a plugin is already installed and you want to overwrite it from a different source (say you were using the npm version and want to switch to a local development copy), use --force:

openclaw plugins install ./local-plugin-dev --force

Without --force, OpenClaw will block the install and point you toward plugins update for normal upgrades. This is a safety mechanism - accidental overwrites of production plugins would be bad.

Marketplace Installs

OpenClaw supports multiple marketplace sources. If a marketplace is registered in your local cache at ~/.claude/plugins/known_marketplaces.json, you can use shorthand:

openclaw plugins install my-plugin@marketplace-name

For marketplaces not in your local cache, specify them explicitly:

openclaw plugins install my-plugin --marketplace owner/repo
openclaw plugins install my-plugin --marketplace https://github.com/owner/repo
openclaw plugins install my-plugin --marketplace ./my-local-marketplace

Remote marketplace installs have a security constraint worth knowing about. Plugin entries in remote marketplaces must use relative paths within the cloned repo. OpenClaw rejects absolute paths, HTTP URLs, git URLs, and any other non-path sources from remote manifests. This prevents a compromised marketplace from redirecting installs to arbitrary locations.

Security Considerations

I want to be direct about this because it affects how you should approach plugins in production.

Plugin installs run code. Not just configuration - actual code. Every npm dependency install runs with --ignore-scripts for safety, which helps, but the plugin code itself runs in your gateway process. A malicious plugin has the same access as your gateway.

OpenClaw includes a built-in dangerous-code scanner that runs during installation. If it finds something flagged as critical, the install stops. There's a --dangerously-force-unsafe-install flag to override this, but the name should tell you everything about when to use it - only for confirmed false positives.

For our AI consulting work, we recommend:

• Pin versions on everything in production. Don't use @latest in deployment scripts.
• Review plugin code before installing in production environments. At minimum, check what permissions it requests and what network calls it makes.
• Use ClawHub over raw npm when possible. ClawHub packages are submitted specifically for OpenClaw and get more community scrutiny.
• Run openclaw plugins doctor periodically. It checks for configuration issues, version conflicts, and other problems that can creep in over time.

Prerelease Handling

A nice safety feature - if a bare install spec or @latest resolves to a prerelease version on npm, OpenClaw stops and asks you to opt in explicitly with a tag like @beta or @rc, or with an exact version like @1.2.3-beta.4. This prevents accidentally running unstable code in production just because a maintainer tagged a prerelease.

Managing Installed Plugins

Day-to-day plugin management is straightforward:

openclaw plugins enable my-plugin       # Turn on a disabled plugin
openclaw plugins disable my-plugin      # Turn off without uninstalling
openclaw plugins inspect my-plugin      # Detailed info
openclaw plugins inspect --all          # Everything at once
openclaw plugins uninstall my-plugin    # Remove completely

The distinction between disable and uninstall is useful. Disabling keeps the plugin installed but inactive - handy for troubleshooting when you suspect a plugin is causing issues. Uninstall removes it completely.

For updates:

openclaw plugins update my-plugin      # Update a specific plugin
openclaw plugins update --all          # Update everything

Updates are the preferred path for routine version bumps of already-tracked npm plugins. install --force is for when you're changing the source entirely.

Config Include Handling

This is a detail that matters for teams managing OpenClaw configuration in version control. If your plugins section in openclaw.json is backed by a single-file $include, plugin management commands (install, update, enable, disable, uninstall) write through to that included file rather than modifying openclaw.json directly.

This keeps your main config file clean and lets you manage plugin configuration separately - useful when different team members or environments need different plugin sets.

However, there are shapes that don't work. Root includes, include arrays, and includes with sibling overrides will fail closed rather than attempting to flatten the configuration. If you hit this, restructure your includes so the plugins section uses a single-file include.

Hook Packs

Plugins aren't the only thing that ships through this system. Hook packs - packages that expose openclaw.hooks in their package.json - install through the same plugins install command. Once installed, you manage individual hooks through openclaw hooks rather than the plugins interface.

Think of hook packs as event-driven automation that triggers on specific gateway events. We covered hooks in more detail in a previous post.

Practical Advice

After deploying OpenClaw in several agentic automation projects, here's what we've learned about plugins:

Start with bundled plugins. They cover the most common use cases (model providers, speech, browser) and are tested against your OpenClaw version. Only reach for third-party plugins when bundled ones don't cover your needs.

Keep your plugin list short. Every plugin is code running in your gateway. More plugins means more attack surface, more potential conflicts, and more things to update. Install what you need, remove what you don't.

Use plugins doctor before debugging weird issues. Configuration drift, version mismatches, and stale plugin state cause subtle problems. Doctor catches most of them.

Test in isolation first. Install new plugins in a development gateway before touching production. The inspect command gives you a good overview of what a plugin does and what it needs before you commit.

The OpenClaw plugin documentation covers additional edge cases around bundled plugin recovery, config validation, and the relationship between plugins and skills. Worth reading if you're building a production gateway.

Plugins are one of those features that seem simple on the surface but have real depth underneath. Get the basics right - careful installation, version pinning, regular audits - and they'll save you significant development time. Skip those basics and they'll cause headaches you didn't need.