1. Windows 上跑 opencode先别急着装 Node.js如果你刚在 Windows 上接触 opencode大概率会经历两个卡点一是 Node.js 版本装乱了二是 API Key 不知道往哪配。opencode 本身是个命令行里的 AI 编码助手能读你当前目录的代码、帮你改文件、跑命令适合想用自然语言驱动项目开发的开发者。它依赖 Node.js 运行而 Node.js 在 Windows 上直接装官方安装包后面想换版本会很痛苦——卸载重装、环境变量残留、全局包丢失全是坑。我自己的做法是先用 nvm-windows 把 Node.js 版本管起来再用 TaoToken 统一 API Key 和通道这样 opencode 换模型、换项目都不用反复改配置。这篇就按这个顺序把每一步的命令和配置文件都给你照着敲就能跑通。先说清楚适用人群你是 Windows 用户装过或没装过 Node.js 都行想用 opencode 做日常编码辅助不追求本地跑大模型本地模型后面会提一句 ollama 的接法但不是主线。整篇的核心检索词就是 opencode、Windows、Node.js、nvm、API Key 配置你按这几个词找问题基本都能对上。2. 用 nvm-windows 管好 Node.js 版本2.1 为什么不用官方安装包opencode 对 Node.js 版本有要求通常需要 18 以上某些新特性可能要 20。如果你电脑里已经有别的项目锁在 Node 16直接升级会把老项目搞崩。nvm-windows 就是解决这个的它让你在同一台机器上装多个 Node 版本用一条命令切换全局包按版本隔离。安装前先做一件事把系统里已有的 Node.js 卸载干净。控制面板卸载 Node.js然后检查这几个目录是否还在有就手动删掉——C:\Program Files\nodejs、C:\Users\你的用户名\AppData\Roaming\npm、C:\Users\你的用户名\AppData\Roaming\npm-cache。环境变量里如果有 NODE_PATH 之类的也清掉。这一步不做后面 nvm 切换会失效。2.2 安装 nvm-windows 并设置镜像去 nvm-windows 的 releases 页面下载nvm-setup.exe双击安装。安装过程中有两个目录要选nvm 安装目录建议D:\dev\nvm别放 C 盘默认路径后面 Node 都装这下面。Node.js symlink 目录建议D:\dev\nodejs这是 nvm 用来指向当前激活版本的软链接。装完后打开一个新的 cmd必须新开让环境变量生效验证nvm version能打印版本号就说明装好了。接着设置国内镜像不然下载 Node 会很慢。nvm-windows 的镜像配置在安装目录下的settings.txt直接编辑D:\dev\nvm\settings.txt加上两行node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/保存后安装一个 Node 版本试试nvm install 20.11.1 nvm use 20.11.1 node -v npm -vnode -v输出v20.11.1就对了。如果报nvm use失败多半是没用管理员权限开 cmd右键 cmd 选“以管理员身份运行”再试。切换版本就是再nvm install另一个版本然后nvm use全局包不会串。2.3 装 opencodeNode 就绪后用 npm 全局装 opencodenpm install -g opencode-ai装完验证opencode --version有版本号输出即可。如果提示命令找不到检查D:\dev\nodejs是否在 PATH 里nvm 正常工作时这个软链接目录会自动进 PATH。3. 用 TaoToken 统一 Key 和 API 通道3.1 为什么要在 opencode 里配 TaoTokenopencode 支持多种模型提供方你可以直接填某家的 Key但问题是换模型就要换 Key、换 baseURL项目一多配置就散。TaoToken 提供统一的 API 通道和 Key 管理opencode 里只配一次后面切模型只改模型名。它的 API 地址是https://taotoken.net/api官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后在控制台生成 Key。先去控制台拿 Key打开https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite登录后进 API Keys 页面创建一个复制出来。这个 Key 就是 opencode 要填的凭证。3.2 opencode 配置文件骨架opencode 的配置放在项目根目录的opencode.json或者全局配置目录。项目级配置更灵活建议每个项目一份。在你要开发的项目文件夹下新建opencode.json内容如下{ $schema: https://opencode.ai/config.json, provider: { taotoken: { name: TaoToken, npm: ai-sdk/openai-compatible, options: { baseURL: https://taotoken.net/api, apiKey: 你的_TaoToken_Key }, models: { claude-sonnet-4-5: { name: claude-sonnet-4-5 }, gpt-4o: { name: gpt-4o } } } } }几个关键点npm字段用ai-sdk/openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议baseURL填https://taotoken.net/api注意不要多加斜杠apiKey填你刚复制的 Key。models里列你想用的模型名具体可用模型以控制台或文档为准接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。如果你不想把 Key 写进文件项目要提交 git 的话可以用环境变量。把apiKey那行改成apiKey: {env:TAOTOKEN_API_KEY}然后在系统环境变量里加TAOTOKEN_API_KEY值是你的 Key。这样配置文件可以安全提交。3.3 启动并选模型在项目目录下用管理员身份打开 cmd运行opencode进入交互界面后输入/models应该能看到taotoken下面的模型列表。选一个比如claude-sonnet-4-5就可以开始对话了。第一次用建议先让它读一下项目结构比如输入“列出当前目录的文件并说明项目类型”确认它能正常读文件、正常返回。4. 验证请求确认环境真的通了配置完别急着写业务代码先做一次最小验证。在 opencode 对话框里输入读取当前目录下的 package.json告诉我项目名称和依赖数量如果项目里没有 package.json就换成任意一个存在的文件比如README.md。正常的话它会调用工具读文件然后返回内容摘要。这一步验证了三件事Node 环境正常、opencode 启动正常、TaoToken 通道能通。如果你想在命令行层面单独验证 API 通道可以用 curlWindows 10 以上自带curl https://taotoken.net/api/v1/models -H Authorization: Bearer 你的_TaoToken_Key返回模型列表的 JSON 就说明 Key 和通道都没问题。这一步排障很有用能把 opencode 的问题和 API 通道的问题分开。5. 本篇常见错排查5.1 nvm use 报错或切换后 node 版本没变最常见原因是没管理员权限。nvm-windows 切换版本要改软链接必须管理员 cmd。另一个原因是之前装过官方 Node.js 没卸干净C:\Program Files\nodejs还在PATH 里它排在前面。卸载官方版并删目录重开 cmd。5.2 opencode 启动报找不到模块或版本不兼容先确认node -v是 18 以上。如果 nvm 切了版本但 opencode 是旧版本 Node 下装的全局包可能不兼容。重新npm install -g opencode-ai一次让它在当前 Node 版本下重装。5.3 /models 里看不到 TaoToken 的模型检查opencode.json的位置必须在运行 opencode 的那个目录下。如果你在 A 目录启动 opencode配置文件却在 B 目录它读不到。另外检查 JSON 格式多一个逗号都会导致解析失败。可以用node -e require(./opencode.json)验证 JSON 是否合法。5.4 请求返回 401 或鉴权失败Key 错了或没生效。先确认apiKey字段填的是完整 Key没有多余空格。如果用环境变量方式确认TAOTOKEN_API_KEY在当前 cmd 会话里能echo %TAOTOKEN_API_KEY%出来。改完环境变量要重开 cmd。5.5 想接 ollama 本地模型如果你本机跑了 ollamaopencode 也能接。在opencode.json的provider里加一段ollama: { name: ollama, npm: ai-sdk/openai-compatible, options: { baseURL: http://localhost:11434/v1 }, models: { qwen3.5:27b: { name: qwen3.5:27b } } }启动后/models里就能选。但说实话笔记本能跑的本地模型从思考到执行代码的连贯性跟云端模型差距明显入门阶段建议先用 TaoToken 的通道跑通流程本地模型当补充。6. 后续怎么用得更顺环境通了之后日常使用有几个习惯能省事。一是每个项目单独放opencode.json模型按项目需求选前端项目用响应快的复杂重构用推理强的。二是 Key 用环境变量注入别硬编码。三是遇到 opencode 行为异常先用第 4 节的 curl 验证通道通道没问题就查 opencode 版本和配置文件。如果你打算长期用 opencode 做编码和 Agent 任务可以看下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它针对高频编码场景做了额度优化。日常只是想验证模型对话效果用模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite直接试就行。Key 管理和新建都在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。Claude Code 相关的接入说明在https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite。最后提醒一句opencode 再顺手也替代不了你对项目结构的理解。它读文件、改代码、跑命令但方案对不对、边界在哪还是得你自己判断。先把 nvm 和 Key 这两个地基打稳后面换模型、换项目都是改几行配置的事。
