Install and Use Plugin Bundles in OpenClaw

OpenClaw pulls in plugins from four outside ecosystems: the format-agnostic Agent Plugins standard, along with Codex, Claude, and Cursor. These packages, referred to as bundles, carry content and metadata that OpenClaw translates into built-in features such as skills, hooks, and MCP tools.

Info

Bundles differ from OpenClaw's own native plugins. Native plugins execute within the process and can register any capability. Bundles, by contrast, are content packages with selective feature mapping and a more limited trust boundary.

Why bundles exist

Plenty of useful plugins ship in Agent Plugins, Codex, Claude, or Cursor form. Rather than making authors rework them into native OpenClaw plugins, OpenClaw recognizes these formats and converts their supported content into the native feature set. Install an Agent Plugins package, a Claude command pack, or a Codex skill bundle and it works right away.

Install a bundle

Install from a directory, archive, or marketplace

# Local directory
openclaw plugins install ./my-bundle

# Archive
openclaw plugins install ./my-bundle.tgz

# Claude marketplace
openclaw plugins marketplace list <source>
openclaw plugins install <plugin> --marketplace <source>

A local marketplace path/repo or a git/GitHub source is what <source> refers to.

Verify detection

openclaw plugins list
openclaw plugins inspect <id>

Bundles display Format: bundle alongside a Bundle format: value chosen from agent (Agent Plugins), codex, claude, or cursor.

Restart and use

openclaw gateway restart

Mapped features (skills, hooks, MCP tools, LSP defaults) become available starting with the next session.

What OpenClaw maps from bundles

Not every bundle feature is operational in OpenClaw at this time. The list below covers what functions now and what gets detected but remains unwired.

Supported now

Skill content

• Bundle skill roots are loaded just like regular OpenClaw skill roots.
• Additional skill roots come from Claude commands/ roots.
• Cursor .cursor/commands/ roots also count as extra skill roots.

Both Claude markdown command files and Cursor command markdown pass through the standard OpenClaw skill loader.

Hook packs

Bundle hook roots only work when they follow the standard OpenClaw hook-pack structure: HOOK.md combined with handler.ts or handler.js. As it stands, this mostly covers the Codex-compatible scenario.

MCP for embedded OpenClaw

• Enabled bundles can supply MCP server configuration.
• Bundle MCP config gets merged into the effective embedded OpenClaw settings as mcpServers.
• During embedded OpenClaw agent turns, OpenClaw surfaces supported bundle MCP tools by spawning stdio servers or dialing into HTTP servers.
• The coding and messaging tool profiles include bundle MCP tools by default; opt out for an agent or gateway with tools.deny: ["bundle-mcp"].
• Project-local embedded agent settings take precedence after bundle defaults, so workspace settings can override bundle MCP entries when necessary.
• Bundle MCP tool catalogs get sorted deterministically before registration, so shifts in upstream listTools() order don't disrupt prompt-cache tool blocks.

Transports

MCP servers support either stdio or HTTP transport.

Stdio spawns a child process:

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

HTTP links to an already-running MCP server, defaulting to sse unless streamable-http is specified:

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

• transport takes either "streamable-http" or "sse"; when omitted, sse is used by default.
• type: "http" suits CLI-native downstream usage; for OpenClaw config, go with transport: "streamable-http". Both openclaw mcp set and openclaw doctor --fix standardize the common alias.
• Allowed URL schemes are limited to http: and https:.
• Interpolation with ${ENV_VAR} is supported in headers values.
• A server entry that includes both command and url gets rejected.
• Tool descriptions and logs strip out URL credentials, including userinfo and query parameters.
• The default 30-second connection timeout for stdio and HTTP transports is overridden by connectionTimeoutMs. Request timeout starts at 60 seconds and can be changed via requestTimeoutMs.

Tool naming

Provider-safe names are assigned by OpenClaw to bundle MCP tools in the format serverName__toolName. Take a server with the key "vigil-harbor" that exposes a memory_search tool; it registers as vigil-harbor__memory_search.

• Any character outside A-Za-z0-9_- gets swapped for -.
• Fragments beginning with a non-letter receive a letter prefix, meaning numeric server keys like 12306 turn into provider-safe tool prefixes.
• Server prefixes are limited to 30 characters.
• Tool names can reach up to 64 characters.
• When a server name is empty, mcp steps in as the fallback.
• Numeric suffixes resolve collisions among sanitized names.
• Tool exposure order is deterministic by safe name, keeping repeated embedded-agent turns cache-stable.
• Profile filtering sees every tool from one bundle MCP server as plugin-owned by bundle-mcp, so allow/deny lists can target either specific exposed tool names or the bundle-mcp plugin key.

Embedded OpenClaw settings

With the bundle enabled, Claude settings.json loads in as default embedded OpenClaw settings. Before applying shell override keys, OpenClaw sanitizes them:

• shellPath
• shellCommandPrefix

Embedded OpenClaw LSP

• Enabled Claude bundles may supply LSP server configuration.
• OpenClaw pulls in .lsp.json plus any manifest-declared lspServers paths.
• Bundle LSP config merges into the effective embedded OpenClaw LSP defaults.
• Today only stdio-backed LSP servers that are supported can run; unsupported transports still appear in openclaw plugins inspect <id>.

Detected but not executed

These are acknowledged and flagged in diagnostics, but OpenClaw leaves them unrun:

• Claude agents, hooks/hooks.json automation, outputStyles
• Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
• Codex .app.json metadata beyond capability reporting

Bundle formats

Agent Plugins bundles

Marker: plugin.json sits at the package root, following the open Agent Plugins 1.0.0 standard

Optional content: skills/, mcp.json

Format behavior:

• The manifest must be strict JSON, not JSON5. OpenClaw demands a non-empty name; every other field in the manifest is optional, and any unknown fields get ignored
• Any immediate child folder of skills/ that includes a SKILL.md is loaded as a skill; folders lacking one are skipped with a warning, and scanning does not go beyond that first level
• mcp.json has to specify the 1.0.0 $schema and an mcpServers object exclusively; the stdio, streamable-http, and older sse transports are all accepted
• For stdio servers, the environment includes PLUGIN_ROOT (the plugin root) and PLUGIN_DATA (a per-plugin data directory that persists, created by OpenClaw under its state dir); placeholders ${PLUGIN_ROOT} and ${PLUGIN_DATA} get expanded inside args, env values, and cwd all in one pass
• A stdio command has to be either a bare executable name or a ./-relative path located within the plugin; cwd must not leave PLUGIN_ROOT or PLUGIN_DATA
• When mcp.json is invalid, MCP gets disabled for the plugin with a diagnostic, though skills still load; individual server entries that are invalid are simply skipped
• .mcp.json (prefixed with a dot) and inline manifest mcpServers are not read for this format; the closed schema from the standard takes precedence
• OpenClaw reads extensions["ai.openclaw"]; at present it supports activation with the same behavior as other bundle manifests
• Extension namespaces from other manifests are ignored and kept aside for their clients
• Client directories using reverse-domain names are ignored and kept aside

Codex bundles

Markers: .codex-plugin/plugin.json

Optional content: skills/, hooks/, .mcp.json, .app.json

Codex bundles work best with OpenClaw when they rely on skill roots and hook-pack directories in the OpenClaw style (HOOK.md + handler.ts).

Claude bundles

Two detection modes:

• Manifest-based: .claude-plugin/plugin.json
• Manifestless: default Claude layout (skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, settings.json)

Behavior specific to Claude:

• commands/ gets treated as skill content
• settings.json gets imported into embedded OpenClaw settings (shell override keys are sanitized)
• .mcp.json makes supported stdio tools available to embedded OpenClaw
• .lsp.json plus lspServers paths declared in the manifest load into the embedded OpenClaw LSP defaults
• hooks/hooks.json is detected but never executed
• Custom component paths in the manifest add to the defaults; they extend rather than replace them

Cursor bundles

Markers: .cursor-plugin/plugin.json

Optional content: skills/, .cursor/commands/, .cursor/agents/, .cursor/rules/, .cursor/hooks.json, .mcp.json

• .cursor/commands/ counts as skill content
• .cursor/rules/, .cursor/agents/, and .cursor/hooks.json are only detected, not executed

Detection precedence

OpenClaw first attempts to identify a native plugin format:

1. A openclaw.plugin.json or a valid package.json containing openclaw.extensions is recognized as a native plugin
2. Client-specific bundle markers (.codex-plugin/, .cursor-plugin/, .claude-plugin/) mark the package as a bundle in that format
3. A root-level plugin.json indicates an Agent Plugins bundle
4. The default manifestless Claude layout (skills/, commands/, .mcp.json, ...) is treated as a Claude bundle

When a package includes both a client-specific marker and a root plugin.json, the client-specific format takes precedence, preserving its richer mappings for commands, hooks, and settings. If a directory has both a native manifest and bundle markers, the native path is chosen. This prevents dual-format packages from being partially installed as bundles.

Runtime dependencies and cleanup

• Third-party compatible bundles do not receive startup npm install repair. They should be installed via openclaw plugins install and include everything required in the installed plugin directory.
• OpenClaw-owned bundled plugins are either shipped lightweight in core or fetched through the plugin installer. Gateway startup never invokes a package manager for them.
• openclaw doctor --fix clears stale local bundled-plugin install records and can restore downloadable plugins missing from the local plugin index when config still points to them.

Security

Bundles operate within a tighter trust boundary than native plugins:

• OpenClaw does not load arbitrary bundle runtime modules in-process.
• Skills and hook-pack paths must remain within the plugin root (boundary-checked).
• Settings files are subject to the same boundary checks.
• Supported stdio MCP servers may be launched as subprocesses.

This makes bundles safer by default, but third-party bundles should still be treated as trusted content for the features they expose.

Troubleshooting

Bundle is detected but capabilities do not run

Execute openclaw plugins inspect <id>. If a capability appears but is flagged as not wired, that indicates a product limit, not a broken install.

Claude command files do not appear

Confirm the bundle is enabled and the markdown files reside within a detected commands/ or skills/ root.

Claude settings do not apply

Only embedded OpenClaw settings from settings.json are supported. OpenClaw does not treat bundle settings as raw config patches.

Claude hooks do not execute

hooks/hooks.json is only detected, not executed. For runnable hooks, use the OpenClaw hook-pack layout or ship a native plugin.

Related

• Install and Configure Plugins
• Building Plugins - create a native plugin
• Plugin Manifest - native manifest schema