1. Windows 上跑 OpenCode 到底卡在哪：Node.js、npm 与 API 端点三件事
OpenCode 是一个跑在终端里的 AI 编程助手，能读你本地项目、改代码、跑命令，适合习惯命令行、又想把模型能力接进真实工程目录的开发者。它本身不绑定某一家模型服务，只要有一个兼容 OpenAI 协议的端点，就能把对话、补全、Agent 任务都指过去。对 Windows 用户来说，第一次跑通它通常不是败在 OpenCode 本身，而是败在三件小事上：Node.js 版本太旧、npm 全局目录没进 PATH、以及 API 的 Base URL 和 Key 没配对。
我见过太多人卡在opencode命令敲下去提示「无法识别」，或者配置写完了却报 401。前者是环境问题，后者是端点问题。这篇就按「先装环境、再装工具、再配 Key、最后发一次真实请求验证」的顺序走一遍，每一步都给可复制的命令和配置片段。你跟着敲，基本能在十几分钟内看到 OpenCode 正常回话。
需要先说明的是，OpenCode 的配置走的是一个 JSON 文件，路径在 Windows 上是C:\Users\你的用户名\.config\opencode\opencode.json。这个文件里要写清楚三样东西：用哪个兼容层（@ai-sdk/openai-compatible）、Base URL 指向哪里、API Key 是什么。只要这三样对，模型列表里挂几个模型名就能用。下面从 Node.js 开始。
2. 前置准备：Node.js 18+ 与 npm 全局路径在 Windows 的坑
OpenCode 依赖 Node.js 运行，官方要求 18 或更高。Windows 上装 Node.js 有两条路：官网下.msi安装包，或者用包管理器。官网方式最省心，去 nodejs.org 点 LTS 版本下载，双击一路默认下一步即可，安装器会自动把node和npm加进 PATH。如果你装了 Chocolatey 或 Scoop，也可以命令行装：
# 使用 Chocolatey choco install nodejs # 或使用 Scoop scoop install nodejs装完先别急着装 OpenCode，打开一个新的 PowerShell 窗口验证一下。注意一定要新开窗口，因为 PATH 的更新不会自动同步到已经开着的终端里：
node --version npm --version正常会输出类似v20.11.0和10.2.4的版本号。如果node能出但npm报错，多半是安装时没勾选 npm 组件，重装一次即可。如果两个都提示「无法将...识别为 cmdlet」，说明 PATH 没生效，检查系统环境变量里有没有 Node.js 的安装目录。
接下来是 Windows 上最容易埋雷的一步：npm 全局安装目录。默认情况下 npm 会把全局包装到%APPDATA%\npm，但这个目录有时不在 PATH 里，导致你npm install -g成功了，敲命令却找不到。先看一眼当前配置：
npm config get prefix如果输出的是C:\Users\你的用户名\AppData\Roaming\npm，那就要确认这个路径已经加进用户环境变量 PATH。没加的话，手动加进去，或者干脆把 prefix 设到一个你确定在 PATH 里的目录：
npm config set prefix "$env:APPDATA\npm"设完再确认一次 PATH 里包含这个目录。这一步做完，后面opencode命令能不能被识别，基本就定了。另外提醒一句，PowerShell 默认的执行策略可能会拦住某些脚本，如果后面遇到执行策略报错，用这条命令放开当前用户范围：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser环境这块就这些。Node.js 版本够、npm 全局目录在 PATH、执行策略不拦脚本，三条满足就可以进下一步。
3. 安装 OpenCode 并写入 opencode.json：Base URL、Key、Model ID 三件套
先装 OpenCode 本体，全局安装最新版：
npm install -g opencode-ai@latest装完验证：
opencode --version能打印版本号就说明命令已经可用。如果这里报「无法识别」，回到上一节检查 npm 全局目录是否在 PATH，然后重开一个 PowerShell 窗口再试。
接下来创建配置目录。OpenCode 在 Windows 上读的是用户目录下的.config\opencode：
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode"然后用记事本打开配置文件（文件不存在时记事本会新建）：
notepad "$env:USERPROFILE\.config\opencode\opencode.json"把下面这段 JSON 粘进去。这里我用 TaoToken 作为统一端点，它的 Base URL 是https://taotoken.net/api，兼容 OpenAI 协议，所以npm字段填@ai-sdk/openai-compatible。Key 去控制台创建，模型名按你实际要用的填：
{ "$schema": "https://opencode.ai/config.json", "provider": { "taotoken": { "npm": "@ai-sdk/openai-compatible", "name": "TaoToken", "options": { "baseURL": "https://taotoken.net/api", "apiKey": "你的API密钥" }, "models": { "claude-sonnet-4-5-20250929": {}, "claude-opus-4-5-20251101": {}, "gpt-5.2": {}, "gpt-5.2-codex": {}, "gemini-2.5-pro": {} } } } }三件套对照着看：Base URL 是https://taotoken.net/api，Key 是你从控制台复制的那串，Model ID 是models节点里的键名。这三个任何一个写错，请求都会失败。保存时注意记事本的「保存类型」要选「所有文件」，否则容易被存成opencode.json.txt，OpenCode 读不到。
Key 的获取入口在控制台的 API Keys 页面，创建后复制完整字符串。如果你还没账号，可以先注册再建 Key。配置写完后，模型列表里挂几个你常用的就行，不用全填。想省事的话，把models里只留一两个确认可用的模型，减少选错模型的概率。
4. 验证请求：启动 OpenCode 发一次对话确认 Key 与端点生效
配置写完，进项目目录启动 OpenCode：
cd C:\path\to\your\project opencode启动后先切模型。在 OpenCode 的交互界面里输入：
/model然后搜taotoken，从列表里选你配置的模型，比如claude-sonnet-4-5-20250929，回车确认。选完就可以发一句话测试，比如让它解释当前目录下的某个文件，或者直接问「你现在用的是哪个模型」。
如果一切正常，你会看到模型正常回话，说明 Base URL、Key、Model ID 三件套全部生效。这一步是整个流程的验收点：只要这里能出结果，前面的环境、安装、配置就都对了。
常用命令顺手记一下：/model切模型，/help看帮助，/new开新对话，/exit退出。日常用最多的就是/model和/new。如果你想让 OpenCode 读某个具体文件，直接在对话里把路径写清楚，它会去读本地内容再回答。
验证通过后，你可以把这段配置当成模板，以后换模型只改models节点，换端点只改baseURL，Key 过期就换apiKey。三件套的结构不变，改起来很快。
5. 常见报错排查：401、local proxy failed、reading choices 与命令找不到
401 Unauthorized：Key 不对或没生效。先确认opencode.json里的apiKey是完整字符串，没有多余空格或换行。然后确认这个 Key 在控制台里是启用状态。如果 Key 刚创建，复制时容易漏掉尾部字符，重新复制一次。改完配置要重启 OpenCode 才生效。
local proxy failed / 连接失败：Base URL 写错，或者网络到不了端点。检查baseURL是不是https://taotoken.net/api，注意不要多写/v1或少写协议头。如果本机有防火墙或安全软件拦了 OpenCode 的出站请求，把它加进白名单再试。
reading choices 相关报错：这类通常是响应结构不符合预期，多半是端点或模型名不匹配。确认你选的模型 ID 确实在models节点里，且这个模型在当前端点可用。换一个确认可用的模型再试，能快速判断是模型问题还是配置问题。
opencode 命令找不到：按顺序排查。先npm list -g opencode-ai确认装上了，再npm config get prefix看全局目录，然后确认这个目录在 PATH 里。最省事的办法是重开一个 PowerShell 窗口刷新 PATH，还不行就重装一次npm install -g opencode-ai@latest。
配置文件读不到：确认路径是C:\Users\你的用户名\.config\opencode\opencode.json，文件名带.json后缀，且不是.txt。用dir "$env:USERPROFILE\.config\opencode"看一眼实际文件名，不对就改名。
PowerShell 执行策略报错：用Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser放开当前用户范围，然后重开窗口。
这些报错里，401 和 local proxy failed 出现频率最高，基本都出在 Key 和 Base URL 上。把这两样对着控制台再核一遍，多数问题当场解决。
6. 把 Key 统一到 TaoToken：后续换模型、换工具都不用重配
跑通之后你会发现，OpenCode 的配置核心就是那个opencode.json，而它依赖的只是「一个兼容 OpenAI 协议的端点 + 一个 Key」。把 Key 统一到 TaoToken 之后，你以后在别的工具里接模型，也可以复用同一个 Key 和同一个 Base URL，不用每个工具都去申请一遍。
如果你还想在浏览器里直接试模型效果，可以打开模型对话页面发几条消息，确认同一个 Key 在网页端也能用。想长期把 OpenCode 当日常编码助手用，可以看下 Coding Plan 的说明，按用量选合适的档位。Key 的管理和新建都在 API Keys 页面，接入细节在接入文档里，遇到端点或参数问题翻一下就能对上。
配置这件事，一次写对，后面就是改模型名的事。把opencode.json备份一份，换机器时直接粘过去，改个 Key 就能继续用。
