openCode 安装与初始化配置（Windows / macOS / Linux）

前五篇把 openCode 是什么、和 Cursor 怎么选、核心概念全讲清楚了。这篇直接装机------macOS、Linux 原生安装 + Windows WSL2 全流程，从零到能用的完整路径。

openCode 是开源项目，安装方式和其他 CLI 工具一样------npm 全局安装一条命令。但配置环节比闭源工具多一步：你需要自己选择模型提供商、配置 API Key。这个"多一步"换来的，是模型自由切换的权利。

前置依赖：装之前先确认三件事

Node.js 18 或更高版本 ：openCode 是 Node.js CLI 工具，终端输入 node -v 确认版本。推荐用 nvm 管理 Node，方便切换。

bash 复制代码

node -v  # 确认 >= 18

Git ：需要 Git 做代码变更追踪。输入 git --version 确认已安装。

一个可用的 API Key：openCode 本身不提供模型服务，你需要至少一个模型提供商的 API Key。支持 Anthropic、OpenAI、DeepSeek、Ollama 等。安装前先去至少一个平台获取 Key。

macOS 安装

一条命令：

bash 复制代码

npm install -g @opencode-ai/cli

安装完成后验证：

bash 复制代码

opencode --version

输出类似 opencode x.x.x 表示安装成功。

首次启动配置 ：在项目目录下输入 opencode，首次启动会引导你完成初始配置。第一步是选择默认模型提供商------这是 openCode 区别于其他工具的关键步骤。

Linux 安装

安装命令和 macOS 完全一致：

bash 复制代码

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（管理员）运行：

bash 复制代码

wsl --install

安装完成后重启电脑，进入 Ubuntu 终端设置用户名和密码。

第二步：装 Node.js

bash 复制代码

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18
node -v  # 确认 >= 18

第三步：安装 openCode

bash 复制代码

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：

bash 复制代码

# 方式一：环境变量
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 支持同时配置多个模型，在对话中随时切换：

bash 复制代码

# 配置多个 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）配置：

bash 复制代码

# 先安装 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：

markdown 复制代码

# 项目名称：用户管理系统

## 技术栈
- 后端：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 自动加载，免去每次对话都重复介绍项目背景。

首次验证：确保一切就绪

验证一：版本检查

bash 复制代码

opencode --version

验证二：基础交互

在项目目录下启动 openCode：

bash 复制代码

cd ~/your-project
opencode

输入第一个指令：

请列出当前目录下有哪些文件，按修改时间排序。

openCode 应该能正确列出文件。这表明 Node 环境正常、安装正确、认证通过。

验证三：模型切换

bash 复制代码

/model list       # 查看已配置的模型
/model claude-sonnet   # 切换到 Claude
> 你好，请介绍一下你自己

不同模型回复不同，确认模型切换生效。

升级和卸载

升级：

bash 复制代码

npm update -g @opencode-ai/cli

卸载：

bash 复制代码

npm uninstall -g @opencode-ai/cli
rm -rf ~/.opencode   # 清理配置和对话历史

总结

openCode 的安装三步到位：装 Node.js → npm 全局安装 → 配模型和 API Key。Windows 用户多一步 WSL2 环境准备。

和 Claude Code、Codex 的关键区别在于配置环节------openCode 不绑定模型，你需要自己选、自己配。这个"多一步"换来的是模型自由切换的能力。

下一篇是安装踩坑实录------最常见的问题和解决办法，装机时对着排查。

如果这篇安装指南帮你顺利装好了 openCode，欢迎分享给也在装机器的朋友。你用哪个模型作为默认？评论区聊聊~