Windows10使用OpenCode Desktop自带CLI配置指南

适用场景：只安装 OpenCode Desktop（桌面版），不安装 npm 版 OpenCode；在 CMD、PowerShell、Git Bash 中直接使用 opencode 命令。如果系统里已经装过 npm 版 OpenCode，先卸载它。

本文以默认的“当前用户”安装方式为例，桌面版路径为： %LOCALAPPDATA%\Programs\@opencode-aidesktop

1. 原理说明

OpenCode Desktop 安装目录里自带了一份 CLI 二进制：

%LOCALAPPDATA%\Programs\@opencode-aidesktop\resources\opencode-cli.exe

这个路径是稳定的，桌面版升级时会原地替换文件，路径不变。

桌面版运行时，还会把 CLI 复制到带版本号的目录：

%APPDATA%\ai.opencode.desktop\cli\<版本>-<架构>\opencode-cli.exe

例如：

%APPDATA%\ai.opencode.desktop\cli\2.2.6-x64\opencode-cli.exe

不要把这个带版本号的路径写进 PATH 或 shim，因为桌面版每次升级，2.2.6-x64 这段都会变，命令会失效。

另一个问题：桌面版自带的文件叫 opencode-cli.exe，不是 opencode.exe，所以不能只把目录加进 PATH 就得到 opencode 命令。需要创建一个名为 opencode 的转发脚本（shim）。

2. 前置检查

打开 PowerShell，确认桌面版和自带 CLI 是否存在：

# 检查桌面版自带 CLI
Test-Path "$env:LOCALAPPDATA\Programs\@opencode-aidesktop\resources\opencode-cli.exe"

# 查看 CLI 版本
& "$env:LOCALAPPDATA\Programs\@opencode-aidesktop\resources\opencode-cli.exe" --version

# 查看桌面版记录的 CLI 版本
Get-Content "$env:LOCALAPPDATA\Programs\@opencode-aidesktop\resources\opencode-cli.version"

预期输出类似：

True
opencode v2.2.6
2.2.6

同时检查系统里现有的 opencode 来源：

Get-Command opencode -All -ErrorAction SilentlyContinue | Format-List Name,CommandType,Source
where.exe opencode
npm ls -g --depth=0

如果 npm ls -g --depth=0 里出现 @opencode/cli，说明装了 npm 版，继续下一步卸载。

3. 卸载 npm 版 OpenCode

3.1 执行卸载

npm uninstall -g @opencode/cli

3.2 确认卸载结果

npm ls -g --depth=0

正常情况下只会剩下 npm 自己，例如：

C:\Users\<用户名>\AppData\Roaming\npm
`-- npm@11.19.0

3.3 清理残留（可选）

如果之前安装过程中断过，可能在 %APPDATA%\npm 留下临时的 shim 文件，例如：

.opencode-YvySKsRm
.opencode.cmd-U9bdMxHM
.opencode.ps1-YdoRpeH4
opencode
opencode.cmd
opencode.ps1
opencode2
opencode2.cmd
opencode2.ps1

先查看：

Get-ChildItem "$env:APPDATA\npm" -Force | Where-Object Name -like '*opencode*'

确认没有其他程序在使用后，再删除：

Remove-Item "$env:APPDATA\npm\opencode*" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:APPDATA\npm\.opencode*" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:APPDATA\npm\node_modules\@opencode" -Recurse -Force -ErrorAction SilentlyContinue

删除后再次确认：

Get-Command opencode -All -ErrorAction SilentlyContinue

此时应该找不到 opencode，这是正常的，下一步会创建桌面版的 shim。

4. 创建 shim

shim 统一放到：

%USERPROFILE%\.opencode\bin

这个目录也是 OpenCode 官方安装脚本默认使用的目录。

下面的 shim 内容按默认安装路径 %LOCALAPPDATA%\Programs\@opencode-aidesktop 编写。如果你的 OpenCode Desktop 安装在其他位置，请把 shim 里的路径替换成实际路径（查找方法见 11.4）。

4.1 创建目录

$dir = "$env:USERPROFILE\.opencode\bin"
New-Item -ItemType Directory -Force -Path $dir | Out-Null

4.2 创建 `opencode.cmd`（供 CMD 使用）

@'
@echo off
"%LOCALAPPDATA%\Programs\@opencode-aidesktop\resources\opencode-cli.exe" %*
exit /b %errorlevel%
'@ | Set-Content -Path "$dir\opencode.cmd" -Encoding ASCII

4.3 创建 `opencode.ps1`（供 PowerShell 使用）

@'
$exe = Join-Path $env:LOCALAPPDATA 'Programs\@opencode-aidesktop\resources\opencode-cli.exe'
if ($MyInvocation.ExpectingInput) {
  $input | & $exe @args
} else {
  & $exe @args
}
exit $LASTEXITCODE
'@ | Set-Content -Path "$dir\opencode.ps1" -Encoding ASCII

4.4 创建 `opencode`（供 Git Bash 使用，可选）

@'
#!/bin/sh
if command -v cygpath >/dev/null 2>&1; then
  LOCALAPPDATA="$(cygpath -u "$LOCALAPPDATA")"
fi
exec "$LOCALAPPDATA/Programs/@opencode-aidesktop/resources/opencode-cli.exe" "$@"
'@ | Set-Content -Path "$dir\opencode" -Encoding ASCII

创建完成后目录内容应为：

opencode
opencode.cmd
opencode.ps1

5. 把 shim 目录加入用户 PATH

推荐放在用户 PATH 的最前面，确保优先于可能残留的 npm 目录。

5.1 PowerShell 方式

$dir = "$env:USERPROFILE\.opencode\bin"
$old = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($null -eq $old) { $old = '' }

# 去重，并放到最前面
$parts = @($old -split ';' | Where-Object { $_ -and $_ -ne $dir })
$new = (@($dir) + $parts) -join ';'

[Environment]::SetEnvironmentVariable('Path', $new, 'User')

# 让当前窗口立即生效（新窗口会自动读取）
$env:PATH = $dir + ';' + $env:PATH

5.2 图形界面方式（等效）

按 Win + R，输入 sysdm.cpl 回车。
选择“高级” → “环境变量”。
在上方“用户变量”里选中 Path，点击“编辑”。
点击“新建”，输入：%USERPROFILE%\.opencode\bin
选中这一项，点击“上移”，移到最顶部。
连续点击“确定”保存。

注意：改的是“用户变量”里的 Path，不是“系统变量”。

6. 验证

必须新开一个终端窗口（已经打开的窗口不会自动读取新的 PATH）。

PowerShell

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

预期：

Name        : opencode.ps1
CommandType : ExternalScript
Source      : C:\Users\<用户名>\.opencode\bin\opencode.ps1

opencode v2.2.6

CMD

where opencode
opencode --version

预期能找到 ...\.opencode\bin\opencode.cmd，并且版本与桌面版一致。

Git Bash（可选）

which opencode
opencode --version

7. 一次完成全部步骤（可选脚本）

如果是从零开始配置，可以直接把下面整段脚本保存为 install-opencode-cli.ps1，用 PowerShell 运行。

$ErrorActionPreference = 'Stop'

$exe = Join-Path $env:LOCALAPPDATA 'Programs\@opencode-aidesktop\resources\opencode-cli.exe'
if (-not (Test-Path $exe)) {
    throw "未找到桌面版 CLI：$exe。请确认 OpenCode Desktop 已安装，或修改脚本中的路径。"
}

$dir = Join-Path $env:USERPROFILE '.opencode\bin'
New-Item -ItemType Directory -Force -Path $dir | Out-Null

@'
@echo off
"%LOCALAPPDATA%\Programs\@opencode-aidesktop\resources\opencode-cli.exe" %*
exit /b %errorlevel%
'@ | Set-Content -Path "$dir\opencode.cmd" -Encoding ASCII

@'
$exe = Join-Path $env:LOCALAPPDATA 'Programs\@opencode-aidesktop\resources\opencode-cli.exe'
if ($MyInvocation.ExpectingInput) {
  $input | & $exe @args
} else {
  & $exe @args
}
exit $LASTEXITCODE
'@ | Set-Content -Path "$dir\opencode.ps1" -Encoding ASCII

@'
#!/bin/sh
if command -v cygpath >/dev/null 2>&1; then
  LOCALAPPDATA="$(cygpath -u "$LOCALAPPDATA")"
fi
exec "$LOCALAPPDATA/Programs/@opencode-aidesktop/resources/opencode-cli.exe" "$@"
'@ | Set-Content -Path "$dir\opencode" -Encoding ASCII

$old = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($null -eq $old) { $old = '' }
$parts = @($old -split ';' | Where-Object { $_ -and $_ -ne $dir })
[Environment]::SetEnvironmentVariable('Path', (@($dir) + $parts) -join ';', 'User')

$env:PATH = $dir + ';' + $env:PATH
Write-Host "已创建 shim：$dir"
Write-Host "请新开一个终端，然后执行：opencode --version"

8. 更新策略与限制

8.1 `opencode update` 不会更新桌面版 CLI

桌面版 CLI 不属于 npm、pnpm、bun、brew、winget、curl 等任何一种可识别的安装方式。执行：

opencode update

会提示：

could not detect the installation method. update with your package manager or download the latest release.

后台自动更新检查也会跳过（update skipped: installation method not found）。

8.2 正确更新方式

通过 OpenCode Desktop 自身的更新功能升级桌面版。升级完成后：

resources\opencode-cli.exe 会被替换为新版本；
我们的 shim 指向的是这个稳定路径，所以 opencode 会自动变成新版本；
可以用下面的命令确认：

opencode --version
Get-Content "$env:LOCALAPPDATA\Programs\@opencode-aidesktop\resources\opencode-cli.version"

两个版本号应当一致。

9. 副作用与注意事项

CLI 版本跟随桌面版 CLI 不再独立更新，桌面版是什么版本，命令行就是什么版本。如果桌面版关闭了自动更新，CLI 也会停留在旧版本。
不要指向带版本号的目录 不要使用： %APPDATA%\ai.opencode.desktop\cli\2.2.6-x64\opencode-cli.exe 桌面版升级后这个路径会失效。始终使用： %LOCALAPPDATA%\Programs\@opencode-aidesktop\resources\opencode-cli.exe
不要同时保留 npm 版 两个版本会共用同一份配置和数据目录： %USERPROFILE%\.config\opencode %USERPROFILE%\.local\share\opencode 版本不一致时可能出现数据库或协议不兼容。建议只保留一种。
桌面版升级时不要长期占用 CLI 文件 如果 opencode 正在后台长期运行，桌面版更新替换 resources\opencode-cli.exe 时可能遇到文件占用。更新前关闭终端里正在运行的 opencode 即可。
卸载桌面版后命令会消失 这是预期行为。opencode uninstall 对桌面版二进制通常也无法识别安装方式，应该通过 Windows 的“应用和功能”或桌面版自带卸载程序卸载。
桌面版内置的 “Install CLI” 目前仅 macOS 可用 桌面版代码里有 “Install CLI” 功能，但菜单项被限定为 macOS。Windows 上需要按本文手动创建 shim。

10. 回退到 npm 版

如果以后想重新使用 npm 版：

npm install -g @opencode/cli

然后从用户 PATH 中移除 %USERPROFILE%\.opencode\bin，或者直接删除该 shim 目录：

Remove-Item "$env:USERPROFILE\.opencode\bin" -Recurse -Force

再新开终端验证：

where.exe opencode
opencode --version

npm 版安装后，opencode update 可以正常识别 npm 安装方式并执行更新。

11. 常见问题排查

11.1 新终端里仍然提示找不到 `opencode`

# 查看 PATH 中是否包含 shim 目录
$env:PATH -split ';' | Select-String '\.opencode\\bin'

# 查看命令解析情况
Get-Command opencode -All -ErrorAction SilentlyContinue
where.exe opencode

常见原因：

没有新开终端；
PATH 加到了“系统变量”而不是“用户变量”；
shim 目录被放在了 npm 目录后面，旧的 npm shim 抢先命中。

11.2 版本不是桌面版的版本

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

如果仍然指向 %APPDATA%\npm\opencode.ps1 等旧 shim，说明 npm 版没卸载干净，或者 PATH 顺序不对。

11.3 PowerShell 提示脚本被禁止运行

如果 opencode.ps1 被执行策略拦截，可以：

临时改用 CMD 的 opencode.cmd；
或者只为当前用户放宽策略：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

11.4 桌面版安装在其他位置

如果桌面版不是默认的当前用户安装路径，先找到真实路径：

Get-Process OpenCode -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty Path

或者搜索：

Get-ChildItem "$env:LOCALAPPDATA\Programs", "$env:ProgramFiles" -Recurse `
  -Filter 'opencode-cli.exe' -ErrorAction SilentlyContinue |
  Select-Object FullName

然后把 shim 里的路径替换成实际路径。

11.5 `resources\opencode-cli.exe` 不存在

极少数情况下，桌面版可能只保留了带版本号的运行副本。可以先查看：

Get-ChildItem "$env:APPDATA\ai.opencode.desktop\cli" -Directory |
  Sort-Object Name -Descending |
  Select-Object -First 1

然后把 shim 指向该目录下的 opencode-cli.exe。但这种方式在桌面版升级后需要同步修改 shim，只作为临时方案。

12. 最终文件清单

%USERPROFILE%\.opencode\bin\opencode
%USERPROFILE%\.opencode\bin\opencode.cmd
%USERPROFILE%\.opencode\bin\opencode.ps1

用户 PATH 最前面新增：

%USERPROFILE%\.opencode\bin

实际执行的程序：

%LOCALAPPDATA%\Programs\@opencode-aidesktop\resources\opencode-cli.exe

最终效果：

PS> opencode --version
opencode v2.2.6

版本号以你当前安装的 OpenCode Desktop 为准。

#ai #opencode