插件包

OpenClaw 可以安装来自三个外部生态系统的插件：Codex、Claude 和 Cursor。它们称为 bundle——一种内容和元数据包， OpenClaw 会将其映射为 Skills、Hooks 和 MCP 工具等原生功能。

为什么需要 bundle

许多实用插件以 Codex、Claude 或 Cursor 格式发布。OpenClaw 无需作者将其重写为原生 OpenClaw 插件，而是会检测这些格式， 并将其中支持的内容映射到原生功能集。你可以安装 Claude 命令包或 Codex Skills bundle，并立即使用。

安装 bundle

从目录、归档文件或市场安装

# 本地目录
openclaw plugins install ./my-bundle

# 归档文件
openclaw plugins install ./my-bundle.tgz

# Claude 市场
openclaw plugins marketplace list <source>
openclaw plugins install <plugin> --marketplace <source>

<source> 是本地市场路径/仓库或 git/GitHub 来源。

验证检测结果

openclaw plugins list
openclaw plugins inspect <id>

bundle 会显示 Format: bundle，以及值为 codex、 claude 或 cursor 的 Bundle format:。

重启并使用

openclaw gateway restart

映射后的功能（Skills、Hooks、MCP 工具、LSP 默认值）将在下一个会话中可用。

OpenClaw 从 bundle 映射的内容

目前并非所有 bundle 功能都能在 OpenClaw 中运行。以下列出了 已经可用的功能，以及已检测但尚未接通的功能。

当前支持

Skills 内容

• bundle Skills 根目录作为普通 OpenClaw Skills 根目录加载。
• Claude commands/ 根目录被视为额外的 Skills 根目录。
• Cursor .cursor/commands/ 根目录被视为额外的 Skills 根目录。

Claude Markdown 命令文件和 Cursor 命令 Markdown 都通过 常规 OpenClaw Skills 加载器工作。

Hook 包

只有使用常规 OpenClaw Hook 包布局时，bundle Hook 根目录才有效： HOOK.md 加 handler.ts 或 handler.js。目前这主要适用于 与 Codex 兼容的情况。

嵌入式 OpenClaw 的 MCP

• 已启用的 bundle 可以提供 MCP 服务器配置。
• OpenClaw 将 bundle MCP 配置作为 mcpServers 合并到 有效的嵌入式 OpenClaw 设置中。
• OpenClaw 会在嵌入式 OpenClaw 智能体轮次期间，通过启动 stdio 服务器或连接 HTTP 服务器来公开受支持的 bundle MCP 工具。
• coding 和 messaging 工具配置默认包含 bundle MCP 工具； 使用 tools.deny: ["bundle-mcp"] 可针对智能体或 Gateway 网关选择停用。
• 项目本地的嵌入式智能体设置仍在 bundle 默认值之后应用，因此 工作区设置可在需要时覆盖 bundle MCP 条目。
• bundle MCP 工具目录会在注册前进行确定性排序，因此 上游 listTools() 顺序变化不会导致提示缓存的工具块频繁变动。

传输协议

MCP 服务器可以使用 stdio 或 HTTP 传输协议。

Stdio 会启动子进程：

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

HTTP 会连接正在运行的 MCP 服务器，除非请求 streamable-http，否则默认为 sse：

{
  "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 凭据（用户信息和查询参数） 会被隐去。
• connectionTimeoutMs 会覆盖 stdio 和 HTTP 传输协议默认的 30 秒连接超时。请求超时默认为 60 秒， 可使用 requestTimeoutMs 覆盖。

工具命名

OpenClaw 使用 serverName__toolName 形式的提供商安全名称注册 bundle MCP 工具。例如，键为 "vigil-harbor" 的服务器公开 memory_search 工具时，会注册为 vigil-harbor__memory_search。

• A-Za-z0-9_- 之外的字符会替换为 -。
• 以非字母开头的片段会添加字母前缀，因此 12306 等数字服务器键会变成提供商安全的工具前缀。
• 服务器前缀最长为 30 个字符。
• 完整工具名称最长为 64 个字符。
• 空服务器名称会回退为 mcp。
• 清理后发生冲突的名称会使用数字后缀消除歧义。
• 最终公开的工具按安全名称进行确定性排序，以保持 重复的嵌入式智能体轮次缓存稳定。
• 配置文件筛选会将来自同一个 bundle MCP 服务器的每个工具 视为由 bundle-mcp 插件拥有，因此配置文件允许/拒绝列表可以引用 单个公开工具名称或 bundle-mcp 插件键。

嵌入式 OpenClaw 设置

启用 bundle 后，Claude settings.json 会作为默认嵌入式 OpenClaw 设置导入。OpenClaw 会在应用前清理 shell 覆盖键：

• shellPath
• shellCommandPrefix

嵌入式 OpenClaw LSP

• 已启用的 Claude bundle 可以提供 LSP 服务器配置。
• OpenClaw 会加载 .lsp.json 以及清单声明的所有 lspServers 路径。
• bundle LSP 配置会合并到有效的嵌入式 OpenClaw LSP 默认值中。
• 目前只有受支持的 stdio 后端 LSP 服务器可以运行；不受支持的 传输协议仍会显示在 openclaw plugins inspect <id> 中。

已检测但未执行

以下内容可以识别并显示在诊断信息中，但 OpenClaw 不会运行它们：

• Claude agents、hooks/hooks.json 自动化、outputStyles
• Cursor .cursor/agents、.cursor/hooks.json、.cursor/rules
• Codex 中能力报告以外的 .app.json 元数据

bundle 格式

检测优先级

OpenClaw 首先检查原生插件格式：

1. openclaw.plugin.json 或带有 openclaw.extensions 的有效 package.json——视为原生插件
2. bundle 标记（.codex-plugin/、.claude-plugin/ 或默认 Claude/Cursor 布局）——视为 bundle

如果目录同时包含两种格式，OpenClaw 会使用原生路径。这可以防止 双格式包以 bundle 形式被部分安装。

运行时依赖项和清理

• 第三方兼容 bundle 不会在启动时进行 npm install 修复。 它们应通过 openclaw plugins install 安装，并在已安装的插件目录中 附带所需的一切内容。
• OpenClaw 自有的内置插件要么以轻量形式随核心一起提供，要么 可通过插件安装器下载。Gateway 网关启动时绝不会为它们运行 包管理器。
• openclaw doctor --fix 会移除过时的本地内置插件安装记录； 当配置仍引用可下载插件，但本地插件索引中缺少该插件时， 还可以恢复该插件。

安全性

bundle 的信任边界比原生插件更窄：

• OpenClaw 不会在进程内加载任意 bundle 运行时模块。
• Skills 和 Hook 包路径必须位于插件根目录内（经过边界检查）。
• 读取设置文件时使用相同的边界检查。
• 受支持的 stdio MCP 服务器可能会作为子进程启动。

这使 bundle 默认更安全，但对于第三方 bundle 实际公开的功能， 仍应将其视为可信内容。

故障排查

相关内容

• 安装和配置插件
• Building Plugins - 创建原生插件
• Plugin Manifest - 原生清单架构