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 設定