1. Windows 下 opencode-AI skill 安装到底卡在哪Node.js 环境与 skill 目录的真实关系opencode-AI 是一个跑在终端里的 AI 编码助手它能读你本地的代码、按指令改文件、执行命令而 skill 就是给它加装的“技能包”——装上 skill-creator 它就能自己造新技能装上别的 skill 它就能按预设流程处理特定任务。这套东西适合谁适合已经在 Windows 上写代码、想让 AI 直接动手改项目而不是只聊天的开发者。但很多人第一次装的时候会卡在三个地方Node.js 版本不对导致全局命令装不上、skill 包解压后放错目录导致 opencode 根本扫不到、以及模型 Key 没配好导致 skill 触发时请求直接 401。我自己在 Windows 11 上从零走了一遍发现最容易被忽略的不是安装命令本身而是“skill 到底该放在哪”和“Key 怎么统一管”。opencode-AI 默认会去几个固定路径找 skill你从 GitHub 下载的 ZIP 解压后如果直接扔在下载文件夹它永远读不到。另外 opencode-AI 支持多种模型后端如果你每个 skill 都单独配一次 Key后面换模型会非常痛苦。所以这篇教程的思路是先把 Node.js 环境弄干净再装 opencode-AI然后用 TaoToken 统一管 Key最后把 skill 目录结构摆对跑一次真实触发验证。先说你会在哪些步骤上花时间。Node.js 安装本身五分钟但如果你之前装过旧版本npm 全局目录可能残留冲突opencode-AI 全局安装大概一两分钟skill 包下载解压两分钟真正花时间的是配 Key 和验证请求能不能通。我实测下来只要 Key 配对了skill 触发就是秒级响应日志里能看到完整的请求和返回。下面按顺序来每一步都给可复制的命令和配置片段。2. TaoToken 前置准备统一 Key 与 Base URL 怎么拿、怎么配进 opencode-AIopencode-AI 要调模型就得有 API Key 和 Base URL。TaoToken 在这里的作用是给你一个统一的入口你不用为每个模型单独去开账号、记不同的 Key。你需要准备三样东西Base URL、API Key、以及你要用的 Model ID。这三件套在 opencode-AI 的配置里是绑在一起的缺一个请求就发不出去。先拿 Key。打开 https://taotoken.net/api 这个地址是 API 入口注册登录后进控制台在 API Keys 页面创建一个新 Key。创建的时候给它起个名字比如 “opencode-win”方便后面区分。复制出来的 Key 一般以 sk- 开头只显示一次先粘到记事本里存着。然后看文档确认 Base URLTaoToken 的 API 地址是 https://taotoken.net/api注意这个地址后面不加 UTM 参数配置里就写这个。Model ID 取决于你想用哪个模型控制台里模型列表会给出对应的 ID 字符串比如 claude 系列或者 gpt 系列的标识复制那个准确的 ID。这里有个坑opencode-AI 的配置读取顺序是环境变量优先于配置文件。如果你在系统环境变量里设了 OPENAI_API_KEY 之类的旧值它会覆盖你新写的配置。所以配之前先检查一下有没有残留的环境变量。在 PowerShell 里跑Get-ChildItem Env: | Where-Object {$_.Name -like *API*}能列出来有冲突的就先清掉。配的时候有两种方式。一种是直接写进 opencode-AI 的配置文件另一种是用环境变量。我推荐配置文件方式因为 skill 多了以后环境变量会乱。opencode-AI 在 Windows 下的配置目录通常是%USERPROFILE%\.opencode\或者项目根目录下的.opencode文件夹具体看你装的是哪个版本。你可以在 opencode-AI 界面里输入“请显示你的配置路径”让它告诉你。拿到路径后在里面建一个config.json把 Base URL、Key、Model ID 写进去。下面给一个可复制的 JSON 片段路径和字段名按你实际版本对齐{ provider: { taotoken: { baseURL: https://taotoken.net/api, apiKey: sk-你的Key粘这里, model: 你的ModelID } }, defaultProvider: taotoken }注意 apiKey 这一行实际用的时候把 sk- 后面换成你控制台复制的完整 Key。model 字段填控制台里显示的准确 ID不要自己猜。保存后关掉再重开 opencode-AI让它重新读配置。如果你更习惯用环境变量也可以在 PowerShell 里临时设$env:OPENAI_API_KEYsk-...和$env:OPENAI_BASE_URLhttps://taotoken.net/api但这种方式每次开新窗口都要重设长期用还是配置文件省事。配完先别急着装 skill先验证 Key 能不能通。在 opencode-AI 里随便问一句“你好”如果它能正常回说明 Base URL 和 Key 没问题。如果报 401就是 Key 错了或者没读到如果报连接失败检查 Base URL 有没有多写斜杠或者少写。这一步过了再往下走不然 skill 装好了也触发不了。3. 可复制配置Node.js 环境变量、opencode-AI 安装命令与 skill 目录结构这一节把命令和配置集中给出来你照着粘就行。先确认 Node.js。打开 PowerShell跑node --version和npm --version。如果显示版本号且 node 在 18 以上可以跳过安装。如果没有或者版本太低去 Node.js 官网下载 Windows 安装包选 64 位一路下一步安装过程中问要不要装必要工具就保持默认。装完关掉 PowerShell 重开再跑一次版本命令确认。Node.js 好了之后装 opencode-AI。全局安装命令是npm install -g opencode-ai如果你之前装过旧版这条命令会直接更新。装完跑opencode-ai --version确认。然后进 opencode-AI 界面输入“请显示你的安装路径”它会告诉你 skill 应该放哪。通常是在%USERPROFILE%\.opencode\skills\或者安装目录下的skills文件夹。你手动建这个目录如果它不存在的话。skill 包从 GitHub 拿。搜索 skill 相关的仓库找到 ZIP 下载。下载完解压你会看到里面通常是一个文件夹里面包含SKILL.md或者skill.json之类的描述文件。关键来了不要把整个解压出来的外层文件夹直接扔进去要看清楚 skill 的根目录在哪。正确的结构是skills/你的skill名/SKILL.md而不是skills/解压文件夹/你的skill名/SKILL.md。多一层少一层都扫不到。下面给一个目录结构示例%USERPROFILE%\.opencode\ ├── config.json └── skills\ ├── skill-creator\ │ └── SKILL.md └── your-skill\ └── SKILL.mdconfig.json 就是上一节写的那个。skills 下面每个子文件夹是一个独立 skill文件夹名就是 skill 的标识。SKILL.md 里写的是这个 skill 的触发条件和执行逻辑。放好之后重开 opencode-AI输入“你有哪些 skill”它应该能列出来。如果列不出来先检查目录层级再检查 SKILL.md 的文件名大小写Windows 虽然不区分大小写但有些工具会严格匹配。还有一个配置项值得单独说如果你用 Cline MCP 或者 Codex 的 auth.json 方式接三件套要写全。Base URL 写https://taotoken.net/apiKey 写你创建的 sk- 开头那串Model ID 写控制台里对应的标识。这三个少一个都会在请求阶段报错。opencode-AI 自己的 config.json 里也是同样的三件套逻辑只是字段名可能不同。你可以在文档里确认字段映射或者直接在界面里问它“怎么配 provider”。4. 验证请求与成功结果触发一次 skill 并看日志确认链路通了配置和目录都弄好之后做一次真实触发。重开 PowerShell进 opencode-AI输入“你有哪些 skill”。如果前面步骤都对它会列出 skill-creator 和你放进去的其他 skill。然后输入“用 skill-creator 帮我创建一个新 skill”观察它的反应。正常情况它会开始读 skill-creator 的 SKILL.md然后按里面的流程问你问题或者直接生成文件。这时候看日志。opencode-AI 一般会在终端输出请求信息或者你可以让它“显示最近的请求日志”。成功的标志是能看到发往https://taotoken.net/api的请求返回状态 200并且有模型返回的内容。如果 skill 触发了但请求失败日志里会显示错误码。我实测下来第一次触发时最容易看到的是 401原因是 config.json 里的 Key 没粘全或者多了空格。把 Key 重新复制一遍注意不要带换行。另一个验证方式是直接问模型一个需要 skill 能力的问题。比如你装了一个处理特定文件格式的 skill就让它“用那个 skill 处理一下这个文件”。如果它正确调用了 skill 并返回结果说明整条链路通了opencode-AI 读到 skill 描述匹配到你的指令通过 TaoToken 的 Base URL 发请求模型返回skill 执行。日志里会留下完整的调用记录你可以对照看是哪一步在耗时。成功之后你可以试试切换模型。在 opencode-AI 里输入/models会列出可用模型支持模糊搜索。输入glm或者qwen能筛出对应的。切换模型不需要改 Key因为 TaoToken 统一管了你只要保证 config.json 里的 Model ID 是控制台里存在的就行。如果切完模型请求报错说模型不存在回去控制台核对 ID 拼写。这一步过了说明你的环境已经能稳定跑 skill 了。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错对照装的过程中有几个报错几乎每个人都会遇到这里按真实错误信息对照给解法。第一个是 401 Unauthorized。日志里通常写401或者invalid api key。原因就三个Key 复制错了、Key 过期了、或者配置文件没被读到。先检查 config.json 里的 apiKey 字段确认 sk- 后面没有多余空格和换行。然后确认 opencode-AI 读的是你改的那个配置文件有时候它读的是项目目录下的.opencode而不是用户目录下的。你可以在界面里问“你当前读的配置文件路径是什么”对比一下。如果 Key 没问题但还是 401去 TaoToken 控制台看这个 Key 是不是被禁用了或者额度用完了。第二个是local proxy failed或者连接被拒绝。这个通常出现在你本机有网络层拦截或者端口冲突的时候。先确认 Base URL 写的是https://taotoken.net/api没有多写路径。然后检查系统里有没有设 HTTP_PROXY 之类的环境变量有的话先清掉再试。如果你在公司网络里可能有防火墙规则换一个网络环境试。这个报错和 Key 无关纯粹是请求发不出去。第三个是reading choices相关的报错比如cannot read property choices of undefined。这个说明请求发出去了但返回的结构不是预期的格式。常见原因是 Model ID 写错了或者 Base URL 指向了一个不兼容的接口。回去确认 Model ID 和控制台里完全一致Base URL 没有拼错。如果用的是兼容 OpenAI 格式的接口确认 TaoToken 的 API 地址支持你要调的那个模型。第四个是 OAuth 相关报错。如果你在配置里选了 OAuth 认证方式而不是 API Key但没走完授权流程就会报这个。最简单的解法是切回 API Key 方式在 config.json 里明确写 apiKey 字段。OAuth 适合有专门授权流程的场景本地开发用 Key 更直接。如果你确实要用 OAuth确认回调地址和客户端配置都对但这个排查起来比 Key 麻烦得多新手建议先用 Key 跑通。还有一个不报错但很烦的问题skill 列不出来。这基本是目录结构问题。回去看skills文件夹下面是不是直接就是 skill 名文件夹skill 名文件夹里是不是直接就是 SKILL.md。多一层嵌套就扫不到。另外确认文件夹名没有特殊字符和空格有些工具对空格处理不好。6. 语义一致 CTA把 Key 管好之后skill 和模型都能随时换跑通最小示例之后你手里已经有一套能用的环境了Node.js 装好opencode-AI 全局可用TaoToken 的 Key 配在 config.json 里skill 目录结构正确触发验证也过了。接下来你可以用 skill-creator 造自己的 skill也可以去 GitHub 找更多现成的 skill 包往里放。每次加新 skill 只要保证目录层级对重开 opencode-AI 就能识别。Key 这块TaoToken 的好处是你不用为每个模型单独配。想换模型的时候在控制台确认 Model ID改 config.json 里的 model 字段或者直接在 opencode-AI 里用/models切换。Base URL 和 Key 都不用动。如果你后面要接 Cline MCP 或者 Codex 的 auth.json记住三件套写全Base URL 用https://taotoken.net/apiKey 用你创建的那串Model ID 用控制台里对应的。三个字段对齐了请求就能通。常用命令里/plan和/build切换工作模式plan 模式只分析不改文件build 模式会动手改。用 plan 模式的时候如果它思考出有用的内容记得让它保存到本地因为执行阶段如果崩了之前没保存的思考就丢了。/skill列出可用 skill 并切换你也可以直接在输入框里叫它用某个 skill。/new或/clear开新会话/exit退出。这些命令在刚开始用的时候频率最高熟悉之后你会有自己的习惯。最后说一个实际经验skill 装多了之后opencode-AI 匹配 skill 的速度会受描述文件质量影响。SKILL.md 里写清楚触发条件和适用场景它匹配得就准。如果发现它该用某个 skill 却没用先检查 SKILL.md 的描述是不是太模糊。另外 Python 环境建议也装上很多 skill 内部会调 Python 脚本没有的话会报找不到命令。装完 Python 记得把路径加进系统环境变量不然 opencode-AI 调不到。