opencode 升级实战：从版本检查到配置迁移与排坑全记录

我把手头这台开发机的opencode从旧版本升到了最新版，前前后后折腾了小半天。中间踩了几个不大不小的坑，比如Windows终端突然不认opencode命令了、升级完模型一直连不上、Skill目录扫描不到，最后都逐一解决了。今天这篇文章就把整个升级过程、操作命令、配置迁移和排坑经验完整记录下来。如果你手里也在用opencode，或者正准备从老版本升上来，这篇内容应该能帮你少走不少弯路。

先简单说下opencode是什么。它是一个开源的终端AI编程助手，形态上和Claude Code、Codex CLI类似，核心是在命令行里通过自然语言驱动模型帮你读代码、改代码、跑测试、查日志，支持多模型接入，也提供TUI交互界面。和很多同类工具不同的是，它把Skill机制、Agent工作流、Workspace管理都做成了第一等公民，还能直接接入VSCode和JetBrains系IDE插件。正因为它天天都在用，升级这件事才不是"装个新版"这么简单，配置、订阅凭据、Skill目录、IDE插件全都要跟着动。

下面我按实际操作的顺序，把升级前后你要做和要注意的事逐条拆开讲。

1. 升级前哨：先搞清楚你手里是什么版本

1.1 为什么要升级

很多人会问，工具用得好好的，干嘛要冒着破坏环境的风险去升级？我的答案是：opencode这类工具迭代速度极快，几乎每个大版本都会带来影响工作流的变化。比如老版本对Skill目录的扫描规则不完善，Agent的上下文管理有瓶颈，某些模型服务的请求格式兼容性差，这些痛点往往在新版本里被修复，但你必须先升级才能拿到。

另外，新版本通常会跟进上游模型API的变动。模型服务商调整接口格式、废弃旧参数、增加新能力，如果你手上的opencode长期不升级，就会出现"明明Key没问题，但请求一直报错"的怪现象。与其等到出问题再被动处理，不如在可控的时间窗口内主动升级。

还有一点是生态同步。IDE插件和CLI主程序之间有版本匹配关系，如果你的插件更新到了新版，而CLI还是老的，两者之间的通信协议可能对不上，轻则功能失灵，重则直接连不上。所以，升级opencode其实是把CLI、插件、Skill配置当做一个整体来刷新，不是单点操作。

1.2 升级前的版本确认

动手之前，先确认当前版本。这条操作看起来简单，但很多人会跳过，结果升级完不知道到底升没升成功，或者误把降级当升级。

bash复制opencode --version

这个命令会输出当前安装版本号和构建信息。你可以顺手把它记下来，或者直接拿它和opencode官方GitHub仓库的Releases页面做对比。如果发现当前版本落后了三个大版本以上，我建议你走"新装"路线，而不是覆盖升级，后面第2章会细说。

再说一个判断技巧：如果你已经不记得自己是什么时候装的opencode，那大概率是几个月前。这种情况下，你手里的版本配置格式很可能和新版不兼容，别指望直接覆盖完旧配置还能无缝用。最好先看一眼版本，再决定备份哪些文件。

1.3 该备份的配置清单

升级前备份这一步，我建议不要省。虽然正常情况下配置会自动迁移，但就怕模型订阅信息、Skill目录这种自定义资产出问题。我和其他用过opencode的人交流时，发现大家的配置文件基本集中在下面几个位置：

我实际操作的时候，是直接把这几个目录整体打了个压缩包放到临时目录，大概几十MB，几分钟的事。重点不是备份文件本身，而是给自己留一条回退的路。特别是auth.json里面存着各模型服务商的订阅凭据，如果升级后登录态失效，你还能从备份里把Key捞回来。

注意：auth.json是敏感文件，备份时别顺手传到网盘或Git仓库里。本地压缩、升级完即删，这是基本操作。

2. 三种升级路径，选你顺手的

2.1 脚本一键升级（推荐）

如果你当初是用官方脚本安装的opencode，那升级最简单，因为脚本本身是幂等的，重复执行就能覆盖到最新版本。macOS和Linux用户执行：

bash复制curl -fsSL https://