卸载和更新插件
本页介绍如何移除和更新已安装的插件，以及如何在不重启 Gateway 的情况下重新加载编辑过的插件代码。
在 Gateway 运行时，普通卸载会等待包运行时所有者停止后再删除文件；而更新会在本地包操作完成后刷新 Gateway。在 Gateway 未运行时，这些命令会将更改保存下来，供其下次启动时生效。有关安装来源和 Gateway 宿主路径要求，请参阅安装插件。
如果 Gateway 因仍有其他操作正在运行而拒绝生命周期请求，CLI 会在现有请求超时内遵循其重试延迟。连接失败以及变更开始后发生的失败仍会中止命令。
卸载¶
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，上下文引擎对应 legacy）。
匹配的加载路径引用会在包文件之前被移除，因此符号链接别名不会留下无效配置。在 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 spec 以更新所选内容，或不带 ID 地使用 --all。重复的目标和同级插件 ID 只会更新其包一次。显式 npm spec 会覆盖同一包的仅 ID 选择；同一包的两个不同显式 spec 会被拒绝。未知目标和冲突的选择会在更新开始前失败，包括在 --dry-run 模式下。现有的批量更新器先处理插件包，再处理 hook-pack，在另一个包失败时保留成功的更新，并通过一次最终刷新将已保存的更改应用到运行中的 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 spec
当你传入插件 ID 时，OpenClaw 会从其记录的安装源开始。对于多入口包，子 ID 会解析到其包所有者，并一起更新所有同级项。如果新包版本移除或重命名了子项，OpenClaw 会删除已退休子项的条目、允许/拒绝策略、精确的子项加载路径、通道配置以及内存/上下文槽选择，同时保留保留/新子项和不相关插件。存储的 dist-tag（如 @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 spec 以供将来基于 ID 的更新使用。
不附带版本或标签地传入 npm 包名，同样会解析回受跟踪的插件记录。当插件被固定到精确版本，且你想让其回到注册表的默认发布线时，可使用此方式。
Beta 通道更新
定向的 openclaw plugins update <id-or-npm-spec> 在存在配置的更新通道时使用该通道。否则，可识别的官方插件会继承 OpenClaw 的注册表通道。批量 openclaw plugins update --all 对官方插件使用相同的注册表通道解析器。即使下载的工件具有精确版本，移动选择器也保持移动；恢复的 OpenClaw 发布固定遵循相同策略。
openclaw update 从新安装的核心版本解析插件目标。beta 通道上的 npm 更新会选择包的 beta 和 latest 发布中较新的那个；ClawHub 默认发布线更新会尝试 @beta，并在该发布不可用时回退到记录的默认/最新选择器。完整性、兼容性、信任、安装策略和能力同意失败不会触发源回退。插件更新不可用时会留下通知，而不会导致原本成功的核心版本更新失败。显式选择器保留其含义，并适用上述受管理的 OpenClaw 发布固定恢复机制。
现有插件源选择
更新会保留记录的 npm 或 ClawHub 源。较早的安装记录不区分自动 ClawHub 选择与显式 clawhub: 请求，因此 OpenClaw 不会静默地将这些记录切换到 npm。要刻意更改现有插件，请查看并运行 openclaw plugins install npm:<package> --force。对镜像拥有的捆绑插件进行自动外部化时，会优先使用 npm，其次使用其声明的 ClawHub 源。
版本检查与完整性漂移
在进行实时 npm 更新之前，OpenClaw 会将已安装的包版本与 npm 注册表元数据进行核对。如果已安装版本和记录的工件身份已经与解析目标匹配，它会避免下载或重新安装。请求的选择器更改或受管理的发布固定恢复仍然可以更新插件索引，而无需重写 openclaw.json。
当已存储的完整性哈希存在且获取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式 openclaw plugins update 命令会打印预期哈希和实际哈希，并在继续之前请求确认。非交互式更新辅助工具会失败关闭，除非调用方提供明确的继续策略。
更新时的 --acknowledge-install-policy-warning
plugins update 使用与安装相同的警告确认方式，在交互式终端中需要输入 type: '<plugin>' to update anyway。策略会被重新评估，block 或策略失败仍为终止状态。
更新时的 ClawHub 安全审计
社区 ClawHub 支持的插件更新会在下载替换包之前运行与安装完全相同的精确版本信任检查。审查结果仅作为信息打印并继续；被阻止的版本仍不可安装。官方 ClawHub 包和捆绑的 OpenClaw 插件源会绕过此版本信任检查。
Reload¶
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。
繁忙的插件会接受替换，并将新的保留工作限制在旧实例上。现有代理运行保留其原始回调，而新运行等待替换完成。在停止服务或通道之前，替换会最多等待 60 秒，让保留的工作和进行中的调用完成。详细就绪状态和 Gateway 日志会显示排队工作数量和截止时间；该命令会等待最终已应用回执。成功发布会发出 plugins.changed 并记录已应用的替换。如果工作超出预算，重新加载会失败一次，并且前一代恢复服务；未完成的运行不会被强制释放。在该工作完成后重试 openclaw plugins reload <id>，或使用 openclaw plugins reload <id> --wait 对已接受的工作无截止时间地等待。
--wait 会让新运行保持在同一替换门之后。按 Ctrl+C 可取消等待；断开其 Gateway 请求也会取消它。在发布之前，如果恢复成功，取消会恢复前一代，而不会取消已接受的运行。一旦发布提交，取消不会撤销它。服务关闭、资源清理和恢复保留其现有截止时间。详细就绪状态会暴露待处理的重新加载；显式等待没有排空截止时间。传入消息保留其通道现有的队列和重放契约；此选项不会为缺少持久入口的通道添加持久入口。请在本身持有目标插件的回合之外运行此维护命令：等待该回合，而该回合又在等待重新加载，无法取得进展。
替换要求前一个注册的资源清理完成，然后其继任者才能获取这些资源。清理失败可能会阻止替换和自动恢复；重试前请检查报告的失败。回执也可能包含清理警告。模块和原生库在其注册被移除后可能仍保持加载状态。
捆绑插件可以在保留其启用或禁用策略的同时重新加载。编译后的捆绑插件在其注册重新加载时会复用其进程已加载的代码。如果插件文件在其原始模块仍保持加载时发生变化，结果会报告 restartRequired: true 并带有警告，CLI 和工具输出会说明需要重启 Gateway 才能加载已编辑的代码。重新加载不会重新构建编译后的捆绑代码；源代码安装也需要构建。外部捕获源在替换后返回 restartRequired: false。重新加载未更改的捆绑文件也返回 restartRequired: false；通道和服务注册可以在不重启 Gateway 的情况下替换。重新加载已发现的源不会创建安装记录，也不会授予安装、替换或删除其文件的权限。
重新加载也适用于外部管理的配置（OPENCLAW_CONFIG_READONLY=1）和 Nix 模式（OPENCLAW_NIX_MODE=1），包括使用 $include 组合的配置。它会保留配置和安装状态。如果更改的能力需要新的同意，请在重新加载前通过部署负责人记录该接受。
已更改的声明能力可能需要再次审查。交互式文本输出会提示同意；--json 从不提示。仅在审查更改后使用 --accept-capabilities，包括将其与 --json 组合使用时。如果准备失败，错误会报告是否已发布替换。发布后的失败可能使新一代保持活动状态；重试前请检查报告的状态。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw