跳转至

插件包

OpenClaw 可以从四个外部生态安装插件:厂商中立的 Agent Plugins 标准,以及 Codex、Claude、Cursor。这些被称为 捆绑包(bundles)——即 OpenClaw 映射为原生技能(skills)、hooks、MCP 工具等功能的内容与元数据包。

Info

捆绑包并不等同于 OpenClaw 原生插件。原生插件在进程内运行,可以注册任何能力。捆绑包是内容包,具有选择性特性映射和更窄的信任边界。

为什么需要捆绑包

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

安装捆绑包

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>

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

3. 使用捆绑包

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

OpenClaw 会从捆绑包中映射什么

并非捆绑包的每个功能都能在 OpenClaw 中运行。下面是可运行的内容,以及已检测到但未接入的内容。

目前已支持

特性 映射方式 适用范围
技能内容 捆绑包技能根目录作为普通 OpenClaw 技能加载 所有格式
命令 commands/ 和 .cursor/commands/ 被视为技能根目录 Claude、Cursor
Agents 与输出样式 Claude agents/ 和 output-styles/ 被视为技能根目录 Claude
Hook 包 OpenClaw 风格的 HOOK.md + handler.ts 布局 Claude、Codex
MCP 工具 捆绑包的 MCP 配置合并到嵌入式 OpenClaw 设置中;加载受支持的 stdio 和 HTTP 服务器 所有格式
环境变量契约 PLUGIN_ROOT 和 PLUGIN_DATA 环境变量,以及针对 stdio MCP 服务器的占位符展开 Agent Plugins
LSP 服务器 Claude .lsp.json 和清单中声明的 lspServers 合并到嵌入式 OpenClaw LSP 默认值中 Claude
设置 Claude settings.json 作为嵌入式 OpenClaw 默认设置导入 Claude

技能内容

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

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

Hook 包

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

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

嵌入式 OpenClaw 设置

启用捆绑包时,Claude settings.json 会作为默认的嵌入式 OpenClaw 设置导入。OpenClaw 在应用以下 shell 覆盖键之前会先进行清理:

  • shellPath
  • shellCommandPrefix

嵌入式 OpenClaw LSP

  • 已启用的 Claude 捆绑包可以提供 LSP 服务器配置。
  • OpenClaw 会加载 .lsp.json 以及清单中声明的任何 lspServers 路径。
  • 捆绑包的 LSP 配置会合并到生效的嵌入式 OpenClaw LSP 默认值中。
  • 运行时工具允许列表可以通过 bundle-lsp、group:plugins 或匹配的 lsp_* 名称与 glob 来选择捆绑包 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

  • 已启用的捆绑包可以提供 MCP 服务器配置。
  • Stdio 命令默认将插件配置目录作为工作目录。远程 HTTP 服务器不会获得隐式工作目录。
  • OpenClaw 会将捆绑包的 MCP 配置以 mcpServers 的形式合并到生效的嵌入式 OpenClaw 设置中。
  • 在嵌入式 OpenClaw agent 回合期间,OpenClaw 会通过启动 stdio 服务器或连接 HTTP 服务器来暴露受支持的捆绑包 MCP 工具。
  • coding 和 messaging 工具配置默认包含捆绑包 MCP 工具;可使用 tools.deny: ["bundle-mcp"] 为某个 agent 或 Gateway 选择退出。
  • 项目本地的嵌入式 agent 设置仍会在捆绑包默认值之后应用,因此工作区设置可在需要时覆盖捆绑包 MCP 条目。
  • 捆绑包 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 凭据(userinfo 和查询参数)会从工具描述和日志中脱敏。
  • connectionTimeoutMs 会覆盖 stdio 和 HTTP 传输的默认 30 秒连接超时。请求超时默认为 60 秒,并可通过 requestTimeoutMs 覆盖。会话开始时的工具列表(tools/list)在设置了 requestTimeoutMs 时使用该值,否则使用 10 秒。

工具命名

OpenClaw 会以对提供方安全的名称注册捆绑包 MCP 工具,形式为 serverName__toolName。例如,键为 "vigil-harbor" 的服务器暴露一个 memory_search 工具时,会注册为 vigil-harbor__memory_search。

  • A-Za-z0-9_- 之外的字符会被替换为 -。
  • 以非字母开头的片段会添加字母前缀,因此诸如 12306 这样的数字服务器键会变成对提供方安全的工具前缀。
  • 服务器前缀最多 30 个字符。
  • 完整工具名称最多 64 个字符。
  • 空服务器名称会回退为 mcp。
  • 冲突的规范化名称会通过数字后缀进行区分。
  • 最终暴露的工具顺序按安全名称确定,从而保持重复的嵌入式代理轮次缓存稳定。
  • 配置文件过滤会将来自同一个捆绑包 MCP 服务器的每个工具视为由 bundle-mcp 插件拥有,因此配置文件允许/拒绝列表可以引用单个暴露的工具名称,也可以引用 bundle-mcp 插件键。

捆绑包格式

Agent Plugins 捆绑包

标记:包根目录中的 plugin.json,遵循开放的 Agent Plugins 1.0.0 标准

可选内容:skills/、mcp.json

格式行为:

  • 清单是严格 JSON(不是 JSON5)。OpenClaw 要求非空 name;其他清单字段可选,未知字段会被忽略
  • skills/ 的直接子目录如果包含 SKILL.md,会作为 技能加载;没有该文件的子目录会带警告跳过,更深层 目录不会被扫描
  • mcp.json 必须仅声明 1.0.0 的 $schema 和一个 mcpServers 对象 ;支持 stdio、streamable-http 和旧版 sse 传输
  • stdio 服务器启动时,其环境中会包含 PLUGIN_ROOT(插件根目录)和 PLUGIN_DATA(OpenClaw 在其状态目录下创建的每个插件的持久数据目录);${PLUGIN_ROOT} 和 ${PLUGIN_DATA} 占位符会在 args、env 值和 cwd 中一次性展开
  • stdio 的 command 必须是裸可执行文件名,或插件内的 ./ 相对路径 ;cwd 必须保持在 PLUGIN_ROOT 或 PLUGIN_DATA 内
  • 无效的 mcp.json 会禁用该插件的 MCP 并给出诊断信息,同时 技能继续加载;无效的单个服务器条目会被跳过
  • 对于此格式,不会读取 .mcp.json(点前缀)和清单内联的 mcpServers;标准的封闭模式优先
  • OpenClaw 会读取 extensions["ai.openclaw"];它仅支持 activation,语义与其他捆绑包清单相同
  • 其他清单扩展命名空间会被忽略,并保留给其客户端
  • 反向域名客户端目录会被忽略并保留
Codex 捆绑包

标记:.codex-plugin/plugin.json

可选内容:skills/、hooks/、.mcp.json、.app.json

当 Codex 捆绑包使用技能根目录和 OpenClaw 风格的 hook-pack 目录(HOOK.md + handler.ts)时,与 OpenClaw 最匹配。

Claude 捆绑包

两种检测模式:

  • 基于清单: .claude-plugin/plugin.json
  • 无清单: 默认 Claude 布局(skills/、commands/、agents/、hooks/、.mcp.json、.lsp.json、settings.json)

output-styles/ 不是检测标记。仅包含 output-styles/ 的 捆绑包不会被识别为 Claude 捆绑包。请添加 .claude-plugin/plugin.json 或上述任一标记,以便检测 成功。检测在清单加载之前运行,因此未检测到的 目录不会到达下面的组件路径。

Claude 特定行为:

  • commands/、agents/ 和 output-styles/ 被视为技能内容
  • settings.json 会导入到嵌入式 OpenClaw 设置中(shell 覆盖键会被规范化)
  • .mcp.json 会向嵌入式 OpenClaw 暴露受支持的 stdio 工具
  • .lsp.json 加上清单中声明的 lspServers 路径会加载到嵌入式 OpenClaw LSP 默认设置中
  • hooks/hooks.json 会被检测到但不会执行
  • 清单中的自定义组件路径是附加的;它们扩展默认值,而不是替换默认值
Cursor 捆绑包

标记:.cursor-plugin/plugin.json

可选内容:skills/、.cursor/commands/、.cursor/agents/、.cursor/rules/、.cursor/hooks.json、.mcp.json

  • .cursor/commands/ 被视为技能内容
  • .cursor/rules/、.cursor/agents/ 和 .cursor/hooks.json 仅用于检测

检测优先级

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 自有的捆绑插件要么以轻量方式随核心发布,要么可通过插件安装程序下载。Gateway 启动时不会为它们运行包管理器。
  • openclaw doctor --fix 会移除过期的本地捆绑插件安装记录,并可在配置仍引用但本地插件索引中缺失时恢复可下载的插件。

安全

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

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

这使得捆绑包默认更安全,但对于它们确实暴露的功能,仍应将第三方捆绑包视为受信任内容。

故障排查

检测到捆绑包但功能无法运行

运行 openclaw plugins inspect <id>。如果某个功能已列出但标记为未连接,这是产品限制,而不是安装损坏。

Claude 命令、代理或输出样式文件未出现

确保捆绑包已启用,并且 Markdown 文件位于已检测到的 skills/、commands/、agents/ 或 output-styles/ 根目录内。这四种文件都通过相同的 skill 加载器加载。

Claude 设置未生效

仅支持来自 settings.json 的嵌入式 OpenClaw 设置。OpenClaw 不会将捆绑包设置视为原始配置补丁。

Claude 钩子未执行

hooks/hooks.json 仅用于检测。如果你需要可运行的钩子,请使用 OpenClaw hook-pack 布局或提供一个原生插件。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw