企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它的作用是让你用一套 Base URL 和 Key 就能调用多个模型，不用为每个模型单独配一套凭证。对 opencode 这种需要频繁切换模型的 agent 来说，统一通道能省掉大量配置维护。

去控制台创建 Key 的入口是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建完把 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指定目标 agent：

npx 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

全局安装（用户级，对所有项目生效）加-g：

npx 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 改到 TaoToken

opencode 的模型配置通常放在项目根目录的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/api，Key 填你在控制台创建的那串，Model ID 填你要用的模型标识。这三件套（Base URL + Key + Model ID）是任何 agent 接入统一通道的最小集合，缺一个都会报错。

如果你不想把 Key 写死在 JSON 里，可以用环境变量：

export TAOTOKEN_API_KEY="sk-你的密钥"

然后把 JSON 里的apiKey改成"{env:TAOTOKEN_API_KEY}"。opencode 支持这种占位符语法。

配置改完，Skill 也装好了，下一步就是验证。

4. 验证请求：跑一次真实调用确认 Skill 生效

装完不验证等于没装。这一节给一套可执行的检查动作。

先确认 opencode 能读到配置和 Skill。启动 opencode：

opencode

进去之后问一个能触发 Skill 的问题。比如你装的是vercel-react-best-practices，就让它写一个 React 组件：

帮我写一个带 loading 状态的用户列表组件

如果 Skill 生效，agent 的输出会明显带上 Skill 里定义的规范——比如特定的文件组织方式、hooks 使用约定、命名风格。如果它还是自由发挥，说明 Skill 没被加载。

更直接的验证方式是看 opencode 启动日志里有没有加载 Skill 的记录。可以在启动时加 verbose：

opencode --log-level debug

日志里会打印扫描到的 Skill 路径。确认路径是.opencode/skill/vercel-react-best-practices/SKILL.md这种形态。

再验证模型通道是否走通。在 opencode 里发一条最简单的请求：

用一句话说明你现在用的是哪个模型

如果返回正常，说明 Base URL 和 Key 配置正确。如果报 401，就是 Key 问题；如果报连接失败，就是 Base URL 问题。这两个错误的排查在下一节展开。

想单独测 TaoToken 通道是否通，可以脱离 opencode 直接打 API：

curl 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_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 看看当前支持的模型列表。

如果你打算长期用 opencode 做编码和 Agent 任务，可以考虑 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它针对高频编码场景做了额度优化。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言的完整示例。Key 管理统一在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，可以随时创建和吊销。

最后给一个实用习惯：每次装完新 Skill，先跑一次--list确认仓库内容，装完立刻用ls .opencode/skill/检查落盘位置，再启动 opencode 发一条触发请求验证。这三步花不了一分钟，但能省掉后面大量“为什么没生效”的排查时间。Skill 目录建议纳入版本控制，团队里其他人 clone 下来就能用同一套 agent 行为，比口头约定规范靠谱得多。