1. 为什么你的 OpenCode 规则总是不生效很多人第一次用 OpenCode 的时候都会遇到一个很迷惑的现象明明在项目根目录写了AGENTS.md里面清清楚楚写着「用 pnpm 不用 npm」「组件必须放src/components」结果 AI 该用 npm 还是用 npm该乱放文件还是乱放。于是开始怀疑是不是规则文件没被读到或者 OpenCode 的 Rules 功能根本是摆设。我试过在同一个仓库里同时放AGENTS.md、CLAUDE.md、CONTEXT.md三个文件想看看 OpenCode 到底认哪个。结果发现它只读了AGENTS.md另外两个完全被忽略。这就是 OpenCode Rules 体系最核心的一个设计每个类别里第一个匹配的文件获胜后面的直接不看。理解这一点你才能明白为什么有些规则「写了等于没写」。OpenCode Rules 本质上是一套给 LLM 注入上下文的机制。它把项目约定、编码标准、工具配置这些信息在会话开始前塞进模型的上下文里让 AI 助手知道「这个项目该怎么干活」。它跟 Cursor 的 Rules 思路类似但文件格式和优先级规则完全不同。适合谁用适合那些已经在用 OpenCode 做日常开发、并且希望团队里多个 AI 工具比如 OpenCode 和 Claude Code行为保持一致的开发者。这套规则体系分三个层次项目规则、全局规则、Claude Code 兼容规则。项目规则放在仓库根目录的AGENTS.md只对当前目录及子目录生效通过 Git 跟团队共享全局规则放在~/.config/opencode/AGENTS.md对所有 OpenCode 会话生效属于你个人的偏好不跟团队共享Claude Code 兼容规则则是给从 Claude Code 迁移过来的人准备的让CLAUDE.md和~/.claude/skills/也能被识别。真正让人踩坑的是优先级。OpenCode 启动时会按顺序查找先从当前目录向上遍历找AGENTS.md找不到再找CLAUDE.md再找不到找CONTEXT.md本地都没有才去看全局的~/.config/opencode/AGENTS.md最后才轮到~/.claude/CLAUDE.md。所以如果你项目里同时有AGENTS.md和CLAUDE.md只有AGENTS.md会被加载CLAUDE.md形同虚设。这个规则不搞清楚你写的规则永远可能被另一个文件「顶掉」。还有一个容易被忽略的点opencode.json里的instructions字段。它跟AGENTS.md不是二选一的关系而是合并关系。也就是说AGENTS.md的内容和instructions里列出的文件内容会一起塞进上下文。这就给了你模块化管理规则的空间——把详细规范拆到单独文件用opencode.json引用进来保持AGENTS.md简洁。下面这张表把三种规则类型的关键差异列清楚你可以对照自己的项目看看该用哪种规则类型文件位置作用域是否团队共享典型用途项目规则项目根目录AGENTS.md当前目录及子目录是提交 Git编码标准、架构约定、工具配置全局规则~/.config/opencode/AGENTS.md所有 OpenCode 会话否个人偏好、常用工具习惯Claude Code 兼容CLAUDE.md/~/.claude/CLAUDE.md同项目/全局视位置而定从 Claude Code 平滑迁移搞清楚这套体系之后你就能理解为什么「规则不生效」往往不是 OpenCode 的 bug而是文件放错位置、或者被更高优先级的文件覆盖了。接下来我们先把 TaoToken 的接入配好因为无论规则怎么写模型调用得先跑通。2. TaoToken 前置把模型通道先打通规则写得再漂亮模型调不通也是白搭。OpenCode 支持自定义模型提供商我们可以通过 TaoToken 的 API 来接入 Claude 系列模型。TaoToken 是一个模型 API 聚合服务官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是让你用一个统一的 Key 和 Base URL就能调用包括 Claude 在内的多种模型省去分别对接各家平台的麻烦。先说清楚一个概念避免新手懵OpenCode 本身是个客户端工具它不生产模型只是负责把你的代码上下文和指令打包发给模型再把模型返回的结果展示给你。所以你需要一个「模型通道」TaoToken 就扮演这个角色。你拿到 Key 之后OpenCode 通过 Base URL 把请求发到 TaoTokenTaoToken 再转发给对应的模型。第一步去 TaoToken 控制台创建一个 API Key。打开 https://taotoken.net/api-keys 登录后新建一个 Key复制出来保存好。这个 Key 只显示一次丢了就得重建。注意不要把它硬编码进提交到 Git 的文件里后面我们会用环境变量的方式管理。第二步确认你要用的模型 ID。TaoToken 支持 Claude 系列比如claude-sonnet-4-5、claude-opus-4-1这类。具体可用的模型列表可以在模型对话页面查看https://taotoken.net/models 。选一个适合你日常编码的Sonnet 系列性价比高Opus 系列能力更强但消耗也大。第三步理解 OpenCode 的配置加载顺序。OpenCode 会读全局配置和项目配置项目配置优先级更高。全局配置一般在~/.config/opencode/opencode.json项目配置就是仓库根目录的opencode.json。我们推荐把模型通道配置放在全局把项目规则放在项目里这样切换项目时不用重复配 Key。这里有个关键点TaoToken 的 Base URL 是https://taotoken.net/api注意结尾没有斜杠也不要加/v1之类的后缀OpenCode 会自己拼接路径。如果你加了多余的后缀很可能遇到 404 或者local proxy failed这类报错。如果你同时用 Claude Code那更要注意两边配置的一致性。Claude Code 用的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量而 OpenCode 用的是自己的配置文件。想让两边规则一致除了模型通道要指向同一个 TaoToken规则文件也要做好兼容——这正是后面AGENTS.md和CLAUDE.md要处理的事。关于 Coding Plan如果你打算长期用 OpenCode 做编码和 Agent 任务可以了解一下 https://taotoken.net/coding-plan 它针对高频编码场景做了额度优化比按量计费更划算。不过这是后话先把基础通道跑通。配好 Key 和 Base URL 之后别急着写规则先用一个最小请求验证通道是否正常。下一节我们直接上可复制的配置片段。3. 可复制配置opencode.json 与 AGENTS.md 模板这一节是全文的核心给你可以直接抄的配置。先讲opencode.json再讲AGENTS.md最后讲两者怎么配合。3.1 opencode.json 完整片段全局配置放在~/.config/opencode/opencode.json项目配置放在仓库根目录的opencode.json。下面这份是项目级配置包含了模型通道和规则引用两部分{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/anthropic, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, claude-opus-4-1: { name: Claude Opus 4.1 } } } }, model: taotoken/claude-sonnet-4-5, instructions: [ CONTRIBUTING.md, docs/guidelines.md, .cursor/rules/*.md, packages/*/AGENTS.md ] }逐段解释一下。provider里定义了一个叫taotoken的提供商npm字段指定用ai-sdk/anthropic这个适配器因为 TaoToken 的接口兼容 Anthropic 格式。baseURL就是https://taotoken.net/apiapiKey用{env:TAOTOKEN_API_KEY}从环境变量读取这样 Key 不会进 Git。models里列出你要用的模型 ID名字可以自定义。model字段指定默认用哪个模型格式是提供商/模型ID。instructions是规则文件列表支持 glob 模式比如packages/*/AGENTS.md会匹配所有子包的规则文件。注意这里的路径是相对于项目根目录的。环境变量怎么设在~/.zshrc或~/.bashrc里加一行export TAOTOKEN_API_KEYsk-你的实际Key然后source ~/.zshrc生效。如果你用 Windows在系统环境变量里加同名的即可。3.2 AGENTS.md 模板AGENTS.md是项目规则的主文件放在仓库根目录。下面这份模板可以直接改成你自己的项目# 项目规则 这是一个使用 pnpm 工作区的 TypeScript monorepo 项目。 ## 项目结构 - packages/ - 所有工作区包core, web, functions - infra/ - 基础设施定义 - docs/ - 项目文档 ## 代码标准 - 使用 TypeScript 严格模式 - 共享代码放在 packages/core/通过 my-app/core 导入 - 组件统一放在 src/components/使用函数式组件 - 禁止使用 any必要时用 unknown 加类型守卫 ## 工具约定 - 包管理器用 pnpm禁止用 npm 或 yarn - 提交信息遵循 Conventional Commits - 测试用 vitest放在 __tests__ 目录 ## 外部文件加载 遇到文件引用时按需用 Read 工具加载不要预加载所有引用。 - TypeScript 风格docs/typescript-guidelines.md - React 组件架构docs/react-patterns.md - API 设计规范docs/api-standards.md这份模板的关键在于「简洁 引用」。AGENTS.md本身不要写太长把详细规范拆到docs/下的单独文件用docs/xxx.md引用。OpenCode 遇到这种引用时会按需加载而不是一股脑全塞进上下文。这样既省 token又让规则模块化。3.3 与 Claude Code 保持一致的配置如果你团队里有人用 Claude Code有人用 OpenCode想让规则一致有两个做法。一是保留CLAUDE.md让 OpenCode 通过兼容机制读取二是统一迁移到AGENTS.md然后给 Claude Code 做个软链接指向同一个文件。推荐第二种因为AGENTS.md是 OpenCode 的原生格式优先级最高不会被覆盖。做法很简单ln -s AGENTS.md CLAUDE.md这样两个工具读的是同一份内容改一处两边都生效。如果你不想用软链接也可以在CLAUDE.md里写一行AGENTS.md引用但兼容性不如软链接稳。如果你确实需要禁用 Claude Code 兼容比如避免规则冲突可以设环境变量export OPENCODE_DISABLE_CLAUDE_CODE1这会禁用所有.claude支持。也可以只禁用某一部分比如OPENCODE_DISABLE_CLAUDE_CODE_PROMPT1只禁用~/.claude/CLAUDE.mdOPENCODE_DISABLE_CLAUDE_CODE_SKILLS1只禁用.claude/skills/。配置写完了下一步是验证它到底有没有生效。很多人配完就以为完事了结果规则根本没被加载。下一节教你几个验证方法。4. 验证请求确认规则真的被加载了配置写完不代表生效必须验证。这里给你三个层次的验证方法从通道到规则逐层确认。4.1 验证模型通道先确认 TaoToken 通道能通。在项目目录下运行opencode run 回复 OK 两个字如果返回OK说明模型通道正常。如果报错看错误类型401是 Key 不对检查TAOTOKEN_API_KEY环境变量有没有设对local proxy failed通常是 Base URL 写错了确认是https://taotoken.net/api而不是别的reading choices这类错误一般是响应格式不对可能是模型 ID 写错了。你也可以直接用 curl 测一下通道排除 OpenCode 本身的干扰curl https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }返回里有content字段且内容是OK就说明通道没问题。4.2 验证规则被加载通道通了之后验证规则。最直接的办法是问一个只有规则里才有答案的问题。比如你的AGENTS.md里写了「包管理器用 pnpm」那就问opencode run 这个项目用什么包管理器只回答一个词如果回答pnpm说明规则被读到了。如果回答npm或者「不确定」说明规则没生效。这时候要检查AGENTS.md是不是在项目根目录有没有被CLAUDE.md或CONTEXT.md顶掉opencode.json的instructions路径对不对再测一个更细的比如规则里写了「组件放src/components/」问opencode run 新建一个 Button 组件应该放哪个目录回答里出现src/components就对了。4.3 验证 instructions 引用生效如果你在opencode.json里引用了docs/guidelines.md可以问一个只有那个文件里才有的细节。比如docs/guidelines.md里写了「函数命名用 camelCase」就问opencode run 这个项目的函数命名规范是什么回答camelCase说明引用生效。如果没生效检查路径是不是相对于项目根目录glob 模式有没有写对。4.4 验证 Claude Code 兼容如果你保留了CLAUDE.md并想确认 OpenCode 读到了它可以临时把AGENTS.md改名然后问一个CLAUDE.md里才有的规则。如果回答正确说明兼容机制在工作。测完记得改回来。这里有个小技巧OpenCode 启动时可以用--verbose或类似参数看它加载了哪些文件具体参数看版本。如果能看到加载日志就能直接确认哪个文件被读了比猜要快得多。验证通过之后你可能会遇到一些报错。下一节把常见的坑列出来对照排查。5. 常见报错排查401、local proxy failed、reading choices这一节把 OpenCode 配 TaoToken 时最容易遇到的几个报错拆开讲每个都给出原因和解决办法。5.1 401 Unauthorized报错长这样Error: 401 Unauthorized {type:error,error:{type:authentication_error,message:invalid x-api-key}}原因基本就三个Key 没设、Key 设错、Key 没被读到。先确认环境变量echo $TAOTOKEN_API_KEY如果输出为空说明没设。如果输出的是{env:TAOTOKEN_API_KEY}这种字面量说明opencode.json里的变量语法没被解析检查你的 OpenCode 版本是否支持{env:...}语法或者改成直接读环境变量的方式。如果 Key 设了但还是 401去 TaoToken 控制台确认这个 Key 还有效、额度没用完。有时候 Key 被删了或者过期了也会 401。5.2 local proxy failed报错长这样Error: local proxy failed: connect ECONNREFUSED这个通常是 Base URL 配错了。检查opencode.json里的baseURL是不是https://taotoken.net/api。常见错误包括写成了https://taotoken.net/api/v1多了/v1、写成了http://少了 s、结尾多了斜杠https://taotoken.net/api/。这几个都会导致路径拼接错误。还有一种可能是网络问题但这种情况比较少。先排除配置错误。5.3 reading choices 相关错误报错长这样Error: Cannot read properties of undefined (reading choices)这个错误说明 OpenCode 期望的响应格式和实际返回的对不上。原因通常是模型 ID 写错了或者用了不兼容的适配器。检查opencode.json里models下的模型 ID 是不是 TaoToken 支持的比如claude-sonnet-4-5而不是claude-3-5-sonnet。模型 ID 写错时TaoToken 可能返回一个错误结构OpenCode 解析时就报reading choices。另外确认npm字段是ai-sdk/anthropic用错适配器也会导致格式不匹配。5.4 OAuth 相关报错如果你之前配过 Claude Code 的 OAuth 登录可能会遇到Error: OAuth token expired这是因为 OpenCode 和 Claude Code 的认证方式不同。OpenCode 用 API KeyClaude Code 可能用 OAuth。如果你想让两边共用 TaoToken建议都改成 API Key 方式避免 OAuth 过期问题。在 Claude Code 里设ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL指向 TaoToken 即可。5.5 规则不生效但没报错这种最隐蔽。通道正常模型也回复但规则就是没被遵守。排查顺序先确认AGENTS.md在项目根目录再确认没有同名的CLAUDE.md或CONTEXT.md抢优先级然后确认opencode.json的instructions路径正确最后确认规则内容本身没有语法问题比如docs/xxx.md引用的文件不存在。如果用了 CC Switch 或 Cline MCP 这类工具注意它们可能有自己的配置文件别跟 OpenCode 的配置混在一起。三件套要写全Base URL、Key、Model ID缺一个都可能出问题。排查完这些基本能覆盖 90% 的报错。剩下的就是具体项目结构带来的特殊情况按同样的思路逐层验证即可。6. 把规则用起来接入文档与后续动作规则配好、验证通过之后接下来就是日常使用。这里给你几个实用建议以及需要进一步查资料时的入口。第一规则要定期维护。项目结构变了、技术栈升级了AGENTS.md也要跟着改。建议在 PR 模板里加一条「是否更新了 AGENTS.md」提醒团队。第二模块化拆分。别把所有规则堆在一个文件里用opencode.json的instructions引用多个文件按主题拆分。比如docs/coding-style.md、docs/testing.md、docs/api.md各管一块。第三跨工具一致。如果团队同时用 OpenCode 和 Claude Code用软链接把CLAUDE.md指向AGENTS.md保证两边读同一份规则。这样不会出现「OpenCode 遵守了但 Claude Code 没遵守」的割裂。第四善用远程指令。如果多个项目共享一套规则可以把规则文件放到一个公共仓库用远程 URL 引用{ $schema: https://opencode.ai/config.json, instructions: [ https://raw.githubusercontent.com/my-org/shared-rules/main/style.md ] }注意远程指令有 5 秒超时网络不好时可能加载失败建议关键规则还是放本地。如果你在接入过程中遇到问题或者想查更详细的配置说明可以看接入文档https://taotoken.net/doc 。想直接测试模型效果去模型对话页面https://taotoken.net/models 。需要管理 Key 就去控制台https://taotoken.net/api-keys 。长期做编码和 Agent 任务的话Coding Plan 页面在 https://taotoken.net/coding-plan 。最后说一个我踩过的坑一开始我把AGENTS.md写得很长塞了几百行规则结果模型反而抓不住重点经常忽略关键约定。后来改成「主文件只写核心约定 详细规范拆到子文件按需加载」效果明显好了很多。规则不是越多越好而是越精准越好。把最重要的三五条放在AGENTS.md顶部剩下的用引用让模型在需要时才去读这样既省上下文又提高遵守率。