Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
Bundles are not native OpenClaw plugins. Native plugins run in process and can register OpenClaw capabilities directly. Bundles are content and metadata packs that OpenClaw maps selectively into supported surfaces.

​
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.
NeedUse
Reuse skills, command markdown, MCP config, or LSP defaults from a compatible ecosystemBundle
Execute arbitrary plugin runtime code in OpenClawNative plugin
Publish a full OpenClaw capabilityNative plugin
Port an existing Claude or Cursor command packBundle
See Building plugins for native plugin authoring and Plugins for the main install workflow.

​
Install and verify a bundle

1

Install the bundle

Install from a local directory, archive, or supported marketplace source:
# 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>
2

Check detection

openclaw plugins list
openclaw plugins inspect <id>
A compatible bundle appears with Format: bundle and a codex, claude, or cursor subtype.
3

Restart the Gateway

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

FeatureHow it mapsApplies to
Skill contentBundle skill roots load as normal OpenClaw skillsAll formats
Commandscommands/ and .cursor/commands/ are treated as skill rootsClaude, Cursor
Hook packsOpenClaw-style HOOK.md and handler.ts or handler.js layoutsPrimarily Codex
MCP toolsBundle MCP config merges into embedded Pi settings; supported stdio and HTTP servers loadAll formats
LSP serversClaude .lsp.json and manifest-declared lspServers merge into embedded Pi LSP defaultsClaude
SettingsClaude settings.json imports as embedded Pi defaults after shell override keys are removedClaude

​
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:
Marker: .codex-plugin/plugin.jsonSupported 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.
Detection modes:
  • 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.
Marker: .cursor-plugin/plugin.jsonSupported 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

SymptomCheckFix
Capability is listed but does not runRun openclaw plugins inspect <id> and check whether it is marked as not wiredThis is a current product limit, not a broken install
Claude command files do not appear as skillsCheck that markdown files are inside commands/ or a declared command pathMove the files under a detected commands/ or skills/ root, enable the bundle, and restart
Claude settings.json does not applyCheck that the bundle is enabled and inspect diagnosticsOnly embedded Pi settings are imported; shell override keys are removed
Claude hooks do not executeCheck whether the bundle only has hooks/hooks.jsonUse an OpenClaw hook-pack layout or ship a native plugin