升级与卸载

2026-11-05评分加载中…

本文介绍如何升级 OPW 到新版本,以及如何卸载 OPW。

升级

升级包括两部分:先用新版压缩包更新本机的 OPW,再到每个已有工程中同步配置。

查看当前版本

opw --version

升级步骤

  1. 从 GitHub 下载新版 OPW 压缩包open in new window。

  2. 用新版压缩包重新安装 OPW。推荐让 AI 帮你完成:在 AI 工具中新建会话,把 <ZIP 文件路径> 替换为新版压缩包的实际路径后输入:

    我已下载新版 Open Pilot Wizard 压缩包,路径是 <ZIP 文件路径>。
    请按照压缩包中的 INSTALL_AGENT.md 帮我把 Open Pilot Wizard 升级到这个版本;需要权限时请请求批准。
    

    也可以解压后手动执行安装脚本,见手动安装。安装过程会升级 OPW,并同步全局的 Skills、知识库、脚本和工程模板,不会修改你的插件工程。

  3. 重启终端和 AI 工具。

  4. 进入每个已有工程的根目录,同步工程配置并自检:

    opw update  # 把已安装版本的内容同步到当前工程
    opw doctor  # 检查同步后的工程是否就绪
    

opw update 不会下载新版 OPW,只会把已安装版本的内容同步到当前工程,所以必须先用新版压缩包完成安装,再执行 opw update。

opw update 的可选参数

执行 opw update 时,可以附加以下参数:

参数作用
--global只同步全局的 Skills、知识库、脚本和工程模板,不修改当前工程中的 OPW 文件
--tools <tools>指定要同步的 AI 工具,用逗号分隔,可选 claude、opencode、codex;不传则自动探测已安装的工具
--force强制覆盖已被你修改过的 OPW 管理文件

不带 --global 时,opw update 只会更新当前工程中的以下两个目录,不会修改你的插件代码:

  • openspec/:AI 开发任务使用的工作流配置。你的需求规格和设计方案(openspec/specs/、openspec/changes/)不会被修改。
  • .open-pilot-wizard/:OPW 在本机记录的文件清单和运行日志。

注意: --force 会覆盖你对 OPW 管理文件的修改,使用前先备份需要保留的内容。

升级后检查

opw doctor 通过即可。如果提示工程存在历史问题、需要修复,执行 opw doctor --fix,再按提示让 AI 继续完成修复,详见排障。

升级失败时

升级成功时,安装脚本最后会输出「OPW <版本> 安装及全局同步完成」。如果最后输出的是以 ! 开头的错误信息,说明新版 OPW 已经安装,但同步全局的 Skills、知识库、脚本和工程模板时出错。让 AI 安装时,AI 会在汇报中说明失败原因。

根据错误信息处理:

错误信息处理方式
提示同步存在冲突,并列出冲突文件这些是你修改过的 OPW 文件(如 AI 工具中的 Skills),脚本保留了你的修改。确认不再需要这些修改后,执行 opw update --global --force
其他错误,如网络中断、权限不足解决问题后重新执行安装脚本

卸载

卸载分为两个层级:

命令作用插件代码
opw uninstall卸载当前工程中由 OPW 管理的配置保留
opw self uninstall卸载 OPW 本身,删除整个 ~/.open-pilot-wizard/ 目录并清理激活配置保留

如果多个工程使用了 OPW,建议按下面的顺序操作:先在每个工程里卸载,最后再卸载 OPW 本身。因为卸载 OPW 后,opw 命令不再可用。

卸载工程中的 OPW 配置

在工程根目录(即包含 .open-pilot-wizard/ 的目录)执行:

opw uninstall

该命令只处理当前目录。在子目录或其他目录执行时不会报错,但不会清理任何内容。

命令只清理未被你修改过的 OPW 管理配置,保留你修改过的文件,以及工程中的规格和变更记录。加上 --force 时,会删除 OPW 记录的全部文件,即使已被你修改。

注意: 工程卸载会直接移除 OPW 在 openspec/config.yaml 中添加的配置片段。如果你定制过这一部分,先备份。--force 会删除你修改过的 OPW 管理文件,使用前同样先备份。

卸载 OPW 本身

警告: 这一步不可撤销,会删除整个 ~/.open-pilot-wizard/ 目录(Windows 为 %USERPROFILE%\.open-pilot-wizard\),包括模板、知识库、缓存、偏好、统计,以及你自己放入其中的文件。先备份需要保留的内容。

先查看删除计划。不带 --yes 时,命令只展示计划,不会执行:

opw self uninstall

确认无误后执行:

opw self uninstall --yes

卸载的范围如下:

内容行为
OPW CLI卸载
~/.open-pilot-wizard/整体删除
AI 工具目录中 OPW 的 Skills 和入口与记录一致才删除,你修改过的文件会保留并报告
macOS shell 启动文件只移除安装脚本添加的 OPW 激活行,保留其他配置
Windows 用户 PATH清理指向 OPW 目录的条目,其他路径保留
插件工程、规格和变更记录保留
AI 工具程序、系统 Node.js、JDK、Android SDK 和 Android Studio保留

在 Windows 上,如果自带的 Node.js 正被当前命令占用,卸载会先返回「待处理」,等命令退出后再完成清理。

卸载后确认

  1. 重启终端和 AI 工具,让环境变量生效。
  2. 执行 opw --version,确认命令已不可用。
  3. 在 AI 工具中确认 pilot-plugin-dev 和 OPW 的 Skills 已不再出现。

你的插件工程不会被删除。需要重新使用时,按快速开始重新安装即可。

最近修改: