OpenClaw Plugin Bundles 完整指南安装与映射 Agent Plugins、Codex、Claude、Cursor 生态插件【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 原生插件运行在进程内并可以注册任意能力而bundle插件包是来自外部生态的内容与元数据包。本文以 docs/plugins/bundles.md 为骨架系统讲解如何通过openclaw plugins install安装 vendor-neutral 的Agent Plugins标准包以及Codex / Claude / Cursor三类兼容格式说明 OpenClaw 如何把它们映射为 skills、hooks、MCP 工具等原生能力并结合src/plugins/下的源码实现bundle-manifest.ts、bundle-mcp.ts、bundle-capability-support.ts等深入剖析检测优先级、占位符展开、工具命名与安全边界。读完你能够独立安装任意格式的 bundle、判断哪些能力会被真实运行、并利用openclaw plugins inspect定位已检测但未接线的疑难场景。Bundle 与原生插件的区别在动手之前必须先明确一个概念bundle 不是原生 OpenClaw 插件。原生插件在进程内运行可以注册任何能力hooks、commands、MCP 服务器、模型提供方等拥有完整信任边界。Bundle 是内容包OpenClaw 只做选择性功能映射把它能理解的那部分内容转成原生特性其余内容只检测、不运行。从源码看bundle 的解析入口集中在 src/plugins/bundle-manifest.ts其文件头注释直接说明职责是Reads Agent/Codex/Claude/Cursor bundle manifests into OpenClaw plugin manifest metadata——即把四种生态的清单翻译成 OpenClaw 插件清单元数据而非直接加载运行它们的运行时模块。为什么需要 Bundle大量有用的插件以 Agent Plugins、Codex、Claude 或 Cursor 的格式发布。与其要求作者把这些插件全部重写成 OpenClaw 原生插件OpenClaw 选择检测这些格式并把受支持的内容映射进原生能力集。这意味着安装一个 Agent Plugins 包可以直接使用其 skills 与 MCP 服务器安装一个 Claude 命令包command pack可以直接使用其命令与输出风格安装一个 Codex skill bundle 可以直接使用其技能内容。从实现角度bundle 的读取遵循各自生态的封闭 schema详见下文Bundle 格式一节而非 OpenClaw 自己的原生清单 schema这正是映射而非重写的技术基础。安装一个 Bundle安装入口统一走openclaw plugins命令族支持目录、压缩包、marketplace 三种来源。第一步从目录、压缩包或 marketplace 安装# 本地目录 openclaw plugins install ./my-bundle # 压缩包 openclaw plugins install ./my-bundle.tgz # Claude marketplace openclaw plugins marketplace list source openclaw plugins install plugin --marketplace sourcesource可以是本地 marketplace 路径/仓库也可以是 git/GitHub 来源。第二步验证检测结果openclaw plugins list openclaw plugins inspect id安装成功且被识别为 bundle 时openclaw plugins inspect id会显示Format: bundleBundle format:字段取值为agent (Agent Plugins)、codex、claude或cursor之一plugins inspect是排障的第一现场它能区分该能力已接线可运行与已检测但未接线详见 Troubleshooting 一节。第三步重启并开始使用openclaw gateway restart重启后映射出的能力skills、hooks、MCP 工具、LSP 默认配置在下一个会话中即可用。bundle 的 MCP 服务器由 embedded OpenClaw 在 agent 回合中按需拉起stdio 子进程或连接HTTP 服务无需手动注册。OpenClaw 从 Bundle 中映射什么并非 bundle 的每个特性都会在 OpenClaw 中运行。下表列出现在受支持的映射关系以及哪些内容被检测但未接线。当前受支持的映射特性映射方式适用范围Skill 内容Bundle 的 skill 根目录按普通 OpenClaw skill 加载所有格式命令 Commandscommands/与.cursor/commands/视为 skill 根目录Claude、CursorAgents 与输出风格Claude 的agents/与output-styles/视为 skill 根目录ClaudeHook 包OpenClaw 风格的HOOK.mdhandler.ts布局Claude、CodexMCP 工具Bundle 的 MCP 配置合并进 embedded OpenClaw 设置受支持的 stdio 与 HTTP 服务器可加载所有格式Env 契约PLUGIN_ROOT、PLUGIN_DATA环境变量以及 stdio MCP 服务器的占位符展开Agent PluginsLSP 服务器Claude 的.lsp.json与清单中声明的lspServers合并进 embedded OpenClaw LSP 默认值Claude设置 SettingsClaude 的settings.json作为 embedded OpenClaw 默认设置导入ClaudeSkill 内容Bundle 的 skill 根目录按普通 OpenClaw skill 根目录加载。Claude 的commands/、agents/、output-styles/根目录被视为额外的 skill 根目录。Cursor 的.cursor/commands/根目录被视为额外的 skill 根目录。Claude 的 markdown 命令文件与 Cursor 的命令 markdown 都走同一个普通 OpenClaw skill loader。Hook 包Bundle 的 hook 根目录是集合目录把每个 hook 的HOOK.md与handler.ts或handler.js放在各自的子目录中如hooks/my-hook/再把hooks/声明为根目录。直接声明 hook 的叶子目录不会被加载。插件 inspection 会把这些 hook 包与检测到的 JSON 自动化分开列出。Claude 的hooks/hooks.json仍会出现在已声明能力中但不会作为受支持的 hook 出现。同时包含两种布局的 bundle 会保留其 OpenClaw hook 包。注意inspection不会执行 handler也无法证明正在运行的 Gateway 已加载它们——这是运行时验证与静态声明的差异。Embedded OpenClaw 设置Claude 的settings.json在 bundle 启用时作为默认的 embedded OpenClaw 设置导入。应用前 OpenClaw 会净化 shell 覆盖键shellPathshellCommandPrefix这两个键不会被当作可执行的 shell 覆盖配置避免 bundle 内容劫持 shell 行为。Embedded OpenClaw LSP已启用的 Claude bundle 可以贡献 LSP 服务器配置。OpenClaw 加载.lsp.json以及清单中声明的lspServers路径。Bundle 的 LSP 配置合并进生效的 embedded OpenClaw LSP 默认值。只有受支持的 stdio 型 LSP 服务器可运行不支持的传输仍会出现在openclaw plugins inspect id中。已检测但不执行以下内容会被识别并出现在诊断中但 OpenClaw不会运行它们Claudehooks/hooks.json自动化Cursor 的.cursor/agents、.cursor/hooks.json、.cursor/rulesCodex 的.app.json元数据仅用于能力报告MCP for Embedded OpenClawMCP 是 bundle 中最有实战价值的部分。要点如下已启用的 bundle 可以贡献 MCP 服务器配置。OpenClaw 把 bundle 的 MCP 配置合并进生效的 embedded OpenClaw 设置作为mcpServers。在 embedded OpenClaw agent 回合中OpenClaw 通过启动 stdio 子进程或连接 HTTP 服务器来暴露受支持的 bundle MCP 工具。coding与messaging工具 profile 默认包含 bundle MCP 工具可用tools.deny: [bundle-mcp]为某个 agent 或 gateway 整体退出opt out。项目级的 embedded agent 设置在 bundle 默认值之后生效因此 workspace 设置可以在需要时覆盖 bundle 的 MCP 条目。Bundle MCP 工具目录在注册前会按确定性顺序排序上游listTools()返回顺序的变化不会打乱 prompt-cache 中的工具块避免缓存抖动。从实现看这一整套逻辑在 src/plugins/bundle-mcp.ts 中它通过resolveBundleMcpConfigPaths决定读取mcp.jsonAgent Plugins 格式还是.mcp.json其他格式再通过extractMcpServerMap归一化mcpServers/servers/裸对象三种形态最后按 bundle 格式做路径绝对化与占位符展开。传输方式MCP 服务器支持 stdio 或 HTTP 两种传输。Stdio启动一个子进程{ mcp: { servers: { my-server: { command: node, args: [server.js], env: { PORT: 3000 } } } } }HTTP连接到一个已运行的 MCP 服务器默认使用sse除非显式请求streamable-http{ mcp: { servers: { my-server: { url: http://localhost:3100/mcp, transport: streamable-http, headers: { Authorization: Bearer ${MY_SECRET_TOKEN} }, connectionTimeoutMs: 30000 } } } }关键约束与默认值transport接受streamable-http或sse省略时默认sse。type: http是 CLI 原生的下游形态在 OpenClaw 配置中应使用transport: streamable-http。openclaw mcp set与openclaw doctor --fix会归一化这个常见别名。只允许http:与https:URL 协议。headers的值支持${ENV_VAR}插值。同时带command与url的服务器条目会被拒绝。URL 凭据userinfo 与 query 参数会从工具描述与日志中脱敏。connectionTimeoutMs覆盖默认 30 秒的连接超时stdio 与 HTTP 均适用请求超时默认 60 秒可用requestTimeoutMs覆盖。源码层面src/plugins/bundle-mcp.ts进一步印证了这些约束的实现细节占位符使用单一正则/\$\{(?:CLAUDE_PLUGIN_ROOT|PLUGIN_ROOT|PLUGIN_DATA)\}/g做单遍展开——注释明确指出一次替换可防止被替换路径引入的新占位符再次展开第 121-132 行。Agent Plugins 的mcp.json顶层只允许$schema与mcpServers两个键AGENT_MCP_TOP_LEVEL_KEYSstdio 条目只允许type/command/args/env/cwdHTTP 条目只允许type/url/headers。command若以./或../等显式相对路径开头会以 bundle 根目录为基准解析为绝对路径。当存在插件数据目录时会强制向 env 注入PLUGIN_ROOT与PLUGIN_DATA两个变量第 227-233 行。工具命名规则OpenClaw 以serverName__toolName的形式注册 bundle MCP 工具保证名称对 provider 安全。例如键名为vigil-harbor的服务器若暴露memory_search工具注册名就是vigil-harbor__memory_search。命名规范细节A-Za-z0-9_-之外的字符替换为-。会以非字母开头的片段会加上字母前缀所以12306这样的纯数字服务器键会变成 provider 安全的工具前缀。服务器前缀上限 30 个字符。完整工具名上限 64 个字符。空服务器名回退为mcp。净化后发生冲突的名字用数字后缀消歧。最终暴露的工具顺序按安全名确定性排序保证重复的 embedded-agent 回合缓存稳定。Profile 过滤把来自同一个 bundle MCP 服务器的所有工具视为bundle-mcp插件所有因此 profile 的 allow/deny 列表既可以引用单个暴露的工具名也可以引用bundle-mcp这个插件键。Bundle 格式详解四种格式各有其检测标记marker与读取行为。Agent Plugins bundles标记包根目录的plugin.json遵循开放的 Agent Plugins 1.0.0 标准。可选内容skills/、mcp.json。格式行为清单是严格 JSON不是 JSON5。OpenClaw 要求非空的name其余清单字段可选未知字段忽略。skills/的直接子目录中包含SKILL.md的会作为 skill 加载没有的跳过并给出警告更深的目录不会被扫描。mcp.json必须声明 1.0.0 的$schema且只含mcpServers对象支持stdio、streamable-http与旧版sse传输。stdio 服务器启动时环境中带有PLUGIN_ROOT插件根目录与PLUGIN_DATAOpenClaw 在状态目录下为每个插件创建的持久数据目录${PLUGIN_ROOT}与${PLUGIN_DATA}占位符会在args、env值、cwd中单遍展开。stdio 的command必须是裸可执行名或插件内部的./相对路径cwd必须保持在PLUGIN_ROOT或PLUGIN_DATA内。非法的mcp.json会让该插件的 MCP 失效并输出诊断skills 仍会继续加载非法的单个服务器条目会被跳过。.mcp.json点前缀与内联清单mcpServers对此格式不读取——标准的封闭 schema 优先。OpenClaw 读取extensions[ai.openclaw]且只支持activation语义与其他 bundle 清单一致其他清单扩展命名空间忽略并保留给各自客户端反向域名reverse-domain客户端目录同样忽略并保留。源码佐证src/plugins/bundle-manifest.ts四种格式的清单相对路径是硬编码常量CODEX_BUNDLE_MANIFEST_RELATIVE_PATH .codex-plugin/plugin.json、CLAUDE_BUNDLE_MANIFEST_RELATIVE_PATH .claude-plugin/plugin.json、CURSOR_BUNDLE_MANIFEST_RELATIVE_PATH .cursor-plugin/plugin.json、AGENT_BUNDLE_MANIFEST_RELATIVE_PATH plugin.json。Agent Plugins 的$schema常量指向https://agent-plugins.org/schemas/1.0.0/plugin.schema.json且清单最大读取 256 KBMAX_AGENT_BUNDLE_MANIFEST_BYTES。插件 ID 通过slugifyPluginId生成把名称或目录名小写化、把非字母数字串折叠为-最终兜底为bundle-plugin。Codex bundles标记.codex-plugin/plugin.json。可选内容skills/、hooks/、.mcp.json、.app.json。Codex bundle 在以下情况下最适合 OpenClaw使用 skill 根目录以及使用 OpenClaw 风格的 hook 包目录HOOK.mdhandler.ts。Claude bundles两种检测模式基于清单.claude-plugin/plugin.json无清单manifestless默认 Claude 布局skills/、commands/、agents/、hooks/、.mcp.json、.lsp.json、settings.json注意output-styles/不是检测标记。只包含output-styles/的 bundle 不会被识别为 Claude bundle。需要添加.claude-plugin/plugin.json或上述任一标记检测才会成功。检测发生在清单加载之前因此未被检测到的目录永远不会进入后续的组件路径。Claude 特有行为commands/、agents/、output-styles/视为 skill 内容。settings.json导入 embedded OpenClaw 设置shell 覆盖键会被净化。.mcp.json向 embedded OpenClaw 暴露受支持的 stdio 工具。.lsp.json以及清单声明的lspServers路径加载进 embedded OpenClaw LSP 默认值。hooks/hooks.json被检测但不执行。清单中的自定义组件路径是叠加式的扩展默认值而不是替换默认值。Cursor bundles标记.cursor-plugin/plugin.json。可选内容skills/、.cursor/commands/、.cursor/agents/、.cursor/rules/、.cursor/hooks.json、.mcp.json。.cursor/commands/视为 skill 内容。.cursor/rules/、.cursor/agents/、.cursor/hooks.json仅检测、不执行。检测优先级OpenClaw 先检查原生插件格式按以下顺序判定openclaw.plugin.json或带openclaw.extensions的有效package.json—— 视为原生插件客户端专属 bundle 标记.codex-plugin/、.cursor-plugin/、.claude-plugin/—— 视为对应格式的bundle根目录的plugin.json—— 视为Agent Plugins bundle默认无清单 Claude 布局skills/、commands/、.mcp.json等—— 视为Claude bundle两条关键裁决规则若包同时带有客户端专属标记和根目录plugin.json客户端专属格式胜出因为它的映射更丰富commands、hooks、settings。若目录同时包含原生清单与 bundle 标记OpenClaw 走原生路径。这防止双格式包被当作 bundle 部分安装。从代码结构可以推断判定逻辑贯穿bundle-manifest.ts的清单加载与loader.bundle.test.ts等测试用例Format: bundle的呈现与Bundle format:字段正是由这套优先级最终决定的。运行时依赖与清理第三方兼容 bundle不会获得启动期的npm install修复。它们应通过openclaw plugins install安装并把所需的一切都随插件目录一并交付。OpenClaw 自有的 bundled 插件要么以轻量方式打进核心要么通过插件安装器下载。Gateway 启动时绝不会为它们运行包管理器。openclaw doctor --fix会移除过期的本地 bundled 插件安装记录当配置仍引用它们而本地插件索引缺失时还能恢复可下载的插件。安全边界Bundle 的信任边界比原生插件更窄OpenClaw不会在进程内加载任意的 bundle 运行时模块。Skill 与 hook 包路径必须保持在插件根目录内有边界检查。设置文件以相同的边界检查读取。受支持的 stdio MCP 服务器可以以子进程方式启动。这让 bundle 在默认情况下更安全但你仍应把第三方 bundle 视为可信内容——至少对它们确实暴露的那些特性而言。安装来源不明的 bundle 前请自行评估其 skills、hook 脚本与 MCP 服务器的可信度。排障指南Bundle 被检测到但能力没有运行运行openclaw plugins inspect id。如果某个能力被列出但标记为未接线not wired那是产品限制不是安装损坏。Claude 的 command、agent 或 output-style 文件不出现确认 bundle 已启用且 markdown 文件位于被检测的skills/、commands/、agents/或output-styles/根目录内。这四类都走同一个 skill loader。Claude 的 settings 不生效只有来自settings.json的 embedded OpenClaw 设置受支持。OpenClaw 不会把 bundle 设置当作原始配置补丁raw config patches处理。Claude hooks 不执行hooks/hooks.json仅检测、不执行。如果需要可运行的 hooks请使用 OpenClaw 的 hook 包布局HOOK.mdhandler.ts或交付一个原生插件。相关文档安装与配置插件 —— 插件安装与管理入口构建插件 —— 创建原生插件插件清单 —— 原生清单 schema核心实现可进一步阅读src/plugins/bundle-manifest.ts、src/plugins/bundle-mcp.ts、src/plugins/bundle-capability-support.ts对应测试见 src/plugins/bundle-claude-inspect.test.ts、src/plugins/bundle-mcp.test.ts 与 src/plugins/loader.bundle.test.ts。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
