opencode安装完整指南：七种方法详解与常见问题

本文详细讲解 opencode安装的全部流程，覆盖 macOS、Linux和Windows三大平台。从一键脚本到包管理器，从环境配置到模型连接，帮助你在十分钟内完成 opencode安装并开始使用。

为什么需要了解 opencode安装

OpenCode是由Anomaly公司开发的开源AI编程代理，在 GitHub 上拥有超过 184,000 颗星标，累计提交超过 14,800 次。它支持在终端界面、桌面应用和 IDE 扩展三种环境中运行，能够接入 Anthropic、OpenAI、Google、DeepSeek 等 75 家以上的 LLM 提供商。正确的 opencode安装是使用这一工具的第一步，也是决定后续使用体验的关键环节。

安装前的准备工作

在开始安装之前，需要确认系统满足以下条件。不同安装方式对系统环境的要求有所差异，选择适合自身环境的方式可以大幅简化安装流程。

终端方面，OpenCode 建议使用 WezTerm、Alacritty、Ghostty 或 Kitty 这类现代终端模拟器。系统默认终端可能在界面渲染上存在问题。

方式一：一键安装脚本

一键安装脚本是官方推荐的安装方式，适用于 macOS 和 Linux 系统。该脚本会自动检测操作系统和处理器架构，从 GitHub 发布页面下载对应的二进制文件，并将其放置到系统的可执行路径中。

执行一键安装命令

在终端中执行以下命令即可完成 opencode安装：

curl -fsSL https://opencode.ai/install | bash

该命令的执行过程包括：下载安装脚本，脚本自动判断操作系统类型和 CPU 架构（x86_64 或 ARM64），从 GitHub Releases 获取最新版本的二进制文件，最后将文件安装到预设目录中。

安装目录选择

一键安装脚本按照以下优先级选择安装目录：

1. $OPENCODE_INSTALL_DIR — 自定义安装目录
2. $XDG_BIN_DIR — XDG 基础目录规范路径
3. $HOME/bin — 用户二进制目录
4. $HOME/.opencode/bin — 默认回退目录

如需自定义安装位置，可以在执行 opencode安装时指定目录：

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

验证安装结果

安装完成后通过版本检查命令确认是否成功：

opencode --version

如果输出类似 v1.17.15 的版本号，说明已经成功安装。如果提示"command not found"，说明安装目录未在 PATH 环境变量中，需要手动添加。

方式二：npm 全局安装

对于已经使用 Node.js 进行开发的用户，通过 npm 安装是最便捷的方式。这种方法支持所有操作系统，包括 Windows。

通过 npm 安装

npm install -g opencode-ai@latest

需要特别注意的是，npm 上的包名称是 opencode-ai，而不是 opencode。opencode 这个名称对应的是另一个不同的项目，如果误装则无法获得正确的命令集合。

使用其他包管理器

# 使用 bun
bun install -g opencode-ai

# 使用 pnpm
pnpm install -g opencode-ai

# 使用 yarn
yarn global add opencode-ai

npm 安装注意事项

npm 全局安装需要 Node.js 18 或更高版本。如果遇到引擎版本错误，先用以下命令检查当前 Node.js 版本：

node --version

如果版本低于 18，建议通过 nvm 升级：

nvm install --lts
nvm use --lts

升级完成后重新执行安装命令。如果遇到权限错误，可以检查 npm 的全局路径配置，或使用 npx 临时运行：

npx opencode-ai@latest

方式三：Homebrew（macOS / Linux）

Homebrew 用户可以通过官方 Tap 完成安装。这种方式最大的优势在于后续的更新维护非常方便。

通过官方 Tap 安装

brew install anomalyco/tap/opencode

这是推荐的方式，由 OpenCode 开发团队直接维护，新版本发布后通常在数小时内即可获取。

通过 Homebrew 核心仓库安装

brew install opencode

这种方式由 Homebrew 核心团队维护，更新频率相对较低，可能存在 1 至 2 周的延迟。

验证与更新

# 验证安装
opencode --version

# 后续更新
brew upgrade opencode

方式四：Windows 平台安装

Windows 用户有多种选择，推荐程度从高到低排列如下。

推荐方案：WSL + 一键安装

WSL（Windows Subsystem for Linux）是 Windows 上运行 OpenCode 的最佳环境。它不仅提供了完整的终端支持，还能避免原生 Windows 终端可能出现的界面渲染问题。

第一步：安装 WSL

以管理员身份打开 PowerShell，执行：

wsl --install

该命令会自动安装 Ubuntu 发行版和 WSL2 内核。安装完成后需要重新启动计算机。

第二步：在 WSL 中完成安装

打开 WSL 终端（Ubuntu），执行一键安装命令：

curl -fsSL https://opencode.ai/install | bash

第三步：访问 Windows 文件系统

WSL 中的 Windows 文件位于 /mnt/c/ 路径下。例如，要访问 C:\Users\YourName\project，在 WSL 终端中输入：

cd /mnt/c/Users/YourName/project
opencode

如需获得更好的文件系统性能，建议将项目代码复制到 WSL 文件系统中（如 ~/code/ 目录）。

备选方案：Scoop

scoop install opencode

备选方案：Chocolatey

choco install opencode

备选方案：npm 直接安装

npm install -g opencode-ai@latest

需要注意的是，OpenCode 的终端界面在原生 Windows 终端（cmd 或 PowerShell）上可能出现渲染问题。如果使用原生 Windows 方式安装，建议配合 Windows Terminal 使用。

方式五：桌面应用

OpenCode 提供桌面应用 Beta 版本，适合偏好图形界面的用户。

各平台安装包

安装包可从 GitHub Releases 页面或 OpenCode 官网获取。

通过包管理器安装

# macOS Homebrew
brew install --cask opencode-desktop

# Windows Scoop
scoop bucket add extras
scoop install extras/opencode-desktop

方式六：Docker

对于希望在隔离环境中使用 OpenCode 的用户，可以通过 Docker 安装：

docker run -it --rm ghcr.io/anomalyco/opencode

这种方法适用于 CI/CD 流水线、临时开发环境或不想在本地系统上安装额外软件的场景。-it 参数是必需的，因为 OpenCode 使用交互式终端界面。

方式七：手动安装

对于无法使用上述自动安装方式的环境，可以从 GitHub Releases 页面手动下载二进制文件。

各平台手动安装命令

# macOS Apple Silicon
wget https://github.com/anomalyco/opencode/releases/latest/download/opencode-darwin-arm64
chmod +x opencode-darwin-arm64
mv opencode-darwin-arm64 /usr/local/bin/opencode

# macOS Intel
wget https://github.com/anomalyco/opencode/releases/latest/download/opencode-darwin-amd64
chmod +x opencode-darwin-amd64
mv opencode-darwin-amd64 /usr/local/bin/opencode

# Linux x86_64
wget https://github.com/anomalyco/opencode/releases/latest/download/opencode-linux-amd64
chmod +x opencode-linux-amd64
mv opencode-linux-amd64 /usr/local/bin/opencode

# Linux ARM64
wget https://github.com/anomalyco/opencode/releases/latest/download/opencode-linux-arm64
chmod +x opencode-linux-arm64
mv opencode-linux-arm64 /usr/local/bin/opencode

安装方式对比

为了便于选择，以下对七种 opencode安装方法进行全面对比：

各平台推荐的安装方案如下：

• macOS 用户：优先选择 Homebrew 或一键安装脚本
• Linux 用户：优先选择一键安装脚本
• Windows 用户：优先选择 WSL 加一键安装脚本
• 全平台通用：npm 安装方式

安装后的环境配置

完成 opencode安装后，需要进行以下配置才能正常使用。

配置 LLM 提供商

OpenCode 本身不包含模型，需要连接外部 LLM 提供商。在终端中运行 opencode 进入界面后，执行 /connect 命令，从列表中选择提供商并粘贴 API 密钥。

对于初次使用的用户，推荐以下方案：

OpenCode Zen：由 OpenCode 团队精选的模型列表，经过测试验证。执行 /connect 后选择 OpenCode Zen，浏览器跳转到 opencode.ai/auth，登录后创建 API Key 即可。

Anthropic Claude：执行 /connect 选择 Anthropic，通过浏览器授权 Claude Pro/Max 订阅。

GitHub Copilot：执行 /connect 选择 GitHub Copilot，在 github.com/login/device 输入设备码完成授权。

初始化项目

# 进入项目目录
cd /path/to/your-project

# 启动 OpenCode
opencode

# 在界面中执行初始化
/init

/init 命令会让 OpenCode 分析项目结构，生成 AGENTS.md 文件，记录项目的编码约定和架构信息。建议将该文件提交到 Git 仓库，以便团队成员共享。

选择模型

在 OpenCode 界面中执行 /models 命令，查看当前提供商可用的模型列表，选择合适的模型后即可开始使用。

常见问题

安装后提示 command not found

这是最常见的问题，原因是安装目录未在系统 PATH 环境变量中。解决方法如下：

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

如果通过 npm 安装后出现此问题，可以找到 npm 的全局路径：

npm prefix -g

然后将该路径下的 bin 目录添加到 PATH 中。

npm 引擎版本错误

错误信息为 npm ERR! engine: requires node >=18。这意味着当前 Node.js 版本过低。使用 nvm 升级即可：

nvm install --lts
nvm use --lts

完成后重新执行 npm 安装命令。

企业网络代理问题

在企业网络环境中，一键安装脚本可能被防火墙阻止。此时可以使用 npm 安装方式替代：

npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port
npm install -g opencode-ai@latest

Windows 终端关闭问题

在原生 Windows 终端中，通过 Ctrl+D 或 /exit 退出时可能关闭整个窗口。这是已知问题（GitHub Issue #22003），解决方案是使用 WSL 而非原生 Windows 终端。

WSL 插件加载失败

在 Windows 上通过 npm 安装的插件无法在 WSL 中加载。解决方法是在 WSL 内部安装 Bun：

curl -fsSL https://bun.sh/install | bash

然后在 WSL 中执行插件安装操作。

旧版本残留

如果系统中存在 0.1.x 版本的 OpenCode，建议先卸载再执行新版本安装：

npm uninstall -g opencode-ai

不同安装方式的更新方法

更新完成后使用 opencode --version 确认版本号。

各平台推荐安装流程

macOS 推荐流程

# 第一步：安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 第二步：安装 OpenCode
brew install anomalyco/tap/opencode

# 第三步：验证安装
opencode --version

# 第四步：启动并连接提供商
opencode
/connect

Linux 推荐流程

# 第一步：安装 OpenCode
curl -fsSL https://opencode.ai/install | bash

# 第二步：验证安装
opencode --version

# 第三步：启动并连接提供商
opencode
/connect

Windows 推荐流程

# 第一步：安装 WSL（管理员 PowerShell）
wsl --install

# 重启后，在 WSL 终端中执行
# 第二步：安装 OpenCode
curl -fsSL https://opencode.ai/install | bash

# 第三步：验证安装
opencode --version

# 第四步：启动并连接提供商
opencode
/connect

常见问题

opencode安装需要什么条件？

macOS 和 Linux 用户只需要终端环境即可通过一键脚本完成安装。Windows 用户推荐使用 WSL。如果选择 npm 安装方式，则需要 Node.js 18 以上版本。无论哪种方式，后续使用都需要连接至少一个 LLM 提供商。

完成 opencode安装后如何连接模型？

安装完成后，在终端中运行 opencode 进入界面，输入 /connect 命令，从列表中选择提供商，按照提示粘贴 API 密钥即可。之后通过 /models 命令选择具体模型。

Windows 上推荐哪种 opencode安装方式？

最推荐的方式是先安装 WSL（Windows Subsystem for Linux），然后在 WSL 中使用一键安装脚本。这种方式能够获得完整的终端支持和最佳的文件系统性能。作为替代，也可以通过 npm 直接在 Windows 上安装。

如何更新已安装的 OpenCode？

根据安装方式的不同，更新命令也有所差异：npm 安装的使用 npm i -g opencode-ai@latest，Homebrew 安装的使用 brew upgrade opencode，一键脚本安装的重新运行脚本即可。截至 2026 年 7 月，最新版本为 v1.17.15。

npm 安装时包名是什么？

npm 上的包名是 opencode-ai，不是 opencode。opencode 是另一个不同项目，如果误装会导致命令不可用。执行 npm install -g opencode-ai@latest 即可完成正确的安装。

opencode安装后找不到命令怎么办？

这通常是因为安装目录不在系统 PATH 中。一键脚本默认安装到 $HOME/.opencode/bin，将该目录添加到 PATH 即可。npm 安装的则找到 npm 全局路径下的 bin 目录添加即可。

OpenCode 支持哪些操作系统？

OpenCode 支持 macOS（Intel 和 Apple Silicon）、Linux（x86_64 和 ARM64）以及 Windows。所有平台均可通过 npm 完成安装，macOS 和 Linux 还支持一键脚本和 Homebrew，Windows 额外支持 Scoop 和 Chocolatey。

npm 安装需要什么版本的 Node.js？

npm 安装方式需要 Node.js 18 或更高版本。可以通过 node --version 检查当前版本。如果版本过低，建议使用 nvm 安装 LTS 版本后再执行安装。

一键脚本安装的文件存放在什么位置？

一键脚本按照优先级依次检查以下目录：$OPENCODE_INSTALL_DIR、$XDG_BIN_DIR、$HOME/bin、$HOME/.opencode/bin。如果以上目录都不存在或不可写，脚本会创建 $HOME/.opencode/bin 目录进行安装。

桌面版和终端版有何区别？

桌面版通过图形界面运行，适合偏好可视化操作的用户。终端版通过命令行界面运行，资源占用更少。两者功能基本一致，可以按需选择。桌面版可以从官网或 GitHub Releases 下载安装包完成安装。

本文信息综合自 OpenCode 官方文档（opencode.ai/docs）、GitHub 仓库（github.com/anomalyco/opencode）及各第三方技术媒体报道。数据更新至 2026 年 7 月，OpenCode 最新版本为 v1.17.15。