本页介绍 OpenClaw 的 Plugin Bundle 功能：无需重写代码，直接安装 Codex、Claude 或 Cursor 格式的扩展包，OpenClaw 自动将其 skill 内容、MCP 工具、LSP 服务器等映射为原生功能。覆盖安装方法、各格式说明、MCP 传输配置和安全边界。

OpenClaw Plugin Bundles

OpenClaw 支持安装来自三个生态系统的插件：Codex、Claude 和 Cursor。这些被称为 bundle — 内容和元数据包，OpenClaw 将其映射为 skill、hook、MCP 工具等原生功能。

Bundle 不等同于原生 OpenClaw 插件。原生插件进程内运行，可注册任何能力。Bundle 是内容包，有选择性的功能映射和更窄的信任边界。

为什么需要 Bundle

很多有用的插件以 Codex、Claude 或 Cursor 格式发布。OpenClaw 检测这些格式并将支持的内容映射到原生功能集，无需作者重写。这意味着你可以直接安装 Claude 命令包或 Codex skill bundle，立即使用。

安装 Bundle

步骤 1：从目录、归档或市场安装

bash

# 本地目录
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>

步骤 2：验证检测

bash

openclaw plugins list
openclaw plugins inspect <id>

Bundle 显示为 Format: bundle，子类型为 codex、claude 或 cursor。

步骤 3：重启并使用

bash

openclaw gateway restart

映射的功能（skill、hook、MCP 工具、LSP 默认值）在下个会话中可用。

Bundle 支持的功能

当前已支持

功能	映射方式	适用格式
Skill 内容	Bundle skill 根作为正常 OpenClaw skill 加载	所有格式
命令	`commands/` 和 `.cursor/commands/` 视为 skill 根	Claude、Cursor
Hook 包	OpenClaw 风格的 `HOOK.md` + `handler.ts` 布局	Codex
MCP 工具	Bundle MCP 配置合并到嵌入式 Pi 设置；加载支持的 stdio 和 HTTP 服务器	所有格式
LSP 服务器	Claude `.lsp.json` 和 manifest 声明的 `lspServers` 合并到嵌入式 Pi LSP 默认值	Claude
Settings	Claude `settings.json` 导入为嵌入式 Pi 默认值	Claude

仅检测不执行

这些功能被识别并显示在诊断中，但 OpenClaw 不运行它们：

Claude agents、hooks.json 自动化、outputStyles
Cursor .cursor/agents、.cursor/hooks.json、.cursor/rules
Codex 内联/应用元数据（能力上报除外）

MCP 配置

已启用的 bundle 可贡献 MCP 服务器配置，OpenClaw 将其合并到嵌入式 Pi 设置的 mcpServers。

Stdio 传输

启动子进程：

json

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

HTTP 传输

连接到运行中的 MCP 服务器：

json

{
  "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
只允许 http: 和 https: URL scheme
headers 值支持 ${ENV_VAR} 插值
同时含 command 和 url 的入口被拒绝
URL 中的凭证（userinfo 和 query params）会从工具描述和日志中被脱敏
connectionTimeoutMs 覆盖默认 30 秒连接超时（stdio 和 HTTP 均适用）

工具命名规则

OpenClaw 以 serverName__toolName 格式注册 bundle MCP 工具。例如，名为 "vigil-harbor" 的服务器暴露 memory_search 工具，注册为 vigil-harbor__memory_search。

A-Za-z0-9_- 以外的字符替换为 -
服务器前缀最多 30 字符
完整工具名最多 64 字符
空服务器名回退到 mcp
重名时添加数字后缀消歧义

Bundle 格式说明

Codex Bundle

标记文件：.codex-plugin/plugin.json
可选内容：skills/、hooks/、.mcp.json、.app.json
Hook 仅支持 OpenClaw 风格的 hook-pack 目录（HOOK.md + handler.ts）

Claude Bundle

两种检测模式：

基于 Manifest：.claude-plugin/plugin.json
无 Manifest：默认 Claude 布局（skills/、commands/、agents/、hooks/、.mcp.json、.lsp.json、settings.json）

Claude 特有行为：

commands/ 视为 skill 内容
settings.json 导入到嵌入式 Pi 设置（shell 覆盖键会被清理）
.mcp.json 向嵌入式 Pi 暴露支持的 stdio 工具
hooks/hooks.json 仅检测不执行

需要清理的 settings 键：shellPath、shellCommandPrefix

Cursor Bundle

标记文件：.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 不生效： 只支持嵌入式 Pi settings（settings.json）。OpenClaw 不将 bundle settings 视为原始配置补丁。

Claude hook 不执行： hooks/hooks.json 仅检测不执行。如需可运行的 hook，使用 OpenClaw hook-pack 布局或提交原生插件。

常见问题

Q: 我有一个 Claude Code 的 .claude/commands/ 目录，可以直接用到 OpenClaw 里吗？

A: 可以。将整个目录结构打包为 bundle（OpenClaw 识别默认 Claude 布局），通过 openclaw plugins install ./my-bundle 安装，commands/ 里的 markdown 文件会被作为 skill 加载。

Q: Bundle 里的 MCP 工具 stdio 服务器会在后台持续运行吗？

A: MCP stdio 服务器在需要时作为子进程启动，不是常驻后台服务。每次 Agent 调用 MCP 工具时，OpenClaw 管理服务器进程的生命周期。

Q: Codex bundle 的 hooks 和 OpenClaw 原生 hook-pack 有什么区别？

A: 格式一致时等效——都需要 HOOK.md + handler.ts 的目录结构。Codex bundle 只是打包在 .codex-plugin/ 结构下的 OpenClaw hook-pack，检测到后使用相同的 hook 加载器。

OpenClaw Plugin Bundles ​

为什么需要 Bundle ​

安装 Bundle ​

Bundle 支持的功能 ​

当前已支持 ​

仅检测不执行 ​

MCP 配置 ​

Stdio 传输 ​

HTTP 传输 ​

工具命名规则 ​

Bundle 格式说明 ​

Codex Bundle ​

Claude Bundle ​

Cursor Bundle ​

检测优先级 ​

安全边界 ​

故障排查 ​

相关文档 ​

常见问题 ​

OpenClaw Plugin Bundles

为什么需要 Bundle

安装 Bundle

Bundle 支持的功能

当前已支持

仅检测不执行

MCP 配置

Stdio 传输

HTTP 传输

工具命名规则

Bundle 格式说明

Codex Bundle

Claude Bundle

Cursor Bundle

检测优先级

安全边界

故障排查

相关文档

常见问题