装不上怎么办？

安装过程遇到问题？这里有系统的排查方法。

问题 1：`command not found` / `opencode 不是内部或外部命令`

症状：

排查步骤：

1. 确认重启了终端

真的关掉窗口重新打开了吗？不是新建标签页，是关掉整个窗口。

2. 检查 OpenCode 装在哪了

macOS/Linux（官方脚本安装）：

如果显示文件存在，说明安装成功了，只是 PATH 没配好。

查看 PATH 是否包含安装目录：

如果没有输出，说明 PATH 没配好。

3. 手动添加到 PATH

macOS/Linux (zsh)：

macOS/Linux (bash)：

Windows（Scoop 安装）：

Scoop 会自动配置 PATH，如果没生效，重启 PowerShell。

问题 2：网络错误 / 下载超时

症状：

排查步骤：

1. 确认网络正常

如果百度也连不上，那是网络问题，不是 OpenCode 的问题。

2. 检查是否需要代理

如果你在公司/学校网络，可能需要配置代理。请看 1.3 网络配置。

3. 换其他安装方式

官方脚本从 GitHub 下载，如果 GitHub 访问不畅，可以试试：

npm 安装（npm 有国内镜像）：

Homebrew 安装（brew 有国内镜像）：

更多安装方式见 1.2a 备用安装方式。

问题 3：GitHub API 限流

症状：

error: rate limit exceeded

原因：

GitHub API 对匿名请求有频率限制（60 次/小时）。

解决方案：

等一小时后重试

或者用其他安装方式（npm、Homebrew 等）

问题 4：安装脚本提示缺少工具

症状：

Error: 'tar' is required but not installed.
# 或
Error: 'unzip' is required but not installed.

解决方案：

安装缺少的工具：

问题 5：Windows 执行策略限制

症状（安装 Scoop 时）：

Running scripts is disabled on this system

解决方案：

运行以下命令（只需一次）：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

如果公司策略不允许修改执行策略，可以用 Chocolatey（需要管理员权限）或直接下载二进制文件。

问题 6：想定位二进制文件在哪

问题 7：macOS 桌面应用无法启动

症状：

双击 OpenCode.app 没反应，或者弹出"无法打开，因为无法验证开发者"的提示。

原因：

这通常发生在以下情况：

从非官方渠道（如第三方网站）下载的安装包

自行编译的开发版本

网络问题导致下载不完整

官方发布的桌面应用已经过 Apple 签名和公证，正常情况下不会触发此问题。如果你从官方渠道下载仍遇到拦截，可以用以下命令解除：

然后重新双击打开。

提示

这个命令会清除应用的隔离属性（quarantine flag），告诉 macOS 你信任这个应用。只需执行一次。

问题 8：想干净卸载重装

OpenCode 提供了卸载命令：

会提示你要删除哪些内容（配置、数据、缓存等）。

如果 opencode 命令都跑不了，可以手动删除：

macOS/Linux（官方脚本安装）：

Homebrew 安装：

npm/pnpm/Yarn 安装：

Scoop 安装：

scoop uninstall opencode

Chocolatey 安装：

choco uninstall opencode

还是搞不定？

查看官方故障排除文档

在 GitHub Issues 搜索或提问

下一步

问题解决后，回到 1.2 安装验证安装是否成功。

::: tip 还是搞不定？
加入社群，和 2000+ 同路人一起交流，实时答疑。
:::

问题 1：command not found / opencode 不是内部或外部命令#

1. 确认重启了终端#

2. 检查 OpenCode 装在哪了#

3. 手动添加到 PATH#

问题 2：网络错误 / 下载超时#

1. 确认网络正常#

2. 检查是否需要代理#

3. 换其他安装方式#

问题 3：GitHub API 限流#

问题 4：安装脚本提示缺少工具#

问题 5：Windows 执行策略限制#

问题 6：想定位二进制文件在哪#

问题 7：macOS 桌面应用无法启动#

问题 8：想干净卸载重装#

还是搞不定？#

下一步#

问题 1：`command not found` / `opencode 不是内部或外部命令`

1. 确认重启了终端

2. 检查 OpenCode 装在哪了

3. 手动添加到 PATH

问题 2：网络错误 / 下载超时

1. 确认网络正常

2. 检查是否需要代理

3. 换其他安装方式

问题 3：GitHub API 限流

问题 4：安装脚本提示缺少工具

问题 5：Windows 执行策略限制

问题 6：想定位二进制文件在哪

问题 7：macOS 桌面应用无法启动

问题 8：想干净卸载重装

还是搞不定？

下一步