Plugin bundles

Plugin bundles let OpenClaw reuse compatible Codex, Claude, and Cursor plugin layouts without loading them as native OpenClaw runtime modules. Use this page when you have an existing bundle and need to install it, verify how OpenClaw classified it, and understand which parts become OpenClaw skills, hooks, MCP tools, settings, or diagnostics.

Choose the right plugin format

Use a bundle when you already have a Codex, Claude, or Cursor-compatible package and want OpenClaw to map its supported content into skills, hook packs, MCP tools, settings, or LSP defaults without rewriting it as a native plugin. Build a native OpenClaw plugin when the integration must register a channel, provider, service, HTTP route, Gateway method, plugin-owned CLI command, or another runtime capability.

See Building plugins for native plugin authoring and Plugins for the main install workflow.

Install and verify a bundle

```bash
# Local directory
openclaw plugins install ./my-bundle

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

# Claude marketplace
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```

A compatible bundle appears with `Format: bundle` and a `codex`, `claude`,
or `cursor` subtype.

Installing or updating plugin code requires restarting the Gateway.

What OpenClaw maps from bundles

Not every bundle feature runs in OpenClaw today. OpenClaw maps supported content into native surfaces and reports detect-only content in plugin diagnostics.

Supported now

Skill content

Bundle skill roots load as normal OpenClaw skill roots. Claude commands/ and Cursor .cursor/commands/ load through the same path.

Hook packs

Bundle hook roots run only when they use the normal OpenClaw hook-pack layout: HOOK.md with handler.ts or handler.js. Today this is primarily the Codex-compatible case.

MCP tools

Enabled bundles can contribute MCP server config to embedded Pi as mcpServers. Supported stdio and HTTP servers can expose tools during embedded Pi turns. The coding and messaging tool profiles include bundle MCP tools by default; use tools.deny: ["bundle-mcp"] to opt out for an agent or Gateway.

Embedded Pi settings

Claude settings.json imports as default embedded Pi settings when the bundle is enabled. OpenClaw removes shell override keys before applying them.

Embedded Pi LSP

Claude .lsp.json and manifest-declared lspServers merge into embedded Pi LSP defaults. Supported stdio-backed LSP servers can run.

Detected but not executed

OpenClaw reports these in diagnostics but does not run them:

• Claude agents, hooks/hooks.json, outputStyles
• Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
• Codex app or inline metadata

Bundle formats and detection

OpenClaw checks native plugin markers before bundle markers. A directory with openclaw.plugin.json or a valid package.json openclaw.extensions entry is treated as a native plugin, even if it also contains bundle files. This prevents dual-format packages from being partially loaded through the bundle path.

After native detection, OpenClaw recognizes these bundle layouts:

Supported mapped content: `skills/`, `hooks/`, `.mcp.json`, and `.app.json`
capability reporting.

Codex bundles fit OpenClaw best when they use skill roots and OpenClaw-style
hook-pack directories.

- **Manifest-based:** `.claude-plugin/plugin.json`
- **Manifestless:** default Claude layout with `skills/`, `commands/`,
  `agents/`, `hooks/hooks.json`, `.mcp.json`, `.lsp.json`, or
  `settings.json`

Supported mapped content: `skills/`, `commands/`, `settings.json`,
`.mcp.json`, `.lsp.json`, manifest-declared `mcpServers`, and
manifest-declared `lspServers`.

Detect-only content: `agents`, `hooks/hooks.json`, and `outputStyles`.

Supported mapped content: `skills/`, `.cursor/commands/`, and `.mcp.json`.

Detect-only content: `.cursor/agents`, `.cursor/hooks.json`, and
`.cursor/rules`.

Claude manifest component paths are additive. Declaring custom paths extends the default paths that exist in the bundle instead of replacing them.

MCP config reference

Bundle MCP tools use the synthetic plugin key bundle-mcp for profile filtering. To opt out for an agent or Gateway, deny that key:

{
  tools: {
    deny: ["bundle-mcp"],
  },
}

Project-local embedded Pi settings still apply after bundle defaults, so workspace settings can override bundle MCP entries when needed.

MCP config shape

Bundle MCP files can use either mcpServers, servers, or a top-level server map. Stdio servers launch a child process:

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

HTTP servers connect over sse by default, or streamable-http when requested:

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3100/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer local-dev-token"
      },
      "connectionTimeoutMs": 30000
    }
  }
}

Rules:

• transport may be "sse" or "streamable-http". When omitted, OpenClaw uses sse.
• type: "http" is a CLI-native downstream alias. Prefer transport: "streamable-http" in bundle config; openclaw mcp set and openclaw doctor --fix normalize the alias.
• Only http: and https: URLs are supported.
• headers must be a JSON object with string-compatible values.
• A server entry with command is treated as stdio. A server entry with url and no command is treated as HTTP.
• URL credentials, including userinfo and query params, are redacted from tool descriptions and logs.
• connectionTimeoutMs overrides the default 30-second connection timeout for stdio and HTTP transports.

For stdio startup safety, unsupported environment-variable entries are ignored with diagnostics instead of being passed through blindly.

MCP paths and tool names

File-backed MCP config is resolved relative to the bundle file that declared it. Explicit relative command, args, cwd, and workingDirectory values are expanded against that file's directory. Claude bundle config can also use ${CLAUDE_PLUGIN_ROOT} to refer to the bundle root.

OpenClaw registers bundle MCP tools with provider-safe names:

serverName__toolName

Naming rules:

• Characters outside A-Za-z0-9_- become -.
• Server prefixes must start with a letter; numeric server keys get an mcp- prefix.
• Empty server names fall back to mcp.
• Server prefixes are capped at 30 characters.
• Full tool names are capped at 64 characters.
• Colliding sanitized names get numeric suffixes.
• Exposed tools are sorted deterministically by safe name so repeated Pi turns keep stable tool blocks.
• Profile allowlists and denylists can name either individual exposed tools or the bundle-mcp plugin key.

Embedded Pi settings and LSP defaults

Enabled Claude bundles can contribute settings.json defaults to the embedded Pi runtime. OpenClaw applies those settings before project-local settings, then sanitizes shell override keys so bundle or workspace settings cannot change shell execution behavior.

Sanitized keys:

• shellPath
• shellCommandPrefix

Enabled Claude bundles can also contribute LSP server config through .lsp.json or manifest-declared lspServers. OpenClaw merges those entries into embedded Pi LSP defaults. Supported stdio-backed LSP servers can run; unsupported server entries still appear in openclaw plugins inspect <id> diagnostics.

Runtime dependencies and cleanup

Third-party compatible bundles do not get startup npm install repair. Install them with openclaw plugins install, and ship every runtime file they need inside the installed plugin directory.

OpenClaw-owned bundled plugins are either shipped lightweight in core or downloadable through the plugin installer. Gateway startup does not run a package manager for them. openclaw doctor --fix can remove legacy staged dependency directories and recover downloadable plugins that config references but the local plugin index is missing.

Security boundary

Bundles have a narrower runtime boundary than native plugins:

• OpenClaw does not load arbitrary bundle runtime modules in process.
• Skill roots, hook-pack paths, settings files, MCP files, and LSP files are read with plugin-root boundary checks.
• OpenClaw-style hook packs must stay inside the plugin root.
• Supported stdio MCP servers can still launch subprocesses.

Treat third-party bundles as trusted content for the mapped features they expose, especially MCP servers and hook packs.

Troubleshooting

Related

• Plugins - install, configure, and troubleshoot plugins
• Manage plugins - common plugin CLI examples
• Plugin inventory - generated bundled and external plugin list
• Plugin manifest - native plugin manifest schema
• Building plugins - create a native plugin