插件包

OpenClaw 可以从四个外部生态系统安装插件：厂商中立的 Agent Plugins 标准，以及 Codex、Claude 和 Cursor。这些被称为 bundle（内容包）——即 OpenClaw 会映射到技能（skills）、钩子（hooks）和 MCP 工具等原生功能的内容与元数据包。

为什么会有 bundle¶

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

安装 bundle¶

1. 从目录、归档或市场安装

# Local directory
openclaw plugins install ./my-bundle

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

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

<source> 可以是本地市场路径/仓库，也可以是 git/GitHub 源。

2. 验证检测

openclaw plugins list
openclaw plugins inspect <id>

Bundle 会显示 Format: bundle，以及 Bundle format: 值为 agent (Agent Plugins)、codex、claude 或 cursor。

3. 使用 bundle

安装会应用到正在运行的本地 Gateway，无需重启。如果 Gateway 已停止，请启动它。参见应用更改并检查。映射后的功能（技能、钩子、MCP 工具、LSP 默认值）将在下一个会话中可用。

OpenClaw 会从 bundle 中映射什么¶

并非所有 bundle 功能都会在 OpenClaw 中运行。以下列出可用的功能，以及会被检测到但未接入的功能。

当前支持¶

技能内容¶

• Bundle 技能根目录会作为普通 OpenClaw 技能根目录加载。
• Claude 的 commands/、agents/ 和 output-styles/ 根目录会被视为额外的技能根目录。
• Cursor 的 .cursor/commands/ 根目录会被视为额外的技能根目录。

Claude 的 Markdown 命令文件和 Cursor 的命令 Markdown 都可以通过普通的 OpenClaw 技能加载器工作。

Hook 包¶

Bundle 的 hook 根目录是集合目录。请将每个 hook 的 HOOK.md 和 handler.ts 或 handler.js 放在各自的子目录中，例如 hooks/my-hook/，并将 hooks/ 声明为根目录。直接声明 hook 的叶子目录不会加载它。

插件检查会将这类 hook 包与检测到的 JSON 自动化分开列出。Claude hooks/hooks.json 仍保留在声明的能力中，但不会显示为受支持的 hook。同时包含两种布局的 bundle 会保留其 OpenClaw hook 包。检查操作不会执行 handler，也无法证明正在运行的 Gateway 已加载它们。

嵌入式 OpenClaw 设置¶

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

• shellPath
• shellCommandPrefix

嵌入式 OpenClaw LSP¶

• 已启用的 Claude bundle 可以提供 LSP 服务器配置。
• OpenClaw 会加载 .lsp.json 以及任何清单中声明的 lspServers 路径。
• Bundle LSP 配置会合并到有效的嵌入式 OpenClaw LSP 默认值中。
• 运行时工具允许列表可以通过 bundle-lsp、group:plugins 或匹配的 lsp_* 名称和 glob 来选择 bundle LSP 工具。每个独立的限制都必须允许该工具。
• 只有受支持的基于 stdio 的 LSP 服务器可以运行；不受支持的传输方式仍会出现在 openclaw plugins inspect <id> 中。
• 取消某个回合或进行压缩（compaction）会取消待处理的 LSP 启动、阻止其他服务器启动，并清理该操作已获取的服务器。

会被检测到但不会执行¶

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

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

用于嵌入式 OpenClaw 的 MCP¶

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

传输方式¶

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

Stdio 启动一个子进程：

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

HTTP 连接到正在运行的 MCP 服务器，默认使用 sse，除非请求了 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"；省略时默认为 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 覆盖。会话启动时的工具列表（tools/list）在设置了 requestTimeoutMs 时使用该值，否则使用 10 秒。

工具命名¶

OpenClaw 以 serverName__toolName 的形式注册捆绑 MCP 工具，使用提供方安全的名称。例如，一个键为 "vigil-harbor" 的服务器若暴露了 memory_search 工具，则会注册为 vigil-harbor__memory_search。

• A-Za-z0-9_- 之外的字符会被替换为 -。
• 以非字母字符开头的片段会获得字母前缀，因此 12306 等数字服务器键会变成提供方安全的工具前缀。
• 服务器前缀上限为 30 个字符。
• 完整工具名称上限为 64 个字符。
• 空的服务器名称会回退为 mcp。
• 发生冲突的清理后名称会通过数字后缀来消除歧义。
• 最终暴露的工具顺序按安全名称确定，从而在重复的嵌入式代理轮次中保持缓存稳定。
• 配置文件过滤会将来自同一个捆绑 MCP 服务器的每个工具都视为归 bundle-mcp 插件所有，因此配置文件的允许/拒绝列表既可以引用单个暴露的工具名称，也可以引用 bundle-mcp 插件键。

捆绑包格式¶

检测优先级¶

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

1. openclaw.plugin.json 或包含 openclaw.extensions 的有效 package.json - 被视为原生插件
2. 客户端特定的捆绑包标记（.codex-plugin/、.cursor-plugin/、.claude-plugin/）- 被视为该格式的捆绑包
3. 根目录下的 plugin.json - 被视为Agent Plugins 捆绑包
4. 默认无清单的 Claude 布局（skills/、commands/、.mcp.json、...）- 被视为Claude 捆绑包

如果一个包同时带有客户端特定标记和根目录 plugin.json， 客户端特定格式优先，以便保留其更丰富的映射（命令、钩子、 设置）。如果一个目录同时包含原生清单和捆绑包标记，OpenClaw 会使用原生路径。这可防止双格式 包被部分安装为捆绑包。

运行时依赖与清理¶

• 第三方兼容捆绑包不会获得启动时的 npm install 修复。它们 应通过 openclaw plugins install 安装，并在已安装的插件目录中 携带所需的一切。
• OpenClaw 拥有的捆绑插件要么以轻量方式随核心发布， 要么可通过插件安装程序下载。网关启动时不会为它们运行 包管理器。
• openclaw doctor --fix 会移除过期的本地捆绑插件安装记录， 并且当配置仍引用可下载插件、但本地插件 索引中缺失时，可以恢复这些可下载插件。

安全¶

捆绑包比原生插件具有更窄的信任边界：

• OpenClaw 不会在进程内加载任意捆绑包运行时模块。
• Skills 和 hook-pack 路径必须保持在插件根目录内（经过边界检查）。
• 设置文件以相同的边界检查方式读取。
• 支持的 stdio MCP 服务器可以作为子进程启动。

这使捆绑包默认更安全，但你仍应将第三方 捆绑包视为其已暴露功能所对应的受信任内容。

故障排除¶

相关¶

• 安装和配置插件
• 构建插件 - 创建原生插件
• 插件清单 - 原生清单模式