OpenCode 2.0 升级教程：从 1.x 迁移配置、插件与会话（附回滚方法）

Name

Soren Atelier

更新于 2026/11/4

先说结论： 备份 OpenCode 的配置和数据目录，升级到最新的 1.x，然后再执行大版本升级。

# 1. 备份配置和数据（会话保存在数据目录里）
cp -R ~/.config/opencode ~/opencode-v1-config-backup
cp -R ~/.local/share/opencode ~/opencode-v1-data-backup
 
# 2. 先升级到最新的 1.x（--major 从 v1.19.0 开始才有）
opencode upgrade
 
# 3. 升级到 OpenCode 2
opencode upgrade --major

在终端界面里输入 /update 效果相同。如果想干净安装，先卸载 v1 的包，再使用下文第 3 步里的任一 v2 安装命令。

大部分 v1 设置可以继续使用。有三处是有意做出的破坏性改动：v1 插件无法加载；服务端 API 换成了新的；tui.json 被 cli.json 取代。另外两处改动不那么显眼，却经常让人措手不及：v2 不再读取 CLAUDE.md；默认允许访问项目以外的目录。本文逐一说明这些变化，并整理了 2.x 发布头几周里已知的 bug。

我们核实了什么、没核实什么： 2026 年 10 月 25 日，我们在 macOS 上安装 OpenCode 1.18.19，检查了 v1 一侧，阅读了它的 upgrade、export、session 和 debug paths 命令。我们还查看了 npm registry 中 @opencode/cli 2.1.4 的数据，以及下文引用的 GitHub issue 和维护者回复。本文写作过程中我们没有实际运行 OpenCode 2。所有关于 v2 行为的描述都来自官方迁移指南 (opens in a new tab)、v2 文档 (opens in a new tab)、OpenCode 2.0 发布公告 (opens in a new tab)以及上述维护者回复。每一处都附了来源链接。2026 年 11 月 4 日，我们又对照 @opencode/cli 2.2.5 和 opencode-ai 1.19.5 复核了版本号、发布页面和 issue 讨论。

现在该不该升级？

OpenCode 2.0 于 2026 年 9 月 11 日以 @opencode/cli 的包名发布到 npm。但许多通过 npm 或安装脚本安装 v1 的用户直到 10 月才注意到它（Homebrew core 的用户更早就拿到了，见第 3 步里关于 Homebrew 的坑）。原因是 opencode upgrade --major 这条升级路径在 10 月 11 日的 v1.19.0 中才加入，而团队在 10 月 14 日才正式宣布 2.0。这条公告在 Hacker News 上拿到了 888 分。从 10 月 11 日起，仓库新增了 4,000 多个 issue，其中 130 个提到了 2.0。

两个版本目前并行发布。npm 上的 opencode-ai 仍然是 v1（10 月 28 日为 1.19.5），@opencode/cli 是 v2（10 月 30 日为 2.2.5）。从 v2.2.0（10 月 27 日）起，2.x 的构建也会出现在 GitHub Releases (opens in a new tab) 上，但标记为 Latest 的 release 仍然是 1.x。这是团队有意为之：v1 通过 Latest release 检查更新，团队不希望 v1 的自动更新把用户直接带到 2.x（#57675 (opens in a new tab)）。

第 1 步：动手之前先备份

官方迁移指南建议在测试期间保留一份 v1 配置的副本，但没说具体要复制哪些内容。在 macOS 和 Linux 上，opencode debug paths 会列出相关目录。我们的 1.18.19 安装显示如下：

复制前两个目录即可（命令见本文开头）。复制前先退出 OpenCode，这样会话数据库（opencode.db 及其 -wal 文件）才能在一致的状态下被复制。另外，把你在意的项目级 opencode.json 和 .opencode/ 目录也复制一份。它们留在各自的仓库里，多数情况下已经由 git 跟踪。

如果想把某段重要对话导出成可移植的副本，请在升级之前用 v1 导出：

opencode session list
opencode export <sessionID> > my-session.json

opencode export 会把会话写成 JSON。分享文件前，加上 --sanitize 可以去掉敏感的对话内容和文件数据。

第 2 步：先升级到最新的 1.x

opencode upgrade --major 从 v1.19.0 才开始提供。在我们的 1.18.19 上，opencode upgrade --help 里没有 --major 参数。如果你还在 1.18 或更早的版本，先执行一次普通升级：

opencode --version
opencode upgrade

然后确认 opencode --version 输出的是 1.19.x。从 v1.19.0 起，更新不再自动安装，所以不手动执行这一步，旧版本会一直停在旧版本。

第 3 步：升级或安装 v2

原地升级（从 1.19.x）：

opencode upgrade --major

干净安装。 迁移指南要求先卸载通过包管理器安装的 v1，因为 v1 和 v2 默认不能并存安装。然后从以下官方 v2 命令中选一个：

# 官方安装脚本（会替换 v1 的二进制文件）
curl -fsSL https://opencode.ai/v2/install | bash
 
# Homebrew（注意 formula 名带 -v2；先卸载用 brew 安装的 v1）
brew uninstall opencode
brew install anomalyco/tap/opencode-v2
 
# npm（新的包名）
npm uninstall -g opencode-ai
npm install -g @opencode/cli

包管理器的几个坑：

• npm 包名。 v1 是 opencode-ai，v2 是 @opencode/cli。今天执行 npm install -g opencode-ai，装到的仍然是 1.19.5。
• Homebrew core 与 tap 的区别。 brew install opencode（不带 tap）从 9 月 28 日起安装的就是 OpenCode 2，所以这类安装执行 brew upgrade 时，不需要 --major 就会升到 2.x。1.x 的 formula 是 anomalyco/tap/opencode，2.x 的是 anomalyco/tap/opencode-v2。两者互相冲突，所以安装另一个之前，先运行 brew uninstall opencode。
• 安装脚本。 v2 的 npm 包通过 postinstall 脚本选择原生二进制文件。如果你用 Bun 或 pnpm，需要加上 --trust（Bun）或 --allow-build=@opencode/cli（pnpm）。不加的话，二进制文件会缺失。
• 两个命令名。 这个 npm 包在 bin 字段里同时注册了 opencode 和 opencode2（我们核对过 registry 元数据）。
• mise 从 2026.10.9 版本起才会安装 v2，更早的 mise 安装的是 OpenCode 1。
• Windows 包管理器（Scoop、Chocolatey）不支持 v2，opencode upgrade --major 也无法切换这类安装。请从 v2 安装页面 (opens in a new tab)下载独立的 Windows CLI 二进制文件或桌面应用，或者使用 WSL。有一份中文报告称 v2 在 WSL 下会卡住（#55033 (opens in a new tab)），该 issue 已于 10 月 16 日因缺少细节被关闭。
• Docker： 有带版本号的镜像，例如 ghcr.io/anomalyco/opencode:2.0.0。

运行 opencode --version，确认输出的是 2.x。

第 4 步：检查 v2 从 v1 配置里读到了什么

你不需要重写配置。v1 和 v2 读取的是相同的位置（~/.config/opencode/opencode.json、项目里的 opencode.json、.opencode/）。v2 会在内存中映射 v1 的字段名，不会改写你的文件。第一次启动 v2 时，全局 tui.json 里的设置会迁移到新建的 ~/.config/opencode/cli.json，v1 的文件保持原样。

在真正信任它之前，打开一个实际项目，检查五项：模型、provider 凭据、agent、权限和 MCP 服务器。迁移指南给的也是这份检查清单。

如果之后想改成原生 v2 配置，下面这些是最重要的字段变化：

迁移指南里有两条规则，能避免大多数迁移错误：

1. 每个条目只用一种格式。 顶层可以混用 v1 和 v2 语法，但在单个 agent、provider、命令或模型条目内部，只能选一种格式。
2. 不要让 v1 读取已转换的文件。 两个版本读取相同的路径。一旦把某个文件转成仅 v2 支持的语法，v1 就读不了它。如果打算回滚，最后再做转换。

指南还建议让 OpenCode 自己来做转换。在项目中启动 v2，给它这段提示词："Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings."（意思是：把我的 OpenCode 配置，包括基于文件的定义，从 V1 格式迁移到原生 V2 格式，保持其行为和所有无关设置不变。）保留之前先检查 diff。

v2 会忽略的 v1 字段

下列字段只会打印一条警告，不会生效：

agent 级别的 temperature、top_p 和 options 也不再生效。v2 会把它们保留在 agent 的 request.body 里，但不会发送出去。请改为在模型 variant 上设置。

下面这些 v1 字段看起来像旧写法，但仍然有效，也不会出现警告，因为 v2 会替你转换。清理配置时不要删掉它们：

LSP 配置会保留，但不会运行。 如果你依赖 OpenCode 的 LSP 诊断，请改为给 agent 明确的 lint、类型检查或编译命令（例如写在 AGENTS.md 里）。

第 5 步：升级后才会暴露的行为变化

这些行为变了也不会报任何错，所以最容易让人意外。

v2 不读取 CLAUDE.md

v1 在没有 AGENTS.md 时会回退读取 CLAUDE.md，v2 不会。如果你的项目规则写在 CLAUDE.md 里，v2 启动时就没有这些规则，而且没有任何提示。修复只需一分钟：

# 在每个只有 CLAUDE.md 的仓库里执行
git mv CLAUDE.md AGENTS.md

v1 在 ~/.config/opencode/AGENTS.md 不存在时，还会把 ~/.claude/CLAUDE.md 当作全局规则。v2 同样去掉了这个回退。如果你没有全局的 AGENTS.md，把它复制过去：

cp ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md

现在 Claude Code 在没有 CLAUDE.md 时会读取 AGENTS.md，所以一个文件仍然可以同时服务两个工具。设置方法见 Claude Code 读取 AGENTS.md。恢复回退行为的功能请求目前在 #53402 (opens in a new tab) 中处于 open 状态。

默认允许访问项目以外的目录

在 v1 中，agent 访问项目外的目录前会先询问。在 v2 中，外部目录访问默认是允许的。要恢复 v1 的行为，在 permissions 中加上这条规则：

{
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

如果你开启了自动批准，或者机器上在仓库之外存有敏感文件，请在第一次使用 v2 之前加上这条规则。

Todo 默认关闭

v1 中 todo 列表默认开启，v2 中默认关闭。用 "experimental": { "todo": true } 重新打开。

整个用户账户共用一个后台服务

v2 会启动一个共享的后台服务器，TUI、Web 界面和桌面应用都连接到它。opencode pair（一次性链接，5 分钟后过期）和后台任务（Ctrl+B）正是靠它实现的。如果你不想要它：

opencode service set disabled true   # 停止服务并取消自动启动
opencode service unset disabled      # 重新启用
opencode --standalone                # 仅本次运行使用一个独立服务器

服务被禁用时，配对功能无法使用。该服务也不读取 cli.json，所以终端界面设置只影响终端客户端。

第 6 步：插件、Oh My OpenCode 和 VS Code 扩展

v1 插件无法在 v2 中加载。 插件 API 是全新的。仅仅把配置里的 plugin 改成 plugins 是不够的，每个插件的代码都要移植（参见官方插件迁移指南 (opens in a new tab)）。

此前最常见的失败案例是 Oh My OpenCode（oh-my-openagent）。在 OpenCode 2.0.27 上，它的 5.1.32 版本报错 Plugin must export a default definition with an id and an effect or setup function（oh-my-openagent #10089 (opens in a new tab)）。修复（#10439 (opens in a new tab)）已于 10 月 18 日合并，5.1.38 是第一个包含该修复的 npm 版本。11 月 2 日，维护者确认当前版本可以在 OpenCode 2 上加载，并会显示一条提示，引导用户使用 OmO Native，也就是独立应用 omo。升级 OpenCode 之前，先把 oh-my-openagent 更新到 5.1.38 或更高版本。如果你更想转到 omo，其 README 说明只需运行一次 omo setup，就能带上 provider 密钥、MCP 服务器、skills 和模型选择。如果你还不熟悉这套工具本身，可以先看 OpenCode 使用指南（含 Oh My OpenCode）。

VS Code 扩展报错 Unrecognized flag: --port。 旧版扩展用 opencode --port <port> 启动 CLI，而 v2 移除了这个参数。把扩展更新到 v1.0.0 或更高版本（Marketplace 或 Open VSX）。更新之前，可以在 VS Code 里打开终端，自己运行 opencode（#55219 (opens in a new tab)）。

你自己调用服务端的脚本。 v1 的服务端 API 已经移除。请把脚本迁移到 @opencode/client 包，它还能自动找到后台服务。在 shell 中，opencode api 调用的是同一套 API。OPENCODE_SERVER_USERNAME 已不再支持，用户名固定为 opencode。OpenCode GitHub Action 已在 2.2.0 中移除。

升级后的已知问题

以下是 2.x 发布头几周里仍未关闭或刚刚修复的 GitHub issue。修复方法来自各 issue 中维护者、报告者或项目机器人的回复。

如何回滚到 1.x

迁移指南没有讲如何回退。下面是稳妥的顺序：

1. 卸载 v2。opencode uninstall --dry-run 会显示将要删除的内容。然后运行 opencode uninstall，它会删除程序，但保留磁盘上的会话、配置和状态。
2. 用固定版本重新安装 v1：npm install -g opencode-ai@1.19.5，或 brew install anomalyco/tap/opencode（不带 -v2 的 formula）。
3. 如果你把某个配置文件转成了仅 v2 支持的语法，从 ~/opencode-v1-config-backup 恢复它。
4. 如果 v2 使用过会话数据库之后 v1 无法读取，就恢复 ~/opencode-v1-data-backup。我们没有测试 v1 能否打开被 v2 写入过的数据库，请做好用备份的准备。

安全提示：OpenCode Console 泄露事件

这件事和升级无关，但发生在同一周。10 月 17 日，OpenCode 团队表示，有人未经授权访问了一个正在下线的旧系统（Hacker News 上引用的声明原文 (opens in a new tab)）。保存在 Console 工作区里的第三方 provider 密钥 "may have been exposed"（可能已经泄露）。官方建议：在各个 provider 的控制台里吊销并更换这些密钥，并检查近期用量。之后的一篇说明称，受影响的 Console 用户占比为 1.4%，联合创始人 Dax Raad 表示 CLI 和桌面应用没有受到影响（TechCrunch (opens in a new tab)）。如果你曾在 Console 中保存过 OpenAI、Anthropic 或其他密钥，无论升级前后，都请轮换它们。

2.0 真正新增了什么

完成升级并不需要了解这些。它们解释了架构为什么要改：

• 后台服务：由 TUI、Web 界面和桌面应用共享，另有 opencode pair 用于 Web 访问。
• 后台任务：按 Ctrl+B 可把正在运行的 shell 命令或 subagent 放到后台，主 agent 继续工作。
• Code Mode：把 MCP 服务器和 OpenAPI 端点变成函数，agent 可以在一步之内串联调用。MCP 服务器默认使用它。
• 热重载：OpenCode 可以在会话中途为自己写一个插件，并立即使用。
• @opencode/sdk 和 @opencode/client：CLI 背后的代码，可用来构建你自己的客户端。

如果你不是要升级，而是从零挑选一个终端 agent，Codex 使用教程和 Pi Coding Agent 使用教程介绍了最接近的替代方案。

相关指南

• OpenCode 使用指南：快速上手、实战技巧，以及何时搭配 Oh My OpenCode
• Claude Code 读取 AGENTS.md：与 Codex、OpenCode、Cursor 共用一个文件
• Codex 使用教程
• Pi Coding Agent 1.0 使用教程
• DeepSeek Harness 使用教程
• 并行代码 Agent 详解