1. Windows 上装 OpenCode 到底卡在哪OpenCode 是一个跑在终端里的开源 AI 编程助手能读你当前项目的代码、按自然语言改文件、生成单元测试适合习惯命令行、又想让 AI 直接动工程目录的人。它在 macOS 和 Linux 上体验相当顺但一到 Windows很多人第一步就卡住了照着官方文档敲npm i -g opencode-ai装完敲opencode要么提示找不到命令要么直接甩一段平台识别失败的报错。我自己在 Windows 11 上前后折腾了三轮npm 装了两遍、手动解压二进制一遍最后用 Chocolatey 才真正跑通。核心原因不复杂OpenCode 的主体是一个编译好的原生二进制文件npm 包只是个「下载器 解压器」而 Windows 在解压opencode-windows-x64.zip时经常因为路径过长、文件被占用、权限不足导致解压不完整最后你拿到的是一个空壳 CLI。Chocolatey 走的是系统级包管理自动识别架构、自动补依赖、自动写 PATH把这一堆坑一次性绕开。这篇就按真实落地顺序写先复现 npm 的报错让你知道坑长什么样再切到 Chocolatey 部署最后在settings.json里写入 TaoToken 的统一 Key 和 API 通道让 OpenCode 真正能对话。全程 PowerShell 命令可直接复制配置骨架和逐条验证动作都给到目标是让你一次跑通。2. 前置准备TaoToken 通道与 Key 先拿到手OpenCode 装好只是有了壳真正让它干活的是背后的模型通道。我这边统一用 TaoToken 做 API 入口一个 Key 就能覆盖对话、编码、Agent 这几类调用省得在多个平台之间来回切。你先把通道和 Key 准备好后面写settings.json时直接填。打开浏览器进官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在里面找到 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 新建一个 Key 并复制保存。这个 Key 只显示一次丢了就得重建建议先粘到记事本里。API 的基础地址是 https://taotoken.net/api 注意这个地址后面不加任何查询参数写进配置时保持干净。如果你后面想先验证模型通不通可以进模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 手动发一条消息确认 Key 有效再往下走。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到字段不确定时对着查。环境侧确认三件事Windows 10/11 64 位用管理员身份开 PowerShellNode 如果已经装了不影响但 npm 那条路我们后面会主动放弃。Git 建议装上OpenCode 强依赖.git索引没有仓库的目录它启动后可能直接退出。3. 先复现 npm 安装的报错知道坑在哪这一步不是让你真用 npm而是让你亲眼看到报错后面才不会怀疑「是不是我操作错了」。管理员 PowerShell 里执行npm i -g opencode-ai装完敲opencode --version大概率会遇到下面两类报错之一It seems that your package manager failed to install the right version of the opencode CLI for your platform.ENOTEMPTY: directory not empty, rmdir ...\opencode-windows-x64\bin第一条是平台识别失败npm 没判断对 Windows x64 该拉哪个二进制第二条是解压时目录非空、文件被占用rmdir删不掉。根因都一样npm 在 Windows 上解压原生二进制不稳定CLI 变成空壳。如果你已经踩了先做一次强力清理别让残留影响后面 Chocolatey 的安装npm uninstall -g opencode-ai Remove-Item -Path $env:APPDATA\npm\node_modules\opencode-ai -Recurse -Force -ErrorAction SilentlyContinue Remove-Item -Path $env:APPDATA\npm\opencode* -Recurse -Force -ErrorAction SilentlyContinue清理完where.exe opencode应该查不到任何结果说明环境干净了。这一步做完再进下一节能避免「新旧版本混在一起」的诡异问题。4. Chocolatey 部署 OpenCode 完整流程4.1 安装 Chocolatey如果机器上已经有 chocochoco --version能出版本号就跳过这步。没有的话管理员 PowerShell 执行官方安装脚本Set-ExecutionPolicy Bypass -Scope Process -Force [System.Net.ServicePointManager]::SecurityProtocol [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 iex ((New-Object System.Net.WebClient).DownloadString(https://community.chocolatey.org/install.ps1))装完关掉终端重开一个管理员窗口验证choco --version能输出类似2.4.1的版本号就 OK。这一步如果卡在下载多半是网络问题换个时间段重试即可。4.2 一键安装 OpenCode同一个管理员终端里choco install opencode -y这条命令背后做了三件事自动识别你的 Windows 架构并下载匹配的原生二进制自动补齐fzf、ripgrep、unzip这些 OpenCode 依赖的底层组件安装完成后把opencode路径写进系统 PATH。整个过程不需要你手动解压、不需要配环境变量。4.3 验证安装结果关掉当前终端重新开一个普通权限即可执行opencode --version正常会输出版本号比如v1.1.47。再确认一下路径来源where.exe opencode应该指向C:\ProgramData\chocolatey\bin\opencode.exe。如果--version报「无法将 opencode 识别为 cmdlet」说明 PATH 没刷新重启终端或重启一次系统即可。5. 写入 settings.jsonTaoToken 统一 Key 与 API 通道OpenCode 的配置放在用户目录下的.config\opencode\settings.json。Windows 上完整路径是C:\Users\你的用户名\.config\opencode\settings.json。目录不存在就手动建New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.config\opencode然后创建或编辑settings.json骨架如下把sk-你的TaoTokenKey换成第 2 节拿到的真实 Key{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, models: { default: claude-sonnet-4-5, fast: claude-haiku-4-5 } } }, defaultProvider: taotoken, defaultModel: claude-sonnet-4-5 }几个字段说明一下。type填openai是因为 TaoToken 的 API 兼容 OpenAI 协议格式OpenCode 按这个协议发请求就能通。baseURL必须是https://taotoken.net/api结尾不要带斜杠、不要加多余参数。apiKey就是你的 Key。models里可以按用途分档日常改代码用默认档快速补全用 fast 档具体模型名以接入文档里列的为准。写完后用 PowerShell 校验一下 JSON 格式有没有写错少个逗号、多个括号都会让 OpenCode 启动失败Get-Content $env:USERPROFILE\.config\opencode\settings.json -Raw | ConvertFrom-Json没报错就说明格式合法。这一步很多人忽略结果启动后各种诡异报错其实就是一个逗号的问题。6. 验证请求确认配置真的生效配置写完不算完得实际发一次请求确认通道打通。先进一个 Git 仓库目录cd D:\WorkSpace\MyAwesomeProject如果这个目录还不是 Git 仓库先git init一下OpenCode 依赖.git索引来理解项目结构。然后启动opencode首次启动会进交互界面。如果settings.json写对了它应该直接读取到taotoken这个 provider不再弹「选择 Provider」的引导。你在输入框里发一条测试消息比如「用一句话说明这个项目是做什么的」观察返回。返回正常说明三件事同时成立Key 有效、baseURL可达、模型名正确。如果返回 401是 Key 问题返回 404多半是baseURL写错或模型名不存在返回超时是网络到taotoken.net的连通性问题。想单独验证 Key 而不启动 OpenCode可以进模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条能通就说明 Key 和通道没问题问题在 OpenCode 配置侧。如果你打算长期用 OpenCode 做编码和 Agent 任务调用量会比较大可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 按套餐走比单次调用更划算。Claude Code 相关的接入配置在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 如果你同时用 Claude Code可以参考那边的字段写法。7. 本篇常见报错逐条排查opencode 命令找不到。先where.exe opencode看有没有输出。没有就检查C:\ProgramData\chocolatey\bin是否在系统 PATH 里没有就手动加进去然后重启终端。加了还不行的重启一次系统让 PATH 彻底刷新。启动后立即闪退。九成是当前目录没有.git文件夹。OpenCode 启动时要读 Git 索引没有就退出。git init一下再启动。settings.json 改了没生效。检查文件路径是不是C:\Users\你的用户名\.config\opencode\settings.json注意是.config不是config前面有个点。另外确认没有多个 settings.json 冲突比如项目目录下也放了一个。JSON 解析报错。用第 5 节的ConvertFrom-Json命令校验它会告诉你哪一行有问题。常见的是尾随逗号、中文引号、注释JSON 不支持注释。请求超时或连接失败。先确认能访问taotoken.net浏览器打开官网能加载就说明网络通。如果公司网络有限制检查是否需要走内部网络策略具体按你所在环境的合规要求处理。终端 UI 乱码。建议用 Windows Terminal 配合 Nerd Fonts 字体普通 cmd 的字符渲染对 TUI 界面不友好会出现方块和错位。npm 残留导致冲突。如果之前 npm 装过又没清干净where.exe opencode可能同时列出两个路径。按第 3 节的清理命令删掉 npm 那份只保留 Chocolatey 的。8. 后续怎么用起来装好之后日常就是在项目目录里敲opencode然后用自然语言让它改代码、写测试、解释模块。我自己的习惯是每个项目单独开一个终端窗口让它读当前仓库的上下文改完直接git diff看改动确认没问题再提交。配置这块settings.json里可以按项目需要加更多模型档位但baseURL和apiKey保持指向 TaoToken 就行一个 Key 管所有调用。如果后面要换模型改defaultModel字段重启 OpenCode 即可不用重装。遇到配置字段不确定的对着接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 查比在终端里瞎试快得多。Key 管理在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 定期轮换是个好习惯。
