免费 AI IDE
OpenClaw 插件捆绑包指南：兼容 Codex/Claude/Cursor 的第三方包支持，功能映射与安全模型
OpenClaw 插件捆绑包
OpenClaw 支持一类共享的外部插件包：插件捆绑包（bundle plugins）。目前这涵盖了三个紧密相关的生态：
Codex 捆绑包
Claude 捆绑包
Cursor 捆绑包
在 openclaw plugins list 中，OpenClaw 会将它们全部显示为 Format: bundle。详细输出以及 openclaw plugins inspect <id> 还会显示子类型（codex、claude 或 cursor）。
相关文档：
插件系统总览：插件
CLI 安装 / 列表流程：插件
原生清单 schema：插件清单
什么是捆绑包
捆绑包是一个内容 / 元数据包，而非原生的进程内 OpenClaw 插件。 目前，OpenClaw 不会在进程内执行捆绑包的运行时代码。相反，它会检测已知的捆绑包文件，读取元数据，并将支持的捆绑包内容映射到原生的 OpenClaw 功能上，比如技能、钩子包、MCP 配置，以及嵌入式 Pi 设置。 这是主要的信任边界： 原生 OpenClaw 插件：运行时模块在进程内执行 捆绑包：元数据 / 内容包，仅进行选择性的功能映射
共享捆绑包模型
Codex、Claude 和 Cursor 的捆绑包足够相似，因此 OpenClaw 将它们视为一个标准化的模型。
共享的核心逻辑：
一个小型的清单文件，或是默认的目录布局
一个或多个内容根目录，比如 skills/ 或 commands/
可选的工具 / 运行时元数据，比如 MCP、钩子、代理或 LSP
以目录或归档的形式安装，然后在常规的插件列表中启用
OpenClaw 的通用行为：
检测捆绑包的子类型
将其标准化为一个内部捆绑包记录
将支持的部分映射到原生的 OpenClaw 功能
将不支持的部分报告为 “已检测但未接入” 的能力
实际上，大多数用户无需先考虑厂商专属的格式。更有意义的问题是：OpenClaw 目前支持映射哪些捆绑包功能？
检测顺序
OpenClaw 会优先处理原生的 OpenClaw 插件 / 包布局，再处理捆绑包。
实际效果：
openclaw.plugin.json 的优先级高于捆绑包检测
带有有效 package.json + openclaw.extensions 的包安装会使用原生安装路径
如果一个目录同时包含原生和捆绑包元数据，OpenClaw 会优先将其视为原生插件
这避免了将双格式包部分安装为捆绑包，之后又将其作为原生插件加载的问题。
当前支持的功能
OpenClaw 将捆绑包元数据标准化为一个内部捆绑包记录，然后将支持的功能映射到现有的原生行为中。
当前已支持的功能
技能内容
捆绑包的技能根目录会作为常规的 OpenClaw 技能根目录加载
Claude 的 commands 根目录会被视为额外的技能根目录
Cursor 的 .cursor/commands 根目录会被视为额外的技能根目录
这意味着 Claude 的 markdown 命令文件可以通过常规的 OpenClaw 技能加载器工作，Cursor 的命令 markdown 也可以通过相同的路径工作。
钩子包
捆绑包的钩子根目录仅在使用常规的 OpenClaw 钩子包布局时才会生效。目前这主要是兼容 Codex 的场景：
HOOK.md
handler.ts 或 handler.js
Pi 的 MCP 支持
已启用的捆绑包可以贡献 MCP 服务器配置
OpenClaw 会将捆绑包的 MCP 配置合并到有效的嵌入式 Pi 设置中，作为 mcpServers
OpenClaw 还会在嵌入式 Pi 代理轮次期间，通过启动支持的 stdio MCP 服务器作为子进程，来暴露支持的捆绑包 MCP 工具
项目本地的 Pi 设置仍会在捆绑包默认值之后生效，因此工作区设置可以在需要时覆盖捆绑包的 MCP 条目
嵌入式 Pi 设置
Claude 的 settings.json 会在捆绑包启用时，作为默认的嵌入式 Pi 设置导入
OpenClaw 在应用前会对 shell 覆盖键进行清理
已清理的键：
shellPath
shellCommandPrefix
已检测但暂未执行的功能
这些功能会被检测到，显示在捆绑包的能力列表中，也可能出现在诊断 / 信息输出中，但 OpenClaw 目前还不会运行它们：
Claude agents（代理）
Claude hooks.json 自动化
Claude lspServers（LSP 服务器）
Claude outputStyles
Cursor .cursor/agents
Cursor .cursor/hooks.json
Cursor .cursor/rules
Codex 除能力报告之外的内联 /app 元数据
能力报告
openclaw plugins inspect <id> 会显示标准化捆绑包记录中的捆绑包能力。
支持的能力会静默加载。不支持的能力会生成如下警告：
bundle capability detected but not wired into OpenClaw yet: agents
当前的例外情况：
Claude commands 被视为已支持，因为它会映射到技能
Claude settings 被视为已支持，因为它会映射到嵌入式 Pi 设置
Cursor commands 被视为已支持，因为它会映射到技能
捆绑包 MCP 被视为已支持，因为它会映射到嵌入式 Pi 设置，并向嵌入式 Pi 暴露支持的 stdio 工具
Codex hooks 仅在使用 OpenClaw 钩子包布局时才被视为已支持
格式差异
这些格式很接近，但并非完全一致。以下是在 OpenClaw 中需要注意的实际差异。
Codex
典型标识：
.codex-plugin/plugin.json
可选的 skills/
可选的 hooks/
可选的 .mcp.json
可选的 .app.json
当 Codex 捆绑包使用技能根目录和 OpenClaw 风格的钩子包目录时，最适配 OpenClaw。
Claude
OpenClaw 同时支持：
基于清单的 Claude 捆绑包：.claude-plugin/plugin.json
无清单的 Claude 捆绑包，使用默认的 Claude 布局
OpenClaw 可识别的默认 Claude 布局标识：
skills/
commands/
agents/
hooks/hooks.json
.mcp.json
.lsp.json
settings.json
Claude 专属说明：
commands/ 会被视为技能内容
settings.json 会被导入到嵌入式 Pi 设置
.mcp.json 和清单的 mcpServers 可以向嵌入式 Pi 暴露支持的 stdio 工具
hooks/hooks.json 会被检测到，但不会作为 Claude 自动化执行
Cursor
典型标识：
.cursor-plugin/plugin.json
可选的 skills/
可选的 .cursor/commands/
可选的 .cursor/agents/
可选的 .cursor/rules/
可选的 .cursor/hooks.json
可选的 .mcp.json
Cursor 专属说明：
.cursor/commands/ 会被视为技能内容
.cursor/rules/、.cursor/agents/ 和 .cursor/hooks.json 目前仅支持检测
Claude 自定义路径
Claude 捆绑包清单可以声明自定义的组件路径。OpenClaw 会将这些路径视为附加的，而非替换默认值。
目前可识别的自定义路径键：
skills
commands
agents
hooks
mcpServers
lspServers
outputStyles
示例：
默认的 commands/ 加上清单的 commands: "extra-commands" => OpenClaw 会扫描这两个目录
默认的 skills/ 加上清单的 skills: ["team-skills"] => OpenClaw 会扫描这两个目录
安全模型
捆绑包的支持有意比原生插件的支持更窄。 当前行为： 捆绑包发现会读取插件根目录内的文件，并进行边界检查 技能和钩子包路径必须保持在插件根目录内 捆绑包设置文件的读取也会使用相同的边界检查 支持的 stdio 捆绑包 MCP 服务器可能会作为子进程启动，用于嵌入式 Pi 的工具调用 OpenClaw 不会在进程内加载任意的捆绑包运行时模块 这使得捆绑包支持默认情况下比原生插件模块更安全，但你仍应将第三方捆绑包视为它们所暴露功能的可信内容。
安装示例
openclaw plugins install ./my-codex-bundle
openclaw plugins install ./my-claude-bundle
openclaw plugins install ./my-cursor-bundle
openclaw plugins install ./my-bundle.tgz
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
openclaw plugins inspect my-bundle
如果该目录是原生的 OpenClaw 插件 / 包，原生安装路径仍会优先。
对于 Claude 市场名称，OpenClaw 会读取本地的 Claude 已知市场注册表，路径为 ~/.claude/plugins/known_marketplaces.json。市场条目可以解析为兼容捆绑包的目录 / 归档，或是原生插件源；解析完成后，常规的安装规则仍然适用。
故障排查
捆绑包已检测，但功能未运行
检查 openclaw plugins inspect <id>。
如果该功能已列出，但 OpenClaw 提示它尚未接入，这是产品的实际限制，而非安装损坏。
Claude 命令文件未显示
确保捆绑包已启用，且 markdown 文件位于检测到的 commands 根目录或 skills 根目录内。
Claude 设置未生效
当前的支持仅限于来自 settings.json 的嵌入式 Pi 设置。OpenClaw 不会将捆绑包设置视为原始的 OpenClaw 配置补丁。
Claude 钩子未执行
hooks/hooks.json 目前仅支持检测。
如果你现在需要可运行的捆绑包钩子，请使用常规的 OpenClaw 钩子包布局，通过支持的 Codex 钩子根目录，或者发布一个原生的 OpenClaw 插件。
更多建议：