OpenCode v2 已在官网开放下载，本文根据 2026-09-15 北京时间看到的官网内容整理。
本文目录
一、v2 在哪下载二、怎么装（按官网）三、跟 v1 的关键区别四、文档里几个值得先看的
一、v2 在哪下载
下载页：https://opencode.ai/zh/download（默认就是 v2——v1 的下载页变成 /download/ 备份路径）。
v2 是当前主推版本——官网首页和导航的"文档"链接都指向 /v2/docs，下载页默认展示 v2 的命令、桌面版下载、扩展、集成。
重要：v2 不在 GitHub releases
查 GitHub releases API（https://api.github.com/repos/anomalyco/opencode/releases），列了 20 个 tag，全是 v1.18.x——v1.18.31 是最新的。
v2 的真实路径：
|
|
|
|
|---|---|---|
|
|
/download/
|
/zh/download
|
|
|
/docs
|
/v2/docs
|
|
|
opencode-ai |
@opencode/cli |
|
|
anomalyco/tap/opencode |
anomalyco/tap/opencode-v2 |
二、怎么装（按官网）
官网列出的 CLI 安装方式（v2 文档）：
桌面版（opencode-desktop）：
直接下载链接（从 v2 文档提取，文件名带 2.0.6）：
- macOS Apple Silicon DMG：
https://opencode.ai/files/bin/2.0.6/opencode-desktop-mac-arm64.dmg - macOS Intel DMG：
https://opencode.ai/files/bin/2.0.6/opencode-desktop-mac-x64.dmg - Windows x64：
https://opencode.ai/files/bin/2.0.6/opencode-desktop-win-x64.exe - Windows ARM64：
https://opencode.ai/files/bin/2.0.6/opencode-desktop-win-arm64.exe - Linux .deb / .rpm / AppImage：同上 URL 前缀
Docker：
Web 接入：
以上安装命令均来自 v2 文档。
三、跟 v1 的关键区别
3 个 breaking changes
按官方 Migrate from V1 文档，v2 有 3 个故意的** breaking change**：
- Plugins 用新 plugin API——v1 plugin 不能直接在 v2 用，得重新打包
- Server API 和客户端有新契约——集成代码可能需要适配
- Terminal client 配置：从分层的
tui.json(c)→ 单一全局cli.json文件——自动迁移
v1 配置大部分继续能用
"Existing supported server config fields, agent definitions, command definitions, skills, and other files in .opencode/ should continue to work without changes."
具体保留的内容：
|
|
|
|---|---|
|
|
~/.config/opencode/opencode.json(c)
|
|
|
<project>/opencode.json(c)
.opencode/opencode.json(c)（位置不变）
|
|
|
|
|
|
|
|
|
|
|
|
要重写
|
配置 schema
v2 引入了 JSON Schema：
加 $schema 字段后，VS Code / Cursor / Zed 等编辑器能自动验证 + autocomplete——v2 文档明确推广这个用法。
v1 → v2 兼容策略
按官方建议的实用迁移路径（不需要全一次性做完）：
- 保留 v1 配置和文件定义
- 启动 v2，先验证模型、凭据、agents、permissions、MCP servers
- 重写 plugins（v1 plugin 不能直接用）
- 改集成代码适配 server API
- 准备好之后再把配置改成 v2 原生格式（这一步可选）
"Keep a copy of your V1 setup while validating the migration."
v2 文档里的几个全局字段
|
|
|
|---|---|
update |
disable / notify（默认） / auto
|
share
autoshare）
|
manual
auto / disabled
|
opencode pair
|
|
#variant 后缀
|
anthropic/claude-sonnet-4-5#high
|
snapshots |
|
四、文档里几个值得先看的
/v2/docs/ 左侧导航有 19 篇子文档——按主题分 6 大类。用户先看 6 篇就够，剩下按需看：
1. Migrate from V1（必看）：https://opencode.ai/v2/docs/migrate-v1/——v1 → v2 迁移指南。如果你从 v1 来，先读这篇。
2. Config（核心）：https://opencode.ai/v2/docs/config/——v2 配置位置、JSON Schema、shell / model / agent / update / share / permissions / snapshots 等所有全局字段。
3. Agents：https://opencode.ai/v2/docs/agents/——自定义 agent 用 Markdown 文件（frontmatter + system prompt）。路径：全局 ~/.config/opencode/agents/<name>.md，项目 .opencode/agents/<name>.md（嵌套目录变成 agent ID 的一部分，如 .opencode/agents/team/reviewer.md → team/reviewer）。
4. Skills：https://opencode.ai/v2/docs/skills/——SKILL.md 文件，目录形式（带 scripts / references 旁挂文件）。agent 按需加载，不用塞进每个 prompt——比 v1 的 skill 加载方式更省 token。
5. Providers：https://opencode.ai/v2/docs/providers/——/connect 命令配置 provider、/models 命令选择模型。catalog 来自 models.dev。
6. Plugins（Breaking）：https://opencode.ai/v2/docs/plugins/——v2 plugin API。v1 plugin 不能直接用——这是 3 个 breaking changes 之一。
其他 13 篇：Models · Commands · Websearch · Network · Snapshots · Compaction · Formatters · References · Attachments · Tools · MCP servers · Permissions · Instructions · Sharing · Warming · Troubleshooting。
一些个人观察
1. v1.18.31 的检查更新查不到 v2——v1 的 update 默认是 notify，但只查 v1.x 系列。要从 v1 跳到 v2，必须手动去官网。
2. v2 是 beta 状态——AUR 的包名是 opencode-beta，Brew 的 formula 是 opencode-v2（带 -v2 后缀），这些命名都在说"还不是 stable"。
3. v2 的官网域名是 opencode.ai/v2/docs（子路径），不是独立子域名——跟 v1 文档的 /docs 共存。
4. OpenCode Go 是 $10/月订阅服务，官网 /zh/go 有独立页面。不是必需——如果你只用免费开源 API provider，可以无视。
互动问题：你用 OpenCode 是 v1 还是 v2？想试 v2 但还在观望的原因是什么？v1 → v2 的 plugin 重写让你犹豫了吗？opencode pair 的 web 模式你想试吗？
