openclaw/docs/plugins/bundles.md

summary, read_when, title

summary	read_when	title
Install and use Codex, Claude, and Cursor bundles as OpenClaw plugins	You want to install a Codex, Claude, or Cursor-compatible bundle You need to understand how OpenClaw maps bundle content into native features You are debugging bundle detection or missing capabilities	Plugin Bundles

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.

Bundles are **not** the same as native OpenClaw plugins. Native plugins run in-process and can register any capability. Bundles are content packs with selective feature mapping and a narrower trust boundary.

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

```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>
```

```bash openclaw plugins list openclaw plugins inspect ```

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

```bash openclaw gateway restart ```

Mapped features (skills, hooks, MCP tools) 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

Feature	How it maps	Applies to
Skill content	Bundle skill roots load as normal OpenClaw skills	All formats
Commands	commands/ and .cursor/commands/ treated as skill roots	Claude, Cursor
Hook packs	OpenClaw-style HOOK.md + handler.ts layouts	Codex
MCP tools	Bundle MCP config merged into embedded Pi settings; supported stdio and HTTP servers loaded	All formats
Settings	Claude settings.json imported as embedded Pi defaults	Claude

Skill content

• bundle skill roots load as normal OpenClaw skill roots
• Claude commands roots are treated as additional skill roots
• Cursor .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:
  • HOOK.md
  • handler.ts or handler.js

MCP for Pi

• enabled bundles can contribute MCP server config
• OpenClaw merges bundle MCP config into the effective embedded Pi settings as mcpServers
• OpenClaw exposes supported bundle MCP tools during embedded Pi agent turns by launching stdio servers or connecting to HTTP servers
• project-local Pi settings still apply after bundle defaults, so workspace settings can override bundle MCP entries when needed

Transports

MCP servers can use stdio or HTTP transport:

Stdio launches a child process:

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

HTTP connects to a running MCP server over sse by default, or streamable-http when requested:

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

• transport may be set to "streamable-http" or "sse"; when omitted, OpenClaw uses sse
• only http: and https: URL schemes are allowed
• headers values support ${ENV_VAR} interpolation
• a server entry with both command and url is rejected
• URL credentials (userinfo and query params) are redacted from tool descriptions and logs
• 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 serverName__toolName. For example, a server keyed "vigil-harbor" exposing a memory_search tool registers as vigil-harbor__memory_search.

• characters outside A-Za-z0-9_- are replaced with -
• server prefixes are capped at 30 characters
• full tool names are capped at 64 characters
• empty server names fall back to mcp
• colliding sanitized names are disambiguated with numeric suffixes

Embedded Pi settings

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

Sanitized keys:

• shellPath
• shellCommandPrefix

Detected but not executed

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

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

Bundle formats

Markers: `.codex-plugin/plugin.json`

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

Codex bundles fit OpenClaw best when they use skill roots and OpenClaw-style
hook-pack directories (`HOOK.md` + `handler.ts`).

Two detection modes:

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

Claude-specific behavior:

- `commands/` is treated as skill content
- `settings.json` is imported into embedded Pi settings (shell override keys are sanitized)
- `.mcp.json` exposes supported stdio tools to embedded Pi
- `hooks/hooks.json` is detected but not executed
- Custom component paths in the manifest are additive (they extend defaults, not replace them)

Markers: `.cursor-plugin/plugin.json`

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

- `.cursor/commands/` is treated as skill content
- `.cursor/rules/`, `.cursor/agents/`, and `.cursor/hooks.json` are detect-only

Detection precedence

OpenClaw checks for native plugin format first:

1. openclaw.plugin.json or valid package.json with openclaw.extensions — treated as native plugin
2. Bundle markers (.codex-plugin/, .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.

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

Run `openclaw plugins inspect `. If a capability is listed but marked as not wired, that is a product limit — not a broken install. Make sure the bundle is enabled and the markdown files are inside a detected `commands/` or `skills/` root. Only embedded Pi settings from `settings.json` are supported. OpenClaw does not treat bundle settings as raw config patches. `hooks/hooks.json` is detect-only. If you need 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