1. 为什么 AGENTS.md 写满了，opencode 还是不动手
如果你正在用 opencode 做后端或全栈开发，大概率已经踩过这个坑：花了一晚上把AGENTS.md写得明明白白，回复语种、中间文件目录、禁止自动 commit、TDD 流程、Chrome DevTools MCP 集成测试全列上了，结果一启动 opencode，它该问的还是问，该乱改的还是乱改，甚至直接告诉你「我无法访问模型」。
问题不在AGENTS.md。AGENTS.md是编码智能体的长期记忆，它在每次会话启动时被加载进上下文，并且不会被压缩或卸载，负责告诉 agent「这个项目怎么跑、怎么测、怎么提交」。但它管的是规则，不管通道。模型通道没接上，规则再全也只是写在纸上——agent 根本连不上模型，自然驱动不了任何编码动作。
我试过把opencode.json里的模型通道指向 TaoToken 的 Base URL，再配合AGENTS.md做长期记忆，整个链路才真正跑通：opencode 负责读规则、拆任务、调工具，TaoToken 负责提供 Key 和 Base URL 把请求送到模型。两者职责不重叠，TaoToken 不替代 opencode，也不改AGENTS.md里的任何一条规则。
这篇就按「接入配置」这个视角，把C:\Users\{工号}\.config\opencode\opencode.json打开之前该做的事、该填的字段、该避的坑，一步步写清楚。适合已经装好 opencode、想把它接到可用模型通道上的后端和全栈同学。
2. 前置准备：先拿到 Key 和 Base URL
opencode 本身是个命令行式的编码智能体，它不内置模型，需要你告诉它「模型从哪来」。这一步就是 TaoToken 的定位：只提供 Key 和 Base URL，不碰你的项目文件，不碰AGENTS.md。
先打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 完成注册，然后在控制台里创建一个 API Key。创建入口在 https://taotoken.net/console ，Key 列表在 https://taotoken.net/api-keys 。Key 只在创建时完整显示一次，复制下来存到本地密码管理器或者临时环境变量里，别直接写进会提交到 git 的文件。
拿到 Key 之后，记住两个值：
| 配置项 | 值 | 说明 |
|---|---|---|
| Base URL | https://taotoken.net/api | 不要加/v1，不要带 UTM 参数 |
| API Key | 控制台创建的那串 | 只用于本地配置，别外传 |
这里有个高频错误：很多人习惯性在 Base URL 后面补/v1，因为不少模型服务是那个格式。TaoToken 的接入地址就是https://taotoken.net/api，多写一段路径会导致请求打到不存在的路由上，opencode 报 404 或者直接连接失败。另外，Base URL 里不要带任何?utm_source=...之类的查询参数，那些是给网页链接用的，写进配置文件会污染请求地址。
如果你还想确认模型侧的行为，可以先用模型对话页面手动发一条消息验证 Key 是否可用，入口在 https://taotoken.net/models 。这一步不是必须的，但能帮你把「Key 本身有问题」和「opencode 配置有问题」两类故障分开。
3. 可复制配置：改 opencode.json 的模型通道
opencode 的全局配置在 Windows 上是C:\Users\{你的工号}\.config\opencode\opencode.json，macOS 和 Linux 在~/.config/opencode/opencode.json。这个文件同时管模型通道和 MCP 工具，我们这次只动模型通道部分，AGENTS.md相关的规则一个字都不用改。
打开文件，找到 provider 或 model 相关配置。不同版本的 opencode 字段名略有差异，核心是「自定义 provider + baseURL + apiKey」。下面是一份可直接参考的配置片段：
{ "$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" }几个关键点逐个说：
baseURL必须是https://taotoken.net/api，结尾没有斜杠，没有/v1。apiKey这里用了{env:TAOTOKEN_API_KEY}的写法，意思是让 opencode 从环境变量里读，避免把明文 Key 写进配置文件。你也可以直接填字符串，但更推荐环境变量，尤其是多人共用机器或者配置会同步到云盘的情况。
npm字段指定用 OpenAI 兼容协议的适配器，TaoToken 的接口按 OpenAI 兼容格式暴露，所以走@ai-sdk/openai-compatible就行。models里列出你要用的模型标识，model字段指定默认用哪个，格式是provider/model。
设置环境变量，Windows PowerShell 里可以这样临时设：
$env:TAOTOKEN_API_KEY = "你的Key"想持久化就写进用户环境变量，或者用.env文件配合 opencode 的加载机制。macOS / Linux：
export TAOTOKEN_API_KEY="你的Key"配置改完，AGENTS.md不用动。它依然会在 opencode 启动时被加载，作为长期记忆生效。你之前写的「始终使用简体中文回复」「中间文件放 tmp/」「严禁自动 commit」「TDD 流程 + Chrome DevTools MCP 集成测试」这些规则，全部照常起作用。通道和记忆是两条独立的线，这次只换了通道。
4. 验证请求：确认通道真的通了
配置写完别急着开新会话写业务代码，先做一次最小验证。在项目目录下启动 opencode：
opencode进入交互界面后，先看它有没有报 provider 相关的错误。如果配置解析失败，opencode 启动阶段就会提示找不到 provider 或者 apiKey 为空。没有报错的话，发一条最简单的消息：
用一句话说明当前项目用的是什么前端框架这条消息会触发一次真实的模型请求。如果通道通了，你会看到模型正常回复，并且回复语言是简体中文——这说明AGENTS.md里的语种规则也被加载了。两个信号同时出现，才代表「通道 + 长期记忆」都生效。
想更直接地验证请求链路，可以在另一个终端里观察 opencode 的日志输出，或者在配置里临时打开 debug 日志。请求成功时，你会看到类似POST https://taotoken.net/api/...的记录，状态码 200。如果看到 401，是 Key 的问题；看到 404，多半是 Base URL 多写了/v1或者带了多余路径；看到连接超时，检查本机网络和代理设置是否干扰了对taotoken.net的访问。
验证通过后，再回到你原来的开发流程：/init生成或更新AGENTS.md，按 Tab 切到 plan agent 做需求澄清和任务拆解，再切到 build agent 执行代码。这时候 agent 才有能力真正读你的接口文档、复用组件、跑 Chrome DevTools MCP 做 UI 自动化测试。通道没通之前，这些步骤全是空转。
5. 本篇常见错排查
接入阶段最容易卡住的就是下面这几类，按出现频率排：
Base URL 写成了https://taotoken.net/api/v1。这是最高频的错误，症状是请求返回 404 或者模型列表拉不到。改回https://taotoken.net/api即可，结尾不要斜杠。
Base URL 里带了 UTM 参数。有人从浏览器地址栏直接复制，把?utm_source=...&utm_campaign=...一起粘进去了。这些参数是网页统计用的，写进 API 请求地址会让路由匹配失败。手动删掉问号后面的全部内容。
apiKey 为空或环境变量没生效。用了{env:TAOTOKEN_API_KEY}但环境变量没设，或者设在了另一个终端会话里。opencode 启动时读不到就会报鉴权失败。确认当前 shell 里echo $TAOTOKEN_API_KEY（Windows 用echo $env:TAOTOKEN_API_KEY）能打印出值。
改了AGENTS.md没重启 opencode。这个和通道无关，但经常和接入问题混在一起。AGENTS.md是启动时加载的长期记忆，手动改完必须重启 opencode 才生效。如果你改完规则发现 agent 行为没变，先重启再排查通道。
模型标识写错。model字段里的taotoken/claude-sonnet-4-5要和models里定义的 key 完全一致，大小写、连字符都不能差。写错会提示模型不存在。
把 TaoToken 当成 opencode 的替代品。再强调一次，TaoToken 只给 Key 和 Base URL，它不接管你的编辑器，不改AGENTS.md，不替你执行代码。opencode 依然是那个读规则、调工具、跑测试的编码智能体。两者是配合关系，不是替代关系。
排障时如果拿不准是 Key 还是配置的问题，先去 https://taotoken.net/api-keys 确认 Key 状态正常，再对照 https://taotoken.net/doc 里的接入说明核对字段格式。文档里有各语言的调用示例，可以拿来和你的opencode.json逐字段比对。
6. 通道接好之后，长期记忆才真正开始工作
把模型通道切到 TaoToken 之后，AGENTS.md的价值才体现出来。它作为开机加载的长期记忆，负责把项目环境、测试命令、提交规范、TDD 流程这些高频信息一次性喂给 agent，避免每轮会话重复解释。通道负责让这些规则有模型可驱动，记忆负责让驱动有章法。
如果你后面要长期跑编码任务、做多轮 agent 协作，可以关注 Coding Plan 这类按周期计费的方式，入口在 https://taotoken.net/coding-plan 。日常调试和验证模型行为，用模型对话页面就够了：https://taotoken.net/models 。Key 的创建和管理统一在控制台：https://taotoken.net/console 和 https://taotoken.net/api-keys 。接入细节和字段说明看文档：https://taotoken.net/doc 。用 Claude Code 或 Anthropic 协议接入的场景，参考 https://taotoken.net/claudecode 。
配置这件事本身不复杂，难的是把「通道」和「记忆」两条线分清楚。通道没通，记忆再全也是空转；通道通了，AGENTS.md才能照常作为开机加载的长期记忆，驱动编码智能体把后端全栈的活一件件干完。
