插件包
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. 验证检测
捆绑包会显示 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 覆盖键之前会先进行清理:
shellPathshellCommandPrefix
嵌入式 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 首先检查原生插件格式:
openclaw.plugin.json或包含openclaw.extensions的有效package.json- 被视为原生插件- 客户端特定捆绑包标记(
.codex-plugin/、.cursor-plugin/、.claude-plugin/)- 被视为该格式的捆绑包 - 根目录下的
plugin.json- 被视为 Agent Plugins 捆绑包 - 默认无清单 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