前五篇把 openCode 是什么、和 Cursor 怎么选、核心概念全讲清楚了。这篇直接装机——macOS、Linux 原生安装 + Windows WSL2 全流程，从零到能用的完整路径。
openCode 是开源项目，安装方式和其他 CLI 工具一样——npm 全局安装一条命令。但配置环节比闭源工具多一步：你需要自己选择模型提供商、配置 API Key。这个”多一步”换来的，是模型自由切换的权利。
前置依赖：装之前先确认三件事
Node.js 18 或更高版本：openCode 是 Node.js CLI 工具，终端输入 node -v 确认版本。推荐用 nvm 管理 Node，方便切换。
node -v # 确认 >= 18
Git：需要 Git 做代码变更追踪。输入 git --version 确认已安装。
一个可用的 API Key：openCode 本身不提供模型服务，你需要至少一个模型提供商的 API Key。支持 Anthropic、OpenAI、DeepSeek、Ollama 等。安装前先去至少一个平台获取 Key。
macOS 安装
一条命令：
npm install -g @opencode-ai/cli
安装完成后验证：
opencode --version
输出类似 opencode x.x.x 表示安装成功。
首次启动配置：在项目目录下输入 opencode，首次启动会引导你完成初始配置。第一步是选择默认模型提供商——这是 openCode 区别于其他工具的关键步骤。
Linux 安装
安装命令和 macOS 完全一致：
npm install -g @opencode-ai/cli
opencode --version
Linux 特有注意事项：
- EACCES 权限报错 → 不要加 sudo，用 nvm 管理 Node，nvm 把全局包装在用户目录下
- 无图形界面服务器 → 只能用 API Key 认证，OAuth 需要浏览器支持
- 终端字体 → 建议安装 Nerd Font（推荐 MesloLGS NF），openCode 的 TUI 界面使用了 Unicode 字符
Windows 安装（WSL2）
openCode 目前没有 Windows 原生版本，Windows 用户通过 WSL2 运行。
第一步：安装 WSL2
PowerShell（管理员）运行：
wsl --install
安装完成后重启电脑，进入 Ubuntu 终端设置用户名和密码。
第二步：装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18
node -v # 确认 >= 18
第三步：安装 openCode
npm install -g @opencode-ai/cli
opencode --version
第四步：关键——项目路径
项目必须放在 WSL 文件系统内（/home/用户名/projects/），不能放在 /mnt/c/ 下。WSL 访问 Windows 文件系统 I/O 性能差，openCode 读写文件容易超时。推荐 VS Code Remote-WSL 插件在 Windows 端编辑 WSL 内的代码。
首次配置：模型与 API Key
openCode 和 Claude Code、Codex 最大的不同在于——它不绑定任何一家模型。你需要自己选模型、配 Key。这个”自由”是 openCode 的核心卖点，也是配置环节最需要讲清楚的地方。
第一步：选默认模型
首次启动 opencode 时，会提示你选择默认模型提供商。选项包括：
- Anthropic（Claude Sonnet/Opus）：代码理解和多文件重构最强
- OpenAI（GPT-4o/GPT-5.x）：通用编程和文档生成均衡
- DeepSeek：中文场景有优势，性价比高
- Ollama：本地运行，完全离线，零 API 费用
选一个作为默认，后续可以随时切换。建议日常开发用 Claude Sonnet（代码能力最强），成本敏感时切 DeepSeek，敏感项目用 Ollama。
第二步：配置 API Key
根据你选的是哪个提供商，用对应的方式配置 Key：
# 方式一：环境变量
export ANTHROPIC_API_KEY=sk-ant-xxx # Anthropic
export OPENAI_API_KEY=sk-xxx # OpenAI
export DEEPSEEK_API_KEY=sk-xxx # DeepSeek
# 方式二：openCode 内置配置
opencode config set provider.anthropic.key sk-ant-xxx
opencode config set provider.openai.key sk-xxx
第三步：配置多个模型（可选）
openCode 支持同时配置多个模型，在对话中随时切换：
# 配置多个 provider
opencode config set providers.anthropic.apiKey sk-ant-xxx
opencode config set providers.openai.apiKey sk-xxx
opencode config set providers.deepseek.apiKey sk-xxx
# 在对话中切换（/model 命令）
/model claude-sonnet # 切到 Claude
/model gpt-4o # 切到 GPT
/model deepseek # 切到 DeepSeek
本地模型（Ollama）配置：
# 先安装 Ollama（ollama.ai 下载）
# 拉取模型
ollama pull codellama:13b
# openCode 中配置 Ollama
opencode config set providers.ollama.url http://localhost:11434
opencode config set defaultModel ollama/codellama:13b
Ollama 本地模型的好处：完全离线、零 API 费用、数据不出电脑。适合处理敏感项目代码。代价是模型能力弱于云端 Claude/GPT。
配置 AGENTS.md：项目说明书
openCode 启动时会自动读取项目根目录下的 AGENTS.md 文件作为基础上下文。这份文件相当于给 openCode 的”项目说明书”——背景、技术栈、规范、常用命令。
在项目根目录创建 AGENTS.md：
# 项目名称：用户管理系统
## 技术栈
- 后端：Python 3.11 + FastAPI
- 数据库：PostgreSQL + SQLAlchemy
- 前端：React 18 + TypeScript
- 测试：pytest（后端）+ Vitest（前端）
## 目录结构
- api/：接口层
- models/：数据模型
- services/：业务逻辑
- tests/：测试文件
## 编码规范
- 函数命名：蛇形命名（snake_case）
- 类型注解：所有函数参数和返回值必须标注类型
- 错误处理：统一使用自定义异常类，不裸抛 Exception
## 常用命令
- 启动开发服务器：uvicorn main:app --reload
- 运行测试：pytest -v
- 数据库迁移：alembic upgrade head
AGENTS.md 不需要很长，但需要覆盖”openCode 理解这个项目所需的最小信息”。每次启动 openCode 自动加载，免去每次对话都重复介绍项目背景。
首次验证：确保一切就绪
验证一：版本检查
opencode --version
验证二：基础交互
在项目目录下启动 openCode：
cd ~/your-project
opencode
输入第一个指令：
请列出当前目录下有哪些文件，按修改时间排序。
openCode 应该能正确列出文件。这表明 Node 环境正常、安装正确、认证通过。
验证三：模型切换
/model list # 查看已配置的模型
/model claude-sonnet # 切换到 Claude
> 你好，请介绍一下你自己
不同模型回复不同，确认模型切换生效。
升级和卸载
升级：
npm update -g @opencode-ai/cli
卸载：
npm uninstall -g @opencode-ai/cli
rm -rf ~/.opencode # 清理配置和对话历史
总结
openCode 的安装三步到位：装 Node.js → npm 全局安装 → 配模型和 API Key。Windows 用户多一步 WSL2 环境准备。
和 Claude Code、Codex 的关键区别在于配置环节——openCode 不绑定模型，你需要自己选、自己配。这个”多一步”换来的是模型自由切换的能力。
下一篇是安装踩坑实录——最常见的问题和解决办法，装机时对着排查。
如果这篇安装指南帮你顺利装好了 openCode，欢迎分享给也在装机器的朋友。你用哪个模型作为默认？评论区聊聊~
