Open Code 文档

主题

首页文档搜索

OpenCode 安装故障排除实战指南 ​

📚 分类: 工具安装与配置 ⏱️ 预计耗时: 15-20 分钟 🎯 难度: 入门 🔧 环境要求: 能访问互联网的电脑（Mac / Linux / Windows）

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 系统地诊断并解决 opencode 命令找不到的问题
  • [ ] 处理网络错误、下载超时和 GitHub API 限流
  • [ ] 在 Windows 上正确配置执行策略
  • [ ] 掌握干净卸载并重新安装 OpenCode 的方法

最终效果 ​

你将能够成功运行 opencode 命令，并启动你的 AI 编程助手，而不再被各种安装错误所困扰。

前置准备 ​

在开始排错前，请确认你已经尝试过基本的安装步骤（例如，通过官方脚本或 npm 安装过 OpenCode）。

1. 打开一个全新的终端窗口 ​

这是排查问题的第一步，也是很多人忽略的一步。请 关闭 当前所有终端窗口，然后重新打开一个。这样可以确保新窗口加载了最新的环境变量（PATH 等）。

💡 提示: 是“关闭整个窗口”，而不是“新建标签页”。

第 1 步：诊断并解决“命令找不到”错误 ​

🎯 目标：当你在终端输入 opencode 后，看到 command not found 或 'opencode' is not recognized 错误时，能找到并解决问题。

📝 操作：

首先，我们来确认 OpenCode 是否真的安装了。

  1. 检查安装文件是否存在

    bash
    # macOS / Linux
ls -la ~/.opencode/bin/opencode
    • ✅ 如果显示文件信息：说明安装成功，问题出在系统找不到这个文件的路径（PATH 配置问题）。
    • ❌ 如果提示 No such file or directory：说明安装没有成功，请跳到本教程末尾的“进阶技巧：干净卸载并重装”部分。

  2. 检查 PATH 环境变量 如果你确认文件存在，接下来检查系统是否知道去哪里找它。

    bash
    # macOS / Linux
echo $PATH | tr ':' '\n' | grep opencode
    • ✅ 如果有输出（例如 /home/youruser/.opencode/bin）：说明 PATH 配置正确，但可能没有在当前终端生效。请回到“前置准备”部分，确保你打开了 全新的终端窗口。
    • ❌ 如果没有输出：说明 PATH 没有配置好。请继续下一步。

  3. 手动配置 PATH 根据你使用的 Shell，执行对应的命令：

    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 (PowerShell): Scoop 安装通常会自动配置。如果没生效，请尝试：

    powershell
    # 重启 PowerShell 窗口

✅ 验证：完成以上步骤后，在新终端中输入 opencode --version，你应该能看到类似 opencode version x.x.x 的输出。

⚠️ 常见错误：在 Windows 上，如果 opencode 不是内部或外部命令，且你使用了 scoop 安装，请尝试运行 scoop reset opencode 来修复路径。

第 2 步：处理网络错误与下载超时 ​

🎯 目标：解决安装过程中因网络问题导致的 Failed to connect 或 ETIMEDOUT 错误。

📝 操作：

  1. 确认网络连通性 首先，确认你的计算机本身可以上网。

    bash
    # 尝试连接一个国内网站
curl -I https://www.baidu.com
    • ✅ 如果成功：说明网络正常，问题可能出在无法访问 OpenCode 或 GitHub 的服务器。
    • ❌ 如果失败：请先检查你的网络连接（Wi-Fi、网线、路由器等）。

  2. 检查是否需要配置代理 如果你在公司、学校或使用 VPN 的网络环境下，可能需要配置代理。

  3. 更换安装方式（推荐） 官方脚本默认从 GitHub 下载，如果你的网络访问 GitHub 不畅，可以尝试以下方式：

    • 使用 npm 安装（推荐）：npm 通常有更快的国内镜像。
      bash
      npm install -g opencode-ai
    • 使用 Homebrew 安装（仅限 macOS）：
      bash
      brew install anomalyco/tap/opencode

✅ 验证：使用新的方式安装后，在终端输入 opencode，看是否成功启动。

第 3 步：解决 GitHub API 限流问题 ​

🎯 目标：解决安装时出现的 rate limit exceeded 错误。

📝 操作：

  • 原因：GitHub 对未登录的匿名请求有频率限制（每小时 60 次）。
  • 解决方案：
    1. 等待：最简单的方法是等待一小时后重试。
    2. 更换安装方式：立即解决问题的最佳方法是使用 第 2 步 中提到的 npm 或 Homebrew 方式安装，这些方式不受 GitHub API 限制。

✅ 验证：使用 npm 或 Homebrew 安装成功后，运行 opencode --version。

第 4 步：解决“缺少工具”错误 ​

🎯 目标：解决安装脚本提示 Error: 'tar' is required 或 Error: 'unzip' is required 等问题。

📝 操作：

这些是系统解压文件的必备工具。根据你的系统安装它们：

  • macOS:

    bash
    # 如果没有安装 Xcode 命令行工具，运行此命令
xcode-select --install

  • Ubuntu / Debian:

    bash
    sudo apt install -y tar unzip

  • CentOS / RHEL:

    bash
    sudo yum install -y tar unzip

✅ 验证：安装完成后，重新运行 OpenCode 的安装脚本。

第 5 步：解决 Windows 执行策略限制 ​

🎯 目标：解决在 Windows 上通过 Scoop 安装时，出现的 Running scripts is disabled on this system 错误。

📝 操作：

  1. 以管理员身份运行 PowerShell：在开始菜单找到 PowerShell，右键点击，选择“以管理员身份运行”。
  2. 修改执行策略：在管理员 PowerShell 中运行以下命令：
    powershell
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  3. 确认修改：当提示是否要更改执行策略时，输入 Y 并按回车。

💡 提示：RemoteSigned 策略允许运行本地脚本和来自互联网的已签名脚本，是一个相对安全的设置。

✅ 验证：关闭管理员 PowerShell，重新打开一个普通 PowerShell 窗口，再次尝试安装 Scoop 或 OpenCode。

⚠️ 如果公司策略禁止修改：请尝试使用 Chocolatey（需要管理员权限）或直接下载 OpenCode 的二进制文件进行安装。

第 6 步：定位二进制文件位置 ​

🎯 目标：如果你想确切知道 opencode 这个程序在你的电脑上存放在哪里。

📝 操作：

  • macOS / Linux:
    bash
    which opencode
  • Windows PowerShell:
    powershell
    Get-Command opencode | Select-Object Source

✅ 验证：命令会输出一个文件路径，例如 /usr/local/bin/opencode 或 C:\Users\YourName\scoop\shims\opencode.exe。

进阶技巧：干净卸载并重装 ​

🎯 目标：当问题无法解决时，彻底删除 OpenCode 及其所有数据，然后重新安装。

📝 操作：

方法一：使用卸载命令（推荐，如果 opencode 命令还能用） ​

bash
opencode uninstall

根据提示，选择你要删除的内容（配置、数据、缓存等）。

方法二：手动删除（当 opencode 命令无法使用时） ​

macOS / Linux (官方脚本安装):

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

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

# 3. 删除数据和缓存
rm -rf ~/.local/share/opencode
rm -rf ~/.cache/opencode

Homebrew 安装:

bash
brew uninstall opencode

npm 安装:

bash
npm uninstall -g opencode-ai

Scoop 安装 (Windows):

powershell
scoop uninstall opencode

Chocolatey 安装 (Windows):

powershell
choco uninstall opencode

✅ 验证：删除后，在终端输入 opencode，应该会再次报 command not found。此时，你可以参照官方文档重新进行安装。

常见问题 (FAQ) ​

Q1: 我按照教程做了，但还是搞不定怎么办？A: 别担心！你可以：

  1. 查看 OpenCode 的官方故障排除文档。
  2. 在 GitHub Issues 页面搜索或提问。
  3. 加入 OpenCode 中文社区微信群，与 500+ 同路人交流。

Q2: 如何确认我最终安装成功了？A: 打开一个 全新的终端窗口，输入 opencode。如果看到一个欢迎界面或提示输入 API Key，就说明安装成功了。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 系统化排错：遇到问题不要慌，从“文件是否存在”到“PATH 配置”再到“网络环境”，一步步排查。
  2. 灵活变通：当一种安装方式受阻时，尝试 npm 或 Homebrew 等替代方案。
  3. 彻底重装：掌握了如何干净地卸载并重装 OpenCode，是解决顽固问题的终极手段。

下一步 ​

问题解决后，你可以继续学习：

💡 练习任务：尝试使用 npm 和 Homebrew 两种不同的方式在你的另一台电脑上安装 OpenCode，体验不同安装方式的优缺点。

yaml

## 相关文档

- [OpenCode 故障排除实战指南](/docs/chang-jian-cuo-wu/opencode-gu-zhang-pai-chu-shi-zhan-zhi-nan.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.