插件¶

插件通过频道、模型提供商、代理框架、工具、技能、语音、实时转录、声音、媒体理解、生成、网页抓取、网页搜索以及其他运行时能力来扩展 OpenClaw。

使用本页安装插件、应用其配置、验证运行时已加载该插件，并排查常见设置故障。仅包含命令的示例请参阅 管理插件。有关内置、官方外部和仅源码插件的生成清单，请参阅 插件清单。

要求¶

• 具有可用 openclaw CLI 的 OpenClaw 检出或安装
• 能够访问所选源（ClawHub、npm 或 git 托管服务）的网络
• 该插件设置文档中提及的任何插件特定凭据、配置键或操作系统工具
• 对所服务频道的 Gateway 具有管理员访问权限

快速开始¶

1. 查找插件

在 ClawHub 中搜索公共插件包：

openclaw plugins search "calendar"

ClawHub 是社区插件的主要发现平台。普通的裸包规范（bare package specs）默认从 npm 安装，除非它们匹配内置或官方插件 ID。匹配内置插件的原始 @openclaw/* 规范会解析为对应的内置副本。当你需要特定来源时，请使用显式源前缀。

2. 安装插件

# From ClawHub.
openclaw plugins install clawhub:<package>

# From npm.
openclaw plugins install npm:<package>

# From git.
openclaw plugins install git:github.com/<owner>/<repo>@<ref>

# From a local development checkout.
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

请像运行代码一样对待插件安装。对于可重现的生产安装，建议使用固定版本。ClawHub 包和 OpenClaw 的内置/官方目录是受信任的来源。在审查并信任来源后，新的任意 npm、git、本地路径/归档、npm-pack: 或市场来源在非交互式安装中需要 --force。

3. 配置并启用插件

在 plugins.entries.<id>.config 下配置插件特定设置。如果插件尚未启用，请启用它：

openclaw plugins enable <plugin-id>

如果设置了 plugins.allow，则安装的插件 ID 必须在该列表中，插件才能加载。openclaw plugins install 会将安装的 ID 添加到现有的 plugins.allow 列表中，并从 plugins.deny 中移除同一 ID，以便显式安装的插件能够加载。

4. 应用更改

插件管理命令会在不重启的情况下将更改应用到正在运行的本地 Gateway。如果 Gateway 已停止，请启动它以加载已保存的更改。请参阅 应用更改并检查。

在默认的混合重载模式下，常规的插件配置编辑也会自动生效。默认情况下，Gateway 会替换受影响的插件实例；但插件的显式重启策略仍可能要求重启 Gateway。接下来检查注册情况，然后通过实际的钩子事件或工具调用来验证正在运行的 Gateway。

5. 验证运行时注册

openclaw plugins inspect <plugin-id> --runtime --json

--runtime 会在用于检查的 CLI 进程中加载插件，并报告已注册的工具、钩子、服务、Gateway 方法以及插件自有的 CLI 命令。普通的 inspect 仅执行冷清单和注册表检查。两者都不能证明已在运行的 Gateway 已经加载了相同的代码。触发钩子或能力并验证其实际效果。

配置¶

选择安装源¶

裸包规范具有特殊的兼容性行为：与内置插件 ID 匹配的裸名称使用该内置源；与官方外部插件 ID 匹配的裸名称使用官方包目录；任何其他裸规范都通过 npm 安装。与内置插件匹配的原始 @openclaw/* 规范也会在 npm 回退之前解析为内置副本。使用 npm:@openclaw/<plugin>@<version> 可有意安装外部 npm 包而不是内置副本。使用 clawhub:、npm:、git: 或 npm-pack: 进行确定性源选择。有关完整命令契约，请参阅 openclaw plugins。

对于 npm 安装，未固定版本的规范（unpinned specs）和 @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 钩子的阻止。

参见 Skills 配置 了解技能和插件共用的 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）为独占类别选择一个插件。槽位选择视为显式激活，并强制启用该槽位选中的插件，即使它原本是需要选择启用的。plugins.deny 和 plugins.entries.<id>.enabled: false 仍会阻止它。
• 捆绑的选择启用插件可以在配置引用其拥有的某个表面时自动激活，例如 provider/model 引用、通道配置、CLI 后端或 agent harness 运行时。
• OpenAI 系 Codex 路由保持 provider 和 runtime 插件边界分离：旧版 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 方式加载时，同样的信任固定规则适用：检查该插件 ID，然后将其固定在 plugins.allow 中，或从受信任来源重新安装，以便 OpenClaw 记录安装来源。

当配置验证报告过期插件 ID、允许列表/工具不匹配或旧版捆绑插件路径时，请运行 openclaw doctor 或 openclaw doctor --fix。如果移除过期 ID 会使一个限制性的 plugins.allow 列表变空，Doctor 会保留已启用的通道和已选择的插件作为显式允许 ID。只有当没有任何剩余项时，它才会禁用插件。在更改通道或插件槽位时，请检查保留的列表。旧版 ID 冲突需要显式的策略选择；参见 配置迁移。

了解插件格式¶

OpenClaw 识别两种插件格式：

两种格式都会出现在 openclaw plugins list、openclaw plugins inspect、openclaw plugins enable 和 openclaw plugins disable 中。有关捆绑包兼容性边界，请参见 插件捆绑包；有关原生插件编写，请参见 构建插件。

插件钩子¶

插件可以在运行时通过两种不同的 API 注册钩子：

• api.on(...) 类型化钩子用于运行时生命周期事件。这是中间件、策略、消息重写、prompt 塑造和工具控制的推荐接口。
• 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 中。清单提示不会绕过全局禁用、deny 或单个插件启用策略。

显式的钩子策略也是启动意图。例如，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 中选择的插件。在源码或清单编辑后，或修复失败的激活后使用它。成功的安装、更新、启用、禁用和卸载命令已经应用了它们的更改；它们不需要额外重载。有关编译后的捆绑代码和清理限制，请参阅 重载。

故障排除¶

当已启用的受管插件在 Gateway 启动期间载荷验证失败时，OpenClaw 会隔离该确切已安装插件根目录用于本次启动，并继续提供其他插件。openclaw status --all、openclaw health 和 openclaw doctor 会将其报告为 configured-unavailable。修复或重新安装该插件，然后重启 Gateway。具有相同插件 id 的健康显式 plugins.load.paths 覆盖不会因过期损坏的安装而被隔离。

当过期插件配置仍引用一个不再可发现的频道插件时，配置验证会将该频道键降级为警告，而不是硬性失败，因此 Gateway 启动仍可提供所有其他频道。运行 openclaw doctor --fix 以移除过期的插件和频道条目。没有过期插件证据的未知频道键仍会验证失败，以便拼写错误保持可见。

对于有意的频道替换，首选插件应使用旧版或较低优先级插件 id 声明 channelConfigs.<channel-id>.preferOver。如果两个插件都被显式启用，OpenClaw 会保留该请求，并报告重复的频道/工具诊断，而不是静默选择一个所有者。

如果已安装包报告其 requires compiled runtime output for TypeScript entry ...，则该包发布时缺少 OpenClaw 运行时所需的 JavaScript 文件。在发布者发布编译后的 JavaScript 后更新或重新安装，或在此之前禁用/卸载该插件。

受信任插件状态被拒绝¶

如果插件因 openKeyedStore is only available for trusted plugins 失败，请比较错误中的 registryPath 与以下来源中的 plugin.trust.registryPath：

openclaw plugins inspect <plugin-id> --runtime --json
openclaw doctor

检查和 Gateway 会报告插件加载期间记录的信任决策，包括 reason、origin、installSource 和 installSpec。可执行文件版本和配置文件匹配并不能建立匹配的注册表数据库。检查会加载到 CLI 进程中，因此请比较两个路径。当本地 Gateway 不可达时，Doctor 还会检查已安装的服务环境；如果无法验证该环境，它会说明这一点。

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 拥有：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

如果你有意以 root 身份运行 OpenClaw，则改为将受管理的插件根目录修复为 root 所有权：

sudo chown -R root:root /path/to/openclaw-config/npm

修复所有权后，重新运行 openclaw doctor --fix 或 openclaw plugins registry --refresh，使持久化的插件注册表 与修复后的文件匹配。

插件工具设置缓慢¶

如果代理轮次在准备工具时似乎停滞，请启用跟踪日志并检查插件工具工厂计时行：

openclaw config set logging.level trace
openclaw logs --follow

查找：

[trace:plugin-tools] factory timings ...

摘要列出工厂总时间和最慢的插件工具工厂，包括插件 id、声明的工具名称、结果形状以及工具是否可选。当单个工厂耗时至少 1 秒或插件工具工厂总准备时间至少 5 秒时，慢速行会被提升为警告。

OpenClaw 会为具有相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包括有效运行时配置、工作区和代理 id、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些受信任字段的工厂会在上下文变化时重新运行。如果计时仍然很高，插件可能在返回其工具定义之前执行了昂贵的工作。

如果某个插件主导了计时，请检查其运行时注册：

openclaw plugins inspect <plugin-id> --runtime --json

然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂内部执行。

有关依赖根、包元数据验证、注册表记录、启动重新加载行为和旧版清理，请参阅 插件依赖解析。

相关¶

• 管理插件 - list、install、update、uninstall 和 publish 的命令示例
• openclaw plugins - 完整 CLI 参考
• 插件清单 - 生成的捆绑和外部插件列表
• 插件参考 - 生成的每个插件参考页面
• 社区插件 - ClawHub 发现和文档 PR 政策
• 插件依赖解析 - 安装根、注册表记录和运行时边界
• 构建插件 - 原生插件编写指南
• 插件 SDK 概览 - 运行时注册、钩子和 API 字段
• 插件清单 - 清单和包元数据
• 上下文引擎 - 可插拔上下文组装插件
• 差异 - 只读差异查看器和文件渲染器（可选插件工具）
• ACP 代理 — 设置 - 配置插件提供的 ACP 代理