Plugin bundles

​

Why bundles exist

​

Install a bundle

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

openclaw plugins list
openclaw plugins inspect <id>

openclaw gateway restart

​

What OpenClaw maps from bundles

​

Supported now

​

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.

​

Hook packs

​

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": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

{
  "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

• 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

• 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

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

​

Bundle formats

​

Detection precedence

1. openclaw.plugin.json or a valid package.json with openclaw.extensions - treated as a native plugin
2. Client-specific bundle markers (.codex-plugin/, .cursor-plugin/, .claude-plugin/) - treated as a bundle in that format
3. A root plugin.json - treated as an Agent Plugins bundle
4. Default manifestless Claude layout (skills/, commands/, .mcp.json, …) - treated as a Claude bundle

​

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

• 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.

​

Troubleshooting

​

Related

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