鲸游最近一周我把日常开发用的 AI 编程助手 opencode 从老版本升到了新版，整个过程折腾了差不多一个下午，中间踩了好几个坑，也把升级前后容易遇到的问题摸了一遍。说实话，opencode 这种工具迭代速度非常快，隔几周就有大版本更新，如果不搞清楚升级的正确姿势，很容易升级完发现配置乱了、模型连不上、甚至命令行直接不认识了。这篇就围绕“opencode 升级”这件事，把升级前、升级中、升级后要做的准备工作、具体操作和排查思路完整记录下来，给正在用或者准备用 opencode 的开发者一个可以直接照抄的参考。
先说清楚 opencode 是什么，避免有读者刚接触这个概念。opencode 是一个运行在终端里的 AI 编程助手，属于 Agent 型编码工具，它不像 Copilot 那样只做补全，而是能自己读项目代码、理解上下文、修改多个文件、执行命令，跑完测试再把结果反馈给你。你可以把它理解成开源世界里比较接近 Claude Code 的替代方案，同时支持接多家大模型，自由度很高。正因为它能力强、可定制性强，升级的时候涉及的点也就特别多——配置文件、模型服务商配置、自定义 skill、IDE 插件联动，每一项都可能在版本跳变后出问题。
这篇内容适合几类人看：已经在日常工作中使用 opencode 的人，想从老版本平滑升级到新版的人，以及在 VSCode、IDEA 里装了 opencode 插件、想搞明白插件和命令行工具版本关系的人。如果你只是听说过 opencode 准备入坑，也能从里面了解到初始安装、版本管理、配置备份这些基础操作。下面直接进入正题。
1. 升级前必须搞懂的三个关键问题
1.1 opencode 的价值，以及为什么升级不是小事
先说个背景。终端型 AI 编程助手这两年发展特别快，和传统的 IDE 插件不一样，这类工具的核心是在命令行里跑一个 Agent，它能看到整个项目的文件结构、能调起构建工具、能跑单元测试，甚至能自己根据报错信息修代码。opencode 在这个赛道里口碑不错，主要因为三点：第一，开源，代码和配置都掌握在自己手里；第二，模型无关，可以接 Anthropic、OpenAI、本地 Ollama、各种兼容 OpenAI 协议的服务商；第三，有 skill 机制，可以把自己的团队规范、常用命令流程沉淀成可复用的能力。
但以上这些优点，恰恰是升级容易翻车的地方。模型接入方式在变、配置结构在变、skill 的加载规则也在变。我见过有同事升级 opencode 之后，原来能用的自定义模型指令全部失效，排查半天发现是配置里 provider 字段从 base_url 改成了 baseURL，这种小事在版本说明里可能就是一行字，但实际踩到就知道多折腾。所以升级之前，先把“我现在用的版本是什么、我配置了哪些东西、哪些数据不能丢”这三件事搞清楚，比直接敲升级命令重要得多。
1.2 升级前的资产盘点：配置、密钥、技能和会话记录
升级前最忌讳的是什么都不管直接升级。我的习惯是先把 opencode 相关的“家底”盘一遍，主要包括四类东西：
- 配置文件：包括全局配置（通常存放在用户目录下的
~/.config/opencode/，Windows 上是%USERPROFILE%\.config\opencode\）和项目级配置（项目根目录下的opencode.json之类）。 - 模型服务商信息：也就是 provider 配置、模型名称、API Key 相关环境变量。很多人的 API Key 是通过 shell 环境变量注入的，不在配置文件里，升级不影响，但要确认升级后 shell 环境是否还带着这些变量。
- 自定义 skill 和指令：opencode 支持类似“技能包”的扩展机制，可能存在
~/.config/opencode/skills/目录下。这些是个人或团队沉淀的资产，备份时最容易漏。 - 历史会话