Appearance
Plugin Bundles
OpenClaw 支持从三个外部生态系统安装插件：Codex、Claude 和 Cursor。这些统称为 bundles（包），是包含内容和元数据的压缩包，OpenClaw 会将其内容映射为原生功能，如 skill、hook 和 MCP 工具。
信息： Bundle 不等于原生 OpenClaw 插件。原生插件在进程内运行，可注册任意能力。Bundle 是内容包，功能映射有限，信任边界也更窄。
为什么需要 bundles
很多有价值的插件已发布为 Codex、Claude 或 Cursor 格式。与其要求作者重写为原生 OpenClaw 插件，OpenClaw 会自动识别这些格式并将其支持的内容映射到原生功能集。这意味着你可以直接安装一个 Claude 命令包或 Codex skill 包，立即上手使用——就像"把别人养的龙虾直接放进你的缸里"。
安装 bundle
第一步：从目录、归档或 marketplace 安装
bash
# 本地目录
openclaw plugins install ./my-bundle
# 归档文件
openclaw plugins install ./my-bundle.tgz
# Claude marketplace
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>第二步：验证检测结果
bash
openclaw plugins list
openclaw plugins inspect <id>Bundle 会显示为 Format: bundle，子类型为 codex、claude 或 cursor。
第三步：重启并使用
bash
openclaw gateway restart映射后的功能（skill、hook、MCP 工具）将在下一个会话中可用。
OpenClaw 从 bundle 中映射的内容
不是所有 bundle 功能在 OpenClaw 中都能运行。以下是目前支持和已检测但尚未接通的内容。
当前支持
| 功能 | 映射方式 | 适用格式 |
|---|---|---|
| Skill 内容 | Bundle skill 根目录作为普通 OpenClaw skill 加载 | 所有格式 |
| Commands | commands/ 和 .cursor/commands/ 视为 skill 根目录 | Claude, Cursor |
| Hook 包 | OpenClaw 风格的 HOOK.md + handler.ts 布局 | Codex |
| MCP 工具 | Bundle 的 MCP 配置合并到内嵌 Pi 设置；支持的 stdio 服务器作为子进程启动 | 所有格式 |
| Settings | Claude 的 settings.json 作为内嵌 Pi 默认值导入 | Claude |
已检测但不执行
以下内容会被识别并在诊断中显示，但 OpenClaw 不会运行它们：
- Claude 的
agents、hooks.json自动化、lspServers、outputStyles - Cursor 的
.cursor/agents、.cursor/hooks.json、.cursor/rules - Codex 的内联/应用元数据（超出能力报告范围的部分）
Bundle 格式
Codex bundles：
标识文件：.codex-plugin/plugin.json
可选内容：skills/、hooks/、.mcp.json、.app.json
当 Codex bundle 使用 skill 根目录和 OpenClaw 风格的 hook-pack 目录（HOOK.md + handler.ts）时，与 OpenClaw 的兼容性最佳。
Claude bundles：
两种检测模式：
- 基于 manifest：
.claude-plugin/plugin.json - 无 manifest： 默认 Claude 布局（
skills/、commands/、agents/、hooks/、.mcp.json、settings.json）
Claude 专属行为：
commands/视为 skill 内容settings.json导入到内嵌 Pi 设置（shell override 键会被清理）.mcp.json向内嵌 Pi 暴露支持的 stdio 工具hooks/hooks.json仅检测，不执行- manifest 中的自定义组件路径是累加的（扩展默认值，不替换）
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/、.claude-plugin/或默认 Claude/Cursor 布局）→ 视为 bundle
如果一个目录同时包含两者，OpenClaw 使用原生路径，防止双格式包被部分安装为 bundle。
安全性
Bundle 的信任边界比原生插件更窄：
- OpenClaw 不会在进程内加载任意 bundle 运行时模块
- Skill 和 hook-pack 路径必须保持在插件根目录内（有边界检查）
- Settings 文件使用相同的边界检查读取
- 支持的 stdio MCP 服务器可以作为子进程启动
这使 bundle 默认更安全，但你仍应将第三方 bundle 视为其所暴露功能范围内的可信内容对待。
故障排查
Bundle 已检测但能力未运行：
运行 openclaw plugins inspect <id>。如果某能力已列出但标记为未接通，这是产品限制，不是安装问题。
Claude command 文件未出现：
确保 bundle 已启用，且 markdown 文件位于已检测的 commands/ 或 skills/ 根目录中。
Claude settings 未生效：
仅支持来自 settings.json 的内嵌 Pi 设置。OpenClaw 不将 bundle settings 视为原始配置补丁。
Claude hooks 未执行：
hooks/hooks.json 仅供检测。如需可运行的 hook，请使用 OpenClaw hook-pack 布局或发布原生插件。