卸载和更新插件
This page covers removing and updating installed plugins, and reloading edited plugin code without restarting the Gateway.
With a running Gateway, ordinary uninstall waits for the package runtime owners to stop before removing files, and update refreshes the Gateway after the local package operation finishes. Without a running Gateway, these commands save changes for its next startup. See 安装插件 for installation sources and Gateway-host path requirements.
If the Gateway rejects a lifecycle request because another operation is still running, the CLI honors its retry delay within the existing request timeout. Connection failures and failures after a mutation starts still stop the command.
卸载¶
openclaw plugins uninstall <ids...>
openclaw plugins uninstall <ids...> --dry-run
openclaw plugins uninstall <ids...> --keep-files
openclaw plugins uninstall <ids...> --force
uninstall 会从 plugins.entries、持久化的插件索引、插件允许/拒绝列表条目,以及任何恰好解析到已记录安装路径的 plugins.load.paths 条目中移除插件设置。对于每个被移除的插件 id,它只保留一个精确的 enabled: false 条目。此标记记录了显式卸载选择,因此剩余的模型、提供商或通道选择不会在启动修复期间自动重新安装该包。重新安装不会静默重新启用它;再次启用插件会替换该标记。对于具有多个子条目的包,任何子 id 都会解析到包所有者;卸载会移除每个同级的策略和插槽/通道引用、唯一的包安装记录,并只移除一次托管目录。链接路径安装还会移除其已记录源路径的精确条目。父目录、子路径、前缀匹配以及无关的加载路径会被保留。除非设置了 --keep-files,卸载还会移除受跟踪的托管安装目录,但仅当它解析到 OpenClaw 插件扩展根目录内部时。如果插件当前拥有 memory 或 contextEngine 插槽,则该插槽会重置为其默认值(memory 为 memory-core,context engine 为 legacy)。
插件条目和允许/拒绝清理使用不区分大小写的策略 ID。混合大小写的 manifest ID 会留下一个规范的小写禁用标记,而不是留下拼写不同且相互冲突的条目。包安装记录会保留其精确的所有者 ID。
匹配的加载路径引用会在包文件之前移除,以便符号链接别名不会留下无效配置。在 Gateway 运行时,运行时排空也会先于安装记录移除,包括使用 --keep-files 或链接安装时。如果运行时排空或文件移除失败,插件会保持禁用且受跟踪,以便你可以重试卸载。
如果在运行时排空期间再次添加了匹配的加载路径引用,卸载会保留文件,并要求你在重试前移除该引用。通过 OpenClaw 的配置写入会等待文件清理完成,包括对共享配置包含项的写入。清理会在每次删除前重新检查其权限,如果操作被撤销则停止。
uninstall 会打印将要移除内容的预览。多条目包在提示前会列出包所有者和每个受影响的子项。传入 --force 可跳过确认提示(适用于脚本和非交互式运行);如果不传入,卸载需要交互式 TTY。--dry-run 会打印相同的预览,并退出,不提示也不更改任何内容。
当提供多个 ID 时,卸载会先解析整个选择,然后再移除任何内容。重复的 ID 和同一包的子项只会选择该包一次。包会按首次请求顺序处理,每个包都有单独的预览和确认。取消或失败会停止剩余的移除;之前成功的移除会保持已提交。无效目标会在任何包被移除前拒绝该选择。
如果受跟踪的包没有已发现的插件条目,卸载可以移除其精确的安装记录和同所有者策略,包括没有其他已发现插件声明的、以所有者为键的通道配置。仅当没有其他安装记录共享其包路径,且没有已发现插件匹配其 id 或已记录路径时,才允许此恢复操作。无关策略保持不变。注册表刷新会重建发现元数据;它不会移除这些孤立安装记录。
具有缺失、模糊或冲突所有权的已发现包仍会失败关闭,且不更改包文件、配置或已安装索引。运行 openclaw plugins registry --refresh,检查 openclaw plugins doctor,并使用 openclaw doctor --fix 修复可修复的旧版索引状态。如果所有权仍然模糊,请在重试更新或卸载前重新安装该包。
Note
--keep-config 是 --keep-files 的已弃用别名。
更新¶
openclaw plugins update <ids-or-npm-specs...>
openclaw plugins update --all
openclaw plugins update <ids-or-npm-specs...> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update @acme/demo
openclaw plugins update openclaw-codex-app-server --acknowledge-install-policy-warning
更新适用于托管插件索引中的受跟踪插件安装,以及共享 SQLite 状态中的受跟踪 hook-pack 安装。它们会复用用户在安装插件时已选择的来源,因此不需要第二次来源确认。
提供多个 ID 或 npm 规范以更新一个选择,或在不提供 ID 时使用 --all。重复的目标和同级插件 ID 只会更新其包一次。显式 npm 规范会覆盖同一包仅基于 ID 的选择;针对一个包的两个不同显式规范会被拒绝。未知目标和冲突选择会在更新开始前失败,包括使用 --dry-run 时。现有的批量更新器会先处理插件包,然后处理 hook packs,当另一个包失败时保留成功的更新,并通过一次最终刷新将保存的更改应用到正在运行的 Gateway。
在激活替换之前,插件更新会通过常规带备份的配置写入器应用其 Doctor 配置修复。这会保留诸如先前配置的 webhook 端点等设置。重试一个已是最新版本的包也会完成待处理的仅配置修复。替换安装(plugins install --force)使用相同的修复所有者。如果必需的 Doctor 工件无法加载,或已记录的数据迁移仍需要维护,则命令会在激活前失败,并指明需要完成的修复。重试前请遵循报告的修复指引;数据迁移需要 openclaw doctor --fix。已禁用的插件会保留其待处理输入,而不会运行状态迁移;无关的待处理迁移仍会保留。
当配置回滚未得到确认时,恢复会保留已发布的包代次。该命令会报告失败,而不会声称运行时已激活。
如果更新最终化失败,错误会首先报告原始原因,并将任何回滚失败保留为额外的诊断上下文。失败的回滚仍可重试;已成功提交或已回滚的安装不会在清理过程中再次应用。
在源码安装中,与主机一起构建的被选插件会保持使用。命名更新、--all 以及 stable/beta 核心更新会报告注册表副本未被接受的原因,并保持其休眠安装记录不变。包所有权检查仍然适用于正在更新的插件;显式插件路径保留其选择优先级。
在 openclaw update 期间,具有显式加载路径的本地链接插件会保留其选择,即使 OpenClaw 捆绑了相同的插件 ID。更新会将保留的插件和路径作为警告报告;请在其源码处更新该插件。链接路径记录被排除在包更新所有权协调之外,因此过时的包元数据不会将链接保留变成更新失败。
update --all 会报告并跳过孤立的基于路径来源的安装记录,以便其余插件可以更新。当其文件不再需要时,使用 openclaw plugins uninstall <id> 删除孤立记录。
解析插件 id 与 npm 规范
当你传入插件 id 时,OpenClaw 会从其记录的安装来源开始。对于多条目包,子 id 会解析到其包所有者,并一起更新所有同级项。如果新的包版本删除或重命名了子项,OpenClaw 会删除已退役子项的条目、允许/拒绝策略、精确子项加载路径、通道配置以及内存/上下文槽位选择,同时保留保留的/新的子项和无关插件。存储的 dist-tags(例如 @beta)会保留其选定的发布线。
一个狭窄的例外是受信任的官方包完成目录声明的插件 id 替换。该更新从目录包选择器开始,以便重命名的清单可以替换旧 id。
经过验证的 OpenClaw 拥有的 npm 插件和官方 ClawHub 插件,在其记录的精确 OpenClaw 发布版本不新于核心,且其目录来源遵循默认发布线时,会恢复自动更新。更新会使用现有通道和兼容性规则,保留记录的注册表,并仅在成功安装或工件未变更验证之后保存默认选择器。对于 npm 安装,当现有版本和记录的工件标识已经匹配目标时,恢复可以在不下载或重新安装的情况下保存默认选择器。
在当前命令中提供的显式 npm 版本或标签仍然具有权威性。较新的发布固定版本、独立版本化的包、第三方包、本地、Git、市场以及自定义 ClawHub 来源会保留其现有选择器。在符合条件的官方 npm 包获得恢复期间,npm 注册表镜像会保持使用。如果保留的固定版本有较新的可用发布版本,OpenClaw 会打印一条显式替换命令。ClawHub 选择器替换使用 plugins install clawhub:<package> --force,因为 plugins update 仅对 npm 记录接受显式选择器覆盖。
较早的官方插件同步可能会在未经用户请求的情况下保存精确版本。这些记录不会区分自动固定版本和手动固定版本,因此符合条件的较早 OpenClaw 发布固定版本在两种情况下都会恢复自动更新。相同的恢复也适用于定向更新、--all、openclaw update 和 openclaw update repair。失败的替换会保留先前的安装记录以便重试。
对于 npm 安装,你还可以传入带有 dist-tag 或精确版本的显式 npm 包规范。OpenClaw 会将该包名称解析回被跟踪的插件记录,更新该已安装插件,并记录新的 npm 规范以供未来基于 id 的更新使用。
传入不带版本或标签的 npm 包名称也会解析回被跟踪的插件记录。当插件被固定到精确版本,而你希望将其移回注册表的默认发布线时,请使用此方式。
Beta 通道更新
定向 openclaw plugins update <id-or-npm-spec> 在存在已配置更新通道时使用该通道。否则,被识别的官方插件会继承 OpenClaw 的注册表通道。批量 openclaw plugins update --all 对官方插件使用相同的注册表通道解析器。即使下载的工件具有精确版本,移动选择器仍保持移动;恢复的 OpenClaw 发布固定版本遵循相同策略。
openclaw update 从新安装的核心解析插件目标。beta 通道上的 npm 更新会选择包 beta 和 latest 发布中较新的一个;ClawHub 默认线更新会尝试 @beta,并在该发布版本不可用时回退到记录的 default/latest 选择器。完整性、兼容性、信任、安装策略以及能力同意失败不会触发来源回退。不可用的插件更新会留下通知,而不会导致原本成功的核心更新失败。显式选择器保留其含义,并遵循上述受管理的 OpenClaw 发布固定版本恢复。
现有插件源选择
更新会保留记录的 npm 或 ClawHub 源。旧的安装记录无法区分自动 ClawHub 选择和显式 clawhub: 请求,因此 OpenClaw 不会静默地将这些记录切换为 npm。若要有意更改现有插件,请审查并运行 openclaw plugins install npm:<package> --force。对镜像拥有的捆绑插件的自动外部化会优先使用 npm,其次使用其声明的 ClawHub 源。
版本检查会报告来自该记录源的可用兼容更新。ClawHub 和 npm 可能在不同时间发布,因此报告的目标可能早于核心或最新 npm 包。更新核心不需要切换注册表。
版本检查与完整性漂移
在执行 npm 更新前,OpenClaw 会将已安装包版本与 npm 注册表元数据比对。如果已安装版本和记录的工件标识已经匹配解析后的目标,它会避免下载或重新安装。请求的选择器更改或受管 release-pin 恢复仍可以更新插件索引,而无需重写 openclaw.json。
当存在存储的完整性哈希,且获取的工件哈希发生变化时,OpenClaw 会将其视为 npm 工件漂移。交互式 openclaw plugins update 命令会打印预期和实际哈希,并在继续前请求确认。非交互式更新辅助工具默认失败关闭,除非调用方提供显式继续策略。
更新时的 --acknowledge-install-policy-warning
plugins update 使用与安装相同的警告确认,在交互式终端中为 type: '<plugin>' to update anyway。策略会被重新评估,block 或策略失败仍为终止性。
更新时的 ClawHub 安全审计
社区 ClawHub 支持的插件更新会在下载替换包之前运行与安装相同的精确发布信任检查。审查结果仅作信息性打印并继续;被阻止的发布仍不可安装。官方 ClawHub 包和捆绑的 OpenClaw 插件源会绕过此发布信任检查。
重载¶
openclaw plugins reload <ids...>
openclaw plugins reload <ids...> --json
openclaw plugins reload <ids...> --wait
在编辑其 TypeScript 源、导入的辅助函数或清单后,重载已发现的插件,包括通过 plugins.load.paths 选择的插件。该命令需要正在运行的 Gateway,并等待替换完成,而不会重启它。配置的启用状态会保留,未更改的插件会保留其运行时实例。JSON 输出包括 pluginIds、restartRequired,以及可用的已应用运行时回执(包括其代次和源摘要)。回执中的 selectedEntries 会列出加载器选择的文件。CLI 和工具输出会提醒你在编辑其源后重新构建编译输出;重载不会运行构建。多个 ID 会使用一个 Gateway 重载请求和一个已应用的运行时代次。重复的 ID 会被合并,Gateway 会一起解析包的同级项。该请求最多支持 64 个不同 ID。
繁忙的插件允许替换,并将新的保留工作限制在旧实例上。现有 agent 运行会保留其原始回调,而新运行会等待替换。在停止服务或通道之前,替换最多会等待 60 秒,让保留的工作和进行中的调用完成。详细就绪状态和 Gateway 日志会显示排队工作数量和截止时间;该命令会等待最终应用的回执。成功发布会发出 plugins.changed,并记录已应用的替换。如果工作超出预算,重载会失败一次,前一代次会恢复服务;未完成的运行不会被强制销毁。在该工作完成后重试 openclaw plugins reload <id>,或使用 openclaw plugins reload <id> --wait 无截止时间地等待已接受的工作。
--wait 会使新运行保持在同一替换门之后。按 Ctrl+C 可取消等待;断开其 Gateway 请求也会取消它。在发布之前,如果恢复成功,取消会恢复前一代次,而不会取消已接受的运行。一旦发布提交,取消不会撤销它。服务关闭、资源清理和恢复会保留其现有截止时间。详细就绪状态会暴露待处理的重载;显式等待没有排空截止时间。传入消息会保留其通道现有的队列和重放契约;此选项不会为缺少持久入口的通道添加持久入口。请在本身持有目标插件的回合之外运行此维护命令:等待该回合,而该回合又在等待重载,无法取得进展。
替换要求前一个注册的资源清理完成,然后其继任者才能获取这些资源。清理失败可能阻止替换和自动恢复;重试前请检查报告的失败。回执还可能包含清理警告。模块和本机库在其注册被移除后可能仍保持加载。
捆绑插件可以重载,同时保留其启用或禁用策略。即使源更新后仍残留休眠的注册表安装记录,重载也会遵循所选的捆绑副本;该记录保持不变。捆绑插件(包括 TypeScript 源条目)在其注册重载时,会复用其进程已加载的代码。如果插件文件已更改,但其原始模块仍保持加载,结果会报告 restartRequired: true 并带有警告,CLI 和工具输出会说明需要重启 Gateway 才能加载已编辑的代码。重载不会重新构建捆绑代码。当安装加载编译输出时,请在重启前重新构建。外部捕获源在替换后返回 restartRequired: false。重载未更改的捆绑文件也会返回 restartRequired: false;通道和服务注册可以在不重启 Gateway 的情况下替换。重载已发现的源不会创建安装记录,也不会授予安装、替换或删除其文件的权限。
Reload 也适用于外部管理的配置(OPENCLAW_CONFIG_READONLY=1)
以及 Nix 模式(OPENCLAW_NIX_MODE=1),包括使用 $include 组合的配置。
它会保留配置和安装状态。如果变更的能力需要新的同意,请在重新加载前通过部署负责人记录该同意。
已声明能力的变更可能需要再次审查。交互式文本输出
会提示请求同意;--json 从不提示。仅在审查变更之后使用 --accept-capabilities,
包括将其与 --json 组合使用时。如果准备
失败,错误会报告是否已发布替换。发布后
失败可能导致新代保持活动状态;重试前请检查报告的状态。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw