docs/plugins/bundles.md
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.
<Info> 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. </Info>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.
# Archive
openclaw plugins install ./my-bundle.tgz
# Claude marketplace
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
Bundles show as `Format: bundle` with a subtype of `codex`, `claude`, or `cursor`.
Mapped features (skills, hooks, MCP tools, LSP defaults) are available in the next session.
Not every bundle feature runs in OpenClaw today. Here is what works and what is detected but not yet wired.
| 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 |
| LSP servers | Claude .lsp.json and manifest-declared lspServers merged into embedded Pi LSP defaults | Claude |
| Settings | Claude settings.json imported as embedded Pi defaults | Claude |
commands roots are treated as additional skill roots.cursor/commands roots are treated as additional skill rootsThis means Claude markdown command files work through the normal OpenClaw skill loader. Cursor command markdown works through the same path.
HOOK.mdhandler.ts or handler.jsmcpServerscoding and messaging tool profiles include bundle MCP tools by
default; use tools.deny: ["bundle-mcp"] to opt out for an agent or gatewaylistTools() order changes do not thrash prompt-cache tool blocksMCP 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 ssetype: "http" is a CLI-native downstream shape; use transport: "streamable-http" in OpenClaw config. openclaw mcp set and openclaw doctor --fix normalize the common alias.http: and https: URL schemes are allowedheaders values support ${ENV_VAR} interpolationcommand and url is rejectedconnectionTimeoutMs overrides the default 30-second connection timeout for
both stdio and HTTP transportsOpenClaw 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.
A-Za-z0-9_- are replaced with -mcpbundle-mcp, so profile allowlists and deny lists can include either
individual exposed tool names or the bundle-mcp plugin keysettings.json is imported as default embedded Pi settings when the
bundle is enabledSanitized keys:
shellPathshellCommandPrefix.lsp.json plus any manifest-declared lspServers pathsopenclaw plugins inspect <id>These are recognized and shown in diagnostics, but OpenClaw does not run them:
agents, hooks.json automation, outputStyles.cursor/agents, .cursor/hooks.json, .cursor/rulesOptional 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`).
- **Manifest-based:** `.claude-plugin/plugin.json`
- **Manifestless:** default Claude layout (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.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
- `.lsp.json` plus manifest-declared `lspServers` paths load into embedded Pi LSP defaults
- `hooks/hooks.json` is detected but not executed
- Custom component paths in the manifest are additive (they extend defaults, not replace them)
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
OpenClaw checks for native plugin format first:
openclaw.plugin.json or valid package.json with openclaw.extensions — treated as native plugin.codex-plugin/, .claude-plugin/, or default Claude/Cursor layout) — treated as bundleIf a directory contains both, OpenClaw uses the native path. This prevents dual-format packages from being partially installed as bundles.
npm install repair. They
should be installed through openclaw plugins install and ship everything
they need in the installed plugin directory.openclaw doctor --fix removes legacy staged dependency directories and can
recover downloadable plugins that are missing from the local plugin index when
config references them.Bundles have a narrower trust boundary than native plugins:
This makes bundles safer by default, but you should still treat third-party bundles as trusted content for the features they do expose.