OpenCode 中文教程

简体中文

English

简体中文

English

Appearance

装不上怎么办？ ​

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

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

症状：

bash
zsh: command not found: opencode
# 或 Windows 上
'opencode' is not recognized as an internal or external command

排查步骤：

1. 确认重启了终端 ​

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

2. 检查 OpenCode 装在哪了 ​

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

bash
ls -la ~/.opencode/bin/opencode

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

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

bash
echo $PATH | tr ':' '\n' | grep opencode

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

3. 手动添加到 PATH ​

macOS/Linux (zsh)：

bash
echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

macOS/Linux (bash)：

bash
echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows（Scoop 安装）：

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

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

症状：

curl: (7) Failed to connect to opencode.ai port 443
# 或
Error: connect ETIMEDOUT

排查步骤：

1. 确认网络正常 ​

bash
curl -I https://www.baidu.com

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

2. 检查是否需要代理 ​

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

3. 换其他安装方式 ​

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

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

    bash
    npm install -g opencode-ai

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

    bash
    brew install anomalyco/tap/opencode

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

问题 3：GitHub API 限流 ​

症状：

error: rate limit exceeded

原因：

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

解决方案：

  1. 等一小时后重试
  2. 或者用其他安装方式（npm、Homebrew 等）

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

症状：

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

解决方案：

安装缺少的工具：

bash
# macOS（一般自带）
# 如果没有，安装 Xcode 命令行工具：
xcode-select --install

# Ubuntu/Debian
sudo apt install -y tar unzip

# CentOS/RHEL
sudo yum install -y tar unzip

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

症状（安装 Scoop 时）：

Running scripts is disabled on this system

解决方案：

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

powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

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

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

bash
# macOS/Linux
which opencode

# Windows PowerShell
Get-Command opencode | Select-Object Source

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

症状：

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

原因：

这通常发生在以下情况：

  • 从非官方渠道（如第三方网站）下载的安装包
  • 自行编译的开发版本
  • 网络问题导致下载不完整

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

bash
xattr -cr /Applications/OpenCode.app

然后重新双击打开。

提示

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

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

OpenCode 提供了卸载命令：

bash
opencode uninstall

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

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

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

bash
# 删除二进制
rm -rf ~/.opencode/bin

# 删除配置
rm -rf ~/.config/opencode

# 删除数据、缓存和状态
rm -rf ~/.local/share/opencode
rm -rf ~/.cache/opencode
rm -rf ~/.local/state/opencode

Homebrew 安装：

bash
brew uninstall opencode

npm/pnpm/Yarn 安装：

bash
# npm
npm uninstall -g opencode-ai

# pnpm
pnpm uninstall -g opencode-ai

# Yarn
yarn global remove opencode-ai

Scoop 安装：

powershell
scoop uninstall opencode

Chocolatey 安装：

powershell
choco uninstall opencode

还是搞不定？ ​

  1. 查看 官方故障排除文档
  2. 在 GitHub Issues 搜索或提问

下一步 ​

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

还是搞不定？

加入社群，和 2000+ 同路人一起交流，实时答疑。