1. 为什么 AGENTS.md 和 CLAUDE.md 总有一个不生效在 opencode 里折腾过配置的人大概率都遇到过这种困惑明明在项目里放了CLAUDE.md写了一大堆规范结果 AI 该乱写还是乱写换成AGENTS.md之后突然就听话了。反过来也有人把规则写进AGENTS.md却发现子目录里的约束完全没被读取。这个问题的本质是opencode 对「指令文件」有一套明确的加载规则不是所有.md文件都会被自动读取。AGENTS.md是唯一被自动加载的约束文件其他.md包括CLAUDE.md、instructions.md、rules.md默认不会自动生效必须通过opencode.json的instructions字段显式注册或者在AGENTS.md里写引导指令让 AI 按需读取。这篇就围绕 opencode 项目里AGENTS.md与CLAUDE.md、instructions等 XXX.md 文件的职责边界和加载优先级展开交付一份可直接复制的opencode.json与AGENTS.md骨架并给出通过 TaoToken 统一 Key/API 通道完成一次请求验证的具体动作帮你确认到底哪类指令文件真正被读取了。适合正在用 opencode 做多模块项目、或者被规则冲突搞晕的开发者。2. 先搞清楚 opencode 的指令文件加载层级在动手写配置之前得先把 opencode 的加载逻辑理清楚。它启动时会从当前工作目录向上遍历查找AGENTS.md同时也会查找子目录中的。具体分三层全局层是~/.config/opencode/AGENTS.md所有项目共享适合放个人通用偏好比如「始终用中文回复」「偏好函数式写法」。这一层优先级最低会被项目级覆盖。项目根目录层是/项目根/AGENTS.md项目级主规则整个项目生效。这是最常用的放项目概览、技术栈、编码规范、目录结构等。子目录层是/项目根/packages/core/AGENTS.md这类路径只在操作该目录或其子目录的文件时生效。适合 monorepo 或多模块项目每个子包有自己的约束。协调原则不是替换是叠加但有优先级。规则冲突时子目录优先于根目录更具体的覆盖更泛的项目级优先于全局级同层多个来源时AGENTS.md优先于CLAUDE.md兼容模式。实际效果是 AI 拿到的上下文等于全局规则加根目录规则加当前工作子目录规则三者合并。这里有个容易踩的坑CLAUDE.md只有在兼容模式下才会被当作AGENTS.md的补充来源而且优先级更低。如果你同时放了两个文件且内容冲突AGENTS.md说了算。所以别指望靠CLAUDE.md覆盖AGENTS.md的规则。3. TaoToken 前置统一 Key 与 API 通道准备opencode 本身是客户端真正跑模型需要接一个 API 通道。我用 TaoToken 做统一入口好处是 Key 和 Base URL 一套配置就能覆盖多个模型不用在 opencode 里为每个 provider 单独填一堆参数。先到控制台创建 API Key地址是 https://taotoken.net/api-keys 登录后新建一个 Key 并复制保存。注意 Key 只在创建时完整显示一次丢了就得重建。拿到 Key 之后opencode 的模型通道配置写在opencode.json里。TaoToken 的 API Base URL 是https://taotoken.net/api这个地址不加任何 UTM 参数直接填进配置即可。模型名按你实际要用的填比如claude-sonnet-4-5或gpt-4o这类具体以控制台模型列表为准。如果你还没注册可以先从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进官网了解整体能力再决定用哪档。长期做编码和 Agent 任务的可以看 Coding Plan 页面 https://taotoken.net/coding-plan 按用量选更划算。这一步的核心是Key 和 Base URL 准备好后面验证请求时才能确认「指令文件是否被读取」这件事否则模型都调不通根本谈不上验证规则生效。4. 可复制的 opencode.json 与 AGENTS.md 骨架下面这份配置是我实测下来比较稳的骨架你可以直接复制改。先看opencode.json放在项目根目录{ $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 }, gpt-4o: { name: GPT-4o } } } }, model: taotoken/claude-sonnet-4-5, instructions: [ docs/**/*.md, .opencode/rules/*.md, packages/*/AGENTS.md ] }这里instructions字段是关键它支持 GLOB 模式。docs/**/*.md表示 docs 下所有 md 文件.opencode/rules/*.md表示 rules 目录下的 md 文件packages/*/AGENTS.md表示各子包的 AGENTS.md。这些被注册的文件会被显式加载不再依赖自动发现。API Key 用环境变量TAOTOKEN_API_KEY注入别硬编码在文件里。设置方式export TAOTOKEN_API_KEY你的Key再看AGENTS.md骨架放在项目根目录# 项目规则 ## 技术栈 - 语言TypeScript 5.x - 框架Node.js pnpm workspace - 测试Vitest ## 编码规范 - 始终使用中文回复 - 函数优先使用箭头函数 - 提交信息遵循 Conventional Commits ## 目录结构 - packages/core核心逻辑 - packages/web前端界面 - docs设计文档 ## 按需读取 当任务涉及数据库时读取 docs/database.md 当任务涉及 API 时读取 docs/api-spec.md最后那段「按需读取」就是懒加载方式AI 只在相关任务时才去读对应文件不会一次性把所有文档塞进上下文。5. 验证请求确认哪类指令文件真正被读取配置写完了怎么确认AGENTS.md和instructions注册的文件真的生效了最直接的办法是发一个能触发规则差异的请求。先启动 opencodeopencode然后在对话里输入一个测试指令比如请用一句话说明本项目的技术栈和编码规范。如果AGENTS.md被正确加载模型应该能答出 TypeScript、pnpm、中文回复、箭头函数这些信息。如果答不出来或者答得含糊说明根目录AGENTS.md没被读到。再测instructions注册的文件。假设docs/database.md里写了「本项目使用 PostgreSQL 16连接池上限 20」你可以问本项目数据库用的是什么连接池上限多少如果模型能准确答出 PostgreSQL 16 和 20说明instructions里的 GLOB 生效了。答不出来就是注册路径写错了或者文件不在 GLOB 匹配范围内。测子目录优先级时在packages/core/AGENTS.md里写一条和根目录冲突的规则比如根目录说「用箭头函数」子目录说「core 包用 function 声明」。然后让 AI 修改packages/core下的文件看它遵循哪条。按规则应该是子目录优先。整个验证过程走下来你就能明确知道AGENTS.md是自动加载的CLAUDE.md和instructions.md这类必须显式注册子目录规则只在操作对应目录时生效。6. 本篇常见错排查报错一模型调不通提示 401 或 invalid api key。先检查环境变量TAOTOKEN_API_KEY是否设置成功用echo $TAOTOKEN_API_KEY确认。再检查opencode.json里baseURL是不是https://taotoken.net/api注意不要多加斜杠或路径。Key 如果泄露过到 https://taotoken.net/api-keys 重建一个。报错二instructions里的文件没生效。GLOB 路径是相对项目根目录的别写成绝对路径。docs/**/*.md能匹配docs/a.md和docs/sub/b.md但匹配不到docs同级目录。如果文件在.opencode/rules/下确认目录名拼写正确。改完opencode.json要重启 opencode 才生效。报错三CLAUDE.md和AGENTS.md冲突。同层多个来源时AGENTS.md优先CLAUDE.md只是兼容模式的补充。如果你想让CLAUDE.md生效要么把它注册进instructions要么在AGENTS.md里写引导指令让 AI 去读。别指望它自动覆盖AGENTS.md。报错四子目录规则影响了其他模块。子目录AGENTS.md只在操作该目录或其子目录的文件时加载不会影响其他模块。如果发现影响了检查是不是把规则写进了根目录AGENTS.md或者instructions的 GLOB 匹配范围太宽。报错五所有层加起来太长模型开始忽略规则。所有层加起来建议不超过 300 行超了就拆到opencode.json的instructions里用外部文件。规则太多模型会抓不住重点反而容易违反。排查完这些接入和验证基本就通了。如果你在验证模型响应是否符合预期可以直接用模型对话页面 https://taotoken.net/model-chat 快速试一条请求确认通道和模型都正常再回到 opencode 里调规则。长期做编码和 Agent 任务的Coding Plan 页面 https://taotoken.net/coding-plan 有更细的用量说明。接入文档在 https://taotoken.net/doc 配置项有疑问可以对照查。