快速入门
插件为 OpenClaw 扩展了渠道、模型提供商、代理框架、工具、技能、语音、实时转录、声音、媒体理解、生成、Web 抓取、Web 搜索以及其他运行时能力。
使用此页面安装插件、应用其配置、验证运行时已加载该插件,并排查常见的安装失败问题。仅限命令的示例请参阅管理插件。有关内置、官方外部和仅源码插件的生成清单,请参阅插件清单。
前提条件¶
- 具有可用
openclawCLI 的 OpenClaw 检出(checkout)或安装 - 对所选来源(ClawHub、npm 或 git 托管平台)具有网络访问权限
- 该插件设置文档中提到的任何插件专用凭据、配置键或操作系统工具
- 对为你的渠道提供服务的 Gateway 具有管理员访问权限
快速开始¶
1. 查找插件
在 ClawHub 上搜索公共插件包:
ClawHub 是社区插件的主要发现平台。普通的裸包规范(bare package specs)默认从 npm 安装,除非它们匹配内置或官方插件 ID。匹配内置插件的原始 @openclaw/* 规范会解析为该内置副本。当你需要明确指定某个来源时,请使用显式的源前缀。
2. 安装插件
# 从 ClawHub 安装。
openclaw plugins install clawhub:<package>
# 从 npm 安装。
openclaw plugins install npm:<package>
# 从 git 安装。
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
# 从本地开发检出安装。
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
请像运行代码一样对待插件安装。对于可复现的生产环境安装,建议使用固定版本(pinned versions)。ClawHub 包以及 OpenClaw 的内置/官方目录是可信来源。对于非交互式安装中的新任意 npm、git、本地路径/归档、npm-pack: 或市场来源,需要在你审查并信任该来源后使用 --force。
3. 配置并启用插件
在 plugins.entries.<id>.config 下配置插件专用设置。如果插件尚未启用,请启用它:
如果设置了 plugins.allow,则已安装的插件 ID 必须位于该列表中,插件才能加载。openclaw plugins install 会将已安装的 ID 添加到现有的 plugins.allow 列表,并从 plugins.deny 中移除相同的 ID,以便显式安装的插件能够加载。
4. 应用更改
插件管理命令会将更改应用到正在运行的本地 Gateway,而无需重启它。如果 Gateway 已停止,请启动它以加载保存的更改。请参阅应用更改并检查。
在默认的混合重载模式下,普通的插件配置编辑也会自动应用。默认情况下,Gateway 会替换受影响的插件实例;但插件的显式重启策略仍可能要求重启 Gateway。接下来检查注册信息,然后通过实际的钩子事件或工具调用来验证正在运行的 Gateway。
5. 验证运行时注册
--runtime 会在检查用的 CLI 进程中加载插件,并报告已注册的工具、钩子、服务、Gateway 方法和插件自有的 CLI 命令。普通的 inspect 只做冷清单和注册表检查。两者都不能证明已在运行的 Gateway 加载了相同的代码。请触发钩子或能力并验证其实际效果。
配置¶
选择安装源¶
| 来源 | 适用场景 | 示例 |
|---|---|---|
| ClawHub | 你需要 OpenClaw 原生的发现、扫描、版本元数据和安装提示 | openclaw plugins install clawhub:<package> |
| npm | 你需要直接的 npm 注册表或 dist-tag 工作流 | openclaw plugins install npm:<package> |
| git | 你需要从仓库获取分支、标签或提交 | openclaw plugins install git:github.com/<owner>/<repo>@<ref> |
| local path | 你正在同一台机器上开发或测试插件 | openclaw plugins install --link ./my-plugin |
| marketplace | 你正在安装与 Claude 兼容的市场插件 | openclaw plugins install <plugin> --marketplace <source> |
裸包规范具有特殊的兼容性行为:与内置插件 ID 匹配的裸名称使用该内置来源;与官方外部插件 ID 匹配的裸名称使用官方包目录;任何其他裸规范均通过 npm 安装。匹配内置插件的原始 @openclaw/* 规范也会在 npm 回退之前解析为内置副本。使用 npm:@openclaw/<plugin>@<version> 可明确安装外部 npm 包,而不是内置副本。使用 clawhub:、npm:、git: 或 npm-pack: 进行确定性的来源选择。完整的命令约定请参阅 openclaw plugins。
对于 npm 安装,未固定版本的规范和 @latest 会选择声明与此 OpenClaw 构建版本兼容的最新稳定包。如果 npm 当前的最新版本声明了比此构建版本所支持的更新的 openclaw.compat.pluginApi 或 openclaw.install.minHostVersion,OpenClaw 会扫描较旧的稳定版本并安装最适合的一个。精确版本和显式渠道标签(如 @beta)会保持固定为所选包,不兼容时将安装失败。
操作员安装策略¶
将 security.installPolicy 配置为在插件安装或更新进行之前运行一个可信的本地策略命令。该策略会接收元数据以及暂存的源路径,并可以允许、警告或阻止安装。它涵盖 CLI 和 Gateway 支持的安装/更新路径。CLI 插件和技能命令可以通过输入目标名称来交互式确认警告,该名称与可疑 ClawHub 发布中出现的名称相同;随后策略会被重新评估。经过审查的非交互式直接 CLI 命令可以使用 --acknowledge-install-policy-warning。该标志批准该命令调用期间遇到的所有警告;在安装继续之前,每条警告仍会被重新评估。Control UI 会显示结构化警告,并提供仍然安装选项。该操作会以 acknowledgeInstallPolicyWarning: true 重新发送相同的插件请求,从而批准该安装调用期间遇到的所有警告;在安装继续之前,每条警告仍会被重新评估。其他 Gateway 支持和自动安装在没有操作员确认流程的情况下仍会被阻止。当存在等效的直接插件或技能命令时,请使用该命令来审查并批准警告。否则,将 security.installPolicy 改为对已审查的请求返回 allow,然后重试托管流程。--force 和已弃用的插件安装/更新标志 --dangerously-force-unsafe-install 都不会批准策略警告。插件的 before_install 钩子会在之后运行,并且仅在加载了插件钩子的 OpenClaw 进程中运行,因此请改用 security.installPolicy 来做操作员自主的安装决策。该标志不会覆盖阻止或策略失败。它也不会绕过 before_install 钩子的阻止。
参见技能配置,了解技能和插件共用的 security.installPolicy exec 模式。
配置插件策略¶
常见的插件配置结构如下:
{
plugins: {
enabled: true,
allow: ["voice-call"],
deny: ["untrusted-plugin"],
load: { paths: ["~/path/to/oss/voice-call-plugin"] },
slots: { memory: "memory-core" },
entries: {
"voice-call": { enabled: true, config: { provider: "twilio" } },
},
},
}
关键策略规则:
plugins.enabled: false会禁用所有插件,并跳过发现/加载工作。在此配置生效期间,过时的插件引用会保持惰性;如果希望移除过时的 ID,请先重新启用插件,再运行 doctor 清理。plugins.deny优先于 allow 以及按插件的启用设置。plugins.allow是一个排他性的允许列表。不在该列表中的插件所属工具,即使tools.allow包含"*",也仍然不可用。plugins.entries.<id>.enabled: false会禁用某个插件,同时保留其配置。plugins.load.paths用于添加明确的本地插件文件或目录。由plugins install管理的本地路径必须是插件目录或归档文件;独立的插件文件请使用plugins.load.paths。- 来自工作区的插件默认处于禁用状态;在使用本地工作区代码之前,请显式启用或将其加入允许列表。
- 内置插件遵循自带的默认启用/默认禁用元数据,除非配置显式覆盖。
plugins.slots.<slot>(memory或contextEngine)为某个独占类别选择一个插件。槽位选择视为显式激活,即使该插件原本是选择加入(opt-in)的,也会为该槽位强制启用它。不过plugins.deny和plugins.entries.<id>.enabled: false仍然会阻止它。- 当配置指定了内置可选插件拥有的某个表面(surface)时,例如 provider/model 引用、频道配置、CLI 后端或 agent harness 运行时,该插件可以自动激活。
- OpenAI 系 Codex 路由会保持 provider 与运行时插件的边界分离:旧版 Codex model 引用属于 doctor 可修复的旧配置;而内置的
codex插件拥有 Codex app-server 运行时,服务于规范的openai/*agent 引用、显式的agentRuntime.id: "codex"以及旧版codex/*引用。
当 plugins.allow 未设置,且从工作区或全局插件根目录自动发现非内置插件时,启动日志会输出 plugins.allow is empty; discovered non-bundled plugins may auto-load: ...,其中包含发现的插件 ID;对于较短的列表,还会给出一个最小的 plugins.allow 配置片段。在将受信任的插件复制到 openclaw.json 之前,请先对列出的插件 ID 运行 openclaw plugins list --enabled --verbose 或 openclaw plugins inspect <id>。当诊断信息显示某个插件加载时 without install/load-path provenance(没有安装/加载路径来源),同样适用这种信任固定(trust-pinning)做法:请检查该插件 ID,然后将其固定到 plugins.allow 中,或从受信任的来源重新安装,以便 OpenClaw 记录安装来源。
当配置校验报告出现过时插件 ID、允许列表/工具不匹配或旧版内置插件路径时,请运行 openclaw doctor 或 openclaw doctor --fix。如果移除过时 ID 导致严格的 plugins.allow 列表变为空,Doctor 会保留已启用的频道和已选择的插件,并将它们作为显式允许的 ID。只有在没有任何插件留存时,它才会禁用插件。在更改频道或插件槽位时,请复查保留的列表。旧版 ID 冲突需要显式的策略选择;请参阅配置迁移。
了解插件格式¶
OpenClaw 识别两种插件格式:
| 格式 | 加载方式 | 适用场景 |
|---|---|---|
| OpenClaw 原生插件 | openclaw.plugin.json 加上一个在进程内加载的运行时模块 |
当你正在安装或构建 OpenClaw 特定的运行时能力时 |
| 兼容包 | 将 Agent Plugins、Codex、Claude 或 Cursor 的插件布局映射到 OpenClaw 插件清单中 | 当你正在复用兼容的技能、命令、钩子或包元数据时 |
两种格式都会出现在 openclaw plugins list、openclaw plugins inspect、openclaw plugins enable 和 openclaw plugins disable 中。关于包的兼容性边界,请参阅插件包;关于原生插件的编写,请参阅构建插件。
插件钩子¶
插件可以通过两种不同的 API 在运行时注册钩子:
api.on(...)用于运行时生命周期事件的类型化钩子。这是中间件、策略、消息重写、提示词塑形和工具控制的首选接口。api.registerHook(...)用于钩子中描述的内部钩子系统。它主要用于粗粒度的命令/生命周期副作用,以及与现有 HOOK 风格自动化的兼容。
快速判断规则:如果处理器需要优先级、合并语义或阻止/取消行为,请使用类型化钩子。如果它只是响应 command:new、command:reset、message:sent 或类似的粗粒度事件,使用 api.registerHook 即可。
由插件管理的内部钩子会以 plugin:<id> 的形式出现在 openclaw hooks list 中。你不能通过 openclaw hooks 启用或禁用它们;请改为启用或禁用对应的插件。
钩子注册还取决于 Gateway 启动时的选择。对于仅使用钩子的插件,请在 openclaw.plugin.json 中声明 activation.onCapabilities: ["hook"],然后启用该插件,并在配置了允许列表时将其包含在 plugins.allow 中。清单中的提示不会绕过全局禁用、拒绝或按插件的启用策略。
显式的钩子策略也代表启动意图。例如,plugins.entries.<id>.hooks.allowConversationAccess: true 既授权非内置的对话钩子,也会将该配置的插件选入 Gateway 启动流程;正常的插件策略仍然适用。更改插件清单或源码后,请运行 openclaw plugins reload <id>。在默认的混合重载模式下,钩子策略更改会热重载插件运行时。使用 openclaw plugins inspect <id> --runtime --json 检查注册情况,然后触发一个事件来验证正在运行的进程。完整示例请参阅插件钩子。
验证活动 Gateway¶
openclaw plugins list 和普通的 openclaw plugins inspect 读取冷配置、清单和注册表状态。它们不能证明已在运行的 Gateway 已导入相同的插件代码。
当插件看似已安装,但实时聊天流量未使用它时:
openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw plugins reload <plugin-id>
插件重载会刷新运行中 Gateway 里选定的插件。在源码或清单编辑后,或修复失败的激活后使用它。成功的安装、更新、启用、禁用和卸载命令已经应用其更改;它们不需要额外重载。有关编译后的内置代码和清理限制,请参阅 重载。
故障排查¶
| 症状 | 检查 | 修复 |
|---|---|---|
插件出现在 plugins list 中,但运行时钩子未运行 |
使用 openclaw plugins inspect <id> --runtime --json,并通过 gateway status --deep --require-rpc 确认活动 Gateway |
检查激活错误;在源码编辑或修复后重载。对于配置更改,检查重载模式和插件重启前缀 |
| 出现重复通道或工具所有权诊断 | 运行 openclaw plugins list --enabled --verbose,使用 --runtime --json 检查每个疑似插件,并比较通道/工具所有权 |
禁用其中一个所有者,移除过期安装,或使用清单中的 preferOver 进行有意替换 |
| 配置显示某个插件缺失 | 检查 插件清单,确认它是内置、官方外部还是仅源码 | 安装外部包,启用内置插件,或移除过期配置 |
| 安装期间配置无效 | 阅读验证消息;如果它指向过期插件状态,则运行 openclaw doctor --fix |
Doctor 可以通过禁用该条目并移除无效负载来隔离无效插件配置 |
| 插件路径因可疑所有权或权限被阻止 | 检查配置错误之前的诊断信息 | 修复文件系统所有权/权限,然后运行 openclaw plugins registry --refresh |
OPENCLAW_NIX_MODE=1 阻止生命周期命令 |
确认安装由 Nix 管理 | 在 Nix 源中更改插件选择,而不是使用插件变更命令 |
| 运行时依赖导入失败 | 检查插件是否通过 npm/git/ClawHub 安装,或从本地路径加载 | 运行 openclaw plugins update <id>,重新安装源码,或自行安装本地插件依赖 |
当已启用的受管插件在 Gateway 启动期间负载验证失败时,OpenClaw 会隔离该确切已安装插件根目录,仅针对本次启动,并继续提供其他插件服务。openclaw status --all、openclaw health 和 openclaw doctor 会将其报告为 configured-unavailable。修复或重新安装该插件,然后重启 Gateway。具有相同插件 id 的健康显式 plugins.load.paths 覆盖不会被过期的损坏安装隔离。
当过期插件配置仍然引用一个不再可发现的通道插件时,配置验证会将该通道键降级为警告,而不是硬性失败,因此 Gateway 启动仍可提供所有其他通道服务。运行 openclaw doctor --fix 以移除过期插件和通道条目。没有过期插件证据的未知通道键仍会验证失败,以便拼写错误保持可见。
对于有意的通道替换,首选插件应声明 channelConfigs.<channel-id>.preferOver,并指定旧版或较低优先级的插件 id。如果两个插件都被显式启用,OpenClaw 会保留该请求,并报告重复通道/工具诊断,而不是静默选择一个所有者。
如果已安装包报告其 requires compiled runtime output for TypeScript entry ...,则该包发布时缺少 OpenClaw 运行时所需的 JavaScript 文件。在发布者发布编译后的 JavaScript 后更新或重新安装,或在此之前禁用/卸载该插件。
插件运行时信任被拒绝¶
每个已加载插件都可以使用自己的键控和 blob 状态以及通道入口队列,包括本地路径和链接安装。钩子代理轮次和 Gateway 范围提升仍然需要信任。
来源警告和 plugins inspect 仍会报告未验证来源;它们不会阻止插件范围存储或队列。
如果插件因 dispatchHookAgentTurn is only available for trusted plugins 而失败,请比较错误中的 registryPath 与以下来源中的 plugin.trust.registryPath:
检查 和 Gateway 会报告插件加载期间记录的信任决策,包括 reason、origin、installSource 和 installSpec。
可执行文件版本和配置文件匹配,并不能证明注册表数据库匹配。检查会加载到 CLI 进程中,因此请比较这两个路径。
当本地 Gateway 无法访问时,Doctor 还会检查已安装的服务环境;如果无法验证该环境,它会明确说明。
如果插件需要受信任限制的能力,请使用下面适用的补救措施。
--link 和 --force 不会为这些能力授予信任。
| 原因 | 补救措施 |
|---|---|
record-missing |
如果 CLI 和 Gateway 的状态路径不同,请对齐它们;否则通过 openclaw plugins install 重新安装,以便记录安装。 |
provenance-missing |
使用 Gateway 的状态/配置路径运行 openclaw doctor --fix。Doctor 会修复目录中可验证的旧版 ClawHub 记录;无法验证的记录需要从官方 npm 包或 ClawHub 列表重新安装。 |
origin-path |
将本地路径/归档安装替换为官方 npm 包或 ClawHub 列表。 |
install-path-mismatch |
重新安装目标包,并移除会选中另一份副本的加载路径。 |
owner-ambiguous |
刷新注册表,并在重新安装前解决冲突的包所有权。 |
provenance-invalid |
从官方来源重新安装;冲突或不完整的来源信息不会被自动信任。 |
bundled 和 trusted-official 标识可接受的来源。具有一致官方包规范的旧版 npm 记录在没有额外解析字段的情况下仍然有效。Doctor 会修复现有安装台账中的来源信息;运行时不会回退到信任包作者提供的元数据。
被阻止的插件路径所有权¶
如果诊断显示
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
并且验证随后显示 plugin present but blocked,则 OpenClaw 发现
插件文件由与加载它们的进程不同的 Unix 用户拥有。
请保留插件配置;修复文件系统所有权,或以拥有状态目录的同一用户身份运行 OpenClaw。
对于 Docker 安装,官方镜像以 node(uid 1000)运行,因此
主机上绑定挂载的 OpenClaw 配置和工作区目录通常应由 uid 1000 拥有:
如果你有意以 root 身份运行 OpenClaw,则改为将受管理的插件根目录修复为 root 所有权:
修复所有权后,重新运行 openclaw doctor --fix 或
openclaw plugins registry --refresh,使持久化的插件注册表
与修复后的文件匹配。
插件工具设置缓慢¶
如果代理回合在准备工具时似乎停滞,请启用 trace 日志记录 并检查插件工具工厂计时行:
查找:
摘要会列出工厂总耗时和最慢的插件工具工厂, 包括插件 id、声明的工具名称、结果形状,以及工具是否为可选。 当单个工厂耗时至少 1s,或插件工具工厂准备总耗时至少 5s 时,慢速行会被提升为警告。
OpenClaw 会为具有相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包括 有效运行时配置、工作区和代理 id、沙箱策略、浏览器设置、交付上下文、请求者身份以及所有权状态,因此 依赖这些受信任字段的工厂会在上下文变化时重新运行。如果计时仍然很高,插件可能在返回其工具定义之前执行了昂贵的工作。
如果某个插件主导了计时,请检查其运行时注册:
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后,而不是在工具工厂内部执行。
有关依赖根、包元数据验证、注册表记录、启动重载行为和旧版清理,请参阅 插件依赖解析。
相关¶
- 管理插件 - list、install、update、uninstall 和 publish 的命令示例
openclaw plugins- 完整 CLI 参考- 插件清单 - 生成的捆绑和外部插件列表
- 插件参考 - 生成的每个插件参考页面
- 社区插件 - ClawHub 发现和文档 PR 策略
- 插件依赖解析 - 安装根、注册表记录和运行时边界
- 构建插件 - 原生插件编写指南
- 插件 SDK 概览 - 运行时注册、钩子和 API 字段
- 插件清单 - 清单和包元数据
- 上下文引擎 - 可插拔上下文组装插件
- 差异 - 只读差异查看器和文件渲染器(可选插件工具)
- ACP 代理 — 设置 - 配置插件提供的 ACP 代理
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw