Plugins

Understand OpenClaw plugins: installable packages that add tools, channels, providers, hooks, speech, media, and packaged skills.

Plugins add runtime capability to OpenClaw. Where a skill teaches the agent a workflow, a plugin can provide the code, credentials, lifecycle hooks, and contracts that make a new capability exist.

What Plugins Can Add

OpenClaw plugins can provide:

• tools
• channel adapters
• model providers
• web search and web fetch providers
• speech and realtime voice
• media generation
• hooks
• CLI surfaces
• packaged skills
• UI or node-related capabilities

This makes plugins the main extension surface for capabilities that need implementation, not just instructions.

When to Use a Plugin

Use a plugin when:

• OpenClaw needs to call a new API
• a channel is not built in
• a model provider needs credential and catalog logic
• a workflow needs durable lifecycle state
• a capability needs binaries, package metadata, or runtime hooks
• the same capability should be distributed and updated

Use a skill instead when plain-language instructions are enough.

Install and Manage

Plugins can come from ClawHub, npm, git, local directories, or archives depending on the package.

Common commands:

openclaw plugins list
openclaw plugins install <plugin>
openclaw plugins enable <plugin>
openclaw plugins disable <plugin>
openclaw plugins doctor <plugin>
openclaw plugins uninstall <plugin>

Run doctor after installation when the plugin depends on native packages, external services, or credentials.

Plugin Contracts

A plugin should declare what it contributes. Typical contracts include:

• tool definitions and schemas
• channel account behavior
• provider catalog and auth support
• hook events
• packaged skill directories
• permission requests

The contract is part of the trust boundary. Operators should know what a plugin adds before enabling it.

Bundled vs External

Some plugins ship with OpenClaw, some are installed on demand, and some are community-managed. For example, several channels and media/search providers are plugin-backed even when they feel first-party in the UI.

That distinction matters operationally:

• plugin updates can fix a channel without changing your workspace
• missing optional packages can disable a capability
• plugin auth can be separate from agent auth
• plugin tool schemas still pass through normal tool policy

Publishing

If you build a reusable capability, publish it through the plugin path rather than asking users to paste long setup instructions into AGENTS.md.

A good plugin package includes:

• a narrow manifest
• explicit configuration
• safe credential handling
• docs for setup and troubleshooting
• tests or smoke checks
• no surprise broad permissions

Security Checklist

Before enabling a plugin:

1. Confirm the source and maintainer.
2. Inspect requested tools, channels, hooks, or provider capabilities.
3. Check credential storage and SecretRef support.
4. Run plugin validation or doctor checks.
5. Keep the agent's active tool profile narrow.
6. Prefer sandboxed runs for untrusted inputs.