1. 先搞清楚这个报错到底在说什么
在 Windows PowerShell 里敲下opencode，回车后蹦出一行红字：opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这句话翻译成人话就是：PowerShell 在它认识的几个地方翻了个遍，没找到叫 opencode 的可执行文件。它不是在说 opencode 坏了，而是在说“我压根不知道 opencode 是谁”。
这个报错和 opencode 本身的功能没有半点关系，它属于 Windows 命令解析层面的问题。PowerShell 找命令的顺序大致是：内置 cmdlet、函数、别名、当前目录下的脚本、PATH 环境变量里列出的目录。只要这五类里都没有匹配项，就会抛出这条CommandNotFoundException。所以排查方向天然就落在三件事上：东西到底装没装、装到哪了、那个目录在不在 PATH 里。
我见过不少新手第一反应是去重装 opencode，结果装了三遍报错依旧，因为问题根本不在安装包，而在“装完之后系统找不到它”。还有一种情况是明明装了，但用的是npx opencode能跑、直接opencode不行，这恰恰说明包在 npm 的缓存或全局目录里，只是没进 PATH。
这篇内容适合两类人：一是刚在 Windows 上接触 opencode 的开发者，二是已经装过但换机器、换终端后突然报错的人。下面我会按“先确认安装形态、再修 PATH、最后验证连通”的顺序走一遍，并且把 endpoint 切到 TaoToken 统一通道做一次真实请求测试，确保你解决的不只是“命令能跑”，而是“能正常调模型”。
先给一个判断口诀：npx opencode能跑说明包在，opencode不能跑说明 PATH 缺；两个都不能跑说明没装或装错。你可以先用这两条命令给自己定位，再往下看对应章节。
# 测试一：走 npx 调用 npx opencode --version # 测试二：直接调用 opencode --version如果测试一有版本号输出、测试二报 cmdlet 错误，直接跳到第 3 节的 PATH 修复；如果两个都报错，从第 2 节的安装开始。
2. 安装形态与 TaoToken 通道前置准备
opencode 在 Windows 上的安装形态主要有两种：全局 npm 安装和 npx 临时调用。全局安装执行npm i -g opencode-ai@latest，包会被放到 npm 的全局目录，通常是C:\Users\你的用户名\AppData\Roaming\npm，这个目录必须出现在 PATH 里，否则就会出现“装了但找不到”。npx 调用则是每次从缓存里取，不依赖 PATH，但每次启动稍慢，也不适合长期使用。
在动手装之前，先把 npm 的全局路径查清楚，这一步很多人跳过，结果后面修 PATH 时凭感觉填路径，填错了照样报错。
# 查看 npm 全局安装目录 npm config get prefix # 查看当前 PATH 里是否已包含该目录 $env:Path -split ';' | Select-String 'npm'npm config get prefix的输出一般就是C:\Users\你的用户名\AppData\Roaming\npm。记住这个值，第 3 节要用。如果这条命令本身也报“npm 不是内部或外部命令”，说明 Node.js 都没装好，先去装 Node.js LTS 版本，再回来继续。
接着说 TaoToken 的前置。opencode 支持自定义 provider 的 base URL 和 API Key，我们要做的是把请求打到 TaoToken 的统一通道，而不是默认的官方端点。你需要准备两样东西：一个 TaoToken 的 API Key，以及确认要用的模型 ID。Key 在控制台的 API Keys 页面创建，地址是https://taotoken.net/api-keys，创建后只显示一次，记得当场复制保存。
模型 ID 建议先在模型对话页面确认一下当前可用的名称，避免配置里写了一个不存在的模型导致后面报reading choices之类的解析错误。模型对话入口在https://taotoken.net/chat，选一个你常用的模型，记下它的 ID 字符串。
这里有个容易踩的坑：TaoToken 的 API 基地址是https://taotoken.net/api，注意结尾不要多加/v1，也不要写成带查询参数的完整 URL。opencode 的 provider 配置里 baseURL 填这个值，它内部会自己拼接/chat/completions之类的路径。写错了最常见的表现就是 404 或者返回一段 HTML 而不是 JSON。
注意：API Key 属于敏感凭证，不要写进会提交到 Git 的配置文件里。opencode 支持从环境变量读取，建议用环境变量方式注入，下面第 3 节会给具体写法。
前置准备清单：Node.js 已安装且npm -v有输出、TaoToken API Key 已创建、模型 ID 已确认、知道 npm 全局目录在哪。这四样齐了，后面的配置就能一次跑通。
3. 可复制的安装与配置片段
这一节是全文的核心操作区，分三步：装包、修 PATH、写配置。每一步都给可直接复制的命令或片段，你按顺序执行即可。
3.1 全局安装 opencode
以管理员身份打开 PowerShell，执行全局安装。用管理员是为了避免 npm 全局目录写入权限不足导致的EACCES或EPERM报错。
# 全局安装最新版 npm i -g opencode-ai@latest # 确认安装位置 npm ls -g opencode-ai安装成功的标志是输出里出现added X packages并且npm ls -g能列出 opencode-ai 及其版本号。如果卡在下载阶段很久，多半是网络到 npm registry 不稳定，可以临时换 registry 重试：
npm i -g opencode-ai@latest --registry=https://registry.npmmirror.com装完后先别急着敲opencode，因为大概率还是报 cmdlet 错误，这正是 PATH 没配好的表现，进入下一步。
3.2 把 npm 全局目录写进 PATH
先拿到全局目录的真实路径：
$npmPrefix = npm config get prefix Write-Output $npmPrefix然后把这个路径追加到用户级 PATH。用用户级而不是系统级，避免影响其他账户，也不需要管理员权限（虽然你当前是管理员窗口，但用户级更稳妥）。
# 读取当前用户 PATH $userPath = [Environment]::GetEnvironmentVariable('Path', 'User') # 判断是否已包含，避免重复追加 if ($userPath -notlike "*$npmPrefix*") { [Environment]::SetEnvironmentVariable('Path', "$userPath;$npmPrefix", 'User') Write-Output "已追加: $npmPrefix" } else { Write-Output "PATH 中已存在，无需追加" }关键点：SetEnvironmentVariable写入的是持久化环境变量，但当前这个 PowerShell 窗口不会立即生效，因为进程启动时已经把旧 PATH 读进内存了。你必须关掉当前窗口，重新开一个 PowerShell，新窗口才会读到更新后的 PATH。很多人改完 PATH 当场测试还是报错，就是栽在这个细节上。
重开窗口后验证：
$env:Path -split ';' | Select-String 'npm' opencode --version如果--version能打印版本号，命令层面的问题就彻底解决了。如果还报错，回到第 5 节对照排查。
3.3 配置 TaoToken provider
opencode 的配置文件放在用户目录下的.opencode文件夹里，主配置文件是opencode.json（部分版本用config.json，以你安装版本的文档为准，下面以opencode.json为例）。路径是C:\Users\你的用户名\.opencode\opencode.json。
先创建目录（如果不存在）：
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.opencode"然后写入配置。下面这段 JSON 可以直接复制，把你的API_KEY和模型 ID 替换成你自己的：
{ "$schema": "https://opencode.ai/config.json", "provider": { "taotoken": { "npm": "@ai-sdk/openai-compatible", "name": "TaoToken", "options": { "baseURL": "https://taotoken.net/api", "apiKey": "{env:TAOTOKEN_API_KEY}" }, "models": { "gpt-4o-mini": { "name": "gpt-4o-mini" } } } }, "model": "taotoken/gpt-4o-mini" }三件套对照一下：Base URL 是https://taotoken.net/api，Key 通过{env:TAOTOKEN_API_KEY}从环境变量读取，Model ID 是gpt-4o-mini（换成你在模型对话页确认过的那个）。model字段的格式是provider名/模型ID，这里 provider 名是taotoken，所以写成taotoken/gpt-4o-mini。
设置环境变量，同样用用户级持久化：
[Environment]::SetEnvironmentVariable('TAOTOKEN_API_KEY', '你的API_KEY', 'User')设置完同样要重开 PowerShell 窗口才生效。验证环境变量是否读到：
$env:TAOTOKEN_API_KEY能打印出你的 Key 就对了。注意不要把 Key 直接硬编码进 JSON 的apiKey字段，那样一旦配置文件被同步或提交就会泄露。
4. 验证请求与成功结果对照
配置写完，重开一个 PowerShell 窗口，做三层验证：命令层、配置层、请求层。三层都过，才算真正跑通。
第一层，命令可用性：
opencode --version预期输出类似0.x.x的版本号。这一步过不了说明 PATH 还没生效，回第 3.2 节。
第二层，配置是否被正确加载。opencode 一般提供查看当前配置的命令，不同版本略有差异，常见的是：
opencode config或者进入交互界面后查看 provider 列表。预期能看到taotoken这个 provider 以及你配置的模型。如果 provider 列表里没有 taotoken，说明 JSON 路径写错或格式有误，用下面的命令校验 JSON 语法：
Get-Content "$env:USERPROFILE\.opencode\opencode.json" -Raw | ConvertFrom-JsonConvertFrom-Json报错就说明 JSON 有语法问题，常见是多了尾逗号或者引号不配对。
第三层，发一次真实请求。最直接的方式是用 opencode 的非交互模式跑一个简单 prompt：
opencode run "用一句话解释什么是 HTTP 状态码 401"预期结果是终端流式输出一段中文解释，没有报错。如果返回的是 401，说明 Key 没读到或无效；如果返回reading choices相关错误，说明响应体不是预期的 JSON 结构，多半是 baseURL 写错导致打到了网页而不是 API；如果报local proxy failed或连接超时，说明网络到taotoken.net不通，检查本机网络和防火墙。
成功时的完整链路是这样的：PowerShell 找到 opencode 可执行文件 → opencode 读取~/.opencode/opencode.json→ 解析出 providertaotoken→ 从环境变量取到 Key → 向https://taotoken.net/api发起 chat completions 请求 → 拿到流式响应并打印。任何一环断了，都会在第三层暴露出来。
再补一个纯 API 层的连通性测试，绕开 opencode，直接验证 Key 和端点是否可用，这样能把“opencode 配置问题”和“凭证/网络问题”分开：
$headers = @{ "Authorization" = "Bearer $env:TAOTOKEN_API_KEY" "Content-Type" = "application/json" } $body = @{ model = "gpt-4o-mini" messages = @(@{ role = "user"; content = "ping" }) } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri "https://taotoken.net/api/chat/completions" -Method Post -Headers $headers -Body $body返回里带choices数组且message.content有内容，说明 Key、端点、模型三者都对。这一步过了但 opencode 还报错，问题就锁定在 opencode 的配置文件上，而不是凭证。
5. 本篇常见报错对照排查
这一节把实际会撞到的报错按现象归类，每条给触发原因和修复动作。你可以拿终端里的红字直接对照。
报错一：opencode : 无法将“opencode”项识别为 cmdlet...这是本篇主题。原因只有两类：没装，或装了但 PATH 没有全局目录。修复动作：先npx opencode --version判断包在不在；在的话执行第 3.2 节的 PATH 追加，然后重开窗口再测。如果npx也报错，执行第 3.1 节全局安装。注意改完 PATH 不重开窗口是最常见的“改了没用”。
报错二：npm : 无法将“npm”项识别为 cmdlet...连 npm 都找不到，说明 Node.js 没装或没进 PATH。去 Node.js 官网下 LTS 安装包，安装时勾选“Add to PATH”，装完重开窗口验证node -v和npm -v。这一步不解决，后面所有 npm 命令都无从谈起。
报错三：401 Unauthorized或invalid api keyKey 没读到或写错。先$env:TAOTOKEN_API_KEY确认环境变量有值；再确认 JSON 里写的是{env:TAOTOKEN_API_KEY}而不是字面量；最后确认 Key 没有多余空格或换行。环境变量是用户级设置的，换终端（比如从 PowerShell 换到 CMD）也要重开才生效。
报错四：reading 'choices'或Cannot read properties of undefined (reading 'choices')响应体不是预期的 OpenAI 兼容 JSON，通常是 baseURL 写错。检查是不是写成了https://taotoken.net（少了/api）或者https://taotoken.net/api/v1（多了/v1）。正确值是https://taotoken.net/api。也可能是模型 ID 不存在，服务端返回了错误对象而非 choices 数组，用第 4 节的Invoke-RestMethod单独测一次就能看到真实错误信息。
报错五：local proxy failed或ECONNREFUSED/ETIMEDOUT本机到taotoken.net的网络不通。先Test-NetConnection taotoken.net -Port 443看端口通不通；不通就检查本机防火墙、公司网络策略或 DNS。这类错误和 opencode 配置无关，属于网络层。
报错六：OAuth相关提示或要求登录说明 opencode 走了默认的官方 provider 认证流程，没读到你自定义的 provider。检查 JSON 里model字段是否写成了taotoken/模型ID，以及 provider 名是否和model前缀一致。配置里 provider 叫taotoken，model就必须以taotoken/开头，写错前缀它会回退到默认认证。
报错七：EACCES/EPERM安装失败npm 全局目录没有写权限。用管理员身份开 PowerShell 重装，或者把 npm prefix 改到用户目录下（npm config set prefix "$env:USERPROFILE\.npm-global"），再把新目录加进 PATH。
排查顺序建议固定为：命令能不能找到 → 配置能不能加载 → 请求能不能通。三层逐层排除，不要一上来就重装，重装解决不了 PATH 问题，只会浪费时间。
6. 后续接入与长期使用建议
命令跑通、请求验证过之后，日常使用还有几个值得注意的点。
第一，PATH 修复是一次性的，但换机器、重装系统、切换 Node 版本管理器（比如 nvm-windows）后，npm 全局目录可能变化，PATH 里的旧路径就失效了。遇到“昨天还好今天报错”，先npm config get prefix看路径是否变了，再对照 PATH 里有没有这个新路径。
第二，环境变量方式管理 Key 比硬编码安全，但也意味着每个新开的终端都要能读到用户级变量。如果你用某些 IDE 内置终端，它可能继承的是启动时的环境，改完变量要重启 IDE 而不是只重开终端标签。
第三，长期做编码和 Agent 类任务的话，按量调用和包周期调用的成本结构不一样。TaoToken 的 Coding Plan 适合高频、长时间的编码场景，入口在https://taotoken.net/coding-plan，可以先看下额度模型再决定用哪种方式。如果只是偶尔跑几个 prompt 验证连通性，按量走 API 就够了。
第四，配置文件的$schema字段建议保留，很多编辑器会据此做字段补全和校验，能提前发现拼写错误。改完 JSON 养成用ConvertFrom-Json校验一次的习惯，比等到运行时才报错省事。
第五，如果你在团队里分发这套配置，不要把带 Key 的opencode.json直接共享，共享一份把apiKey写成{env:TAOTOKEN_API_KEY}的模板，让每个人自己设环境变量。这样配置可以进版本库，Key 不会泄露。
最后给一个日常自检的小命令组合，出问题时依次跑一遍，基本能定位到具体环节：
opencode --version $env:TAOTOKEN_API_KEY.Length Get-Content "$env:USERPROFILE\.opencode\opencode.json" -Raw | ConvertFrom-Json Test-NetConnection taotoken.net -Port 443四条分别对应：命令在不在、Key 读没读到、配置合不合法、网络通不通。四条都正常，请求基本不会失败；哪条异常就回对应章节处理。这套流程我在多台 Windows 机器上验证过，从全新环境到跑通第一次请求，按第 3 节顺序操作通常十分钟内能完成，卡住的地方九成集中在“改完 PATH 没重开窗口”和“baseURL 多写或少写路径”这两个细节上。
