先选择一种安装方式，确认命令能运行，再连接模型提供商。本教程由 OpenCode Tutorial 独立维护，安装命令已于 2026 年 10 月 2 日对照官方安装文档核对。
选择安装方式
| 你的环境 | 建议从这里开始 |
|---|---|
| 已使用 Homebrew 的 macOS | 官方 Homebrew tap |
| 没有 Node.js 的 macOS 或 Linux | 官方安装脚本 |
| 已有 Node.js 环境 | npm 包，也适用于原生 Windows |
| Windows 上使用 Linux 开发工具 | 先设置 WSL，再按 Linux 步骤安装 |
尽量只使用一种包管理器。安装多个副本后，终端可能优先找到旧版本，导致升级完成但运行的版本没有变化。
使用 npm
已有 Node.js 和 npm 时，运行：
npm install -g opencode-ai
opencode --version
安装的包名是 opencode-ai，安装后运行的命令是 opencode。
macOS 使用 Homebrew
使用官方 tap 安装当前版本：
brew install anomalyco/tap/opencode
opencode --version
macOS 或 Linux 使用官方脚本
curl -fsSL https://opencode.ai/install | bash
安装后重新打开终端，再运行 opencode --version。如果找不到命令，按照安装器输出的提示配置 PATH。当前官方指南使用的是 /install，不是旧教程中的 /install.sh。
Windows 与 WSL
如果需要 Linux 开发环境，按照 Microsoft 的 WSL 安装指南设置 WSL，然后在 WSL 终端内运行 Linux 安装命令，并从这个环境打开项目。
原生 Windows 也可以使用上面的 npm 安装方式；平台要求请参阅 OpenCode Windows 指南。在 PowerShell 中安装，并不意味着 WSL 中也安装好了另一个副本。
启动第一个项目
进入实际项目目录并启动：
cd your-project
opencode
随后在 OpenCode 的终端界面中操作：
- 输入
/connect，选择模型提供商并完成认证。 - 输入
/init，生成项目说明文件AGENTS.md，检查生成的内容。 - 先问一个关于项目的小问题，再要求修改代码。
接下来阅读 Plan 与 Build 模式，选择合适的工作方式。需要语言诊断时，参阅 OpenCode LSP 配置。
排查 zsh: command not found: opencode
先区分安装失败和 PATH 问题：
command -v opencode
npm list -g opencode-ai --depth=0
npm prefix -g
后两条命令适用于 npm 安装。在 macOS 和 Linux 中，全局可执行文件通常位于 npm 输出前缀下的 bin 目录。如果包已安装而 command -v 没有输出，把实际的可执行文件目录加入当前 shell 的 PATH，再打开新终端。不要直接照搬他人电脑上的目录。
Homebrew 安装可先检查 brew list opencode，再按照 Homebrew 的 shellenv 提示设置环境。脚本安装应使用安装器提示的目录。WSL 用户要在 WSL 内检查，不能只检查 Windows 的终端。
如果怀疑装了多个副本，可以查看 shell 会优先使用哪个：
type -a opencode
升级现有安装
先确认当前版本，再使用对应安装方式升级：
opencode --version
opencode upgrade
npm 安装需要通过 npm 更新时，使用 npm install -g opencode-ai@latest；官方 Homebrew tap 可使用 brew upgrade anomalyco/tap/opencode。打开新终端后再次检查版本。
如果服务提示必须升级到某个版本，先比较提示中的版本与 opencode --version，并排查重复安装，再考虑认证问题。CLI 升级文档列出了升级选项。
配置文件放在哪里
当前 OpenCode 使用 JSON 或 JSONC。项目配置可以放在 opencode.json，全局配置位于 ~/.config/opencode/opencode.json。添加配置前可参阅配置示例。
旧教程中的 Go 仓库安装命令和 config.yaml 已移除。新安装请使用当前 npm 包或官方安装器。