1. 为什么要在 opencode 里装 Skill以及 npx add-skill 到底解决什么问题如果你最近在折腾 opencode agent大概率会遇到一个很现实的场景模型本身能力不差但一到具体任务就开始“自由发挥”——写 React 组件不按你项目的规范来改代码不先读上下文生成的文件命名乱七八糟。这时候 Skill 就是那个把 agent 从“通用聊天”拉回“按套路干活”的东西。Skill 本质上是一份写给 agent 看的说明书加工具集通常包含一个 SKILL.md 描述触发条件和操作步骤再配上若干脚本或模板文件。opencode 在启动时会扫描本地 Skill 目录把匹配到的 Skill 注入到系统提示里agent 遇到相关任务就会按 Skill 里定义的流程走。你可以把它理解成给 agent 装了一个“岗位操作手册”它不再靠猜而是照着手册执行。那为什么不用手动 clone 再拷贝因为 Skill 仓库越来越多Vercel 的 agent-skills、Anthropic 的 skills 仓库动辄十几个 Skill手动一个个下载、再分别塞进.opencode/skill/目录既容易漏又容易放错层级。npx add-skill就是把这个过程压缩成一条命令给它一个仓库地址它自动 clone、列出可用 Skill、让你选、然后按 agent 类型放到正确目录。支持的目标包括 opencode、claude-code、codex、cursor、antigravity、github-copilot、roo覆盖面够广。这篇要解决的核心链路是用npx add-skill把开源 Skill 装进本地 opencode agent然后把 agent 的 Base URL 和 Key 统一改到 TaoToken 通道最后跑一次真实请求确认 Skill 真的生效了。适合已经在用 opencode、想批量管理 Skill、又希望模型调用走统一入口的人。下面从环境准备开始一步步给可复制的命令和配置。2. 前置准备opencode 环境、TaoToken 统一 Key 与 add-skill 版本确认在动手装 Skill 之前先把三件事确认清楚不然后面报错会很难定位。第一是 opencode 的版本。Skill 目录结构在不同版本里有差异这点后面排障会重点讲。先跑一下opencode --version我实测在 1.1.28 这个版本上opencode 实际读取的是.opencode/skill/单数而不是官方文档里写的.opencode/skills/复数。这个坑很关键装完 Skill 没生效十有八九是目录名不对。第二是 TaoToken 的 Key。TaoToken 是一个统一模型接入通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它的作用是让你用一套 Base URL 和 Key 就能调用多个模型不用为每个模型单独配一套凭证。对 opencode 这种需要频繁切换模型的 agent 来说统一通道能省掉大量配置维护。去控制台创建 Key 的入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完把 Key 复制出来形如sk-开头的一串。API 端点固定是 https://taotoken.net/api 注意这个地址后面不加任何路径后缀opencode 会自己拼/v1/chat/completions之类的路径。第三是 add-skill 本身。它是个 npm 包用 npx 直接跑不用全局安装。先看帮助确认命令形态npx add-skill --help输出里会列出-a, --agent、-s, --skill、-g, --global、-l, --list这些参数。这里有个版本注意点高版本的 add-skill 已经把命令改成了skills add如果你跑npx add-skill提示命令不存在就换成npx skills add参数完全一致。本文以add-skill写法为主你按自己装到的版本对应调整即可。把这三样确认完就可以进入安装环节了。建议先在一个测试项目目录里操作避免污染现有工程。3. 可复制配置用 npx add-skill 装 Skill 并改 opencode 的 Base URL 与 Key这一节是全文的核心操作区分两步先装 Skill再改 opencode 配置指向 TaoToken。3.1 列出仓库里的 Skill装之前先看仓库里有什么避免盲装。以 Vercel 的仓库为例npx add-skill vercel-labs/agent-skills --list输出会显示 clone 进度和找到的 Skill 数量类似Found 2 skills。再看 Anthropic 的仓库npx add-skill anthropics/skills --list这个仓库会列出Found 17 skills。--list只列不装适合先侦察。3.2 安装指定 Skill 到 opencode确认要装哪个之后用-s指定 Skill 名用-a指定目标 agentnpx add-skill vercel-labs/agent-skills -s vercel-react-best-practices -a opencode如果你想装整个仓库的所有 Skill 到 opencode可以省略-s命令会进入交互选择加-y跳过确认npx add-skill vercel-labs/agent-skills -a opencode -y全局安装用户级对所有项目生效加-gnpx add-skill -g vercel-labs/agent-skills -a opencode不加-g就是项目级装到当前目录下。装完之后检查目录结构重点来了——在 opencode 1.1.28 上你要确认 Skill 落在.opencode/skill/而不是.opencode/skills/ls -la .opencode/如果看到的是skills复数手动改一下mv .opencode/skills .opencode/skill每个 Skill 目录里应该有一个SKILL.md这是 agent 读取的入口文件。3.3 把 opencode 的 Base URL 和 Key 改到 TaoTokenopencode 的模型配置通常放在项目根目录的opencode.json或用户级的~/.config/opencode/config.json。下面给一份可复制的 JSON 片段把 provider 指向 TaoToken{ provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥 }, 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 填你在控制台创建的那串Model ID 填你要用的模型标识。这三件套Base URL Key Model ID是任何 agent 接入统一通道的最小集合缺一个都会报错。如果你不想把 Key 写死在 JSON 里可以用环境变量export TAOTOKEN_API_KEYsk-你的密钥然后把 JSON 里的apiKey改成{env:TAOTOKEN_API_KEY}。opencode 支持这种占位符语法。配置改完Skill 也装好了下一步就是验证。4. 验证请求跑一次真实调用确认 Skill 生效装完不验证等于没装。这一节给一套可执行的检查动作。先确认 opencode 能读到配置和 Skill。启动 opencodeopencode进去之后问一个能触发 Skill 的问题。比如你装的是vercel-react-best-practices就让它写一个 React 组件帮我写一个带 loading 状态的用户列表组件如果 Skill 生效agent 的输出会明显带上 Skill 里定义的规范——比如特定的文件组织方式、hooks 使用约定、命名风格。如果它还是自由发挥说明 Skill 没被加载。更直接的验证方式是看 opencode 启动日志里有没有加载 Skill 的记录。可以在启动时加 verboseopencode --log-level debug日志里会打印扫描到的 Skill 路径。确认路径是.opencode/skill/vercel-react-best-practices/SKILL.md这种形态。再验证模型通道是否走通。在 opencode 里发一条最简单的请求用一句话说明你现在用的是哪个模型如果返回正常说明 Base URL 和 Key 配置正确。如果报 401就是 Key 问题如果报连接失败就是 Base URL 问题。这两个错误的排查在下一节展开。想单独测 TaoToken 通道是否通可以脱离 opencode 直接打 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回里有choices数组就说明通道没问题。这一步能把“通道问题”和“opencode 配置问题”彻底分开。验证通过后你就有了一套Skill 装在本地、agent 按 Skill 干活、模型调用走 TaoToken 统一通道的完整环境。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错这一节按真实报错逐条对。401 Unauthorized。最常见Key 不对或没传。检查三处JSON 里apiKey字段有没有拼错环境变量名和占位符是否一致Key 有没有多余空格。TaoToken 的 Key 在控制台创建后只显示一次如果丢了就重新建一个。注意 Base URL 必须是https://taotoken.net/api不要自己加/v1加了会变成/api/v1/v1/...导致鉴权路径错乱。local proxy failed / connection refused。opencode 报这个通常是 Base URL 写错或网络不通。先确认baseURL是https://taotoken.net/api再用上面的 curl 单独测一次。如果 curl 通而 opencode 不通检查 opencode 的 provider 配置有没有被项目级配置覆盖——opencode 会合并用户级和项目级配置项目级的优先级更高容易在这里踩坑。reading choices of undefined。这个报错说明请求发出去了但返回体里没有choices字段。原因一般是 Model ID 写错服务端返回了一个错误对象而不是正常响应。检查model字段填的是不是 TaoToken 支持的模型标识。另外确认请求体里messages格式正确缺字段也会导致返回异常。OAuth 相关报错。如果你之前用 opencode 内置的 OAuth 登录方式配过 provider切到 TaoToken 后要把旧的 auth 清掉否则 opencode 可能还在尝试走 OAuth 流程。检查~/.local/share/opencode/auth.json路径因版本而异把旧的 provider 条目删掉只保留 TaoToken 的 Key 配置。Skill 装了但不生效。回到目录问题确认是.opencode/skill/单数。再确认SKILL.md存在且格式正确文件头部的元信息name、description不能缺。最后确认 opencode 版本高版本如果命令变成了skills add用旧命令装的目录结构可能不一样重新用新命令装一次。add-skill 命令找不到。npx add-skill报 404 或 command not found说明包名或版本变了。换成npx skills add试参数不变。如果还不行去 npm 上搜一下当前包名。把这几条对着排一遍基本能覆盖 90% 的接入问题。6. 后续怎么用Skill 管理、模型切换与统一通道的长期价值装好第一个 Skill 之后你会发现这套流程可以复制到任何仓库。npx add-skill owner/repo -a opencode就是通用模板换仓库名就行。想批量装用--all一把梭想精细控制用-s逐个挑。全局和项目级按需选团队协作建议项目级个人常用工具建议全局。模型切换这块TaoToken 统一通道的价值会随着你用的模型变多而放大。今天用 Claude 写代码明天想换 GPT 试效果只改 JSON 里的model字段就行Base URL 和 Key 不用动。如果每个模型单独配一套凭证切换成本会高很多。想体验不同模型的实际输出差异可以去 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 看看当前支持的模型列表。如果你打算长期用 opencode 做编码和 Agent 任务可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对高频编码场景做了额度优化。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的完整示例。Key 管理统一在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以随时创建和吊销。最后给一个实用习惯每次装完新 Skill先跑一次--list确认仓库内容装完立刻用ls .opencode/skill/检查落盘位置再启动 opencode 发一条触发请求验证。这三步花不了一分钟但能省掉后面大量“为什么没生效”的排查时间。Skill 目录建议纳入版本控制团队里其他人 clone 下来就能用同一套 agent 行为比口头约定规范靠谱得多。