{"id":623,"date":"2026-03-21T22:52:57","date_gmt":"2026-03-21T14:52:57","guid":{"rendered":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/plugins-bundles\/"},"modified":"2026-03-21T23:31:01","modified_gmt":"2026-03-21T15:31:01","slug":"plugins-bundles","status":"publish","type":"post","link":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/plugins-bundles\/","title":{"rendered":"\u63d2\u4ef6\u5305"},"content":{"rendered":"<h1>Plugin Bundles<\/h1>\n<p>OpenClaw can install plugins from three external ecosystems: <strong>Codex<\/strong>, <strong>Claude<\/strong>,<br \/>\nand <strong>Cursor<\/strong>. These are called <strong>bundles<\/strong> \u2014 content and metadata packs that<br \/>\nOpenClaw maps into native features like skills, hooks, and MCP tools.<\/p>\n<p>\n  Bundles are <strong>not<\/strong> the same as native OpenClaw plugins. Native plugins run<br \/>\n  in-process and can register any capability. Bundles are content packs with<br \/>\n  selective feature mapping and a narrower trust boundary.\n<\/p>\n<h2>Why bundles exist<\/h2>\n<p>Many useful plugins are published in Codex, Claude, or Cursor format. Instead<br \/>\nof requiring authors to rewrite them as native OpenClaw plugins, OpenClaw<br \/>\ndetects these formats and maps their supported content into the native feature<br \/>\nset. This means you can install a Claude command pack or a Codex skill bundle<br \/>\nand use it immediately.<\/p>\n<h2>Install a bundle<\/h2>\n<p>    &#8220;`bash  theme={&#8220;theme&#8221;:{&#8220;light&#8221;:&#8221;min-light&#8221;,&#8221;dark&#8221;:&#8221;min-dark&#8221;}}<br \/>\n    # Local directory<br \/>\n    openclaw plugins install .\/my-bundle<\/p>\n<pre><code># Archive\nopenclaw plugins install .\/my-bundle.tgz\n\n# Claude marketplace\nopenclaw plugins marketplace list &lt;marketplace-name&gt;\nopenclaw plugins install &lt;plugin-name&gt;@&lt;marketplace-name&gt;\n```\n<\/code><\/pre>\n<\/p>\n<p>\n    <code>bash  theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}<br \/>\n    openclaw plugins list<br \/>\n    openclaw plugins inspect &lt;id&gt;<\/code><\/p>\n<pre><code>Bundles show as `Format: bundle` with a subtype of `codex`, `claude`, or `cursor`.\n<\/code><\/pre>\n<\/p>\n<p>\n    <code>bash  theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}<br \/>\n    openclaw gateway restart<\/code><\/p>\n<pre><code>Mapped features (skills, hooks, MCP tools) are available in the next session.\n<\/code><\/pre>\n<\/p>\n<h2>What OpenClaw maps from bundles<\/h2>\n<p>Not every bundle feature runs in OpenClaw today. Here is what works and what<br \/>\nis detected but not yet wired.<\/p>\n<h3>Supported now<\/h3>\n<table>\n<thead>\n<tr>\n<th>Feature<\/th>\n<th>How it maps<\/th>\n<th>Applies to<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>Skill content<\/td>\n<td>Bundle skill roots load as normal OpenClaw skills<\/td>\n<td>All formats<\/td>\n<\/tr>\n<tr>\n<td>Commands<\/td>\n<td><code>commands\/<\/code> and <code>.cursor\/commands\/<\/code> treated as skill roots<\/td>\n<td>Claude, Cursor<\/td>\n<\/tr>\n<tr>\n<td>Hook packs<\/td>\n<td>OpenClaw-style <code>HOOK.md<\/code> + <code>handler.ts<\/code> layouts<\/td>\n<td>Codex<\/td>\n<\/tr>\n<tr>\n<td>MCP tools<\/td>\n<td>Bundle MCP config merged into embedded Pi settings; supported stdio servers launched as subprocesses<\/td>\n<td>All formats<\/td>\n<\/tr>\n<tr>\n<td>Settings<\/td>\n<td>Claude <code>settings.json<\/code> imported as embedded Pi defaults<\/td>\n<td>Claude<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>Detected but not executed<\/h3>\n<p>These are recognized and shown in diagnostics, but OpenClaw does not run them:<\/p>\n<ul>\n<li>Claude <code>agents<\/code>, <code>hooks.json<\/code> automation, <code>lspServers<\/code>, <code>outputStyles<\/code><\/li>\n<li>Cursor <code>.cursor\/agents<\/code>, <code>.cursor\/hooks.json<\/code>, <code>.cursor\/rules<\/code><\/li>\n<li>Codex inline\/app metadata beyond capability reporting<\/li>\n<\/ul>\n<h2>Bundle formats<\/h2>\n<p>    Markers: <code>.codex-plugin\/plugin.json<\/code><\/p>\n<pre><code>Optional content: `skills\/`, `hooks\/`, `.mcp.json`, `.app.json`\n\nCodex bundles fit OpenClaw best when they use skill roots and OpenClaw-style\nhook-pack directories (`HOOK.md` + `handler.ts`).\n<\/code><\/pre>\n<\/p>\n<p>\n    Two detection modes:<\/p>\n<pre><code>* **Manifest-based:** `.claude-plugin\/plugin.json`\n* **Manifestless:** default Claude layout (`skills\/`, `commands\/`, `agents\/`, `hooks\/`, `.mcp.json`, `settings.json`)\n\nClaude-specific behavior:\n\n* `commands\/` is treated as skill content\n* `settings.json` is imported into embedded Pi settings (shell override keys are sanitized)\n* `.mcp.json` exposes supported stdio tools to embedded Pi\n* `hooks\/hooks.json` is detected but not executed\n* Custom component paths in the manifest are additive (they extend defaults, not replace them)\n<\/code><\/pre>\n<\/p>\n<p>\n    Markers: <code>.cursor-plugin\/plugin.json<\/code><\/p>\n<pre><code>Optional content: `skills\/`, `.cursor\/commands\/`, `.cursor\/agents\/`, `.cursor\/rules\/`, `.cursor\/hooks.json`, `.mcp.json`\n\n* `.cursor\/commands\/` is treated as skill content\n* `.cursor\/rules\/`, `.cursor\/agents\/`, and `.cursor\/hooks.json` are detect-only\n<\/code><\/pre>\n<\/p>\n<h2>Detection precedence<\/h2>\n<p>OpenClaw checks for native plugin format first:<\/p>\n<ol>\n<li><code>openclaw.plugin.json<\/code> or valid <code>package.json<\/code> with <code>openclaw.extensions<\/code> \u2014 treated as <strong>native plugin<\/strong><\/li>\n<li>Bundle markers (<code>.codex-plugin\/<\/code>, <code>.claude-plugin\/<\/code>, or default Claude\/Cursor layout) \u2014 treated as <strong>bundle<\/strong><\/li>\n<\/ol>\n<p>If a directory contains both, OpenClaw uses the native path. This prevents<br \/>\ndual-format packages from being partially installed as bundles.<\/p>\n<h2>Security<\/h2>\n<p>Bundles have a narrower trust boundary than native plugins:<\/p>\n<ul>\n<li>OpenClaw does <strong>not<\/strong> load arbitrary bundle runtime modules in-process<\/li>\n<li>Skills and hook-pack paths must stay inside the plugin root (boundary-checked)<\/li>\n<li>Settings files are read with the same boundary checks<\/li>\n<li>Supported stdio MCP servers may be launched as subprocesses<\/li>\n<\/ul>\n<p>This makes bundles safer by default, but you should still treat third-party<br \/>\nbundles as trusted content for the features they do expose.<\/p>\n<h2>Troubleshooting<\/h2>\n<p>    Run <code>openclaw plugins inspect &lt;id&gt;<\/code>. If a capability is listed but marked as<br \/>\n    not wired, that is a product limit \u2014 not a broken install.\n  <\/p>\n<p>\n    Make sure the bundle is enabled and the markdown files are inside a detected<br \/>\n    <code>commands\/<\/code> or <code>skills\/<\/code> root.\n  <\/p>\n<p>\n    Only embedded Pi settings from <code>settings.json<\/code> are supported. OpenClaw does<br \/>\n    not treat bundle settings as raw config patches.\n  <\/p>\n<p>\n    <code>hooks\/hooks.json<\/code> is detect-only. If you need runnable hooks, use the<br \/>\n    OpenClaw hook-pack layout or ship a native plugin.<\/p>\n<h2>Related<\/h2>\n<ul>\n<li><a href=\"\/tools\/plugin\">Install and Configure Plugins<\/a><\/li>\n<li><a href=\"\/plugins\/building-plugins\">Building Plugins<\/a> \u2014 create a native plugin<\/li>\n<li><a href=\"\/plugins\/manifest\">Plugin Manifest<\/a> \u2014 native manifest schema<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>Plugin Bundles OpenClaw can install plugins from three  [&hellip;]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-623","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/623","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=623"}],"version-history":[{"count":5,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/623\/revisions"}],"predecessor-version":[{"id":900,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/623\/revisions\/900"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=623"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=623"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=623"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}