升级与卸载
本文介绍如何升级 OPW 到新版本,以及如何卸载 OPW。
升级
升级包括两部分:先用新版压缩包更新本机的 OPW,再到每个已有工程中同步配置。
查看当前版本
opw --version
升级步骤
从 GitHub 下载新版 OPW 压缩包。
用新版压缩包重新安装 OPW。推荐让 AI 帮你完成:在 AI 工具中新建会话,把
<ZIP 文件路径>替换为新版压缩包的实际路径后输入:我已下载新版 Open Pilot Wizard 压缩包,路径是 <ZIP 文件路径>。 请按照压缩包中的 INSTALL_AGENT.md 帮我把 Open Pilot Wizard 升级到这个版本;需要权限时请请求批准。也可以解压后手动执行安装脚本,见手动安装。安装过程会升级 OPW,并同步全局的 Skills、知识库、脚本和工程模板,不会修改你的插件工程。
重启终端和 AI 工具。
进入每个已有工程的根目录,同步工程配置并自检:
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 正被当前命令占用,卸载会先返回「待处理」,等命令退出后再完成清理。
卸载后确认
- 重启终端和 AI 工具,让环境变量生效。
- 执行
opw --version,确认命令已不可用。 - 在 AI 工具中确认
pilot-plugin-dev和 OPW 的 Skills 已不再出现。
你的插件工程不会被删除。需要重新使用时,按快速开始重新安装即可。