Plugin bundles

OpenClaw can install plugins from three external ecosystems: Codex, Claude, and Cursor. These are called bundles — content and metadata packs that OpenClaw maps into native features like skills, hooks, and MCP tools.

Why bundles exist

Many useful plugins are published in Codex, Claude, or Cursor format. Instead of requiring authors to rewrite them as native OpenClaw plugins, OpenClaw detects these formats and maps their supported content into the native feature set. This means you can install a Claude command pack or a Codex skill bundle and use it immediately.

Install a bundle

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

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

text
Copy
Bundles show as `Format: bundle` with a subtype of `codex`, `claude`, or `cursor`.

text
Copy
Mapped features (skills, hooks, MCP tools, LSP defaults) are available in the next session.

What OpenClaw maps from bundles

Not every bundle feature runs in OpenClaw today. Here is what works and what is detected but not yet wired.

Supported now

Skill content

• bundle skill roots load as normal OpenClaw skill roots
• Claude
  text

  Copy

  commands
  roots are treated as additional skill roots
• Cursor
  text

  Copy

  .cursor/commands
  roots are treated as additional skill roots

This means Claude markdown command files work through the normal OpenClaw skill loader. Cursor command markdown works through the same path.

Hook packs

• bundle hook roots work only when they use the normal OpenClaw hook-pack layout. Today this is primarily the Codex-compatible case:
  • text

    Copy

    HOOK.md
  • text

    Copy

    handler.ts
    or
    text

    Copy

    handler.js

MCP for Pi

• enabled bundles can contribute MCP server config
• OpenClaw merges bundle MCP config into the effective embedded Pi settings as
  text

  Copy

  mcpServers
• OpenClaw exposes supported bundle MCP tools during embedded Pi agent turns by launching stdio servers or connecting to HTTP servers
• the
  text

  Copy

  coding
  and
  text

  Copy

  messaging
  tool profiles include bundle MCP tools by default; use
  text

  Copy

  tools.deny: ["bundle-mcp"]
  to opt out for an agent or gateway
• project-local Pi settings still apply after bundle defaults, so workspace settings can override bundle MCP entries when needed
• bundle MCP tool catalogs are sorted deterministically before registration, so upstream
  text

  Copy

  listTools()
  order changes do not thrash prompt-cache tool blocks

Transports

MCP servers can use stdio or HTTP transport:

Stdio launches a child process:

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

HTTP connects to a running MCP server over

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

• text

  Copy

  transport
  may be set to
  text

  Copy

  "streamable-http"
  or
  text

  Copy

  "sse"
  ; when omitted, OpenClaw uses
  text

  Copy

  sse
• text

  Copy

  type: "http"
  is a CLI-native downstream shape; use
  text

  Copy

  transport: "streamable-http"
  in OpenClaw config.
  text

  Copy

  openclaw mcp set
  and
  text

  Copy

  openclaw doctor --fix
  normalize the common alias.
• only
  text

  Copy

  http:
  and
  text

  Copy

  https:
  URL schemes are allowed
• text

  Copy

  headers
  values support
  text

  Copy

  ${ENV_VAR}
  interpolation
• a server entry with both
  text

  Copy

  command
  and
  text

  Copy

  url
  is rejected
• URL credentials (userinfo and query params) are redacted from tool descriptions and logs
• text

  Copy

  connectionTimeoutMs
  overrides the default 30-second connection timeout for both stdio and HTTP transports

Tool naming

OpenClaw registers bundle MCP tools with provider-safe names in the form

• characters outside
  text

  Copy

  A-Za-z0-9_-
  are replaced with
  text

  Copy

  -
• server prefixes are capped at 30 characters
• full tool names are capped at 64 characters
• empty server names fall back to
  text

  Copy

  mcp
• colliding sanitized names are disambiguated with numeric suffixes
• final exposed tool order is deterministic by safe name to keep repeated Pi turns cache-stable
• profile filtering treats all tools from one bundle MCP server as plugin-owned by
  text

  Copy

  bundle-mcp
  , so profile allowlists and deny lists can include either individual exposed tool names or the
  text

  Copy

  bundle-mcp
  plugin key

Embedded Pi settings

• Claude
  text

  Copy

  settings.json
  is imported as default embedded Pi settings when the bundle is enabled
• OpenClaw sanitizes shell override keys before applying them

Sanitized keys:

• text

  Copy

  shellPath
• text

  Copy

  shellCommandPrefix

Embedded Pi LSP

• enabled Claude bundles can contribute LSP server config
• OpenClaw loads
  text

  Copy

  .lsp.json
  plus any manifest-declared
  text

  Copy

  lspServers
  paths
• bundle LSP config is merged into the effective embedded Pi LSP defaults
• only supported stdio-backed LSP servers are runnable today; unsupported transports still show up in
  text

  Copy

  openclaw plugins inspect <id>

Detected but not executed

These are recognized and shown in diagnostics, but OpenClaw does not run them:

• Claude
  text

  Copy

  agents
  ,
  text

  Copy

  hooks.json
  automation,
  text

  Copy

  outputStyles
• Cursor
  text

  Copy

  .cursor/agents
  ,
  text

  Copy

  .cursor/hooks.json
  ,
  text

  Copy

  .cursor/rules
• Codex inline/app metadata beyond capability reporting

Bundle formats

Detection precedence

OpenClaw checks for native plugin format first:

1. text

   Copy

   openclaw.plugin.json
   or valid
   text

   Copy

   package.json
   with
   text

   Copy

   openclaw.extensions
   — treated as native plugin
2. Bundle markers (
   text

   Copy

   .codex-plugin/
   ,
   text

   Copy

   .claude-plugin/
   , or default Claude/Cursor layout) — treated as bundle

If a directory contains both, OpenClaw uses the native path. This prevents dual-format packages from being partially installed as bundles.

Runtime dependencies and cleanup

• Third-party compatible bundles do not get startup
  text

  Copy

  npm install
  repair. They should be installed through
  text

  Copy

  openclaw plugins install
  and ship everything they need in the installed plugin directory.
• OpenClaw-owned packaged bundled plugins have a narrow exception: when one is enabled, Gateway startup can repair missing declared runtime dependencies before import. Operators can inspect or repair that stage with
  text

  Copy

  openclaw plugins deps
  .
• The release pipeline is still responsible for shipping a complete bundled dependency payload when possible (see the postpublish verification rule in Releasing).

Security

Bundles have a narrower trust boundary than native plugins:

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

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

Troubleshooting

Related

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