Windows 安装 OpenCode v2：原生、WSL、Desktop 怎么选？完整配置与避坑指南

这是《OpenCode v2 实战：从零搭建企业级 AI 编程助手》专题的第 2 篇。上一篇解决"OpenCode v2 是什么"，这一篇只做一件事：在 Windows 上选对安装路线，并把 OpenCode v2 安装到可验证、可长期维护的状态。

Windows 用户安装 AI 编程工具，最容易遇到的不是"命令不会敲"，而是环境选错：明明项目、JDK 和数据库工具都在 Windows，却照着 Linux 教程装进 WSL；或者团队全部在 WSL 开发，却把 Agent 装在 Windows，然后让它跨文件系统扫描几万个文件。结果是命令找不到、Git 身份不一致、依赖装了两份，甚至同一台电脑同时运行 V1 和 V2。

本文不要求你把三种方案都安装一遍。最终目标是根据项目实际运行位置，选择原生 CLI、WSL 2 或 Desktop 中的一种主环境，并完成以下闭环：

1. 确认 Windows 架构和现有 OpenCode 来源；
2. 安装正确的 V2 构建；
3. 确认命令解析到唯一可执行文件；
4. 连接模型 Provider，但不把密钥写进项目；
5. 在真实 Git 仓库中完成首次只读任务；
6. 为后续升级、排错和迁移保留明确入口。

一、先选路线：关键不是界面，而是项目运行在哪里

官方 V2 文档目前提供三种主要使用形态：CLI、Desktop 和 Web。对于 Windows 本地安装，最常见的选择是原生 CLI、WSL 内的 Linux CLI，以及 Windows Desktop。

先看结论：

使用场景	推荐路线	原因	主要注意点
Java、.NET、前端项目主要在 Windows 运行	原生 CLI	与现有 Git、JDK、Node、Maven 共用环境	PATH、PowerShell shim、杀毒软件
项目和依赖本来就在 WSL 2	WSL CLI	Linux 命令、权限和容器链路一致	仓库应放在 WSL 文件系统
不熟悉终端，希望图形化管理会话	Desktop	安装和上手成本低	仍要确认项目路径与外部工具位置
偶尔跨设备查看本地会话	CLI + Web 配对	执行仍由本地环境承担	配对链接是一次性的，并会过期
Windows 与 WSL 项目各占一半	分开安装、分开使用	每个 Agent 靠近自己的工具链	不要混用配置、凭据与依赖目录

最重要的判断规则只有一句：

OpenCode 应该安装在"项目实际执行构建、测试和 Git 命令"的环境里。

如果你的 Spring Boot 项目通过 Windows JDK 和 Maven 构建，就优先使用原生 CLI；如果项目位于 ~/projects，日常通过 WSL 的 Java、Node 和 Docker 开发，就在 WSL 内安装 CLI。不要仅因为"Linux 看起来更适合开发"就强行迁移，也不要让 Windows 版 OpenCode 去调用 WSL 中的半套工具链。

二、安装前先做 5 分钟体检

1. 确认处理器架构

在 PowerShell 中执行：

[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture

常见结果是 X64 或 Arm64。官方为 Windows 提供 x64、x64 baseline 和 ARM64 三种独立 CLI 构建，也为 Desktop 提供 x64 与 ARM64 安装包。

其中 baseline 可以理解为对较老 x64 CPU 更保守的兼容构建。大多数近年的 Intel、AMD 电脑直接选 x64；只有普通 x64 构建启动时报非法指令，或机器确实较老时，才考虑 baseline。ARM Windows 设备则选择 ARM64，不要只根据"Windows 11"猜架构。

2. 检查是否已经存在旧命令

Get-Command opencode -All -ErrorAction SilentlyContinue |
  Select-Object CommandType, Name, Source

where.exe opencode

如果没有结果，说明当前 PATH 中没有 OpenCode；如果出现多个路径，先记录它们，不要立即覆盖安装。常见重复来源包括 npm 全局目录、手工解压目录、旧版安装器和其他包管理器。

3. 记录现有开发工具位置

git --version
node --version
npm --version
java -version
mvn -version
wsl --status

并不是每个项目都需要这些工具。检查的目的，是确认 OpenCode 将来执行命令时，看到的环境是否与开发者自己使用的一致。

4. 不要混淆官方支持与"第三方能安装"

V2 官方文档当前明确写着：不支持 Windows 系统包管理器。也就是说，即使某个 Winget、Chocolatey 或 Scoop 源里能搜到同名包，也不能默认它就是官方维护、能及时升级到 V2 的发行渠道。

Windows 上更稳妥的主路径是：

• 官方独立 CLI 压缩包；
• 官方 Desktop 安装包；
• 已有 Node.js 环境时使用官方 npm 包；
• 在 WSL 内按 Linux 官方脚本安装。

5. 特别检查 V1/V2 冲突

V2 文档还提示：使用 mise 时需要 2026.10.9 或更高版本，旧版 mise 会安装 OpenCode 1。无论你是否使用 mise，都应该把"命令能执行"和"执行的是 V2"视为两个不同检查项。

opencode --version
Get-Command opencode -All | Format-List Name,CommandType,Source

后文所有操作都以版本输出和命令路径作为证据，而不是以桌面图标或安装器的"完成"页面作为证据。

三、方案 A：Windows 原生 CLI，适合大多数本地开发

1. 下载官方独立二进制文件

官方 V2 文档的 Windows 下载入口会指向最新构建：

• x64：opencode-windows-x64.zip
• x64 兼容构建：opencode-windows-x64-baseline.zip
• ARM64：opencode-windows-arm64.zip

建议从 OpenCode V2 官方文档 进入下载，不从网盘、转载文章或不明镜像获取可执行文件。

下面给出一套可审计的 PowerShell 安装示例。示例以 x64 为例，并安装到当前用户目录，不要求管理员权限：

$installDir = Join-Path $env:LOCALAPPDATA "Programs\OpenCodeV2"
$zipFile = Join-Path $env:TEMP "opencode-windows-x64.zip"
$downloadUrl = "https://opencode.ai/update/api/latest/cli/opencode/opencode-windows-x64.zip"

New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Invoke-WebRequest -Uri $downloadUrl -OutFile $zipFile
Expand-Archive -Path $zipFile -DestinationPath $installDir -Force
Get-ChildItem -LiteralPath $installDir

不要为了省事把程序长期放在"下载"目录，也不要放进某个业务代码仓库。可执行文件与项目源码分离，升级和清理会简单很多。

2. 把安装目录加入用户 PATH

$installDir = Join-Path $env:LOCALAPPDATA "Programs\OpenCodeV2"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$pathItems = @($userPath -split ';' | Where-Object { $_ })

if ($pathItems -notcontains $installDir) {
    $newPath = (($pathItems + $installDir) -join ';')
    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
}

关闭当前终端，新开一个 PowerShell 或 Windows Terminal，再执行：

where.exe opencode
opencode --version

PATH 更新通常不会自动注入已经打开的终端。刚安装完就报"无法识别 opencode"，第一步应是新开终端，而不是重新安装。

3. 已有 Node.js 时，可以使用 npm

官方也提供 npm 安装方式：

npm i -g @opencode/cli@latest
opencode --version
npm prefix -g

npm 包会通过安装脚本选择当前平台对应的原生 OpenCode 二进制文件。这个方案适合团队已经统一 Node.js 版本与全局包目录的情况；如果机器上有 nvm-windows、多套 Node.js 或企业代理，独立二进制通常更容易排错。

PowerShell 如果阻止 npm 生成的 opencode.ps1，先确认同目录是否存在 opencode.cmd：

where.exe opencode
opencode.cmd --version

不要看到执行策略报错就直接使用 Bypass 永久放开整台机器。优先修正 Node/npm 安装、使用 .cmd shim，或按企业安全策略设置最小范围的执行策略。

四、方案 B：WSL 2 CLI，适合 Linux 工具链项目

1. 先完成 WSL 基础环境

在管理员 PowerShell 中安装 WSL 的典型命令是：

wsl --install -d Ubuntu

根据系统提示重启并完成 Linux 用户初始化。已有 WSL 的机器先检查：

wsl --status
wsl --list --verbose

建议使用 WSL 2。OpenCode 应安装在具体的 Linux 发行版内部，而不是在 Windows 安装一次后，试图从 WSL 远程调用同一份可执行文件。

2. 在 WSL 内执行官方 Linux 安装脚本

进入 Ubuntu 后运行：

sudo apt update
sudo apt install -y curl git ca-certificates

curl -fsSL https://opencode.ai/v2/install | bash
exec "$SHELL" -l

command -v opencode
opencode --version

command -v 应返回 Linux 文件系统中的路径。如果它指向 /mnt/c/... 下的 Windows 程序，说明环境仍然混用了。

3. 仓库也应尽量放在 WSL 文件系统

推荐：

mkdir -p ~/projects
cd ~/projects
git clone https://example.com/your-org/your-project.git
cd your-project
opencode

不推荐把高频扫描、构建的仓库长期放在 /mnt/c/Users/... 再从 WSL 操作。跨 Windows/WSL 文件系统可能带来文件遍历性能、权限语义、大小写、软链接和文件监听差异。

如果公司规定源码必须位于 Windows 盘，应先做一个小型仓库基准测试，再决定是否使用 WSL 路线；不要等到 Agent 扫描大仓库很慢时才发现环境边界不合理。

4. Windows 与 WSL 的 Git 身份彼此独立

git config --global user.name
git config --global user.email
git config --global --list --show-origin

WSL 内的 Git 配置、SSH key、凭据助手、Node、Java 和环境变量，不会天然等于 Windows 中那一套。OpenCode 能看到什么，取决于它所在环境能看到什么。不要把"Windows 上 Git 能拉代码"当成"WSL 里的 OpenCode 一定能访问仓库"。

五、方案 C：Windows Desktop，适合图形化工作流

官方为 Windows 提供 x64 和 ARM64 Desktop 安装包。进入 V2 官方文档，根据架构下载 .exe 安装包即可。

Desktop 的优势不是模型更强，而是降低会话管理、项目切换和结果查看的使用门槛。它适合以下情况：

• 希望通过图形界面选择项目目录；
• 不熟悉 TUI 快捷键；
• 经常同时维护多个会话；
• 希望让团队成员先体验，再逐步学习 CLI。

安装时注意三点：

1. 只从 opencode.ai 官方入口下载安装包；
2. 不要为了通过安全软件而关闭系统防护或全盘添加排除项；
3. 首次打开项目后，仍要验证它能否找到项目需要的 Git、Node、Java 或其他外部工具。

Desktop 与 CLI 是不同入口，但不应该被理解成两套完全无关的产品。团队制定规范时，真正要统一的是项目规则、Provider、安全边界和验证标准，而不是强制所有人使用同一种界面。

六、连接模型并完成第一次可验证运行

1. 从项目根目录启动

先选择一个已经使用 Git 管理、体量不大的测试项目：

cd C:\workspace\demo-project
git status
opencode

WSL 用户使用 Linux 路径：

cd ~/projects/demo-project
git status
opencode

首次体验不要直接选择生产仓库，也不要一上来要求 Agent 批量重构。先让它完成只读任务，例如：

请只读分析当前项目，不要修改文件。输出：
1. 技术栈与启动入口；
2. 主要目录职责；
3. 构建和测试命令；
4. 目前无法确认的信息。

这个任务可以同时验证工作目录、文件读取、项目识别和基本模型连接。

2. 使用 /connect 连接 Provider

V2 官方文档说明，可以在 TUI 中使用 /connect 连接支持的模型 Provider：

/connect

按界面提示选择 Provider 和认证方式。生产使用时遵循两条原则：

• 不把 API Key 直接写进仓库、AGENTS.md、示例代码或可提交的配置文件；
• 不在文章、截图、终端录屏和报错粘贴中暴露完整凭据。

如果公司通过网关或自定义 Provider 接入模型，应单独记录接口地址、模型名、证书、代理和权限范围，后续再写入受控配置。第 4 篇会专门讲 Provider、模型选择与密钥管理。

3. 验收不是"能聊天"，而是四项证据

一次合格安装至少要满足：

验收项	Windows 原生	WSL	Desktop
版本	opencode --version	opencode --version	设置/关于页面
命令来源	where.exe opencode	command -v opencode	官方安装目录
项目读取	能识别仓库结构	能识别 WSL 仓库	能打开目标目录
外部工具	能运行项目所需命令	使用 Linux 工具链	能继承正确环境

只有版本正确但读不到项目，不算完成；能聊天但调用的是旧版命令，也不算完成。

七、V1 与 V2 冲突：不要靠反复重装解决

1. 先定位到底执行了哪个文件

Get-Command opencode -All | Select-Object Name,CommandType,Source
where.exe opencode
opencode --version

Windows 按 PATH 顺序解析命令。即使你已经安装 V2，排在前面的旧版目录仍可能被优先命中。

2. 查清来源后再卸载

处理原则是"一种来源对应一种卸载方式"：

• npm 安装的，用 npm 查看并卸载对应全局包；
• mise 安装的，用 mise 管理版本，并先升级 mise；
• 手工解压的，删除明确的旧目录并移除对应 PATH；
• Desktop 安装的，通过 Windows 应用管理卸载旧版本。

不要在不清楚来源时批量删除所有名为 opencode 的文件。项目目录、配置、缓存、可执行文件和桌面应用是不同对象，误删配置会让迁移问题变成数据丢失问题。

3. 新开终端完成最终验证

where.exe opencode
opencode --version

如果仍有多个结果，继续整理 PATH，直到团队能够解释每一条路径的用途。需要临时并存时，应使用明确的完整路径启动，而不是赌 PATH 顺序。

八、Windows 常见故障与定位顺序

1. opencode 无法识别

按以下顺序检查：

Test-Path "$env:LOCALAPPDATA\Programs\OpenCodeV2"
[Environment]::GetEnvironmentVariable("Path", "User")
where.exe opencode

确认文件存在、用户 PATH 包含目录，再新开终端。不要先重装。

2. 装完仍显示 V1

执行 Get-Command opencode -All。最常见原因是旧目录在 PATH 中排得更靠前，或旧版 mise 仍在管理命令。先确认来源，再针对性升级或卸载。

3. npm 安装阶段卡在 postinstall

npm 包需要运行安装脚本选择原生二进制。检查 Node/npm 版本、企业代理、脚本策略和安全软件日志。如果团队环境经常拦截 postinstall，直接使用官方独立 CLI 往往更简单。

4. PowerShell 报脚本执行策略错误

先尝试同目录的 opencode.cmd，并检查命令来源。执行策略是系统安全边界，不应为一个工具永久设置全局 Bypass。

5. WSL 中扫描项目很慢

检查仓库是否位于 /mnt/c。把测试仓库克隆到 ~/projects 对比，再检查是否有 node_modules、构建产物、日志和大型二进制目录需要排除。

6. 能启动，但找不到 Git、Java 或 Node

OpenCode 继承的是启动它的环境。Windows 原生、WSL 和 Desktop 可能拥有不同 PATH。先在同一终端手工执行对应命令，再启动 OpenCode，不要在 Agent 对话里反复要求它"猜工具在哪里"。

7. 连接 Provider 超时或证书报错

按网络层排查：DNS、代理环境变量、企业证书、网关地址、Provider 凭据和模型权限。不要把完整 API Key 发到公共 Issue，也不要通过关闭 TLS 校验来"临时解决"。

九、给团队的推荐安装基线

个人试用可以自由选择，团队落地则建议形成一个最小基线：

1. 明确主环境：Windows 原生或 WSL 2
2. 明确安装来源：官方独立 CLI、官方 npm 包或官方 Desktop
3. 记录版本：opencode --version
4. 记录命令路径：where.exe / command -v
5. 规定项目位置：Windows 盘或 WSL 文件系统
6. 凭据不进仓库，敏感配置不进文章与日志
7. 首次任务只读，修改前检查 Git 状态
8. 升级后重新执行版本、路径和项目读取验证

对于多数 Java 企业项目，我的建议是：项目原本运行在 Windows，就先用原生独立 CLI；项目已经全面 WSL 化，就在 WSL 内安装；希望低门槛体验时用 Desktop。三者之间没有绝对优劣，环境一致性比界面偏好重要得多。

十、卸载与升级也要可控

独立 CLI 的升级可以重新下载官方最新压缩包，覆盖明确的安装目录；升级前记录旧版本，升级后重新执行：

where.exe opencode
opencode --version

npm 安装则使用同一包管理来源升级：

npm i -g @opencode/cli@latest
opencode --version

卸载时只移除确认过的可执行目录、包和 PATH 条目。是否保留配置、会话与凭据，应根据团队的数据保留策略单独决定，不要把"卸载程序"和"清空用户数据"合并成一个粗暴动作。

十一、本篇小结

Windows 安装 OpenCode v2 的难点，不在于记住某条命令，而在于让 Agent、项目、Git、构建工具和凭据处于同一个可解释的环境中。

本文的核心结论是：

1. Windows 原生项目优先原生 CLI，WSL 项目优先 WSL CLI；
2. 官方提供 Windows x64、x64 baseline、ARM64 独立 CLI，以及 x64、ARM64 Desktop；
3. 不把第三方 Windows 包管理器当作官方发行渠道；
4. 通过版本与命令路径共同识别 V1/V2，而不是只看"能否启动"；
5. WSL 仓库尽量放在 Linux 文件系统，避免跨文件系统性能和权限问题；
6. 使用 /connect 连接 Provider，密钥不进入项目与公开内容；
7. 首次任务先只读分析，再逐步开放文件修改和命令执行。

下一篇将专门处理《OpenCode V1 与 V2 冲突处理及迁移避坑》，包括配置差异、旧命令残留、同机并存、回退策略和团队迁移清单。

参考资料

• OpenCode V2 官方文档：Intro、CLI、Desktop 与 Web
• OpenCode V2 Provider 文档
• OpenCode V2 配置文档
• Microsoft：安装 WSL
• OpenCode 官方 GitHub 仓库