Bundles

• 你想安装一个兼容 Codex、Claude 或 Cursor 的 bundle
• 你需要了解 OpenClaw 如何将 bundle 内容映射为原生功能
• 你正在排查 bundle 检测或缺失能力的问题 title: “插件 bundles”

​

为什么存在 bundles

​

安装 bundle

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

openclaw plugins list
openclaw plugins inspect <id>

openclaw gateway restart

​

OpenClaw 从 bundles 中映射了什么

​

目前支持

​

Skill content

• bundle skill roots 作为普通 OpenClaw skill roots 加载
• Claude commands roots 会被视为额外的 skill roots
• Cursor .cursor/commands roots 会被视为额外的 skill roots

​

Hook packs

• bundle hook roots 仅在使用标准 OpenClaw hook-pack 布局时有效。当前主要是 Codex 兼容场景：
  • HOOK.md
  • handler.ts 或 handler.js

​

嵌入式 OpenClaw 的 MCP

• 启用的 bundles 可以贡献 MCP 服务器配置
• OpenClaw 会将 bundle MCP 配置合并到生效的嵌入式 OpenClaw 设置中，键名为 mcpServers
• OpenClaw 会在嵌入式 OpenClaw agent 回合中，通过启动 stdio 服务器或连接 HTTP 服务器来暴露支持的 bundle MCP 工具
• coding 和 messaging 工具配置文件默认包含 bundle MCP 工具；对 agent 或 gateway 使用 tools.deny: ["bundle-mcp"] 可将其排除
• 项目本地的嵌入式 agent 设置仍会在 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"；如果省略，OpenClaw 使用 sse
• type: "http" 是 CLI 原生的下游形态；在 OpenClaw 配置中使用 transport: "streamable-http"。openclaw mcp set 和 openclaw doctor --fix 会规范化这个常见别名。
• 只允许 http: 和 https: URL scheme
• headers 的值支持 ${ENV_VAR} 插值
• 同时包含 command 和 url 的服务器条目会被拒绝
• URL 凭据（userinfo 和 query 参数）会在工具描述和日志中被脱敏
• connectionTimeoutMs 会覆盖 stdio 和 HTTP 传输的默认 30 秒连接超时

工具命名

• A-Za-z0-9_- 之外的字符会被替换为 -
• 以非字母开头的片段会被加上字母前缀，因此像 12306 这样的数字服务器键会变成提供方安全的工具前缀
• 服务器前缀最长为 30 个字符
• 完整工具名最长为 64 个字符
• 空服务器名会回退为 mcp
• 经过清理后发生冲突的名称会通过数字后缀进行区分
• 最终暴露的工具顺序会按安全名称确定性排序，以保持重复嵌入式 agent 回合中的缓存稳定
• 配置文件过滤会将同一个 bundle MCP 服务器中的所有工具视为由插件 bundle-mcp 拥有，因此配置文件的 allowlist 和 deny list 可以包含单个暴露的工具名，也可以包含 bundle-mcp 插件键

​

嵌入式 OpenClaw 设置

• 启用的 Claude bundles 可以贡献 LSP 服务器配置
• OpenClaw 会在应用之前清理 shell 覆盖键

• shellPath
• shellCommandPrefix

​

嵌入式 OpenClaw LSP

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

​

已检测但未执行

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

​

Bundle 格式

​

检测优先级

1. openclaw.plugin.json 或包含 openclaw.extensions 的有效 package.json —— 视为 native plugin
2. Bundle 标记（.codex-plugin/、.claude-plugin/，或默认 Claude/Cursor 布局）—— 视为 bundle

​

运行时依赖和清理

• 第三方兼容 bundles 不会在启动时通过 npm install 修复。它们应通过 openclaw plugins install 安装，并在已安装的插件目录中提供所需的一切。
• OpenClaw 自带的 bundled 插件要么以轻量形式随核心一起发布，要么可通过插件安装器下载。Gateway 启动时绝不会为它们运行包管理器。
• openclaw doctor --fix 会移除旧的暂存依赖目录，并且在配置引用缺失于本地插件索引中的可下载插件时，可以恢复这些插件。

​

安全

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

​

故障排查

​

相关内容

• Install and Configure Plugins
• Building Plugins — 创建原生插件
• Plugin Manifest — 原生 manifest schema