OpenClaw 可以复用现有 Codex、Claude 或 Cursor 插件包，不需要重写为原生插件就能用上 skill、MCP 工具、LSP 服务器等功能。安装使用 openclaw plugins install，装完后用 openclaw plugins inspect <id> 检查格式和映射状态，最后 openclaw gateway restart 生效。本页覆盖所有支持格式的安装、检测、能力映射和故障排查。

OpenClaw 插件包：安装与配置 Codex/Claude/Cursor 扩展

插件包（Plugin Bundle）让 OpenClaw 重用 Codex、Claude 和 Cursor 兼容的插件布局，不必把它们当作原生运行时模块加载。如果你有现成的插件包，想接入 OpenClaw，可以在这页找到安装方法、格式检测规则、哪些内容会被映射成 skill/hook/MCP 工具/settings 或诊断信息。

插件包不是原生 OpenClaw 插件。原生插件在进程内运行，可以直接注册 OpenClaw 能力。插件包是内容和元数据包，OpenClaw 按规则把支持的部分映射到对应的功能面上。

怎么选择：用插件包还是原生插件

如果你手上有 Codex、Claude 或 Cursor 兼容的包，想让 OpenClaw 把支持的内容映射成 skill、hook 包、MCP 工具、设置或 LSP 默认值，用插件包比较省事。但如果你的集成需要注册渠道、provider、服务、HTTP 路由、Gateway 方法、插件自己的 CLI 命令或其他运行时能力，那就得写原生插件。

需求	方案
复用 skill、命令 markdown、MCP 配置或 LSP 默认值	插件包
在 OpenClaw 中执行任意插件运行时代码	原生插件
发布完整的 OpenClaw 能力	原生插件
移植现成的 Claude 或 Cursor 命令包	插件包

原生插件开发请参考构建插件，主要安装工作流见插件管理。

安装与验证步骤

第一步：安装插件包

从本地目录、归档文件或支持的市场源安装：

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>

第二步：检查检测结果

bash

openclaw plugins list
openclaw plugins inspect <id>

兼容的插件包会显示 Format: bundle，子类型为 codex、claude 或 cursor。

第三步：重启 Gateway

bash

openclaw gateway restart

安装或更新插件包代码后，必须重启 Gateway 才能生效。

OpenClaw 从插件包里映射什么

不是所有插件包功能都能在 OpenClaw 里直接运行。OpenClaw 把支持的内容映射到原生功能面，并将仅检测不执行的内容记录在插件诊断信息中。

目前已支持的功能

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

Skill 内容

插件包 skill 根目录作为正常 OpenClaw skill 根目录加载。Claude 的 commands/ 和 Cursor 的 .cursor/commands/ 走同一个路径。

Hook 包

插件包 hook 根目录仅在遵循 OpenClaw 标准 hook 包布局时才会运行：包含 HOOK.md 和 handler.ts 或 handler.js。目前这主要是 Codex 兼容的情况。

MCP 工具

启用的插件包可以把 MCP 服务器配置作为 mcpServers 提供给嵌入式 Pi。支持的 stdio 和 HTTP 服务器可以在嵌入式 Pi 轮次中暴露工具。coding 和 messaging 工具画像默认包含插件包 MCP 工具；如果你需要在某个智能体或 Gateway 上排除，可以用 tools.deny: ["bundle-mcp"]。

嵌入式 Pi 设置

Claude 的 settings.json 在插件包启用后会作为嵌入式 Pi 的默认设置导入。OpenClaw 会在应用前移除 shell 覆盖键。

嵌入式 Pi LSP

Claude 的 .lsp.json 和 manifest 声明的 lspServers 会合并到嵌入式 Pi LSP 默认值中。支持的 stdio 类型 LSP 服务器可以运行。

仅检测但不执行

这些内容 OpenClaw 会在诊断中报告，但不运行：

Claude：agents、hooks/hooks.json、outputStyles
Cursor：.cursor/agents、.cursor/hooks.json、.cursor/rules
Codex：应用或内联元数据

插件包格式与检测规则

OpenClaw 先检查原生插件标记，再检查插件包标记。如果目录包含 openclaw.plugin.json 或 package.json 中有有效的 openclaw.extensions 入口，就算同时包含插件包文件，也会被当作原生插件处理。这可以防止双格式包通过插件包路径被部分加载。

原生检测之后，OpenClaw 识别以下插件包布局：

Codex 插件包

标记文件：.codex-plugin/plugin.json
支持映射的内容：skills/、hooks/、.mcp.json 和 .app.json 能力上报
Codex 插件包在包含 skill 根目录和 OpenClaw 风格的 hook 包目录时表现最佳

Claude 插件包

检测模式有两种：

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

支持映射的内容：skills/、commands/、settings.json、.mcp.json、.lsp.json、manifest 声明的 mcpServers 和 lspServers。

仅检测不执行的内容：agents、hooks/hooks.json、outputStyles。

Claude manifest 组件路径是可叠加的。声明自定义路径会扩展插件包中已有的默认路径，而不是替换。

Cursor 插件包

标记文件：.cursor-plugin/plugin.json
支持映射的内容：skills/、.cursor/commands/、.mcp.json
仅检测不执行的内容：.cursor/agents、.cursor/hooks.json、.cursor/rules

MCP 配置参考

插件包 MCP 工具使用合成键 bundle-mcp 用于画像过滤。如果需要在智能体或 Gateway 上排除，可以禁止该键：

json5

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

项目本地的嵌入式 Pi 设置会在插件包默认值之后应用，所以工作区设置可以在需要时覆盖插件包的 MCP 条目。

MCP 配置格式

插件包 MCP 文件可以使用 mcpServers、servers 或顶层服务器映射。Stdio 服务器会启动一个子进程：

json

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

HTTP 服务器默认使用 sse 连接，或者使用 streamable-http：

json

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3100/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer local-dev-token"
      },
      "connectionTimeoutMs": 30000
    }
  }
}

规则：

transport 可以是 "sse" 或 "streamable-http"。省略时 OpenClaw 使用 sse。
type: "http" 是 CLI 层面的下游别名。在插件包配置中建议使用 transport: "streamable-http"；openclaw mcp set 和 openclaw doctor --fix 会标准化这个别名。
只支持 http: 和 https: URL。
headers 必须是 JSON 对象，值要是字符串兼容的。
包含 command 的服务器条目视为 stdio。包含 url 但没有 command 的条目视为 HTTP。
URL 中的凭证，包括 userinfo 和 query 参数，会从工具描述和日志中被脱敏。
connectionTimeoutMs 覆盖默认的 30 秒连接超时，适用于 stdio 和 HTTP 传输。

对于 stdio 启动安全，不支持的环境变量条目会被忽略并在诊断中报告，而不是直接透传。

MCP 路径与工具命名

基于文件的 MCP 配置相对于声明它的插件包文件解析。显式的相对路径 command、args、cwd 和 workingDirectory 会根据该文件所在的目录展开。Claude 插件包配置也可以使用 ${CLAUDE_PLUGIN_ROOT} 引用插件包根目录。

OpenClaw 使用 provider 安全的名称注册插件包 MCP 工具：

text

serverName__toolName

命名规则：

超出 A-Za-z0-9_- 范围的字符替换为 -。
服务器前缀必须以字母开头；数字开头的服务器键会获得 mcp- 前缀。
空服务器名称回退为 mcp。
服务器前缀最多 30 个字符。
完整工具名最多 64 个字符。
冲突的 sanitized 名称会添加数字后缀。
暴露的工具按安全名称确定性排序，这样重复的 Pi 轮次能有稳定的工具块。
画像的 allowlist 和 denylist 可以命名单个暴露的工具，也可以使用 bundle-mcp 插件键。

嵌入式 Pi 设置与 LSP 默认值

启用的 Claude 插件包可以把 settings.json 默认值提供给嵌入式 Pi 运行时。OpenClaw 在项目本地设置之前应用这些设置，然后清理 shell 覆盖键，防止插件包或工作区设置改变 shell 执行行为。

被清理的键：

shellPath
shellCommandPrefix

启用的 Claude 插件包也可以通过 .lsp.json 或 manifest 声明的 lspServers 贡献 LSP 服务器配置。OpenClaw 把这些条目合并到嵌入式 Pi LSP 默认值。支持的 stdio 类型 LSP 服务器可以运行；不支持的服务器条目仍然会在 openclaw plugins inspect <id> 的诊断中显示。

运行时依赖与清理

第三方兼容的插件包在启动时不会收到 npm install 修复。它们通过 openclaw plugins install 安装，所有运行时文件都需要打包在安装后的插件目录里。

OpenClaw 自有的捆绑插件要么在核心中轻量级分发，要么可以通过插件安装器下载。Gateway 启动时不会为它们运行包管理器。openclaw doctor --fix 可以移除旧版暂存的依赖目录，并恢复配置引用但本地插件索引中缺少的可下载插件。

安全边界

插件包比原生插件有更窄的运行时边界：

OpenClaw 不会在进程内加载任意插件包运行时模块。
Skill 根目录、hook 包路径、设置文件、MCP 文件和 LSP 文件都经过插件根目录边界检查。
OpenClaw 风格的 hook 包必须保持在插件根目录内。
支持的 stdio MCP 服务器仍然可以启动子进程。

第三方插件包应对其暴露的映射功能视为受信任内容，尤其是 MCP 服务器和 hook 包。

故障排查

症状	检查	修复
能力已列出但不运行	运行 `openclaw plugins inspect <id>` 查看是否标记为未接线	这是目前的产品限制，不是安装问题
Claude 命令文件不显示为 skill	确认 markdown 文件在 `commands/` 或声明的命令路径内	把文件移到检测到的 `commands/` 或 `skills/` 根目录下，启用插件包并重启
Claude `settings.json` 不生效	确认插件包已启用并检查诊断信息	只导入嵌入式 Pi 设置；shell 覆盖键会被移除
Claude hooks 不执行	检查插件包是否只有 `hooks/hooks.json`	使用 OpenClaw hook 包布局或提交原生插件

常见问题

我有个现成的 Claude commands 目录，怎么在 OpenClaw 里用？

直接把整个目录结构打包成插件包（OpenClaw 识别默认 Claude 布局），用 openclaw plugins install ./my-bundle 安装。commands/ 目录里的 markdown 文件会被作为 skill 加载。安装后用 openclaw plugins inspect <id> 确认格式是 bundle，然后重启 Gateway。

插件包的 MCP 工具 stdio 服务器会一直跑在后台吗？

不会。MCP stdio 服务器只在需要时作为子进程启动，不是常驻后台服务。每次智能体调用 MCP 工具时，OpenClaw 会管理服务器进程的生命周期。HTTP 服务器需要你自己保持启动。

Codex 插件的 hook 和 OpenClaw 原生 hook-pack 有什么不同？

格式一致时就一样：都必须包含 HOOK.md + handler.ts 的目录结构。Codex 插件包只是把 hook 包放在 .codex-plugin/ 结构的 hooks 目录下，OpenClaw 检测到后会走相同的 hook 加载器。如果只放 hooks/hooks.json 而不按结构放 handler 文件，那就只会被检测但不执行。

OpenClaw 插件包：安装与配置 Codex/Claude/Cursor 扩展 ​

怎么选择：用插件包还是原生插件 ​

安装与验证步骤 ​

第一步：安装插件包 ​

第二步：检查检测结果 ​

第三步：重启 Gateway ​

OpenClaw 从插件包里映射什么 ​

目前已支持的功能 ​

Skill 内容 ​

Hook 包 ​

MCP 工具 ​

嵌入式 Pi 设置 ​

嵌入式 Pi LSP ​

仅检测但不执行 ​

插件包格式与检测规则 ​

Codex 插件包 ​

Claude 插件包 ​

Cursor 插件包 ​

MCP 配置参考 ​

MCP 配置格式 ​

MCP 路径与工具命名 ​

嵌入式 Pi 设置与 LSP 默认值 ​

运行时依赖与清理 ​

安全边界 ​

故障排查 ​

常见问题 ​

我有个现成的 Claude commands 目录，怎么在 OpenClaw 里用？ ​

插件包的 MCP 工具 stdio 服务器会一直跑在后台吗？ ​

Codex 插件的 hook 和 OpenClaw 原生 hook-pack 有什么不同？ ​

OpenClaw 插件包：安装与配置 Codex/Claude/Cursor 扩展

怎么选择：用插件包还是原生插件

安装与验证步骤

第一步：安装插件包

第二步：检查检测结果

第三步：重启 Gateway

OpenClaw 从插件包里映射什么

目前已支持的功能

Skill 内容

Hook 包

MCP 工具

嵌入式 Pi 设置

嵌入式 Pi LSP

仅检测但不执行

插件包格式与检测规则

Codex 插件包

Claude 插件包

Cursor 插件包

MCP 配置参考

MCP 配置格式

MCP 路径与工具命名

嵌入式 Pi 设置与 LSP 默认值

运行时依赖与清理

安全边界

故障排查

常见问题

我有个现成的 Claude commands 目录，怎么在 OpenClaw 里用？

插件包的 MCP 工具 stdio 服务器会一直跑在后台吗？

Codex 插件的 hook 和 OpenClaw 原生 hook-pack 有什么不同？