插件包

OpenClaw 可以从三个外部生态系统安装插件：Codex、Claude 和 Cursor。这些称为 bundle，也就是 OpenClaw 映射到 Skills、钩子和 MCP 工具等原生功能的内容与元数据包。

# 为什么存在 bundle

许多有用的插件以 Codex、Claude 或 Cursor 格式发布。OpenClaw 不要求作者将它们重写为原生 OpenClaw 插件，而是检测这些格式，并将其支持的内容映射到原生功能集。这意味着你可以安装一个 Claude 命令包或 Codex Skills bundle 并立即使用。

# 安装 bundle

# Local directory
openclaw plugins install ./my-bundle

# Archive
openclaw plugins install ./my-bundle.tgz

# Claude marketplace
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

openclaw plugins list
openclaw plugins inspect <id>

openclaw gateway restart

# OpenClaw 从 bundle 映射什么

目前并非每个 bundle 功能都能在 OpenClaw 中运行。以下是已可用的内容，以及已检测但尚未接线的内容。

# 目前支持

# Skills 内容

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

这意味着 Claude markdown 命令文件会通过普通 OpenClaw Skills 加载器工作。Cursor 命令 markdown 也通过同一路径工作。

# 钩子包

• bundle 钩子根目录仅在使用普通 OpenClaw 钩子包布局时可用。今天这主要是 Codex 兼容的情况：
  • HOOK.md
  • handler.ts 或 handler.js

# Pi 的 MCP

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

# 传输协议

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

Stdio 会启动一个子进程：

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

HTTP 默认通过 sse 连接到正在运行的 MCP 服务器，或在请求时使用 streamable-http：

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

• transport 可以设置为 "streamable-http" 或 "sse"；省略时，OpenClaw 使用 sse
• type: "http" 是 CLI 原生的下游形状；在 OpenClaw 配置中使用 transport: "streamable-http"。openclaw mcp set 和 openclaw doctor --fix 会规范化这个常见别名。
• 仅允许 http: 和 https: URL 方案
• headers 值支持 ${ENV_VAR} 插值
• 同时包含 command 和 url 的服务器条目会被拒绝
• URL 凭证（userinfo 和查询参数）会从工具描述和日志中脱敏
• connectionTimeoutMs 会覆盖 stdio 和 HTTP 传输协议默认的 30 秒连接超时

# 工具命名

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

• A-Za-z0-9_- 之外的字符会替换为 -
• 服务器前缀上限为 30 个字符
• 完整工具名称上限为 64 个字符
• 空服务器名称回退为 mcp
• 发生冲突的清理后名称会用数字后缀消歧
• 最终暴露的工具顺序会按安全名称确定性排序，使重复的 Pi 轮次保持缓存稳定
• 配置文件过滤会将同一个 bundle MCP 服务器中的所有工具视为由 bundle-mcp 插件拥有，因此配置文件 allowlist 和 deny list 可以包含单个暴露工具名称，也可以包含 bundle-mcp 插件键

# 嵌入式 Pi 设置

• 当 bundle 启用时，Claude settings.json 会作为默认嵌入式 Pi 设置导入
• OpenClaw 会在应用 shell 覆盖键之前对其进行清理

清理后的键：

• shellPath
• shellCommandPrefix

# 嵌入式 Pi LSP

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

# 已检测但不执行

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

• Claude agents、hooks.json 自动化、outputStyles
• Cursor .cursor/agents、.cursor/hooks.json、.cursor/rules
• Codex 中超出能力报告范围的内联/应用元数据

# 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 和钩子包路径必须保留在插件根目录内（带边界检查）
• 设置文件会用相同的边界检查读取
• 受支持的 stdio MCP 服务器可以作为子进程启动

这使 bundle 默认更安全，但你仍应将第三方 bundle 视为受信任内容来使用它们暴露的功能。

# 故障排除

# 相关

• 安装和配置插件
• 构建插件 —— 创建原生插件
• 插件清单 —— 原生清单 schema