在 Linux 上升级 OpenCode 的方式，取决于最初用哪种包管理器安装它。在 Rocky Linux 上，通过 npm 安装的 OpenCode 1 会拒绝自行升级，只输出“exit code 243”；Arch 官方 extra 仓库中的软件包已经是 OpenCode 2，而 AUR 中的 opencode-bin 仍是 OpenCode 1；Debian 的 apt 仓库则完全没有提供 OpenCode CLI。

本文覆盖 Rocky Linux、RHEL、Debian、Ubuntu、Arch 以及 Linux 上的 Homebrew 安装方式，说明 npm 与独立二进制的区别，并整理从 OpenCode 1 升级到 2 时遇到的迁移错误。所有安装、升级和错误复现均在 2026 年 10 月于 Rocky Linux 10、Debian 13 和 Arch Linux 虚拟机中完成，版本从 OpenCode 1.19.4 升级到 2.2.0；没有实际执行的步骤会单独说明。

根据发行版选择安装方式

如果发行版提供原生软件包，应优先使用；其他情况使用 v2 安装脚本。在本文涉及的发行版中，Arch 是唯一提供官方 OpenCode 软件包的发行版，RHEL 和 Debian 仓库都不包含 CLI。Debian 13 的 apt-cache policy opencode 没有输出，上游提供的 .deb 与 .rpm 也只用于桌面应用。

测试虚拟机中的结果如下：

发行版	方式	安装内容	安装时间	磁盘占用	后续升级
Rocky Linux 10 / RHEL	v2 curl 脚本	OpenCode 2	10 秒	~/.opencode 约 236 MB	opencode upgrade
Rocky Linux 10 / RHEL	npm 安装 @opencode/cli	OpenCode 2	24 秒	约 940 MB	sudo npm install -g @opencode/cli@latest
Debian 13 / Ubuntu	v2 curl 脚本	OpenCode 2	9 秒	236 MB	opencode upgrade
Arch Linux	pacman -S opencode	OpenCode 2	9 秒	234 MB（另装 ripgrep）	pacman -Syu
Arch Linux	AUR opencode-bin	OpenCode 1	构建 8 秒	205 MB	不建议使用
Linux 上的 Homebrew	brew install opencode	OpenCode 2	20 秒	217 MB，另含 icu4c 与 ripgrep	brew upgrade

最关键的两个数字来自 npm 包和脚本版。npm 会同时下载 x64 Linux 的 glibc、musl 以及不支持 AVX2 的 baseline 构建，每个约 235 MB，因此同一个二进制占用约为脚本版的四倍。pacman 与 Homebrew 管理各自安装的副本，opencode upgrade 不应覆盖它们。服务器推荐 curl 脚本，Arch 使用 pacman，已经用 Homebrew 管理工作站 CLI 时则继续使用 Homebrew。

在 Rocky Linux 和 RHEL 上安装

Rocky Linux 10 云镜像默认没有 git，而 OpenCode 通过项目的 git 仓库跟踪项目状态，因此先安装 git。测试项目第一次运行 git init 时出现了“git: command not found”：

sudo dnf install -y git curl tar

随后以普通用户执行 v2 安装脚本。所有文件都会放入主目录，因此不需要 sudo：

curl -fsSL https://opencode.ai/v2/install | bash

安装耗时 10 秒，并在 ~/.bashrc 的 # opencode 标记下加入一行 PATH 配置：

Installing opencode version: 2.2.0
Successfully added opencode to $PATH in /home/josphat/.bashrc

OpenCode includes free models, to start:

exec $SHELL   # Reload PATH (or open a new terminal)
cd <project>  # Open directory
opencode      # Run command

SELinux 仍保持 enforcing。从 tar 包解出的二进制带有 user_tmp_t 标签，而没有 user_home_t，在 ls -Z 中看起来异常，但实际不影响运行、升级或会话服务。Targeted 策略不会限制普通用户从主目录运行的程序，实验结束时 sudo ausearch -m avc -ts today 显示没有匹配项。打开新 shell 并检查版本：

exec $SHELL
opencode --version
ls -laZ ~/.opencode/bin/

版本号带 v 前缀表示 OpenCode 2，OpenCode 1 只显示纯数字。较小的 opencode2 文件只是两行 shell shim，负责启动 opencode：

opencode v2.2.0
-rwxr-xr-x. 1 josphat josphat unconfined_u:object_r:user_tmp_t:s0  246831280 Oct 26  1985 opencode
-rwxr-xr-x. 1 josphat josphat unconfined_u:object_r:user_home_t:s0        47 Oct 28 01:05 opencode2

如果希望使用 npm 管理，Rocky Linux 10 的 AppStream 直接提供 Node.js 22 普通软件包。EL10 已不再提供 module stream，因此 dnf module list nodejs 会返回“No matching Modules to list”，可以直接安装：

sudo dnf install -y nodejs npm
sudo npm install -g @opencode/cli

测试得到 Node.js 22 和 npm 10，OpenCode 安装新增 5 个包，耗时 23 秒。软件包名非常重要：code>@opencode/cli</code 对应 OpenCode 2，而旧教程常见的 opencode-ai 对应 OpenCode 1，并仍会收到 1.x 更新。发行版 Node 的全局安装目录归 root 所有，位于 /usr/local，因此后续 npm 升级需要 sudo。

从 Arch extra 仓库安装

Arch 在官方 extra 仓库中提供 OpenCode 2，直接使用 pacman 即可，无需 AUR 助手。Arch 不支持部分升级，所以应在同一事务中更新系统：

sudo pacman -Syu opencode

pacman 只新增 ripgrep 这一项依赖，并把 wl-clipboard 和 xclip 列为剪贴板功能的可选依赖。软件包提供 /usr/bin/opencode 以及 bash、fish、zsh 补全，安装耗时 8.7 秒。测试当天 extra 比上游落后一个次版本：它被标记为过期，而较新构建位于多数机器默认未启用的 extra-testing。Arch 延迟数天更新属于正常情况，应等待 pacman -Syu，不要混用其他安装方法。

AUR 中容易装错主版本。opencode-bin 实际构建 OpenCode 1；名字看似测试版的 opencode-beta 才是上游维护的当前 2.x 版本，OpenCode 文档也把 paru -S opencode-beta 列为 Arch 安装命令；opencode-v2-git 则构建较旧的 git 快照。可用 AUR RPC 检查：

curl -s "https://aur.archlinux.org/rpc/v5/info?arg[]=opencode-bin&arg[]=opencode-beta&arg[]=opencode-v2-git" |
  python3 -c '
import sys, json
for r in json.load(sys.stdin)["results"]:
    print(r["Name"], r["Version"], r.get("OutOfDate"), r.get("Conflicts"), r.get("Provides"))
'

三者都与 extra 的 opencode 声明冲突，只有 opencode-beta 与当前上游版本一致：

opencode-bin 1.19.4-1 None ['opencode'] ['opencode']
opencode-beta 2.2.0-1 None ['opencode', 'opencode2'] ['opencode', 'opencode2']
opencode-v2-git 2.0.30.412b2b1d85-1 None ['opencode', 'opencode-bin', 'opencode-git'] ['opencode', 'opencode-v2']

测试构建了 opencode-bin，其 PKGBUILD 从 GitHub 下载 1.x 发布包。覆盖 extra 版本时因冲突停止，使用 --noconfirm 时 pacman 自动回答“N”，不会破坏 OpenCode 2。截图还展示了另一个 Arch 问题：opencode upgrade 无法判断 pacman 管理的二进制是如何安装的，因此拒绝直接覆盖 /usr/bin/opencode：

拒绝覆盖是正确行为，随后 pacman -Qk opencode 确认 16 个软件包文件都完整。不要通过 --method curl 强制覆盖，因为 curl 方式会安装到 ~/.opencode/bin，导致 PATH 中多出第二个副本。extra 与 opencode-beta 之间建议继续使用 Arch 签名构建的 extra 包，并接受它比上游晚几天更新。

在 Debian 13 和 Ubuntu 上安装

Debian 和 Ubuntu 没有 apt 包，只能选择 curl 脚本或 npm，测试中脚本方案的资源占用明显更低。Debian 13 云镜像已有 curl、tar 和 ca-certificates，但没有 git 和 unzip。脚本不需要 unzip，不过仍应安装 git：测试中尚未安装 git 时，第一次 opencode run 无输出等待两分钟，被超时终止；安装 git 后，同样提示不到 5 秒就得到结果：

sudo apt update
sudo apt install -y git curl
curl -fsSL https://opencode.ai/v2/install | bash

Debian 上使用 npm 的代价很高。Debian 13 提供 Node.js 20，在云镜像中执行 sudo apt install -y nodejs npm 会新增 581 个软件包，下载 199 MB、额外占用 880 MB，并要等待 5 分 26 秒才能开始安装 npm 包。如果机器不是已经需要 Node，为了一个命令行程序安装完整运行时并不划算。

同时安装两套 OpenCode 是 Debian 和 Ubuntu 的另一个陷阱。安装脚本把 PATH 配置追加到 ~/.bashrc 末尾，而 Debian 默认 .bashrc 在非交互 shell 中会提前返回，根本执行不到该行。因此 cron、CI 和 ssh host cmd 只会找到 /usr/local/bin 中的 npm 副本，登录 shell 却优先找到 curl 副本。可以这样检查登录 shell：

bash -lic 'which -a opencode'

测试虚拟机同时安装两套时得到：

/home/josphat/.opencode/bin/opencode
/usr/local/bin/opencode

两个不同版本的副本会针对同一配置和会话数据库运行不同版本的 OpenCode，因此必须只保留一套。以下步骤仅在 Debian 上实际执行，但脚本下载的是通用 glibc 二进制，不依赖发行版特有组件，Ubuntu 26.04 也使用同一脚本。

在 Linux 上使用 Homebrew

homebrew-core 的 opencode formula 跟踪 OpenCode 2，并为 x86_64 Linux 提供预编译 bottle，无需本地编译。主要成本是准备 Homebrew。在 Rocky Linux 10 上，其依赖的构建工具安装耗时约 4 分钟：

sudo dnf group install -y "Development Tools"
sudo dnf install -y procps-ng curl file git

随后执行官方安装脚本，全程约 27 秒，并执行输出中给出的 shellenv 命令：

NONINTERACTIVE=1 /bin/bash -c \
  "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

先检查 formula 再安装。OpenCode 文档还列出 anomalyco/tap/opencode-v2，但 core formula 已经是最新版本，无需额外 tap：

brew info opencode
brew install opencode

formula 报告当前 2.x bottle 和两个运行时依赖，安装耗时 20 秒：

==> opencode: stable 2.2.0 (bottled)
AI coding agent, built for the terminal
https://opencode.ai
Not installed
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/o/opencode.rb
License: MIT
==> Dependencies
Required (2): ripgrep, icu4c@79

Homebrew 的 shellenv 会把 /home/linuxbrew/.linuxbrew/bin 放在 /usr/local/bin 之前，因此测试中的 Rocky 机器上，brew 副本悄悄遮蔽了仍然安装的 npm 副本。两者当天版本相同，所以很难及时发现其中一套落后。安装后执行 which -a opencode，并删除不需要的副本。

选择 npm 还是独立二进制

两种方式运行的是完全相同的 246,831,280 字节二进制，区别只在于分发方式和资源成本。npm 包是薄包装，其 postinstall 脚本选择适合当前机器的原生构建并创建硬链接，同时把每个 x64 Linux 变体作为可选依赖下载。Debian 虚拟机中的情况如下：

du -sh /usr/local/lib/node_modules/@opencode/cli/node_modules/@opencode/*

四个构建每个约 235 MB，但机器只会运行其中一个：

236M  /usr/local/lib/node_modules/@opencode/cli/node_modules/@opencode/cli-linux-x64
236M  /usr/local/lib/node_modules/@opencode/cli/node_modules/@opencode/cli-linux-x64-baseline
235M  /usr/local/lib/node_modules/@opencode/cli/node_modules/@opencode/cli-linux-x64-baseline-musl
235M  /usr/local/lib/node_modules/@opencode/cli/node_modules/@opencode/cli-linux-x64-musl

如果机器本来就需要 Node，且希望 OpenCode 与其他全局工具统一管理，或者团队通过 package.json 管理版本，可以选择 npm。服务器、容器和 CI 镜像更适合 curl 二进制，因为它不需要运行时、不需要 root 权限，磁盘占用也约为四分之一。

从 OpenCode 1 升级到 OpenCode 2

首先确认当前安装方式和版本：

which -a opencode
opencode --version

curl 脚本安装在用户目录时，直接升级：

opencode upgrade --major
opencode --version

npm 全局安装需要 sudo。测试中对 Rocky Linux 上由 root 管理的 npm 安装，执行了：

sudo opencode upgrade --major

若使用 npm 自带的升级方式，也可以直接安装 code>@opencode/cli</code 的最新版本：

sudo npm install -g @opencode/cli@latest

升级前应停止正在运行的 OpenCode 会话，备份配置。迁移完成后先检查版本和 which -a opencode，确认没有两个版本同时留在 PATH 中。

检查升级后的配置变化

OpenCode 2 改变了配置和插件结构。升级后运行：

opencode debug config

查看输出中的警告，并检查旧的 ~/.config/opencode 文件是否仍被读取。插件尤其需要检查，因为 OpenCode 2 不再加载顶层 plugin/ 目录中的旧式单文件插件。

配置文件应从旧版本的备份逐步迁移，不要一边升级一边同时运行两个主版本。两个版本共享 ~/.local/share/opencode/opencode.db，但 OpenCode 2 新增了 session_v2 和 session_message 表，旧版本不会显示升级后创建的会话。

修复 OpenCode 2 迁移错误

下面这些错误都来自实验虚拟机在两个版本和不同包管理器之间切换时的真实运行。多数错误不会阻止 OpenCode 启动，因此很容易被忽略。

npm 升级失败（exit code 243）

当 npm 全局安装归 root 所有时，以普通用户运行 opencode upgrade --major 会出现该错误。npm 无法写入 /usr/local/lib/node_modules，而 OpenCode 只显示退出码。243 等于 256 减 13，13 即 EACCES 权限错误，符合 root 拥有的目录。使用 sudo 和完整升级命令，或者改用 nvm 安装 Node，把全局包放在主目录。不要为了让普通用户写入而把 /usr/local/lib 改成自己的所有权。

npm error EEXIST: file already exists /usr/local/bin/opencode

在 opencode-ai 仍安装时执行 sudo npm install -g @opencode/cli 会出现该错误。两个软件包都声明 opencode 命令，npm 下载一分钟后拒绝覆盖：

npm error code EEXIST
npm error path /usr/local/bin/opencode
npm error EEXIST: file already exists
npm error File exists: /usr/local/bin/opencode
npm error Remove the existing file and try again, or run npm
npm error with --force to overwrite files recklessly.

不要使用 --force，否则会留下仍安装的 OpenCode 1 软件包，而命令链接已被新版本接管。先删除旧包，再安装新包：

sudo npm uninstall -g opencode-ai
sudo npm install -g @opencode/cli

测试中卸载不到一秒，干净安装耗时 23 秒，随后 opencode --version 输出 v2 版本号。

Error: @opencode/cli’s postinstall script was not run

如果在安装时使用 --ignore-scripts，或 .npmrc 中设置了 ignore-scripts=true，npm 可能显示“added 5 packages”，却没有执行 postinstall 链接原生二进制，命令因此只是个空壳：

Error: @opencode/cli's postinstall script was not run.
This occurs when installation scripts are disabled.
Run the package postinstall script or reinstall with scripts enabled.

移除该参数或 .npmrc 中的 ignore-scripts 后重新安装。由于平台软件包已下载，重新安装只需 5 秒：

sudo npm install -g @opencode/cli

Bun 和 pnpm 默认阻止安装脚本，因此其 OpenCode 安装命令分别需要 --trust 和 code>--allow-build=@opencode/cli</code。

Could not detect the installation method. Pass --method to choose how to upgrade OpenCode

对发行版包管理器管理的副本执行 opencode upgrade 会出现该错误，例如 Arch extra 中的 /usr/bin/opencode。--method 可选 curl、npm、pnpm、bun、yarn、vp、brew 和 winget，没有 pacman，因此 OpenCode 无法自行升级。应使用包管理器执行 sudo pacman -Syu，不要强行指定 --method curl，那会安装第二份副本，而不是升级现有副本。

opencode-bin 与 opencode 冲突

AUR 助手或 pacman -U 正尝试用 AUR 中的 opencode-bin（OpenCode 1）覆盖 extra 中的软件包。回答“y”会降级到 OpenCode 1。应回答“N”，从助手列表中移除 opencode-bin 并继续使用 extra 包。若 opencode-bin 已经安装，执行 sudo pacman -R opencode-bin，再从 extra 安装 opencode。

failed to load plugin: Plugin must export a default definition

OpenCode 1 的插件 ~/.config/opencode/plugin/notify.js 在升级前每次空闲会话都会触发。升级到 OpenCode 2 后它没有运行，日志中只有一条警告：

level=WARN message="failed to load plugin"
 target=/home/josphat/.config/opencode/plugin/notify.js
 cause="Cause([Fail(PluginModule.LoadError: Plugin must export a default definition with an id and an effect or setup function. (cause: SchemaError(Missing key\n  at [\"default\"])))])"

OpenCode 2 要求插件默认导出包含 id 与 setup(ctx) 函数的对象，并且本地插件是目录而不是单个文件。先将旧文件移走，再把最小插件放入 ~/.config/opencode/plugins/notify/：

mkdir -p ~/.config/opencode/plugins/notify
mv ~/.config/opencode/plugin/notify.js ~/v1-notify.js.bak
vim ~/.config/opencode/plugins/notify/index.js

Rocky 虚拟机实际加载的文件如下：

export default {
  id: "notify",
  async setup(ctx) {
    console.error("notify plugin loaded in " + ctx.location.directory)
  },
}

下一次执行 opencode run 时，日志显示加载 plugins/notify 并启动 watcher，没有失败。Hooks、工具和事件都迁移到了 ctx 对象的新 API，真实插件需要按迁移指南逐个调整。每次升级后都应搜索日志中的“failed to load plugin”，因为 OpenCode 本身不会主动提示。

Error: Server process 52772 is still running

OpenCode 2 会运行一个在单次命令结束后继续存活的后台服务。在 Rocky 上替换 npm 软件包后，第一次 opencode debug config 发现该服务无响应，日志记录“Background service is unresponsive; recovery cannot preserve persistent terminals”，随后命令失败。之后半分钟内日志又重复两次警告，OpenCode 替换了失效服务，相同命令便能正常工作，~/.local/state/opencode/service.json 中出现新 PID。因此应先重试，再排查其他原因。

OpenCode 2 还会在 ~/.config/opencode/ 中写入 service.json，两个副本都包含后台服务密码。如果该目录被纳入点文件仓库，应把 service.json 加入 .gitignore。

固定版本或回退到 OpenCode 1

v2 安装脚本会读取 VERSION 变量，因此可以在新版本出现问题时固定到已知可用版本。测试在 Debian 上固定了较早的 2.x 构建，安装耗时 9 秒，随后 opencode upgrade 又能用 10 秒恢复到最新版本：

export OPENCODE_PIN=2.1.4
curl -fsSL https://opencode.ai/v2/install |
  VERSION="${OPENCODE_PIN}" bash -s -- --no-modify-path
opencode --version

--no-modify-path 阻止脚本再次修改 ~/.bashrc，脚本也接受同样格式的 --version 参数。npm 的等价操作是 sudo npm install -g @opencode/cli@2.1.4，在 Debian 上耗时 28 秒；安装 code>@latest</code 即可前进到最新版本。Arch 可以从 /var/cache/pacman/pkg/ 使用 pacman -U 重装旧包，并在 /etc/pacman.conf 中加入 IgnorePkg = opencode，避免下次 -Syu 覆盖。本文没有实际执行 Arch 回退，且该方式只适用于此前安装过该版本的机器。

完全回到 OpenCode 1 也可以，但需注意旧安装地址仍然提供 1.x：

curl -fsSL https://opencode.ai/install | bash

在 Debian 的 v2 安装上运行该命令会替换二进制（opencode2 shim 会保留），OpenCode 1 在 OpenCode 2 写入数据库之前和之后都能正常启动。两个主版本共用 ~/.local/share/opencode/opencode.db，OpenCode 2 在老表旁新增了 session_v2 和 session_message。OpenCode 2 会导入首次启动时已存在的会话，此后两个版本只列出各自创建的会话。因此回退只适合短时间测试；回退时应使用 OpenCode 1 的配置备份，不要把它指向已经按 OpenCode 2 结构改写的配置，迁移指南明确警告了这种用法。

如果系统仍保留 OpenCode 1，且不需要 v2 的新功能，可继续使用旧版本固定配置与插件，但应明确锁定版本，避免某一套安装方式悄悄升级，导致终端和自动化任务运行不同主版本。