OpenClaw Plugin Bundles Explained

OpenClaw plugin bundles are for teams with useful Codex, Claude, or Cursor content that should run inside OpenClaw without being rewritten as native plugins. The docs call bundles content and metadata packs mapped into native features like skills, hooks, and MCP tools.

30-second answer

Bundles are not the same as native plugins. Native plugins run in-process and can register broad capabilities. Bundles are compatible content packs with selective feature mapping and a narrower trust boundary. Use them to bring over skills, command roots, supported hook packs, MCP server config, settings defaults, and supported LSP config.

Install flow

openclaw plugins install ./my-bundle
openclaw plugins install ./my-bundle.tgz
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
openclaw plugins list
openclaw plugins inspect <id>
openclaw gateway restart

After detection, bundles show as Format: bundle with a subtype such as Codex, Claude, or Cursor. Restart the Gateway before expecting mapped features to appear in new sessions.

Supported mappings

Skill roots load as normal OpenClaw skill roots. Claude command roots and Cursor command roots are treated as additional skill roots. Hook roots work only when they use the normal OpenClaw hook-pack shape. Enabled bundles can also contribute MCP server config to the embedded Pi settings path.

For MCP, the docs describe deterministic tool naming with serverName__toolName, sanitized names, capped prefixes, capped full tool names, and deterministic ordering. Supported transports include streamable HTTP and SSE; URL schemes are limited to HTTP and HTTPS.

Detected but not executed

Some bundle features are detected but not executed, including Claude agents, some hook automation shapes, output styles, Cursor agents, Cursor hooks, Cursor rules, and Codex inline or app metadata beyond capability reporting. That conservative mapping prevents external bundle semantics from silently gaining more authority than OpenClaw has reviewed.

Security model

The docs are clear: OpenClaw does not load arbitrary bundle runtime modules in-process. Skills and hook-pack paths must stay inside the plugin root, settings files are boundary-checked, and supported stdio MCP servers may be launched as subprocesses. Treat bundles as imported operating material, not trusted code by default.

Operator checklist

Before adopting a bundle, inspect what mapped, what was merely detected, and which MCP tools or skills became available. Record the source, restart proof, and any subprocesses. If the bundle touches customer systems, run it first in a sandboxed workspace with safe-read-only tool policy.

The OpenClaw Playbook uses bundles as a migration bridge: keep useful team knowledge, but preserve OpenClaw's trust boundaries instead of blindly importing another ecosystem's assumptions.

Rollout plan

Treat OpenClaw Plugin Bundles Explained as a workflow you roll out in stages, not a switch you flip once. Start with the smallest harmless proof: a status check, dry run, local-only call, private session, or read-only inspection. Confirm the documented behavior matches your installed OpenClaw version, then write the exact commands and expected output into the workspace so the next agent does not rely on memory or vibes.

For a production runbook, document decision owner, source document, acceptance check, upgrade risk, and where future agents should look before changing the behavior. Also write down what the agent may do alone, what requires approval, and what must stop immediately. That boundary is the difference between useful autonomy and a workflow that surprises the operator at the worst possible time.

Keep one rollback note beside the guide. It can be as simple as the command to disable a plugin, the channel to pause, the config key to revert, or the owner who must approve the next run. Include the proof that tells you rollback worked, and keep it visible near the production checklist for future maintainers. Agents are most useful when recovery is obvious.

After the first live run, review the transcript or logs while the details are fresh. Look for missing prerequisites, stale assumptions, broad prompts, confusing errors, and any external side effect that should have been gated. Tighten the guide, then repeat with one wider scope. The OpenClaw Playbook is built around this operating rhythm: cautious first proof, written runbook, verified automation, then gradual autonomy once the evidence is boring.