先看结论
把 OpenCode V2 当作一次有计划的迁移
当 V2 的 CLI 或桌面体验符合你的工作方式，并且有时间验证时，可以开始试用。先保留可用的 V1，逐项检查模型、凭据、agents、权限、MCP 服务、插件、编辑器客户端和项目任务。个人配置简单，可以先在测试项目验证；团队和插件作者更适合分阶段推进。
官方迁移指南说明，受支持的 V1 配置和文件定义预期可以继续使用，熟悉的 opencode 命令也保留了。需要提前处理的是：V1 插件不能直接在 V2 运行；服务端 API 和客户端契约变化；终端偏好设置迁移到全局 cli.json。即使不改写主配置，也应做兼容性检查。
本页把官方安装路径、V1/V2 对照和谨慎迁移清单放在一起。官方核心迁移说明没有承诺批量转换历史会话数据库。如果主要关心模型、API Key 或套餐费用，请看模型指南、Provider 指南或套餐对比。
OpenCode V1 与 V2：哪些变化会影响实际工作流
版本号本身不能说明迁移成本。先看你实际使用的部分：终端客户端、插件、服务端 API 和配置。受支持的项目文件，与可执行的插件代码或 API 客户端不是同一类兼容问题。
| 方面 | V1 | V2 与迁移影响 |
|---|---|---|
| CLI 命令 | opencode | 命令名仍为 opencode；默认不会让 V1 与 V2 并排安装。 |
| 受支持的配置和项目文件 | V1 配置及 .opencode/ 文件 | 受支持字段以及 agents、commands、skills 预期可继续工作；仍要检查自己的 Provider 与权限行为。 |
| 插件 | V1 插件 API 和入口 | 插件 API 已变化；V1 插件必须迁移后才能运行。 |
| 服务端 API 和客户端 | V1 API 契约和生成客户端 | 契约发生变化；调用服务端的集成要换用兼容 V2 的客户端并测试。 |
| 终端偏好 | 分层的 tui.json 或 tui.jsonc | 受支持设置会迁到终端客户端的全局 cli.json；迁移后需复核。 |
| 安装渠道 | V1 包或安装器 | 选择明确面向 V2 的官方渠道；需要时先卸载包管理器安装的 V1。 |
这张表用于划定检查范围，不代表所有 V1 字段都受支持。迁移文档列出了“被接受但不受支持”的字段，并说明忽略的旧字段可能产生警告。修改安全策略、Provider 或自动化配置前，应核对最新官方说明。
现在是否应该升级到 OpenCode V2？
根据兼容性和可回退性来判断，而不是只看主版本号。只使用内置功能的个人配置，与依赖自定义插件及编辑器集成的仓库，迁移成本不同。
适合先试用 V2 的情况
- 主要使用受支持的配置、Provider、内置命令、agents、skills 和 MCP，并能在示例项目逐项验证。
- 需要 V2 CLI 或桌面体验，同时能在试用期间保留当前可用配置。
- 自定义插件或服务端客户端已有 V2 版本，或已安排负责人迁移并测试。
以下情况先不要替换 V1
- 关键工作依赖尚未验证 V2 契约的 V1 插件、服务端端点、IDE 客户端或自动化任务。
- 无法在新流程失败时还原当前安装、配置或重要会话数据。
- 升级的唯一原因是更新提示；V1 内部更新与迁移到 V2 主版本不是同一流程。
拿不准时，可在一次性测试项目验证，并记录命令、包管理器、OpenCode 版本和预期结果。这样能形成具体的兼容清单和回退点，不必依赖笼统的“V2 更好”。
通过官方渠道安装 OpenCode V2
当前 V2 入门文档列出了这些终端安装渠道。优先选用本机已经在使用的包管理器，并核对官方最新说明。迁移时不要把旧 V1 包名直接当成 V2 安装命令。
| 渠道 | 当前命令或入口 | 使用提示 |
|---|---|---|
| Shell 安装器 | curl -fsSL https://opencode.ai/v2/install | bash | 该地址明确指向 V2；迁移指南说明它会替换 V1 二进制。 |
| Homebrew | brew install anomalyco/tap/opencode-v2 | 使用 V2 formula；需要时先确认并移除包管理器安装的 V1。 |
| npm | npm install -g @opencode/cli | 这是 V2 包名；安装脚本会选择平台对应的原生二进制。 |
| Bun | bun install -g --trust @opencode/cli | 官方命令要求允许该包的安装脚本运行。 |
| pnpm | pnpm add -g --allow-build=@opencode/cli @opencode/cli | 官方命令要求为该包添加 allow-build 参数。 |
| Windows | 官方独立 CLI 二进制 | V2 文档称不支持 Windows 包管理器安装；请按官方平台二进制说明操作。 |
npm、Bun、pnpm、Yarn、Vite+ 和 AUR 的当前语法应以 V2 入门文档为准。2026年10月3日查询时，npm registry 的 @opencode/cli 最新标签指向 2.0.22；这是带日期的查询结果，不是固定版本要求。安装前请再查一次实时版本。
安装前先确认 V1 的来源。官方迁移指南说明，包管理器安装的 V1 可能需要先卸载，因为两代都使用 opencode 命令；V2 curl 安装器会替换 V1 二进制。卸载软件包时不要删除共用配置或数据。
如何安全地从 OpenCode V1 迁移到 V2
第一轮迁移应能回退。目标是确认 V2 可以启动且项目正常工作，而不是第一天就重写所有配置。具体卸载和安装步骤要匹配你的操作系统与原包管理器。
- 记录当前版本和安装来源。运行
opencode --version，再检查包管理器或二进制路径，确认哪些 V1 文件会被替换。 - 制作可还原的备份。复制全局与项目配置、
.opencode/文件、插件源码、客户端设置和无法重建的数据。确认备份能打开；密钥不要放进 Git。 - 通过官方渠道安装 V2。若 V1 由包管理器安装，先按该管理器的流程移除再安装；不要假设系统会出现第二个
opencode命令。 - 先在低风险项目验证。用熟悉的任务核对模型、Provider 凭据、agents、权限、MCP 服务、commands 和 skills；检查修改文件与 Git diff。
- 单独迁移扩展。按照官方插件迁移指南处理 V1 插件，并测试工作流使用的每个 hook 或服务端端点，再推广到主项目。
首轮验证期间先保留受支持的 V1 格式配置。官方指南说明 V2 会在内存中规范化受支持的旧配置，不会重写源文件；转为原生 V2 格式是可选步骤。稍后再转换，也更容易定位回归由哪项改动引起。
哪些内容可以沿用，哪些需要手动检查？
仅把当前 V2 指南明确支持的行为视为兼容。下面的差异有助于回答 OpenCode V2 的兼容问题，同时避免暗示所有旧字段或扩展都会继续工作。
| 范围 | 预期起点 | 需要核对 |
|---|---|---|
| 受支持配置 | V2 读取相同的全局与项目位置，并在内存中规范化受支持的 V1 字段。 | 检查具体 Provider、权限、MCP 和模型配置的警告与行为。 |
| Agents、commands、skills | .opencode/ 下受支持的文件定义预期可以继续使用。 | 实际运行代表性的 agent 和 command；检查自定义路径及脚本引用。 |
| 插件 | V1 插件实现不能在 V2 运行。 | 迁移入口以及每个 hook、工具、事件、选项和清理过程；测试安装后的包。 |
| 服务端 API 和客户端 | API 与生成客户端使用新的契约。 | 更新调用方，并测试身份验证、请求结构、响应和异常处理。 |
| 终端偏好 | 受支持的全局 tui.json(c) 设置会迁到终端客户端全局 cli.json。 | 复核迁移结果；项目级 TUI 配置不会作为项目文件迁移。 |
| 旧字段 | 部分 V1 schema 接受但 V2 无对应行为的字段会被忽略并产生警告。 | 对照不支持字段列表；理解警告前不要直接忽略。 |
| 会话历史 | 核心迁移说明没有承诺批量转换历史数据库。 | 单独备份重要数据并核对所需会话；CLI 启动成功不代表历史已迁移。 |
V2 迁移文档把受支持功能失效视为兼容性问题，并把无原生对应项的字段单独列出。因此，能启动只是第一步；还需要测试你的工具、会话流程和安全规则。
移除 V1 备用环境前，先验证 OpenCode V2
在示例项目跑一遍简短验收，并把结果写进升级记录。这样可以重复核对迁移是否成功，而不是凭启动后的第一印象判断。
- 确认
opencode --version显示预期 V2 版本，并核对执行文件来自正确安装路径。 - 连接预期 Provider、列出模型，并先运行只读提示；检查凭据时不要把密钥写入日志。
- 测试一个 command 或 agent、一个 MCP 服务，以及工作必需的每个插件或客户端集成。
- 用安全任务检查权限和项目边界，再检查改动文件和 Git diff。
- 复核启动警告和
cli.json偏好迁移结果；依赖的旧字段若不支持，应先处理。
关键检查失败时，先暂停在该工作流中使用 V2，恢复保留的 V1 安装或包版本。只还原回退所需文件，不要让 V1 读取仅适用于 V2 的配置。具体回退命令取决于包管理器；软件包版本记录应与用户数据分开保留。
已经使用 V2 后进行常规更新，可参考 V2 CLI 的 opencode upgrade 命令，update 是它的别名。从 V1 迁移到 V2 则需要单独的卸载和安装步骤。
OpenCode V2 迁移常见问题
OpenCode V2 是从 V1 普通更新吗？
不是。这是主版本迁移。两者命令都叫 opencode，默认不会把包管理器安装的 V1 与 V2 并排安装；应先确认安装方式并查看官方迁移指南。
V2 一定要重写 OpenCode 配置吗？
不一定。官方指南说明受支持的 V1 配置会被读取并规范化，而不会重写源文件。但部分字段不受支持，所以仍要检查警告，以及 Provider、权限和 MCP 的实际行为。
V1 插件能在 OpenCode V2 使用吗？
不能直接使用。V1 插件实现不会在 V2 运行。请按官方插件迁移指南改入口和行为，再测试实际安装的包。
怎么用 npm 安装 OpenCode V2？
当前 V2 文档使用 npm install -g @opencode/cli。安装前查看官方 V2 入门页和包页面，确认平台支持及安装脚本要求。
OpenCode V2 用什么命令更新？
对已经安装的 V2，CLI 文档列出了 opencode upgrade，update 是别名。从 V1 跨主版本迁移需要另行处理旧包和安装渠道。
升级到 V2 会迁移全部会话历史吗？
核心 V2 迁移指南没有承诺批量转换历史数据库。切换日常工作流前，先备份重要数据并检查必须保留的会话。
OpenCode 官方参考资料
下方安装命令和兼容性说明于2026年10月3日对照第一方文档核验。包版本和安装方式会变化，大版本升级前请重新确认。