1. 为什么国内开发者用 OpenCode 跑 AI Skills 更顺手AI Skills 这段时间确实火简单说它就是给大模型外挂的一套「技能包」一个目录里放SKILL.md和若干脚本、模板模型读到描述后就知道在什么场景下调用它帮你自动写代码、生成表格、整理文档。Claude Code 把这套机制带火了但国内开发者直接上手 Claude Code 时往往会卡在账号、网络、终端环境这几道坎上折腾半天还没摸到 Skills 本身。OpenCode 是一个开源终端 AI 编码工具支持 TUI 和桌面端两种形态模型供应商可以自己接Skills 目录结构也兼容 Anthropic 那套规范。对国内开发者来说它的价值在于模型 API 可以换成国内可直连的服务Skills 加载路径清晰配置全部落在本地文件里出问题好排查。这篇就围绕「OpenCode 接入 AI Skills 的完整落地路径」来写重点解决环境变量配置和 Skills 调用链路这两个最容易翻车的地方。适合谁看已经在用 OpenCode 但 Skills 一直加载不出来的人想从 Claude Code 迁过来、又不想重学一套配置的人以及想给自己项目定制私有 Skills 的开发者。下面所有步骤都是本地可复制的配置片段直接抄命令直接跑。先说清楚一个概念避免后面混淆。OpenCode 里跟「环境变量」相关的配置其实分两层一层是模型供应商的接入信息Base URL、API Key、Model ID另一层是 OpenCode 自身的运行配置全局opencode.json和项目级opencode.json。Skills 的加载则依赖.opencode目录的位置。这三者经常被混在一起讲导致很多人配了模型却加载不出 Skills或者 Skills 加载了但模型调不通。我会把它们拆开一段一段配。2. TaoToken 前置准备把模型接入信息先拿到手OpenCode 本身不带模型你得先有一个能用的模型服务。国内直连的方案里TaoToken 是比较省事的一个它提供 OpenAI 兼容和 Anthropic 兼容两种接口形态OpenCode 通过/connect添加供应商时可以直接填。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在「API Keys」页面创建一个新的 Key。创建时给它起个能认出来的名字比如opencode-skills方便以后区分。Key 只在创建时完整显示一次复制下来先存到本地一个临时文件里别直接贴到聊天窗口。第二步确认你要用的模型 ID。TaoToken 的模型列表在文档里有常用的编码模型都能找到。记下你要用的那个 Model ID后面配置里要填。如果你不确定选哪个先用文档里推荐的默认编码模型跑通链路再换。第三步确认 Base URL。OpenCode 走 OpenAI 兼容协议时Base URL 填https://taotoken.net/api注意这里不加任何 UTM 参数就是干净的 API 地址。走 Anthropic 兼容协议时OpenCode 的/connect里选 Anthropic 供应商Base URL 同样指向https://taotoken.net/api具体路径以文档为准。这里有个容易踩的坑很多人把官网地址当成 API 地址填进去结果请求 404。记住官网是给人看的API 是给程序调的两者不是一回事。API 地址就是https://taotoken.net/api后面拼/v1/chat/completions这类标准路径。拿到这三样东西——Base URL、API Key、Model ID——就可以进 OpenCode 配置了。这三件套在后面每一处配置里都会出现格式必须完全一致少一个字符都会导致 401 或模型找不到。如果你还没装 OpenCode先去 https://opencode.ai/download 下载。Windows 用户直接下桌面端安装包装完目录里会有OpenCode.exe图形界面、OpenCode-cli.exe命令行 TUI和uninstall.exe。我建议先用OpenCode-cli.exe把链路跑通因为 TUI 里报错信息更直接图形界面有时候会把错误吞掉。3. 可复制配置opencode.json 与 Skills 目录一次配好这一节是全文的核心配置片段都可以直接复制。OpenCode 的配置加载顺序是项目级opencode.json覆盖全局~/.config/opencode/opencode.json。Windows 上全局路径是C:\Users\你的用户名\.config\opencode\opencode.json。先建全局配置文件。在C:\Users\你的用户名\.config\opencode\目录下新建opencode.json内容如下{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: sk-你的Key粘贴在这里 }, models: { 你的ModelID: { name: TaoToken 编码模型 } } } }, model: taotoken/你的ModelID }把sk-你的Key粘贴在这里换成你刚才创建的 Key你的ModelID换成实际模型 ID两处要一致。这个配置用的是 OpenAI 兼容协议ai-sdk/openai-compatible是 OpenCode 内置支持的适配器不用额外装包。如果你更习惯用环境变量而不是把 Key 写进文件可以把apiKey那行改成引用环境变量apiKey: {env:TAOTOKEN_API_KEY}然后在系统环境变量里加一条TAOTOKEN_API_KEY值就是你的 Key。Windows 上加完环境变量要重启终端才生效这点很多人会忘。用环境变量的好处是配置文件可以进 Git不怕 Key 泄露。接下来配 Skills 目录。OpenCode 默认从两个位置读 Skills全局的~/.config/opencode/skills/和项目级的.opencode/skills/。注意目录名是.opencode开头带点。很多人建成了opencode不带点结果怎么都不加载。以项目级为例在你的项目根目录下建.opencode/skills/然后把下载的 Skills 解压进去。从 https://github.com/anthropics/skills 下载官方 Skills 压缩包解压后你会看到每个 Skill 是一个独立目录里面有SKILL.md。把整个目录拷到.opencode/skills/下最终结构长这样你的项目/ ├── .opencode/ │ └── skills/ │ ├── skill-creator/ │ │ └── SKILL.md │ └── 其他skill/ │ └── SKILL.md └── opencode.json项目级opencode.json可以只写跟项目相关的覆盖项比如换个模型{ $schema: https://opencode.ai/config.json, model: taotoken/你的ModelID }这样全局配置管供应商和 Key项目配置管模型选择分层清晰。如果你想让某个项目用完全独立的供应商也可以把完整的provider块写进项目配置它会覆盖全局的同名项。配完这两处Skills 的加载链路就通了OpenCode 启动时扫描.opencode/skills/读取每个SKILL.md的元信息模型在对话中根据描述决定是否调用。剩下就是验证。4. 验证请求一次端到端调用把链路跑通配置写完不验证等于没配。这一节带你跑一次完整的端到端调用从启动到 Skills 被识别再到实际触发。打开OpenCode-cli.exe进入你的项目目录。启动后先按一下Tab键把模式从 plan 切到 build。plan 模式只读不写Skills 里的写操作会被拦很多人卡在这以为 Skills 坏了。切到 build 后输入/init回车。OpenCode 会扫描项目、生成AGENTS.md同时加载.opencode/skills/下的所有 Skill。等它跑完直接问一句我能使用什么 skills如果配置正确它会列出你放进去的 Skill 名称和描述。这一步能列出来说明 Skills 加载链路通了。接着验证模型调用。输入/models看列表里有没有你配的taotoken/你的ModelID。选中它然后随便问一个需要模型回答的问题比如「用 Python 写一个读取 CSV 并去重的函数」。如果模型正常返回代码说明 Base URL、Key、Model ID 三件套都对。最后验证 Skills 实际触发。以skill-creator为例输入skill-creator 帮我创建一个把 Markdown 转成表格的 skill。注意会弹出 Skill 选择列表用上下方向键选中回车确认。如果模型开始按 skill-creator 的流程追问细节、生成SKILL.md说明整条链路——模型接入、Skills 加载、Skill 调用——全部跑通。桌面端OpenCode.exe操作逻辑一样只是/命令和引用都变成图形化菜单点选即可。验证通过后你可以把常用的 Skill 固定下来日常直接调用。这里补一句关于auth.json的说明。如果你是用/connect图形化添加的供应商Key 会存到C:\Users\你的用户名\.local\share\opencode\auth.json。这个文件是明文存的别提交到 Git。用opencode.json配的供应商则不存在这里两者不要混用否则会出现「配了但不生效」的怪现象。5. 常见报错排查401、local proxy failed、reading choices链路跑不通时报错信息通常指向几个固定位置。这一节按真实报错来对照排查。401 UnauthorizedKey 错了或没带上。先检查opencode.json里apiKey的值有没有多余空格sk-前缀是否完整。如果用环境变量引用{env:TAOTOKEN_API_KEY}确认环境变量真的生效了——在终端里echo %TAOTOKEN_API_KEY%Windows或echo $TAOTOKEN_API_KEYmacOS/Linux看有没有输出。没有输出就是环境变量没配好或没重启终端。还有一种情况是 Key 被禁用或额度用完去控制台确认 Key 状态。local proxy failed / connection refusedBase URL 填错了。确认填的是https://taotoken.net/api不是官网地址也不是带 UTM 的地址。如果你本地开了某些网络工具先关掉再试避免请求被劫持到错误端口。OpenCode 的请求是直连的不需要额外代理配置。reading choices 相关报错通常是模型返回格式跟 OpenCode 预期不一致。检查你用的 Model ID 是否在 TaoToken 文档的兼容列表里。有些模型只支持特定协议OpenAI 兼容的模型走ai-sdk/openai-compatibleAnthropic 兼容的走 Anthropic 适配器别配错。如果换了模型就好说明是模型兼容性问题不是配置问题。Skills 列不出来九成是目录名或路径问题。确认目录是.opencode/skills/带点且SKILL.md在 Skill 目录的根层不是嵌套在子目录里。另外确认你启动 OpenCode 时的工作目录是项目根目录不是随便一个终端路径。项目级 Skills 只在项目根目录启动时加载。/init没反应或报权限错先确认按了Tab切到 build 模式。plan 模式下/init的写操作会被拦。如果还不行检查项目目录是否有写权限Windows 上某些系统盘目录需要管理员权限。模型列表里没有你的供应商opencode.json的 JSON 格式错了。用编辑器自带的 JSON 校验或者把内容贴到在线 JSON 校验器里过一遍。常见错误是多了个逗号、少了引号、括号不配对。$schema那行可以帮你提前发现字段名写错。排查顺序建议从下往上先确认 JSON 能解析再确认 Key 和 Base URL再确认模型 ID最后确认 Skills 目录。每确认一层就重启一次 OpenCode别一次改一堆否则不知道是哪步生效的。6. 长期编码与 Agent 场景把 Skills 用成日常工具链路跑通只是开始真正省时间的是把 Skills 变成日常编码流程的一部分。这里给几个我实际用下来比较顺的做法。第一把项目级 Skills 和全局 Skills 分开管。全局~/.config/opencode/skills/放通用技能比如代码审查、提交信息生成、文档翻译项目级.opencode/skills/放这个项目专属的比如特定框架的脚手架、内部 API 的调用模板。这样换项目时通用技能还在专属技能跟着仓库走。第二用skill-creator把重复劳动固化下来。你每次都要手动做的事比如「把接口返回的 JSON 转成 TypeScript 类型」「按团队规范生成 commit message」都可以让skill-creator生成一个 Skill。生成后放进.opencode/skills/下次直接调用。Skill 本质就是一段结构化的提示词加脚本写一次省很多次。第三长会话记得用/compact压缩上下文。Skills 调用会往上下文里塞不少内容聊久了容易超窗口。/compact能把历史对话压缩保留关键信息省 token 也省响应时间。/export可以把会话导出存档方便回溯。第四需要长期跑编码任务或 Agent 工作流时用 Coding Plan 更划算。TaoToken 的 Coding Plan 页面在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合高频调用场景。日常零散验证模型效果用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 就够了。第五Key 管理要上心。不同项目用不同的 Key方便按项目统计用量也方便某个 Key 泄露时单独吊销。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 遇到协议层面的问题先查文档再排查。最后说个实际经验Skills 的触发靠的是描述匹配SKILL.md里的描述写得越具体模型越容易在正确场景调用它。别写「处理数据」这种模糊描述写成「读取 CSV 文件按指定列去重输出新的 CSV」这种触发准确率高很多。这个细节调一次后面省很多次手动。