插件包

​

为什么需要 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>

openclaw plugins list
openclaw plugins inspect <id>

openclaw gateway restart

​

OpenClaw 从 bundle 映射的内容

​

当前支持

​

Skills 内容

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

​

Hook 包

​

嵌入式 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": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

{
  "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 覆盖。

工具命名

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

​

嵌入式 OpenClaw 设置

• shellPath
• shellCommandPrefix

​

嵌入式 OpenClaw LSP

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

​

已检测但未执行

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

​

bundle 格式

​

检测优先级

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

​

运行时依赖项和清理

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

​

安全性

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

​

故障排查

​

相关内容

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