OpenCode 安装
OpenCode 是一个开源的 AI 编程 Agent，支持在终端中理解代码、修改文件、执行命令等开发任务，也提供桌面客户端和 Web 界面。
本节介绍终端版的安装方法。
本文按 OpenCode 2 的官方安装文档更新。OpenCode 1 和 2 都使用
opencode命令，默认不能并排安装。旧教程中的opencode-ai是 V1 的 npm 包，新版使用@opencode/cli。如果已经通过包管理器安装 V1，请先使用对应的包管理器卸载旧包，再安装 V2；使用新版官方脚本安装时，会替换脚本安装位置的旧二进制文件。已有插件和服务端 API 集成需参考 V1 迁移指南。
安装前准备
1、操作系统要求
- macOS：支持 Apple Silicon 和 Intel。
- Linux：支持 x64、ARM64，并提供 glibc 和 musl 对应版本。
- Windows：支持原生二进制文件，也可以在 WSL 中按照 Linux 的方式安装。
2、终端工具
建议使用支持真彩色的现代终端，例如：
- WezTerm（跨平台）：https://wezterm.org/
- Alacritty（跨平台）：https://alacritty.org/
- Ghostty（Linux/macOS）：https://ghostty.org/
- Kitty（Linux/macOS）：https://sw.kovidgoyal.net/kitty/
更多终端工具参考：终端工具推荐。
3、模型服务
OpenCode 自带部分免费模型，也支持连接其他模型服务，并非安装前必须准备 API Key。使用第三方模型时，需要按照服务商要求配置 API Key 或完成账户授权。
常见模型服务包括：
- OpenAI（GPT）
- Anthropic（Claude）
- Google（Gemini）
- DeepSeek
- 阿里百炼
- 智谱 GLM
- MiniMax
免费模型的可用范围以当前界面为准；第三方模型的费用由对应服务商收取。
安装方式
以下方式选择一种即可。官方脚本和独立二进制文件不要求预先安装 Node.js；使用 npm 等包管理器时，才需要准备对应环境。
1、一键安装（macOS / Linux / WSL）
在终端中执行新版官方安装脚本：
curl -fsSL https://opencode.ai/v2/install | bash
脚本会识别系统和处理器架构，下载当前发布的版本，并安装到：
~/.opencode/bin
安装完成后，按照终端提示重新打开终端，使 PATH 配置生效。然后进入项目目录并启动：
cd /path/to/your/project opencode
请将 /path/to/your/project 替换为实际项目路径。
上图为旧版安装提示示意，实际命令和提示以当前版本为准。
2、使用 npm、Bun、pnpm 或 Yarn 安装
如果已经安装 Node.js 和 npm，可以执行：
npm install -g @opencode/cli
也可以选择下面任意一种方式：
Bun：
bun install -g --trust @opencode/cli
pnpm：
pnpm add -g --allow-build=@opencode/cli @opencode/cli
Yarn Classic：
yarn global add @opencode/cli
新版 npm 包需要运行安装后脚本，以选择当前平台的原生二进制文件。Bun 的
--trust和 pnpm 的--allow-build用于允许所需脚本，不要省略。上述为 macOS、Linux 和 WSL 的安装方式。当前 V2 文档不支持 Windows 原生包管理器安装，请使用后文的独立二进制文件。
3、macOS / Linux（Homebrew）
已经安装 Homebrew 的用户，可以使用官方 tap：
brew install anomalyco/tap/opencode-v2
brew install anomalyco/tap/opencode 对应 V1。Homebrew 核心仓库的 brew install opencode 当前也提供 V2，但更新节奏可能与官方 tap 不同。
4、Windows 安装
方式一：在 WSL 中安装
如果你希望使用 Linux 开发环境，可以先在管理员 PowerShell 中安装 WSL：
wsl --install
根据提示重启系统，并完成 Linux 用户初始化。随后打开 Ubuntu 等 WSL 发行版终端，执行：
curl -fsSL https://opencode.ai/v2/install | bash
重新打开 WSL 终端，进入项目目录后启动：
cd ~/your-project opencode
以上安装脚本在 WSL 的 Linux 终端中执行，不是在 PowerShell 中执行。
方式二：Windows 原生安装
打开 官方安装文档，在 CLI 下载区域选择 Windows x64 或 ARM64 对应的独立二进制文件。
下载并解压后，在文件所在目录打开 PowerShell，执行：
.\opencode.exe --version
将 opencode.exe 所在目录加入用户的 PATH 环境变量，重新打开终端后，即可在项目目录中运行：
opencode
旧教程中的 Chocolatey、Scoop 和 npm install -g opencode-ai 不作为本节 V2 的 Windows 原生安装方法。
5、Linux 其他安装方式
Arch Linux 官方仓库：
sudo pacman -S opencode
AUR 包：
paru -S opencode-beta
如果使用 Mise，可以执行：
mise use -g opencode
按当前官方文档，安装 V2 需要 Mise 2026.10.9 或更新版本；更早的 Mise 版本会安装 V1。
也可以从 官方安装文档 下载独立 CLI 二进制文件。手动下载时，需要匹配处理器架构和 glibc / musl 环境；较旧的 x64 处理器可选择 baseline 版本。
6、Docker（可选）
OpenCode 也提供 Docker 镜像。V2 使用明确的版本标签，官方文档以 2.0.0 为例：
docker run -it --rm ghcr.io/anomalyco/opencode:2.0.0
这里的 2.0.0 是版本标签示例，并不代表最新版本。实际使用时，请选择需要的已发布标签；需要操作本地项目时，还需配置项目目录挂载。
验证安装
安装完成后，执行：
opencode --version
能够输出版本号，说明命令可以正常运行。本文安装的是 V2，版本号应为 2.x，具体小版本以实际输出为准。
如果仍然显示 1.x，可能是 PATH 中还有旧版本。macOS / Linux / WSL 可以查看：
type -a opencode
Windows PowerShell 可以查看：
Get-Command opencode -All
根据输出检查旧安装位置，使用对应安装方式移除旧版本，再重新打开终端。
启动 OpenCode
在项目目录中执行：
cd /path/to/your/project opencode
也可以直接指定项目路径：
opencode /path/to/your/project
启动后会打开终端交互界面（TUI）：
上图为旧版界面示意，当前版本的布局可能有所不同。
连接模型
在 OpenCode 的输入框中执行：
/connect
选择模型服务商，按照界面提示输入 API Key 或完成账户授权。然后执行：
/models
选择要使用的模型，即可开始提问。例如：
请介绍这个项目的目录结构，并说明如何启动。
/connect 和 /models 是 OpenCode 界面内的命令，不是在系统终端中执行。
常见问题
1、提示找不到 opencode 命令
先重新打开终端。如果使用官方脚本安装，仍然提示 command not found，可以先通过完整路径验证：
"$HOME/.opencode/bin/opencode" --version
如果能够输出版本号，说明主要是 PATH 配置没有生效。Bash / Zsh 用户可以在当前终端执行：
export PATH="$HOME/.opencode/bin:$PATH"
需要永久生效时，将这行配置加入当前 Shell 对应的 ~/.bashrc 或 ~/.zshrc，避免重复添加。Fish 用户可以执行：
fish_add_path "$HOME/.opencode/bin"
2、出现 EACCES 或 permission denied
先查看完整报错中的具体路径。它可能涉及安装目录、数据目录或项目文件，不能仅凭 EACCES 就修改整个 ~/.local 的权限。
macOS / Linux / WSL 可以使用下面的命令检查常见数据目录的所有者：
ls -ld "$HOME/.local" "$HOME/.local/share" "$HOME/.local/share/opencode"
只有确认报错涉及 ~/.local/share/opencode，且该目录因之前使用 sudo 而归 root 所有时，才修复这个目录：
sudo chown -R "$(id -u):$(id -g)" "$HOME/.local/share/opencode"
如果报错路径不同，应检查实际路径及其父目录。日常使用时以普通用户运行 OpenCode，不要对整个 ~/.local 执行递归 chmod 755。
3、查看运行路径和服务状态
V2 可以显示当前实际使用的数据、配置、缓存和日志路径：
opencode debug paths
启动异常时，可以查看后台服务状态：
opencode service status
如果服务卡住，可以尝试重启：
opencode service restart
更新 OpenCode
在系统终端执行：
opencode upgrade
也可以使用原来的包管理器更新。例如 npm 安装的 V2：
npm install -g @opencode/cli@latest
使用官方 Homebrew tap 安装的 V2：
brew upgrade anomalyco/tap/opencode-v2