配置 opencode 和 spec-kit：用 TaoToken 统一 Key 打通 AI 编码工作流

1. 为什么要把 opencode 和 spec-kit 的 Key 收拢到一处如果你同时用 opencode 写代码、用 spec-kit 做规格驱动开发大概率遇到过这种局面opencode 里配了一份模型 Keyspec-kit 初始化时又要选一次 AI 助手、填一次 Key两个工具各存各的配置。换一台机器、换一个模型、Key 到期轮换就得挨个文件翻一遍改漏一个就报 401。opencode 是一个终端里的 AI 编码代理能读项目、改文件、跑命令spec-kit 是 GitHub 出的规格驱动开发工具链通过specify命令把需求拆成规格、计划、任务再交给 AI 助手执行。两者都支持自定义模型端点这就给了统一入口的空间把模型调用都指向 TaoToken 的 API 地址用同一个 Key 驱动两个工具配置只维护一份。这篇就按这个思路走先装好两个工具再把它们的模型配置都改成 TaoToken最后跑一次端到端验证确认 opencode 和 spec-kit 都能正常出结果。适合已经在用 AI 编码、但被多份 Key 配置折腾过的开发者。全程命令可直接复制Windows 和 macOS/Linux 的差异我会标出来。2. 前置准备TaoToken Key 与两个工具的安装2.1 拿到 TaoToken 的 API Key先到 TaoToken 控制台创建一个 API Key。地址是 https://taotoken.net/api-keys 登录后新建 Key复制出来先存到安全的地方后面两个工具都要用。TaoToken 的 API 基地址是 https://taotoken.net/api 兼容 OpenAI 风格的/v1/chat/completions调用。也就是说任何支持自定义 OpenAI 兼容端点的工具把 base_url 指过来、把 Key 填进去就能用。opencode 和 spec-kit 都属于这一类。注意Key 只显示一次创建后立刻保存。不要把它写进会提交到 Git 的配置文件里用环境变量或本地私有配置承载。2.2 安装 opencodeopencode 通过 npm 全局安装一条命令npm install -g opencode-ailatest装完执行opencode --version确认能输出版本号。如果提示找不到命令检查 npm 全局 bin 目录是否在 PATH 里。2.3 安装 spec-kit 依赖的 uvspec-kit 的 CLI 叫specify通过 Python 包管理工具 uv 安装。先装 uv。Windows PowerShellpowershell -ExecutionPolicy Bypass -c irm https://releases.astral.sh/github/uv/releases/download/0.11.2/uv-installer.ps1 | iexmacOS / Linuxcurl -LsSf https://astral.sh/uv/install.sh | sh装完把 uv 的安装目录加进环境变量。Windows 默认在C:\Users\你的用户名\.local\binmacOS/Linux 默认在~/.local/bin。加完重开一个终端执行uv --version验证。2.4 安装 specify-cli有两种装法。想跟最新源码直接从 Git 仓库装uv tool install specify-cli --from githttps://github.com/github/spec-kit.git想本地改代码就先 clone 再本地装git clone https://github.com/github/spec-kit.git cd spec-kit uv tool install specify-cli --from .装完执行specify check它会列出支持的 AI 助手以及当前检测到的安装状态。你能在这里看到 opencode 是否被识别。3. 可复制配置opencode 与 spec-kit 接入 TaoToken3.1 opencode 的 config.toml 骨架opencode 的配置放在用户目录下的~/.config/opencode/config.tomlWindows 是%USERPROFILE%\.config\opencode\config.toml。核心是把 provider 指向 TaoToken 的兼容端点。# ~/.config/opencode/config.toml model taotoken/gpt-4o-mini [provider.taotoken] npm ai-sdk/openai-compatible name TaoToken options { baseURL https://taotoken.net/api/v1 } models { gpt-4o-mini { name gpt-4o-mini } }Key 不写进这个文件用环境变量注入。在 shell 配置里加一行export TAOTOKEN_API_KEYsk-你的KeyWindows PowerShell 临时设置$env:TAOTOKEN_API_KEYsk-你的Keyopencode 读取 provider 的鉴权时会从环境变量取。具体变量名以 opencode 当前版本的 provider 约定为准如果它要求OPENAI_API_KEY就再补一个同名变量指向同一个 Key。3.2 spec-kit 的 settings.json 骨架spec-kit 在项目里初始化后会在项目目录生成配置。执行初始化cd 你的项目目录 specify init --here交互里选择 AI 助手时选 opencode脚本类型按需选 sh 或 ps。初始化完成后项目里会出现 spec-kit 的配置结构其中模型相关的设置放在 settings 文件里。把模型端点改成 TaoToken{ ai: { provider: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKeyEnv: TAOTOKEN_API_KEY, model: gpt-4o-mini } }这里用apiKeyEnv指向环境变量名而不是把 Key 明文写进 JSON。这样两个工具共用同一个TAOTOKEN_API_KEY轮换 Key 时只改一处。3.3 两处配置的对照项目opencodespec-kit配置文件~/.config/opencode/config.toml项目内 settings.json端点字段options.baseURLai.baseUrlKey 来源环境变量apiKeyEnv指向环境变量模型字段modelai.model统一入口https://taotoken.net/api/v1https://taotoken.net/api/v1两边的 baseURL 都指向同一个地址Key 都从TAOTOKEN_API_KEY取这就是「统一 Key」的落点。4. 端到端验证确认两个工具都能调通4.1 先验证 TaoToken 端点本身在配置工具之前先用 curl 确认 Key 和端点可用curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 ok}] }返回里能看到choices字段和内容说明 Key 和端点没问题。这一步排掉网络和鉴权问题后面工具报错就能定位到配置层。4.2 验证 opencode进入任意项目目录启动 opencodeopencode在交互界面里发一句简单指令比如「列出当前目录的文件并说明用途」。如果 opencode 能返回模型生成的内容说明 provider 配置生效。若报鉴权错误回到 3.1 检查环境变量名是否和 provider 约定一致。4.3 验证 spec-kit在已初始化的项目里执行specify check确认 opencode 被识别为可用助手。然后跑一次规格生成/speckit在 opencode 里触发 spec-kit 的流程让它根据当前项目生成一份规格草稿。能看到它调用模型产出结构化内容就说明 spec-kit 也走通了 TaoToken。4.4 一次完整的端到端动作把上面串起来在项目里用/speckit生成规格 → opencode 读取规格并执行任务 → 两者都通过TAOTOKEN_API_KEY调用同一个端点。整个过程只维护一份 Key换模型时改model字段即可两个工具同时生效。5. 本篇常见错排查5.1 opencode 报 401 或鉴权失败最常见的原因是环境变量名不匹配。opencode 的 provider 可能默认读OPENAI_API_KEY而你只设了TAOTOKEN_API_KEY。解决办法是补一个同名变量或者在 provider 配置里显式指定读取的环境变量。另一个原因是 Key 复制时带了空格或换行重新复制一次。5.2 spec-kit 初始化时找不到 opencodespecify check里如果没列出 opencode通常是 opencode 没装好或不在 PATH。先确认opencode --version能输出再重跑specify init --here。Windows 上还要注意 uv 的 bin 目录是否加进了 PATH否则 specify 本身可能都调不起来。5.3 baseURL 写错导致 404TaoToken 的兼容端点是https://taotoken.net/api/v1注意结尾的/v1。有些工具会自动补/v1有些不会。如果报 404先确认你填的地址和 curl 验证时用的完整路径一致。opencode 的options.baseURL和 spec-kit 的ai.baseUrl都要带/v1。5.4 模型名不存在model字段要填 TaoToken 支持的模型标识。填错会返回模型不存在的错误。先用 4.1 的 curl 换几个模型名试确认哪个可用再写进配置。两个工具的模型名要保持一致避免一个能跑一个报错。5.5 改了配置没生效opencode 和 spec-kit 都可能缓存配置。改完 config.toml 或 settings.json 后重启 opencodespec-kit 重新执行一次specify check。环境变量改动后要新开终端旧终端里的变量不会自动刷新。6. 把统一 Key 用在长期编码流里配置跑通只是第一步。真正省事的地方在于当你把 opencode 和 spec-kit 都指向 TaoToken后续换模型、加额度、轮换 Key 都只动一处。想长期用这套组合做规格驱动开发可以到 https://taotoken.net/coding-plan 看 Coding Plan它面向的就是这种持续编码和 Agent 场景配合 opencode 的代理能力和 spec-kit 的规格流程能把「需求 → 规格 → 任务 → 代码」串成一条线。如果你更想先单独验证模型对话效果可以直接用 https://taotoken.net/models 里的对话入口试几个模型确认输出质量再决定写进配置的模型名。接入文档在 https://taotoken.net/doc 里面有各语言和工具的调用示例遇到字段不确定时对着查比猜快。我自己的习惯是项目里只保留TAOTOKEN_API_KEY一个环境变量opencode 和 spec-kit 的配置文件都引用它模型名抽成一处常量。这样换机器时装好工具、设一个变量、复制两份配置五分钟就能恢复整套 AI 编码工作流。