企业官网建设流程全解析

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简洁。

下面这张表把三种规则类型的关键差异列清楚，你可以对照自己的项目看看该用哪种：

搞清楚这套体系之后，你就能理解为什么「规则不生效」往往不是 OpenCode 的 bug，而是文件放错位置、或者被更高优先级的文件覆盖了。接下来我们先把 TaoToken 的接入配好，因为无论规则怎么写，模型调用得先跑通。

2. TaoToken 前置：把模型通道先打通

规则写得再漂亮，模型调不通也是白搭。OpenCode 支持自定义模型提供商，我们可以通过 TaoToken 的 API 来接入 Claude 系列模型。TaoToken 是一个模型 API 聚合服务，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。它的作用是让你用一个统一的 Key 和 Base URL，就能调用包括 Claude 在内的多种模型，省去分别对接各家平台的麻烦。

先说清楚一个概念，避免新手懵：OpenCode 本身是个客户端工具，它不生产模型，只是负责把你的代码上下文和指令打包发给模型，再把模型返回的结果展示给你。所以你需要一个「模型通道」，TaoToken 就扮演这个角色。你拿到 Key 之后，OpenCode 通过 Base URL 把请求发到 TaoToken，TaoToken 再转发给对应的模型。

第一步，去 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/api，apiKey用{env:TAOTOKEN_API_KEY}从环境变量读取，这样 Key 不会进 Git。models里列出你要用的模型 ID，名字可以自定义。

model字段指定默认用哪个模型，格式是提供商/模型ID。instructions是规则文件列表，支持 glob 模式，比如packages/*/AGENTS.md会匹配所有子包的规则文件。注意这里的路径是相对于项目根目录的。

环境变量怎么设？在~/.zshrc或~/.bashrc里加一行：

export TAOTOKEN_API_KEY="sk-你的实际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_CODE=1

这会禁用所有.claude支持。也可以只禁用某一部分，比如OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1只禁用~/.claude/CLAUDE.md，OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1只禁用.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 Key，Claude 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顶部，剩下的用引用，让模型在需要时才去读，这样既省上下文又提高遵守率。