1. 为什么你的 AI 总在重复问同一件事OpenCode Skill 使用指南与统一 Key 配置实战你有没有遇到过这种情况每次让 AI 帮你写代码都得重复强调一遍「记得用 conventional commits」「响应式组件要用 rem」「接口返回要先判空」。说多了自己都烦但不说又不行因为 AI 真的会忘。我跟 AI 助手说了快一年同样的话直到后来才发现原来有个东西叫 Skill能让 AI 一次记住、永远不忘。这篇 OpenCode Skill 使用指南就是把我踩过的坑和跑通的配置完整拆给你看。OpenCode Skill 本质上是你给 AI 写的一份「使用说明书」。你可以把团队规范、项目约定、工作流程这些老生常谈的东西写成一个可复用的指令包。AI 每次遇到相关场景就会自动加载这些 Skill不用你再废话。更关键的是OpenCode 用的 Skill 是开放标准跟 Claude Code、Cursor 这些工具都兼容你写一次哪都能用。但光有 Skill 还不够。Skill 负责「让 AI 知道怎么做」模型通道负责「让 AI 真的能做」。如果你还在用零散的 Key、每个工具配一遍、换台机器就重来那 Skill 的复用价值会被大幅稀释。所以这篇会分两条线走一条是 Skill 的目录结构、触发条件、参数定义和可复制配置另一条是通过 TaoToken 统一 Key/API 通道接入模型让 Skill 在真实会话里稳定生效。两条线合起来才是「让 AI 真正听你话」的完整闭环。适合谁看如果你符合下面任意一条这篇就是写给你的已经在用 OpenCode、Claude Code 或 Cursor但每次都要重复交代规范团队里有代码风格、提交规范、接口约定想让 AI 自动遵守手上有多个 AI 工具Key 管理混乱想统一到一个通道想写 Skill 但不知道 frontmatter 怎么写、目录放哪、怎么验证生效。下面从 Skill 的最小结构讲起再到 TaoToken 的前置准备、可复制配置、验证请求、报错排查最后给一个语义一致的接入入口。全程可跟做命令和配置都能直接抄。2. OpenCode Skill 目录结构与触发条件SKILL.md frontmatter 怎么写才生效先看 Skill 长什么样。一个标准 Skill 是一个目录里面至少有一个SKILL.md可选带scripts、references、assets子目录。my-skill/ ├── SKILL.md # 必填带 YAML frontmatter 的 Markdown 指令 ├── scripts/ # 可选可执行代码Python、Bash 等 ├── references/ # 可选按需加载的参考文档 └── assets/ # 可选模板、字体、图标等资源SKILL.md的 frontmatter 是触发条件的关键。最小可用版本长这样--- name: git-release description: 创建统一的版本发布和更新日志当用户准备打标签发版时使用 license: MIT --- ## 我做什么 - 从已合并的 PR 中起草发版说明 - 建议版本号升级遵循 semver - 提供可直接使用的 gh release create 命令 ## 什么时候用我 在准备带标签的版本发布时使用此技能。这里有两个字段决定 Skill 能不能被正确加载name必须和目录名一致。目录叫git-releasefrontmatter 里就得写git-release。写成release或git_release都会导致加载失败这是最常见的坑之一。description决定 AI 什么时候想起你。写「帮助编写代码」等于没说AI 根本不知道什么时候该调用。要具体到场景比如「当用户准备打标签发版时使用」「当需要审查 PR 代码风格时使用」。description 写得越贴近真实触发语境Skill 被正确调用的概率越高。OpenCode 会从这些位置自动发现 Skill项目级当前项目能用.opencode/skills/name/SKILL.md .claude/skills/name/SKILL.md .agents/skills/name/SKILL.md全局级所有项目都能用~/.config/opencode/skills/name/SKILL.md ~/.claude/skills/name/SKILL.md ~/.agents/skills/name/SKILL.md怎么选团队通用的规范放全局比如代码风格、提交规范、日志格式。项目特有的规则放项目目录比如你们项目用 UnoCSS 还是 Tailwind、API 命名风格是怎样的。搞混了的话AI 在不该用的时候加载了不该有的 Skill反而添乱。调用方式很直接。对话里说「用 code-review 技能来审查这段代码」AI 就会自动加载对应规范。你也可以在 Skill 里定义参数让调用更灵活--- name: api-review description: 审查接口返回处理当用户提交涉及 API 调用的代码时使用 --- ## 参数 - strict: 是否开启严格模式默认 false ## 执行步骤 1. 检查所有接口返回是否先判空 2. 检查错误分支是否有兜底 3. strict 为 true 时额外检查超时和重试配置参数定义写在 Markdown 正文里AI 会根据上下文解析。实测下来把参数写成key: 说明的形式比自然语言描述更稳定。还有一个很实用的功能/skill-creator。你不用从头写规范文档先让 AI 完成一个任务然后调用/skill-creator 把刚才的做法总结成一个标准技能它会自动分析执行过程提取关键步骤生成标准化 Skill 文件。第一次生成的可能不完美用几次后再迭代/skill-creator 分析使用 xxx 技能的过程改进 xxx 技能多迭代几次技能会越来越稳定。这就是「实战驱动」的做法先做一遍再抽象成技能在实际使用中不断完善。3. TaoToken 统一 Key 配置Base URL、API Key 与 Model ID 三件套Skill 写好了接下来要解决模型通道问题。如果你同时用好几个 AI 工具每个工具配一遍 Key换台机器就重来管理成本很高。TaoToken 的思路是提供一个统一的 API 通道你只需要维护一份 Key所有兼容 OpenAI 协议的工具都能接。前置准备很简单三步第一步注册并获取 API Key。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 完成注册然后进控制台创建 Key。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite第二步确认 Base URL。TaoToken 的 API 端点是https://taotoken.net/api注意这个地址不加 UTM 参数直接用于配置。第三步选 Model ID。在模型对话页面可以查看当前可用的模型列表https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite三件套凑齐后配置就统一了Base URL API Key Model ID。下面给几个常见工具的配置片段路径和原文一致可以直接抄。OpenCode 的配置通常在项目根目录或全局配置目录。如果你用的是 OpenAI 兼容模式配置片段如下{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: sk-你的Key, model: 你的ModelID } } }Claude Code 的配置走settings.json路径一般在~/.claude/settings.json或项目级.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: 你的ModelID } }Cline 的 MCP 配置在cline_mcp_settings.json如果你用 Cline 接 TaoToken{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_MODEL: 你的ModelID } } } }Codex 的配置走auth.json路径一般在~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的ModelID }这里要强调一点不管哪个工具Base URL、API Key、Model ID 这三件套必须同时写全。只写 Base URL 不写 Key会报 401只写 Key 不写 Model ID会报 model not foundBase URL 写错会报 local proxy failed 或连接超时。三件套缺一不可。配置完成后Skill 和模型通道就打通了。Skill 负责「告诉 AI 怎么做」TaoToken 负责「让 AI 真的能做」两者配合AI 才会在真实会话里按你的规范执行。4. 验证请求与成功结果用 curl 和真实会话确认 Skill 生效配置写完不算完得验证。验证分两层先确认模型通道通再确认 Skill 在会话里真的被加载。第一层用 curl 验证 API 通道。这是最直接的排障手段curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: 你的ModelID, messages: [ {role: user, content: 回复 OK 两个字母} ] }如果返回类似下面的结构说明通道正常{ choices: [ { message: { role: assistant, content: OK } } ] }如果返回 401说明 Key 不对或没带上如果返回reading choices相关报错说明响应结构解析失败通常是 Base URL 写成了不带/api的地址或者多写了/v1导致路径重复。第二层在 OpenCode 真实会话里验证 Skill。先确认 Skill 目录放对了位置然后启动 OpenCode输入触发语句用 git-release 技能帮我起草这次发版的说明如果 Skill 生效AI 会按你SKILL.md里定义的步骤执行比如先列已合并的 PR再建议版本号最后给gh release create命令。如果 AI 完全没反应说明 Skill 没被加载回去检查三件事目录名和name是否一致、description是否够具体、文件是否放在 OpenCode 能发现的路径下。再验证一个带参数的 Skill用 api-review 技能审查这段代码strict 设为 true观察 AI 是否按 strict 模式额外检查了超时和重试配置。如果只做了基础检查说明参数没被解析检查参数定义格式是否写成了key: 说明。实测下来验证顺序很重要先 curl 通通道再会话验 Skill。通道不通Skill 再对也没用通道通了 Skill 不生效问题一定在 Skill 结构或触发条件上。分开排查效率高很多。5. 常见报错排查401、local proxy failed、reading choices、OAuth 对照表这一节把最常见的几类报错列出来对照着查。401 Unauthorized原因通常是 API Key 没带、带错、或者带了但格式不对。检查Authorization: Bearer sk-xxx里的 Key 是否和控制台创建的一致。如果你用的是 Claude Code检查ANTHROPIC_API_KEY是否写在了正确的settings.json层级。OAuth 类报错也常伴随 401 出现如果你用的是需要 OAuth 的工具确认是否已完成授权流程或者改用 API Key 模式。local proxy failed这个报错通常出现在 Base URL 配置错误时。检查https://taotoken.net/api是否写完整有没有多写或少写/api。有些工具会自动拼接/v1如果你在 Base URL 里已经写了/v1就会变成/api/v1/v1导致路径错误。解决办法是 Base URL 只写到/api让工具自己拼后续路径。reading choices 报错这个报错说明请求发出去了但响应结构解析失败。常见原因是 Base URL 指向了一个返回非标准 OpenAI 格式的端点。确认你的 Base URL 是https://taotoken.net/apiModel ID 是在模型对话页面确认过的可用模型。如果 Model ID 写错有些端点会返回错误结构也会触发这个报错。OAuth 相关报错如果你用的工具默认走 OAuth 授权而你想用 API Key 模式需要在配置里显式关闭 OAuth 或切换到 API Key 认证。Claude Code 的settings.json里确保ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL同时存在工具会优先走 Key 模式。Codex 的auth.json同理api_key字段存在时不会走 OAuth。Skill 不生效这个不算报错但比报错更让人头疼。排查顺序目录名和name是否一致、description是否具体、文件是否在 OpenCode 发现路径下、frontmatter 的---是否闭合。四个都对了再检查调用语句是否命中了description里的场景词。Model not foundModel ID 写错或该模型当前不可用。去模型对话页面确认可用列表复制准确的 Model ID。注意大小写和连字符gpt-4和gpt4是两个不同的 ID。把这张对照表存下来下次报错直接查报错最可能原因检查点401Key 缺失或错误Authorization 头、settings.json 层级local proxy failedBase URL 错误是否只写到 /apireading choices响应结构非标准Base URL、Model IDOAuth认证模式冲突是否显式配置 API KeySkill 不生效结构或触发条件问题目录名、name、descriptionModel not foundModel ID 错误模型对话页面确认6. 让 Skill 和统一 Key 真正跑起来接入入口与长期编码方案Skill 和模型通道都配好之后剩下的就是日常使用和迭代。这里给几个实用建议帮你把整套流程跑顺。Skill 按功能分类目录。别把所有 Skill 堆在skills根目录下建子目录分组比如skills/git/、skills/code-review/、skills/docs/找起来方便AI 加载时也更清晰。团队共享 Skill。把 Skill 放在团队共用的库里新人 clone 下来就能用大家的 AI 助手都遵循同一套规范沟通成本能降不少。配合 TaoToken 统一 Key团队里每个人只需要一份 Key不用各自申请、各自配置。定期迭代 Skill。好的 Skill 是迭代出来的初版往往有考虑不周的地方实际用几次才会暴露问题。定期用/skill-creator优化别写完就当甩手掌柜。如果你长期做编码和 Agent 类任务可以考虑 Coding Plan把模型通道和额度统一管理https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite需要管理多个 Key 或查看用量进控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建和管理 API Key 的入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档在这里配置细节可以对照查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你用 Claude Code 比较多Anthropic 兼容接入的说明在这里https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite想先验证模型效果直接进模型对话页面试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite最后说一个我自己的习惯每次写完一个新 Skill先别急着放进全局目录在项目里跑几次确认触发稳定、参数解析正确再挪到全局。这样能避免一个不成熟的 Skill 污染所有项目的会话。Skill 是给 AI 的说明书说明书要经得起实战检验才值得复用。