1. opencode 安装 skills 报 401 的真实场景与排查思路opencode 是一个跑在终端里的 AI 编码助手支持通过opencode.json引入 plugin也支持把SKILL.md放进 skills 目录做本地指令集扩展。很多人第一次装 skills 时会遇到一个很迷惑的报错终端里刷出401 Unauthorized或者 plugin 拉取阶段直接失败skills 列表里空空如也。这个 401 不是你的 GitHub 密码错了也不是 opencode 本身坏了绝大多数情况是请求在鉴权环节被拦下——要么请求打到了没有正确携带凭证的地址要么 plugin 的拉取链路和模型调用的链路用了两套不同的鉴权配置。我先把结论摆出来opencode 的 skills 安装涉及两条独立的链路。第一条是plugin 拉取链路它负责从远端把 plugin 代码或 skills 包同步到本地缓存第二条是模型调用链路它负责在 skill 真正执行时把请求发到模型服务端。401 可能出现在任意一条上而opencode.json是唯一能同时管到这两条链路的配置文件。所以排查的核心动作就是把opencode.json里的 provider、baseURL、apiKey、plugin 字段逐项对齐确认鉴权信息没有错位。适合读这篇的人有三类一是刚接触 opencode、想用 skills 扩展能力但被 401 卡住的新手二是已经把 opencode 跑起来、但 skills 加载不生效的开发者三是团队里负责统一配置、需要把opencode.json写进仓库做共享的工程同学。下面我会从配置项入手给出可复制的 JSON 片段再一步步验证请求到底卡在哪一环。先理解一个类比opencode 的 plugin 机制像 npm 的依赖声明你在opencode.json里写一个包名它启动时去拉而 skills 目录像你手动放进项目的本地脚本。前者依赖网络和鉴权后者依赖文件路径。401 基本只发生在前者或者发生在 skill 执行时调模型的那一下。把这两件事分开看排查就不会乱。2. TaoToken 前置配置opencode.json 里 provider 与鉴权怎么写在动 skills 之前先把模型调用的鉴权配好否则你就算把 skill 装上了执行时照样 401。opencode 的 provider 配置写在opencode.json里全局路径是~/.config/opencode/opencode.json项目级路径是项目根目录下的opencode.json。项目级会覆盖全局级团队协作时建议把项目级提交到仓库保证每个人克隆下来就是同一套环境。TaoToken 提供的是兼容 OpenAI 风格的接口baseURL 用https://taotoken.net/api模型 ID 按你实际要用的填。下面是一份可以直接抄的opencode.json片段注意provider段和plugin段是并列的不要嵌套错{ $schema: https://opencode.ai/config.json, 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-4.1: { name: GPT-4.1 } } } }, model: taotoken/claude-sonnet-4-5, plugin: [] }这里有几个容易踩的点。第一baseURL结尾不要多加/v1opencode 的 openai-compatible provider 会自己拼路径多写一层就变成/api/v1/v1/...服务端返回 404 或 401。第二apiKey建议用环境变量注入而不是硬编码opencode 支持在 options 里写apiKey: {env:TAOTOKEN_API_KEY}这样密钥不会进 git。第三model字段的格式是provider名/模型IDprovider 名必须和上面provider对象里的 key 完全一致写错了会提示找不到模型。密钥从哪来去 TaoToken 控制台的 API Keys 页面创建地址是https://taotoken.net/console/api-keys。创建后复制那串sk-开头的字符串填进配置或环境变量。如果你还没决定用哪个模型可以先去模型对话页面试一下地址https://taotoken.net/models确认账号和额度正常再回来配 opencode。配好之后先别急着装 skills先验证模型链路通不通。在终端里跑opencode run 用一句话说明什么是 skills如果这条命令能正常返回内容说明 provider 鉴权没问题401 的锅不在模型链路上可以放心去查 plugin 和 skills 目录。如果这条也报 401那问题就锁定在apiKey或baseURL先把这两个改对再往下走。3. 可复制的 opencode.json 配置plugin 与 SKILL.md 加载链路skills 的安装有两种方式对应opencode.json里不同的写法理解它们的差异能帮你快速定位 401 出在哪。方式一是通过plugin字段声明远端包opencode 启动时自动拉取并缓存。写法是在plugin数组里加包名支持 git 地址和版本锁定{ plugin: [ superpowersgithttps://github.com/obra/superpowers.git, opencode-notifierlatest, opencode-dynamic-context-pruninglatest ] }这种方式的鉴权发生在拉取阶段。如果远端仓库是公开的理论上不需要凭证但如果你所在网络环境对 git 协议或 https 拉取有额外要求或者包名解析到了需要鉴权的源就会在启动日志里看到 401。排查时先单独在终端手动 clone 一下那个仓库确认能拉下来再回来看 opencode 的日志。方式二是手动下载 skills 包解压到 skills 目录。全局目录是~/.config/opencode/skills项目目录是.opencode/skills两者物理隔离。每个 skill 包的核心是SKILL.mdopencode 启动时扫描这两个目录读取SKILL.md里的元信息注册 skill。这种方式不涉及远端拉取所以不会因为拉取而 401但如果SKILL.md里声明了需要调用模型执行时仍会走 provider 鉴权。一个完整的项目级opencode.json应该长这样把 provider、model、plugin 三块都写清楚{ $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 } } } }, model: taotoken/claude-sonnet-4-5, plugin: [ superpowersgithttps://github.com/obra/superpowers.git ] }对应的环境变量在 shell 里导出export TAOTOKEN_API_KEYsk-你的TaoToken密钥如果你用的是 zsh写进~/.zshrcbash 写进~/.bashrc。改完记得source一下或者重开终端否则 opencode 读不到新变量还是会拿旧的空值去请求结果就是 401。手动装 skill 的目录结构要摆对以 excalidraw-diagram 为例mkdir -p ~/.config/opencode/skills cd ~/.config/opencode/skills # 把下载的 skill 压缩包解压到这里确保 SKILL.md 在 skill 子目录下 unzip excalidraw-diagram.zip -d excalidraw-diagram ls excalidraw-diagram/SKILL.mdSKILL.md必须在 skill 自己的子目录里不能直接平铺在 skills 根目录否则 opencode 扫描不到。这一点很多人第一次装会搞错然后以为 401 是鉴权问题其实是路径问题。4. 验证请求与成功结果逐步确认 skills 加载生效配置写完接下来是验证。验证要分三层做一层一层排除不要跳步。第一层验证 provider 鉴权。跑一条最简单的模型请求opencode run 回复 OK预期结果是终端打印出模型返回的OK或类似内容。如果这里报 401说明apiKey或baseURL有问题回到第 2 节检查。常见错误是密钥复制时带了空格或者环境变量没生效。可以用echo $TAOTOKEN_API_KEY确认变量有值。第二层验证 plugin 拉取。启动 opencode 时观察日志或者直接看缓存目录opencode --version ls ~/.cache/opencode/plugins 2/dev/null || ls ~/.local/share/opencode/plugins 2/dev/null不同版本缓存路径略有差异但只要能列出你声明的 plugin 目录就说明拉取成功。如果这里报 401重点查 git 拉取链路手动 clone 一次确认网络可达。第三层验证 skills 注册。启动 opencode 后在交互界面里输入 skills 相关的查询命令或者直接看启动日志里有没有扫描到SKILL.md。手动装的 skill 可以用文件确认find ~/.config/opencode/skills -name SKILL.md find .opencode/skills -name SKILL.md 2/dev/null两条命令都应该列出你放的 skill。如果列表为空说明目录结构不对回到第 3 节调整。三层都通过后实际触发一次 skill。比如你装了通知类 skill让它执行一个会触发通知的动作观察桌面是否弹出提示。这一步能同时验证 skill 注册和模型调用两条链路。成功的结果是终端有正常输出skill 声明的副作用通知、文件生成等真实发生日志里没有 401。如果你在验证过程中想确认模型侧是否正常计费和响应可以去模型对话页面手动发一条消息对照地址https://taotoken.net/models。如果那边正常、opencode 这边 401问题一定在 opencode 的配置或环境变量不在账号。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节把几个高频报错逐个拆开对照你的终端输出定位。401 Unauthorized。出现位置不同含义不同。如果出现在opencode run的模型请求阶段检查apiKey是否为空、是否过期、baseURL是否写成了https://taotoken.net/api/v1。如果出现在 plugin 拉取阶段检查 git 仓库是否可公开访问、包名是否拼错。一个隐蔽的坑是全局opencode.json和项目级opencode.json同时存在项目级覆盖了全局级但没写 provider导致鉴权信息丢失。解决方法是确认生效的那份配置里有完整的 provider 段。local proxy failed。这个报错通常和本机网络环境有关比如系统设置了全局代理但代理进程没起来或者代理规则把taotoken.net也拦了。排查时先确认本机能否直接访问https://taotoken.net/api用 curl 测一下curl -i https://taotoken.net/api/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY如果 curl 能通而 opencode 不通说明是 opencode 进程没继承到代理或环境变量检查启动 opencode 的那个终端里TAOTOKEN_API_KEY是否存在。reading choices 相关报错。这类报错一般出现在解析模型返回结构时根因往往是 baseURL 指向了不兼容 OpenAI 响应格式的端点或者模型 ID 写错导致服务端返回了错误结构。确认baseURL是https://taotoken.net/apimodel字段的模型 ID 和控制台里列出的完全一致。OAuth 相关报错。opencode 某些 provider 走 OAuth 流程如果你混用了 OAuth provider 和 API Key provider可能出现鉴权方式冲突。用 TaoToken 这种 API Key 方式时确保 provider 的npm字段是ai-sdk/openai-compatible不要配成需要 OAuth 的 provider 类型。排查时建议开一个干净的终端只导出必要的环境变量再启动 opencode减少干扰。日志级别可以调高把请求的 URL 和状态码打出来401 到底打到了哪个地址一目了然。6. 长期编码与 Agent 场景的配置建议如果你只是偶尔用一下 skills上面这套配置够用了。但如果你打算把 opencode 当成日常编码和 Agent 工作流的主力工具有几个配置习惯值得养成。第一把opencode.json按项目提交到仓库provider 段用环境变量占位密钥不进 git。这样团队每个人克隆下来只需要导出自己的TAOTOKEN_API_KEY配置完全一致不会出现「我这边能跑你那边 401」的情况。第二plugin 版本尽量锁定。latest方便但不可复现团队协作时建议锁到具体 tag 或 commit避免上游更新引入不兼容变更导致拉取失败。第三skills 目录区分全局和项目级。通用的、跨项目复用的 skill 放~/.config/opencode/skills和当前项目强相关的放.opencode/skills并提交到仓库。这样既保证通用能力随处可用又保证项目专属 skill 跟着代码走。第四定期验证鉴权链路。密钥会过期环境变量会丢网络环境会变。把第 4 节那三条验证命令写成一个脚本隔一段时间跑一次比等到 401 了再排查省事得多。如果你需要更完整的接入文档和参数说明可以看接入文档页面地址https://taotoken.net/doc。长期跑编码和 Agent 任务的话Coding Plan 页面有更细的用量和模型选择说明地址https://taotoken.net/coding-plan。密钥管理统一在控制台地址https://taotoken.net/console/api-keys。最后提醒一句opencode 的 skills 安装报 401九成不是 opencode 的 bug而是opencode.json里 provider 鉴权和 plugin 拉取这两条链路有一处没对齐。按第 2 节配好 provider按第 3 节摆对目录按第 4 节三层验证基本都能跑通。真遇到卡住的报错把终端日志里的请求 URL 和状态码截出来对照第 5 节逐条比定位会快很多。