插件 bundles

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

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

• 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

​

Pi 的 MCP

• 已启用的 bundles 可以贡献 MCP server 配置
• OpenClaw 会将 bundle 的 MCP 配置合并到有效的嵌入式 Pi 设置中，作为 mcpServers
• OpenClaw 会在嵌入式 Pi agent 回合期间，通过启动 stdio servers 或连接 HTTP servers，暴露受支持的 bundle MCP tools
• coding 和 messaging 工具配置文件默认包含 bundle MCP tools；如需对 agent 或 gateway 关闭它们，可使用 tools.deny: ["bundle-mcp"]
• 项目本地的 Pi 设置仍会在 bundle defaults 之后生效，因此在需要时， workspace 设置可以覆盖 bundle 的 MCP 条目
• 为了保持 prompt-cache tool blocks 稳定，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 schemes
• headers 的值支持 ${ENV_VAR} 插值
• 同时包含 command 和 url 的 server 条目会被拒绝
• URL 凭据（userinfo 和 query params）会在工具描述和日志中被脱敏
• connectionTimeoutMs 会覆盖 stdio 和 HTTP 传输的默认 30 秒连接超时

工具命名

• A-Za-z0-9_- 之外的字符会被替换为 -
• server 前缀最长为 30 个字符
• 完整工具名最长为 64 个字符
• 空的 server 名称会回退为 mcp
• 冲突的清理后名称会通过数字后缀进行区分
• 最终暴露的工具顺序会按安全名称确定性排序，以保持重复的 Pi 回合缓存稳定
• profile 过滤会将某个 bundle MCP server 的所有工具视为由 bundle-mcp 这个插件拥有，因此 profile 的 allowlist 和 deny list 可以包含单个暴露的 工具名，或 bundle-mcp 插件键

​

嵌入式 Pi 设置

• 当 bundle 启用时，Claude 的 settings.json 会作为默认的嵌入式 Pi 设置导入
• OpenClaw 在应用 shell override keys 前会先进行清理

• shellPath
• shellCommandPrefix

​

嵌入式 Pi LSP

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

​

已检测但不执行

• Claude agents、hooks.json automation、outputStyles
• Cursor .cursor/agents、.cursor/hooks.json、.cursor/rules
• Codex 内联 / 应用元数据，除能力报告之外的内容

​

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-pack 路径必须保留在插件根目录内（会进行边界检查）
• Settings 文件会使用相同的边界检查进行读取
• 支持的 stdio MCP servers 可能会作为子进程启动

​

故障排查

​

相关内容

• 安装并配置插件
• 构建插件 — 创建一个原生插件
• 插件清单 — 原生 manifest 规范