插件 Bundle（Codex/Claude/Cursor 格式）

概述

OpenClaw 支持安装来自三个外部生态系统的 Bundle：Codex、Claude 和 Cursor。Bundle 是内容和元数据包，OpenClaw 将其映射为原生功能（Skills、Hooks、MCP 工具）。Bundle 的信任边界比原生插件更窄。

核心要点

Bundle vs 原生插件：

• 原生插件：进程内运行，可注册任意能力
• Bundle：内容包，选择性功能映射，更窄的信任边界，不加载任意运行时模块

当前支持的映射功能：

• Skill 内容：Bundle skill 根目录作为普通 OpenClaw skill 加载
• Commands：commands/ 和 .cursor/commands/ 作为 skill 根目录
• Hook packs：OpenClaw 风格的 HOOK.md + handler.ts 布局（仅 Codex）
• MCP 工具：Bundle MCP 配置合并到嵌入式 Pi 设置，支持 stdio 和 HTTP 服务器
• LSP 服务器：Claude .lsp.json 合并到嵌入式 Pi LSP 默认值（仅 Claude）
• Settings：Claude settings.json 导入为嵌入式 Pi 默认值（仅 Claude）

检测但不执行的内容：

• Claude agents、hooks.json 自动化、outputStyles
• Cursor .cursor/agents、.cursor/hooks.json、.cursor/rules

Bundle 格式标识：

• Codex：.codex-plugin/plugin.json
• Claude（manifest 模式）：.claude-plugin/plugin.json
• Claude（无 manifest）：默认 Claude 布局（skills/、commands/ 等）
• Cursor：.cursor-plugin/plugin.json

检测优先级：

1. openclaw.plugin.json 或含 openclaw.extensions 的 package.json → 原生插件
2. Bundle 标识符 → Bundle

MCP 工具命名规则：

• 格式：serverName__toolName
• 非字母数字字符替换为 -
• 服务器前缀最多 30 字符，完整工具名最多 64 字符
• 工具顺序确定性，保持 Pi turn 缓存稳定

配置/使用

安装 Bundle：

# 本地目录
openclaw plugins install ./my-bundle
 
# 归档文件
openclaw plugins install ./my-bundle.tgz
 
# Claude 市场
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

MCP HTTP 服务器配置：

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": { "Authorization": "Bearer ${MY_SECRET_TOKEN}" }
      }
    }
  }
}

禁用 Bundle MCP 工具：

{ "tools": { "deny": ["bundle-mcp"] } }

相关页面

• concepts/plugin-manage — 插件安装、更新、卸载管理
• concepts/plugin-building — 创建原生插件
• concepts/plugin-manifest — 原生 manifest schema