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-ailatest包会被放到 npm 的全局目录通常是C:\Users\你的用户名\AppData\Roaming\npm这个目录必须出现在 PATH 里否则就会出现“装了但找不到”。npx 调用则是每次从缓存里取不依赖 PATH但每次启动稍慢也不适合长期使用。在动手装之前先把 npm 的全局路径查清楚这一步很多人跳过结果后面修 PATH 时凭感觉填路径填错了照样报错。# 查看 npm 全局安装目录 npm config get prefix # 查看当前 PATH 里是否已包含该目录 $env:Path -split ; | Select-String npmnpm 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-ailatest # 确认安装位置 npm ls -g opencode-ai安装成功的标志是输出里出现added X packages并且npm ls -g能列出 opencode-ai 及其版本号。如果卡在下载阶段很久多半是网络到 npm registry 不稳定可以临时换 registry 重试npm i -g opencode-ailatest --registryhttps://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 provideropencode 的配置文件放在用户目录下的.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/apiKey 通过{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 的非交互模式跑一个简单 promptopencode 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 叫taotokenmodel就必须以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 多写或少写路径”这两个细节上。