Open Code 文档

主题

首页文档搜索

OpenCode 备用安装方式实战教程 ​

📚 分类: 开发工具安装 ⏱️ 预计耗时: 10-15 分钟（取决于网络和选择的方式） 🎯 难度: 入门 🔧 环境要求: 根据你选择的安装方式，可能需要 macOS、Linux 或 Windows 系统，以及 Node.js（可选） 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

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

  • [ ] 掌握 Homebrew、npm、Scoop 等包管理器安装 OpenCode 的方法
  • [ ] 学会使用 Docker 容器化方式体验 OpenCode
  • [ ] 理解不同安装方式的特点和适用场景
  • [ ] 在官方一键脚本失效时，独立完成 OpenCode 的安装

最终效果 ​

你将在自己的电脑上成功安装 OpenCode，并能在终端中通过 opencode --version 命令看到版本号输出，为后续使用 AI 编程助手做好准备。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
操作系统macOS / Linux / Windows-
终端/命令行可正常使用-
(可选) Node.js≥ 18.0 (推荐 22+)node -v

🤔 为什么要准备这些？ OpenCode 是一款命令行工具，因此你需要一个能运行命令的环境。Node.js 是某些安装方式（如 npm）的必要依赖，如果你选择其他方式，则无需准备。

第 1 步：选择合适的安装方式 ​

🎯 目标：根据你的操作系统和偏好，确定最适合你的安装方法。

在开始操作前，先花一分钟了解各种安装方式的特点，选择最适合你的那一个。

安装方式适用系统特点推荐场景
HomebrewmacOS / Linux体验好，易于管理macOS 用户首选
npm跨平台需要 Node.js，通用性强开发者、Node.js 用户
ScoopWindows无需管理员权限，体验好Windows 用户首选
Docker跨平台隔离运行，不污染系统尝鲜试用、不想安装到系统
手动下载跨平台最直接，无依赖网络受限、特殊需求

💡 提示：如果你不确定选哪个，macOS 用户推荐 Homebrew，Windows 用户推荐 Scoop，Linux 用户推荐 Homebrew 或 npm。

第 2 步：macOS / Linux 用户 - 使用 Homebrew 安装 ​

🎯 目标：通过 Homebrew 包管理器安装 OpenCode。

📝 操作：

  1. 打开终端（Terminal）。
  2. 执行以下命令：
bash
# 添加 OpenCode 的官方仓库并安装
$ brew install anomalyco/tap/opencode

💡 提示：命令中的 anomalyco/tap/opencode 是官方维护的安装源，推荐使用。

⚠️ 注意：社区维护的 brew install opencode 可能更新较慢，不推荐使用。

✅ 验证：

bash
$ opencode --version
# 预期输出：
opencode version x.x.x

第 3 步：跨平台用户 - 使用 npm / pnpm / bun / yarn 安装 ​

🎯 目标：通过 JavaScript 包管理器安装 OpenCode。

📝 操作：

  1. 确保你已经安装了 Node.js (≥ 18.0)。在终端中运行 node -v 检查。
  2. 根据你使用的包管理器，选择一条命令执行：
bash
# npm
$ npm install -g opencode-ai

# pnpm
$ pnpm install -g opencode-ai

# bun
$ bun install -g opencode-ai

# yarn
$ yarn global add opencode-ai

🤔 为什么要用 -g 参数？ -g 代表全局安装，这意味着你可以在终端的任何位置直接运行 opencode 命令，而不需要进入特定的项目目录。

✅ 验证：

bash
$ opencode --version
# 预期输出：
opencode version x.x.x

第 4 步：Windows 用户 - 使用 Scoop 安装（推荐） ​

🎯 目标：通过 Scoop 包管理器安装 OpenCode。

📝 操作：

  1. 如果你还没有安装 Scoop：
    • 打开 PowerShell（非管理员模式，普通用户权限即可）。
    • 逐条运行以下命令：
powershell
# 设置 PowerShell 执行策略，允许运行脚本
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 从官网下载并安装 Scoop
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

# 安装 Git（Scoop 依赖 Git）
scoop install git

⚠️ 注意：如果你的 PowerShell 是以 管理员身份 运行的，安装 Scoop 时需要改用以下命令：

powershell
iex "& {$(irm get.scoop.sh)} -RunAsAdmin"
  1. 安装 OpenCode：
    • 确保 Scoop 安装成功，然后运行：
powershell
# 添加 extras bucket，opencode 在此 bucket 中
scoop bucket add extras

# 安装 opencode
scoop install extras/opencode

✅ 验证：

powershell
$ opencode --version
# 预期输出：
opencode version x.x.x

第 5 步：Windows 用户 - 使用 Chocolatey 安装（备选） ​

🎯 目标：通过 Chocolatey 包管理器安装 OpenCode。

📝 操作：

  1. 以 管理员身份 打开 PowerShell。
  2. 执行以下命令：
powershell
# 安装 opencode
choco install opencode

⚠️ 注意：Chocolatey 安装需要管理员权限，这是它与 Scoop 的主要区别。

✅ 验证：

powershell
$ opencode --version
# 预期输出：
opencode version x.x.x

第 6 步：跨平台用户 - 使用 Docker 尝鲜 ​

🎯 目标：通过 Docker 容器运行 OpenCode，不安装到系统。

📝 操作：

  1. 确保你已经安装并启动了 Docker。
  2. 在终端中运行以下命令：
bash
# 运行 OpenCode 容器，启动后会自动进入交互模式
$ docker run -it --rm ghcr.io/anomalyco/opencode

💡 提示：-it 参数让容器以交互模式运行，--rm 参数在容器退出后自动删除。

✅ 验证： 你会看到 OpenCode 的交互界面启动，表明运行成功。

⚠️ 限制说明： Docker 容器默认只能访问容器内部的文件，无法读写你电脑上的文件。如果你想让它读写当前目录的文件，需要挂载目录：

bash
# 将当前目录挂载到容器的 /workspace 目录
$ docker run -it --rm -v $(pwd):/workspace -w /workspace ghcr.io/anomalyco/opencode

🤔 为什么要挂载目录？ -v $(pwd):/workspace 将你电脑的当前目录（$(pwd)）映射到容器内的 /workspace 目录；-w /workspace 设置容器的工作目录为 /workspace。这样，OpenCode 在容器内操作 /workspace 就相当于操作你电脑上的当前目录了。

第 7 步：其他安装方式（备选） ​

🎯 目标：了解并掌握其他几种安装方法，以备不时之需。

7.1 手动下载 ​

如果以上方法都不适用，你可以直接从 GitHub Releases 页面下载二进制文件。

📝 操作：

  1. 访问 OpenCode 的 GitHub Releases 页面（链接请搜索 “opencode releases”）。
  2. 根据你的操作系统和架构（如 linux-amd64、darwin-arm64），下载对应的压缩包。
  3. 解压文件，将 opencode 可执行文件移动到一个在 PATH 环境变量中的目录（例如 /usr/local/bin 或 ~/bin）。
bash
# 示例：将 opencode 移动到 /usr/local/bin
$ sudo mv ~/Downloads/opencode /usr/local/bin/opencode

✅ 验证：在终端中运行 opencode --version。

7.2 Arch Linux ​

如果你使用 Arch Linux，可以直接从官方仓库安装。

📝 操作：

bash
# 稳定版（推荐）
$ sudo pacman -S opencode

# AUR 最新版（需要 paru 或 yay 辅助）
$ paru -S opencode-bin

✅ 验证：在终端中运行 opencode --version。

7.3 Mise ​

Mise 是一个多语言版本管理器，也可以用来安装 OpenCode。

📝 操作：

bash
# 使用 mise 全局安装 opencode
$ mise use -g github:anomalyco/opencode

✅ 验证：在终端中运行 opencode --version。

进阶技巧（可选） ​

了解安装位置 ​

不同安装方式会将 OpenCode 放置在不同的位置，了解这些有助于你进行管理和排错。

安装方式二进制文件位置配置文件位置
官方脚本~/.opencode/bin/opencode~/.config/opencode/opencode.json
npm/pnpm/bun/yarn全局 node_modules 中同上
Homebrew/opt/homebrew/bin/opencode (Apple Silicon) 或 /usr/local/bin/opencode (Intel)同上
Scoop~/scoop/apps/opencode/current/opencode.exe同上
ChocolateyC:\ProgramData\chocolatey\bin\opencode.exe同上

常见问题 (FAQ) ​

Q1: 安装时提示网络超时怎么办？A: 这通常是因为网络环境不稳定。你可以：

  1. 更换安装方式，例如从 brew 换为 npm。
  2. 使用 Docker 方式，因为 Docker 镜像可能更容易获取。
  3. 尝试使用代理或更换网络环境。

Q2: 安装后运行 opencode 提示“命令未找到”怎么办？A: 这表示 opencode 可执行文件没有被系统找到。请检查：

  1. 你的安装方式是否成功完成。
  2. opencode 的安装目录是否在 PATH 环境变量中。你可以尝试重新登录终端或重启电脑。

Q3: 公司电脑有安装限制，我该怎么办？A: 推荐使用 Scoop（Windows）或 npm（跨平台），因为它们通常不需要管理员权限。或者，使用 Docker 容器化方式，完全不修改系统文件。

Q4: npm install -g opencode-ai 报权限错误怎么办？A: 这是 npm 的常见问题。解决方案：

  1. （推荐）不要使用 sudo，而是配置 npm 的全局安装路径。请参考 npm 官方文档。
  2. （临时）在命令前加上 sudo（Mac/Linux）或以管理员身份运行终端（Windows）。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 多种安装方式：我们学习了 Homebrew、npm、Scoop、Docker 等主流安装方法，并了解了它们各自的适用场景。
  2. 灵活应对：当官方一键脚本失效时，你学会了如何根据自身环境选择备选方案。
  3. 安装验证：你学会了通过 opencode --version 命令来确认安装是否成功。

下一步 ​

安装完成后，请返回主教程的 “1.2 安装” 章节，完成最后的验证安装步骤。

如果你想继续深入，建议学习：

💡 练习任务：尝试使用 Docker 方式运行 OpenCode，并挂载一个包含代码的目录，体验一下在沙箱环境中工作的感觉。

yaml

## 相关文档

- [OpenCode AI 编程助手安装实战教程](/docs/huan-jing-da-jian/opencode-ai-bian-cheng-zhu-shou-an-zhuang-shi-zhan-jiao-cheng.html)
- [OpenCode 实战教程：从零配置到免费接入顶级 AI 模型](/docs/huan-jing-da-jian/opencode-shi-zhan-jiao-cheng-cong-ling-pei-zhi-dao-mian-fei-jie-ru-ding-ji-ai-mo-xing.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.