Skip to main content
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. You can install a Claude command pack or a Codex skill bundle and use it immediately.

​
Install a bundle

1

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>
<source> is a local marketplace path/repo or a git/GitHub source.
2

Verify detection

openclaw plugins list
openclaw plugins inspect <id>
Bundles show Format: bundle plus a Bundle format: value of codex, claude, or cursor.
3

Restart and use

openclaw gateway restart
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

FeatureHow it mapsApplies to
Skill contentBundle skill roots load as normal OpenClaw skillsAll formats
Commandscommands/ and .cursor/commands/ treated as skill rootsClaude, Cursor
Hook packsOpenClaw-style HOOK.md + handler.ts layoutsCodex
MCP toolsBundle MCP config merged into embedded OpenClaw settings; supported stdio and HTTP servers loadedAll formats
LSP serversClaude .lsp.json and manifest-declared lspServers merged into embedded OpenClaw LSP defaultsClaude
SettingsClaude settings.json imported as embedded OpenClaw defaultsClaude

​
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.
Claude markdown command files and Cursor command markdown both work through the normal OpenClaw skill loader.

​
Hook packs

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

​
MCP for embedded OpenClaw

  • Enabled bundles can contribute MCP server config.
  • OpenClaw merges bundle MCP config into the effective embedded OpenClaw settings as mcpServers.
  • OpenClaw exposes supported bundle MCP tools during embedded OpenClaw agent turns by launching stdio servers or connecting to HTTP servers.
  • 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.
  • Project-local embedded agent 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 listTools() order changes do not thrash prompt-cache tool blocks.
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, defaulting to sse unless streamable-http is requested: 
{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}
  • transport accepts "streamable-http" or "sse"; omitted defaults to sse.
  • type: "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.
  • 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. Request timeout defaults to 60 seconds and can be overridden with requestTimeoutMs.
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 -.
  • Fragments that would start with a non-letter get a letter prefix, so numeric server keys such as 12306 become provider-safe tool prefixes.
  • 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.
  • Final exposed tool order is deterministic by safe name, keeping repeated embedded-agent turns cache-stable.
  • Profile filtering treats every tool from one bundle MCP server as plugin-owned by bundle-mcp, so profile allow/deny lists can reference either individual exposed tool names or the bundle-mcp plugin key.

​
Embedded OpenClaw settings

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

​
Embedded OpenClaw LSP

  • Enabled Claude bundles can contribute LSP server config.
  • OpenClaw loads .lsp.json plus any manifest-declared lspServers paths.
  • Bundle LSP config is merged into the effective embedded OpenClaw LSP defaults.
  • Only supported stdio-backed LSP servers are runnable today; unsupported transports still show up in openclaw plugins inspect <id>.

​
Detected but not executed

These are recognized and shown in diagnostics, but OpenClaw does not run them:
  • Claude agents, hooks/hooks.json automation, outputStyles
  • Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
  • Codex .app.json metadata beyond capability reporting

​
Bundle formats

Markers: .codex-plugin/plugin.jsonOptional content: skills/, hooks/, .mcp.json, .app.jsonCodex 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, .lsp.json, settings.json)
Claude-specific behavior:
  • commands/ is treated as skill content
  • settings.json is imported into embedded OpenClaw settings (shell override keys are sanitized)
  • .mcp.json exposes supported stdio tools to embedded OpenClaw
  • .lsp.json plus manifest-declared lspServers paths load into embedded OpenClaw LSP defaults
  • 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.jsonOptional 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 a valid package.json with openclaw.extensions - treated as a native plugin
  2. Bundle markers (.codex-plugin/, .claude-plugin/, or default Claude/Cursor layout) - treated as a 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 npm install repair. They should be installed through openclaw plugins install and ship everything they need in the installed plugin directory.
  • OpenClaw-owned bundled plugins are either shipped lightweight in core or downloadable through the plugin installer. Gateway startup never runs a package manager for them.
  • openclaw doctor --fix removes stale local bundled-plugin install records and can recover downloadable plugins that are missing from the local plugin index when config still references them.

​
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 <id>. 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 OpenClaw 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.