当前位置：首页 > news >正文

OpenCode 安装指南：5 分钟完成选型、编译与验证

news 2026/8/29 9:59:19

OpenCode 安装指南：5 分钟完成选型、编译与验证

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode

OpenCode 是一个开源的终端 AI 编程代理：它直接运行在终端里，能读写项目文件、执行 shell 命令、管理编码会话，并允许在 Anthropic、OpenAI、Google 以及本地模型等提供商之间切换。完成 OpenCode 安装后，即可在任意项目目录中执行opencode启动一次 AI 辅助编码会话。整个过程分四步：自检、选型、执行安装、验证。

安装前自检：系统支持与前置依赖

先确认环境在支持矩阵内，可以避开大部分“命令找不到、架构不匹配”一类的问题。

操作系统与架构支持

平台	架构	说明
Linux	x64、arm64	支持直接安装
macOS	x64、arm64	支持直接安装
Windows	—	需经 WSL 使用，无原生包

前置依赖

所有路线都需要一个可用的 shell（bash 或 zsh）与网络访问。
源码编译路线额外需要 Bun 运行时和 Git。
包管理器路线需要对应管理器（npm / bun / pnpm / yarn / Homebrew / paru）。

安装方式速查表

路线	适合人群	所需环境	维护成本
一键脚本	普通用户、首次安装	bash + 网络	最低，重跑脚本即可升级
包管理器	有固定包管理工作流的人	npm、bun、pnpm、yarn、Homebrew、AUR	低，单条命令升级
源码编译	开发者、需要最新未发布改动的人	Bun + Git	较高，依赖手动构建

拿不准时，从一键脚本路线开始。

一键脚本路线：给追求最少操作的人

这条路线适合希望在几分钟后让 OpenCode 跑起来的用户，不需要理解底层构建链。

执行命令：

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

关键注意点：

脚本自动识别操作系统与架构并下载对应二进制，默认安装到~/.opencode/bin，并把 PATH 写入 shell 配置文件。
变更安装目录：OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash可装到系统级目录；XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash可指定用户自定义目录。
脚本支持--version固定版本、--no-modify-path跳过 PATH 修改，完整参数见仓库根目录install脚本顶部的帮助输出。

包管理器路线：给偏好系统级管理的人

用 Homebrew 安装 macOS 版

brew install sst/tap/opencode

Arch Linux 安装

paru -S opencode-bin

其余发行版没有专门的分发包，使用一键脚本或源码编译。

Node.js 系包管理器

npm i -g opencode-ai@latest bun add -g opencode-ai@latest pnpm add -g opencode-ai@latest yarn global add opencode-ai@latest

关键注意点：该路线装进包管理器的全局目录，升级与卸载由对应的upgrade/uninstall命令负责。同一台机器不要混用多种路线（比如同时装脚本版和 npm 版），否则opencode命令实际指向哪个版本会变得不确定。

源码编译路线：给要改代码的开发者

适用场景：需要向 OpenCode 贡献代码，或依赖尚未进入官方发布的改动。

执行命令：

git clone https://gitcode.com/GitHub_Trending/openc/opencode cd opencode bun install bun dev bun build

关键注意点：

根目录package.json将 packageManager 锁定为 bun@1.3.14，先装对应版本的 Bun，避免版本漂移。
bun install安装整个 monorepo 的依赖；bun dev以开发模式运行主程序；bun build产出生产版本。
主程序源码位于packages/opencode；若要参与开发，另外看infra/与CONTRIBUTING.md。

统一验证与首次启动引导

三条路线共用同一套验证。先确认版本：

opencode --version

输出版本号即代表安装成功。接着在任意项目目录内执行opencode完成首次启动，系统会引导你依次完成：选择 AI 模型提供商（Anthropic、OpenAI、Google、本地模型等）、配置 API 密钥、设置个性化偏好、测试基础功能。启动后界面顶部显示当前版本，中部列出可用斜杠命令（/help、/models、/init、/sessions等），底部显示当前选中的模型，用来确认环境与模型都配置到位。

故障速查

现象	原因	处理
`opencode: command not found`	安装目录不在 PATH 中	先临时执行`export PATH=$HOME/.opencode/bin:$PATH`；永久生效则把该行追加到`~/.bashrc`、`~/.zshrc`或`~/.config/fish/config.fish`，重启 shell
版本行为异常，`--version`输出与预期不符	旧安装方式残留	先卸载旧包（如`npm uninstall -g opencode-ai`），再清理`~/.opencode`目录后重装
脚本下载失败或超时	网络无法访问下载源	检查网络或代理设置；也可自行下载二进制，再用脚本的`--binary <path>`选项指向本地文件安装
Windows 原生环境脚本报错	不支持原生 Windows	在 WSL 中执行，按 Linux 流程重装