opencode : 无法将"opencode"项识别为 cmdlet、函数、脚本文件或可运行程序的名称 解决方案

问题描述

在 Windows 上通过 npm 全局安装 OpenCode 后，PowerShell 或 CMD 中执行 opencode 命令出现：

opencode : 无法将"opencode"项识别为 cmdlet、函数、脚本文件或可运行程序的名称。
请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。
所在位置 行:1 字符: 1
+ opencode
+ ~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (opencode:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

原因分析

和 OpenClaw 的同类错误完全一样，根本原因是 npm 全局安装的 bin 目录不在系统 PATH 环境变量中。在 Windows 上，npm 全局包的路径通常是：

C:\Users\你的用户名\AppData\Roaming\npm\

OpenCode 安装后，应该在该目录下生成 opencode.cmd（CMD 脚本）和 opencode.ps1（PowerShell 脚本），但 PATH 没包含这个目录，所以 PowerShell 找不到。

解决方案

方案一：添加 npm 全局路径到 PATH

# 1. 查看 npm 全局路径
npm config get prefix
# 输出: C:\Users\xxx\AppData\Roaming\npm

# 2. 添加到系统 PATH（管理员权限运行）
$npmPath = npm config get prefix
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$npmPath",
    "User"
)

# 3. 重启终端

方案二：直接用完整路径执行

# 在终端输入完整路径
& "$(npm config get prefix)\opencode.cmd"

方案三：使用 npx 调用

npx opencode

方案四：添加到 PowerShell Profile（永久快捷方式）

# 创建 PowerShell Profile
New-Item -Path $PROFILE -Type File -Force

# 添加 alias
Add-Content $PROFILE "`nfunction opencode { & '$(npm config get prefix)\opencode.cmd' @args }"

# 重新加载
. $PROFILE

总结

opencode 命令识别问题与 openclaw、codex、gemini 等所有 npm 全局安装的 CLI 工具一样，解决方案都是：确保 npm config get prefix 的路径在 PATH 中。这个知识对所有 npm 全局工具通用。