1. Windows 上装完 OpenCode 却跑不起来问题多半在 Node.js 与 Git 环境OpenCode 是一款在终端里运行的 AI 编程助手能接 Claude、GPT、Gemini 这类大模型帮你读代码、改文件、跑命令。它比 Cursor、VS Code 这类图形编辑器轻得多一个命令行窗口就能干活特别适合习惯在 PowerShell 里敲命令的 Windows 开发者。但很多人装完之后卡住opencode命令找不到、npm 全局包装不上、Git 拉不动依赖、API Key 散落在四五个配置文件里改一处忘一处。这篇就按「Windows 系统安装 OpenCode」这条线把 Node.js、Git、npm 三件套和统一 Key 管理一次讲透装完就能直接发请求。先说清楚适合谁看。如果你满足下面任意一条这篇就是写给你的刚在 Windows 上装完 OpenCodeopencode --version报「不是内部或外部命令」npm 全局安装卡在idealTree半天不动手里有多个模型的 Key想用一个通道统一管起来用 Git 拉代码时提示找不到git或凭据反复弹窗。这些问题的根子往往不在 OpenCode 本身而在它依赖的 Node.js 版本、npm 全局路径、Git 的 PATH 配置以及 Key 的存放方式。我试过在一台干净的 Windows 11 上从零走一遍踩的坑基本集中在三处Node.js 版本低于 20 导致 OpenCode 启动即崩npm 全局目录没进 PATH装完命令找不到Key 直接写死在opencode.json里换模型要改文件还要重启终端。下面按「先修环境、再装工具、最后统一 Key」的顺序来每一步都给可复制的命令和配置片段你照着敲就行。核心检索词就三个Windows 安装 OpenCode、Node.js 与 Git 环境、TaoToken 统一 Key全文围绕它们展开。2. 装 OpenCode 前先把 Node.js、Git、npm 三件套理顺OpenCode 的运行依赖 Node.js 20 及以上版本这是硬门槛。低于 20 会在启动时抛SyntaxError或直接闪退因为它的部分依赖用了较新的运行时特性。Git 则是拉代码、管理依赖、以及 OpenCode 内部调用版本控制时的必需品。npm 随 Node.js 一起装但它的全局目录默认不在 PATH 里这是「命令找不到」的头号原因。2.1 Node.js 安装与版本校验去 Node.js 官网下 LTS 版选 v20.x 或更高。安装时那个「Add to PATH」的勾一定要留着它会把node和npm写进系统环境变量。装完别急着下一步先开一个新的 PowerShell 窗口验证——注意是新开旧窗口读不到刚写入的 PATH。node -v npm -v正常会输出类似v20.11.1和10.2.4。如果node -v报错八成是 PATH 没生效重启终端或注销重登一次。如果版本低于 20去官网下新版覆盖安装别用npm install -g node那种野路子升级容易把全局目录搞乱。2.2 Git 安装与 PATH 确认Git 去官网下 64 位安装包全程默认选项即可。安装向导里有个「Adjusting your PATH environment」默认选的是「Git from the command line and also from 3rd-party software」保持默认就对了。装完同样新开终端验证git --version输出git version 2.44.0.windows.1这类就正常。如果报「无法将 git 识别为 cmdlet」说明 PATH 没配好手动把C:\Program Files\Git\cmd加进系统环境变量即可。2.3 npm 全局目录与 PATH 对齐这一步最容易被忽略。npm 的全局包默认装在%APPDATA%\npm但这个目录不一定在 PATH 里。先查一下npm config get prefix如果输出的是C:\Users\你的用户名\AppData\Roaming\npm确认这个路径在系统环境变量 Path 里。不在的话手动加上否则npm i -g装完的命令你永远找不到。改完 PATH 记得新开终端。2.4 用 TaoToken 统一 Key 的思路环境理顺后Key 管理是下一个痛点。默认情况下 OpenCode 每个 provider 各配一个 Key写在opencode.json里换模型要改文件、重启、还可能把 Key 提交进 Git。更省事的做法是走一个统一的 API 通道把 Base URL 指向同一个入口Key 只存一份在环境变量里。TaoToken 提供的就是这样一个统一入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是让你用一份 Key、一个 Base URL 去调不同模型OpenCode 的配置里只写一次环境变量里只存一个值。这样 Node.js、Git、npm 环境装好后OpenCode 的接入就变成「填一个地址、填一个 Key、选一个模型」三件事。3. 可复制的 OpenCode 配置Base URL、Key 与 Model ID 三件套这一节给可直接粘贴的配置。OpenCode 的配置文件在%USERPROFILE%\.config\opencode\opencode.jsonWindows 下展开就是C:\Users\你的用户名\.config\opencode\opencode.json。如果目录不存在手动建一下。下面这份 JSON 把 provider 指向 TaoToken 的统一入口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: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, gpt-4o: { name: GPT-4o } } } }, model: taotoken/claude-sonnet-4-5 }这份配置里有三个关键点也就是常说的「三件套」Base URL 是https://taotoken.net/apiKey 通过{env:TAOTOKEN_API_KEY}从环境变量读Model ID 是taotoken/claude-sonnet-4-5。三者缺一不可Base URL 写错会 404Key 没读到会 401Model ID 拼错会报模型不存在。3.1 环境变量的两种写法临时生效当前终端窗口有效$env:TAOTOKEN_API_KEY sk-你的Key永久生效写入用户级环境变量新开终端都有效[Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, sk-你的Key, User)推荐用永久写法省得每次开终端都要重设。设完用echo $env:TAOTOKEN_API_KEY确认能读出来。Key 去 https://taotoken.net/api-keys 生成注意别把 Key 直接写进opencode.json那样一旦文件被 Git 跟踪就泄露了。3.2 如果你用 Cline MCP 或 Codex配置逻辑一样有些同学同时在用 Cline 的 MCP 或 Codex它们的配置思路和上面完全一致都是 Base URL Key Model ID 三件套。Cline 的 MCP 配置里把baseUrl指向https://taotoken.net/apiapiKey读同一个环境变量Codex 的auth.json里同样填这个 Base URL 和 Key。统一的好处是换模型只改 Model ID 一处Key 永远只有一份环境变量改一次全局生效。这就是「统一 Key」的实际价值不是概念是少改文件、少重启、少泄露。3.3 配置文件的路径与备份opencode.json改之前先备份一份改坏了能回滚。路径固定是%USERPROFILE%\.config\opencode\opencode.json别放到项目目录里否则每个项目都要配一遍。如果你有多个项目想用不同模型可以在项目根目录放一个opencode.json覆盖全局配置但 Key 依然建议走环境变量不要写进项目文件。4. 验证请求用 npm 与 Git 动作确认 OpenCode 真的通了配置写完不算完得验证 OpenCode 能真正发出请求并拿到响应。这一节给三个验证动作命令行版本检查、一次真实的模型对话、以及 npm 与 Git 的联动确认。4.1 版本与启动检查先确认 OpenCode 本身装好了opencode --version输出类似0.4.x就正常。如果报「不是内部或外部命令」回到 2.3 节检查 npm 全局目录是否在 PATH。然后启动opencode启动后它会读opencode.json如果配置有语法错误会直接报错并指出行号。看到交互界面且模型名显示为taotoken/claude-sonnet-4-5说明配置被正确加载。4.2 发一次真实请求在 OpenCode 交互界面里输入一句简单的话比如「用一句话解释什么是闭包」。如果配置正确几秒内会返回模型输出。这一步验证的是 Base URL、Key、Model ID 三件套全部生效。如果返回 401是 Key 没读到或无效返回 404是 Base URL 写错返回「model not found」是 Model ID 拼错。三种错误对应三个配置项逐个排查即可。4.3 npm 与 Git 联动验证OpenCode 干活时会调用 npm 装依赖、调用 Git 看变更。验证这两个工具在 OpenCode 的上下文里也能用npm ls -g --depth0 git statusnpm ls能列出全局包说明 npm 正常git status在当前目录能输出分支信息说明 Git 正常。如果 OpenCode 在改完代码后能自动跑git diff给你看变更说明整条链路打通了。这一步很关键因为很多人 OpenCode 能对话但一让它改代码就报 Git 相关错误根子就是 Git 没进 PATH 或凭据没配。4.4 用模型对话页快速验证 Key如果你不想在终端里反复试也可以直接去 https://taotoken.net/chat 用同一个 Key 发一条消息确认 Key 本身有效。终端里报 401 时先用这个页面排除「Key 本身失效」的可能再去查环境变量有没有被正确读取。这个分流排查能省不少时间。5. 常见报错排查401、local proxy failed、reading choices、OAuth装 OpenCode 的过程里报错基本集中在几个固定位置。这一节按真实报错逐个拆每个都给定位方法和修复动作。5.1 401 Unauthorized最常见。含义是请求带上了 Key 但服务端不认。排查顺序先echo $env:TAOTOKEN_API_KEY看环境变量是否为空再看opencode.json里是不是写成了{env:TAOTOKEN_API_KEY}而不是硬编码最后确认 Key 本身没过期。如果环境变量在旧终端里设的新终端读不到用永久写法重设一次。注意 Key 前后不要有空格复制时容易带上。5.2 local proxy failed这个报错通常出现在网络层含义是 OpenCode 尝试走本地代理但连不上。检查系统代理设置确认没有残留的代理配置指向一个已经关掉的端口。如果你之前设过HTTP_PROXY或HTTPS_PROXY环境变量清掉它们Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue然后重开终端再试。这个报错和 Key 无关纯粹是网络路径问题。5.3 reading choices 报错这个报错说明请求发出去了、也拿到了响应但响应结构里没有choices字段通常是 Base URL 指向了一个不兼容 OpenAI 格式的端点。确认baseURL是https://taotoken.net/api不要多加/v1或漏掉路径。OpenCode 用的是 OpenAI 兼容格式端点必须匹配。改完配置重启 OpenCode。5.4 OAuth 相关报错如果你在配置里误开了某个需要 OAuth 的 provider会看到 OAuth 流程相关的报错。OpenCode 的配置里如果同时存在 OAuth provider 和 API Key provider可能冲突。检查opencode.json确保provider下只保留你要用的那个把不需要的 OAuth 配置删掉。用统一 Key 的好处在这里体现得很明显只有一个 provider、一份 Key不存在多套认证方式打架的问题。5.5 命令找不到与执行策略opencode命令找不到回 2.3 节查 npm 全局目录。PowerShell 报「禁止运行脚本」执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个只影响当前用户安全可控。改完重开终端。npm 安装慢的话可以换镜像源但注意镜像源只加速下载不影响 Key 和 Base URL 的配置。6. 把 Key 收进环境变量让 OpenCode 在 Windows 上长期稳定跑走到这里Node.js、Git、npm 三件套应该都验证过了OpenCode 也能正常发请求。最后收个尾讲几个让它长期稳定跑的习惯。第一Key 永远只存环境变量opencode.json里只写{env:TAOTOKEN_API_KEY}这样配置文件可以随便备份、同步、甚至提交到私有仓库都不怕。第二Base URL 和 Model ID 集中在一处改换模型只动model字段一行不用碰 Key。第三Git 的凭据用git config --global credential.helper manager管起来避免每次拉代码弹窗。如果你后面要长期用 OpenCode 做编码或跑 Agent 任务可以了解下 Coding Plan 这类按量方案地址在 https://taotoken.net/coding-plan 适合高频调用场景。日常排障和接入文档在 https://taotoken.net/doc Key 管理在 https://taotoken.net/api-keys 模型对话验证在 https://taotoken.net/chat 。这几个入口配合上面的配置基本覆盖了从装环境到长期使用的全流程。最后提醒一句Windows 上环境变量改了之后一定要新开终端才生效这是最多人踩的坑。配置改完先opencode --version再启动两步都过了再发请求能省掉大量来回试的时间。