OpenCode 安装失败：常见错误与解决方法

目录

• 先分清：是安装错误还是连接错误？
• 错误 1：error: opencode-ai's postinstall script was not run.
• 错误 2：brew install opencode 不管用
• 错误 3：command not found: opencode
• 错误 4：在 Ubuntu 上装了却找不到包
• 错误 5：我有 v1，想迁到 v2
• 错误 6：安装器要权限，或报 EACCES
• 错误 7：TUI 打开了，但模型不回答
• 错误 8：好好的，下午半截就没了
• 错误 9：装了两遍，行为变得诡异
• 快速清单
• 继续阅读

先分清：是安装错误还是连接错误？

这个区分能省你好几个小时，而几乎没人做。

如果 TUI 能打开——你能在终端里看到 OpenCode 的界面——安装就是成功的。之后的一切问题都是配置问题：API key、服务商、额度。别重装任何东西。

只有命令不存在、或安装器中途退出，才是真正的安装问题。往下读。

错误 1：error: opencode-ai's postinstall script was not run.

这是被搜索最多的错误，它有两个被人们混为一谈的不同原因。

原因 A：包管理器拦截了脚本。 npm 包用一个受信任的 postinstall 脚本下载你平台的原生二进制。出于安全设计，bun 和 pnpm 不会在未经明确许可的情况下运行 postinstall 脚本。如果你用它们安装时没加参数，包就是半装状态：装上了，但没有二进制。

# bun
bun install -g --trust @opencode/cli

# pnpm
pnpm add -g --allow-build=@opencode/cli @opencode/cli

原因 B：你装的是旧包。 看报错里的名字：opencode-ai。那是旧包。v2 的是 @opencode/cli。如果你照着 2025 年的教程装的，装错了。

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

就算你觉得自己没装过，也把卸载跑一遍。两个包在你的 PATH 上注册同一个 opencode 命令，产生的报错会和原因长得毫无关系。

错误 2：brew install opencode 不管用

不管用是因为它不存在。v2 文档写得很明白：不支持 Homebrew、AUR、Scoop 和 Chocolatey。

如果你搜了 brew install anomalyco/tap/opencode 一无所获，不是 tap 挂了：它根本不是官方渠道。从镜像站下散装 .exe 也一样。

真正能用的渠道：

渠道	命令
npm	npm install -g @opencode/cli
bun	bun install -g --trust @opencode/cli
pnpm	pnpm add -g --allow-build=@opencode/cli @opencode/cli
yarn	yarn global add @opencode/cli
官方脚本	curl -fsSL https://opencode.ai/v2/install | bash
Docker	ghcr.io/anomalyco/opencode 加版本标签

任何递给你 brew install 的 OpenCode 教程，要么是 2025 年的，要么来源不官方。当前清单在 OpenCode 文档里。

错误 3：command not found: opencode

这几乎从来不是安装的锅，是 PATH 的锅。

1. 新开一个终端。 用 curl 脚本安装的话，当前会话可能没加载那个目录。
2. 不想关终端就重载 shell：source ~/.bashrc 或 source ~/.zshrc。
3. 确认二进制落在哪：npm bin -g 会打印 npm 的全局目录。如果它不在你的 $PATH 里，加进去。

在 Windows 上这个错误更常见，因为装 Node 时 npm 的全局前缀有时没进系统 PATH。那是 Node 的问题，不是 OpenCode 的：修好一次，你所有全局包都跟着受益。

错误 4：在 Ubuntu 上装了却找不到包

没有 apt 或 snap 包。Linux 上的装法和 macOS 一模一样：走 npm/bun/pnpm/yarn，或 v2 官方脚本。

如果你在 Ubuntu 用了 curl 脚本但命令没出现，回到错误 3：是 PATH。脚本装进自己的目录，你的 shell 得知道那个目录。

错误 5：我有 v1，想迁到 v2

版本跳跃改了包名，坏就坏在这。对旧包跑 npm update -g 升不到 v2，因为它们在 registry 里是两个不同的包。

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

最后核对版本。如果它还报旧的，说明某个 PATH 目录里有个孤儿二进制：用 which -a opencode 找出来，删掉不属于的那一个。

错误 6：安装器要权限，或报 EACCES

Linux 和 macOS 上经典的全局 npm 问题：全局目录属于 root，你的用户写不进去。

错误但诱人的修法是 sudo npm install -g。能用，但会把 root 所有的文件留在你的 home 里，之后出问题。正确的修法是把 npm 的前缀改到你自己的 home 目录下，或用 nvm、fnm、volta 这类 Node 版本管理器——它们把一切装在你的 home 下，从根上消灭问题。

错误 7：TUI 打开了，但模型不回答

把开头的警告再说一遍，因为在这里白重装的人最多：这不是安装错误。

在 TUI 里运行 /connect。确认 API key 是对的，选中的服务商就是你付费的那家。如果你用的是 Z.ai 的 Coding Plan，端点很关键：有一个 Anthropic 兼容端点和一个 OpenAI 兼容端点，选错了意味着你套餐的额度永远不会被扣。这在Z.ai Coding Plan：Base URL 与 API key 配置里专门讲了。

错误 8：好好的，下午半截就没了

也不是 bug。那是你套餐的用量天花板。

OpenCode Go 按时间窗设限，不是单一月度额度。如果你下午半截用干了，撞的是 5 小时窗的上限，不是月度的。具体数字和怎么分配，在OpenCode Go：价格、使用限额，以及2026年是否值得订阅。

错误 9：装了两遍，行为变得诡异

症状：命令报出的版本和装的那个对不上，或者改配置不生效。

which -a opencode

这个命令会列出二进制存在的每一条路径。如果返回不止一个，你有互相打架的安装：通常是一个来自 npm、一个来自 curl 脚本，或者是很久以前试 brew 留下的。删掉不要的，只留一个。

快速清单

不想读上面全部的话，这是诊断顺序：

1. TUI 能打开吗？ → 问题不在安装，在 /connect。
2. which -a opencode → 不止一个就清理。
3. npm uninstall -g opencode-ai → 移除旧包。
4. npm install -g @opencode/cli → 装 v2 的。
5. 新开终端 → 排除 PATH。
6. 用 bun 或 pnpm → 加 --trust 或 --allow-build。
7. 永远别 brew。

继续阅读

• 完整教程：如何安装OpenCode：一步步用AI写代码
• 如果问题是额度：OpenCode Go：价格、使用限额，以及2026年是否值得订阅
• 如果问题是端点：Z.ai Coding Plan：Base URL 与 API key 配置