企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册并登录。登录后进控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在「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 Unauthorized：Key 错了或没带上。先检查opencode.json里apiKey的值有没有多余空格，sk-前缀是否完整。如果用环境变量引用{env:TAOTOKEN_API_KEY}，确认环境变量真的生效了——在终端里echo %TAOTOKEN_API_KEY%（Windows）或echo $TAOTOKEN_API_KEY（macOS/Linux）看有没有输出。没有输出就是环境变量没配好或没重启终端。还有一种情况是 Key 被禁用或额度用完，去控制台确认 Key 状态。

local proxy failed / connection refused：Base URL 填错了。确认填的是https://taotoken.net/api，不是官网地址，也不是带 UTM 的地址。如果你本地开了某些网络工具，先关掉再试，避免请求被劫持到错误端口。OpenCode 的请求是直连的，不需要额外代理配置。

reading choices 相关报错：通常是模型返回格式跟 OpenCode 预期不一致。检查你用的 Model ID 是否在 TaoToken 文档的兼容列表里。有些模型只支持特定协议，OpenAI 兼容的模型走@ai-sdk/openai-compatible，Anthropic 兼容的走 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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合高频调用场景。日常零散验证模型效果，用模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 就够了。

第五，Key 管理要上心。不同项目用不同的 Key，方便按项目统计用量，也方便某个 Key 泄露时单独吊销。Key 列表在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，定期清理不用的。接入细节和协议说明看文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到协议层面的问题先查文档再排查。

最后说个实际经验：Skills 的触发靠的是描述匹配，SKILL.md里的描述写得越具体，模型越容易在正确场景调用它。别写「处理数据」这种模糊描述，写成「读取 CSV 文件，按指定列去重，输出新的 CSV」这种，触发准确率高很多。这个细节调一次，后面省很多次手动@。