企业官网建设流程全解析

1. 为什么你的 AI 编程助手总在“猜”项目规矩

你有没有遇到过这种场景：让 AI 帮你改一个函数，它写出来的代码风格跟项目里其他文件完全不一样；或者它把新文件放到了错误的目录，你不得不手动挪回去；再或者它用了一个项目里早就废弃的依赖，跑起来直接报错。这些问题的根源不在于模型不够聪明，而在于它不知道你这个项目的“脾气”。

OpenCode 这套工具解决的就是这个问题。它本身是一个开源的 AI 编程助手框架，可以在终端里跟各种大语言模型对话、让它读写代码、执行命令。但真正让它在实际项目里好用的，是它的一套自定义指令体系——核心就是 AGENTS.md 和 CLAUDE.md 这两个文件。你可以把它们理解成给 AI 看的“项目说明书”：哪里放什么代码、用什么构建命令、有哪些坑不能踩，全部写清楚，模型每次会话开始前都会自动读一遍。

这篇文章面向的是已经在用或者准备用 OpenCode 的开发者，尤其是那些觉得“AI 写代码总差点意思”的人。我会从零开始讲清楚 AGENTS.md 的写法、CLAUDE.md 的兼容逻辑、怎么通过 opencode.json 引入外部规则文件，以及最关键的——怎么把 TaoToken 的统一 API 通道接进来，让 OpenCode 能稳定调用模型。整套流程都是可复制的，你跟着做就能在自己的项目里跑通。

先说结论：OpenCode 的指令体系分三层——项目级、全局级、外部引用级。项目级管团队共识，全局级管个人偏好，外部引用级管跨仓库复用。三层叠加，模型就能从“通用聪明”变成“懂你这个项目”。

2. TaoToken 接入前置：统一 Key 与 API 通道准备

在讲指令配置之前，得先把模型通道打通。OpenCode 本身不绑定任何模型提供商，它通过 OpenAI 兼容的 API 接口来调用模型。TaoToken 提供的就是这样一个统一通道：你拿一个 Key，就能调用多个主流模型，不用在每个提供商那里分别注册、分别充值、分别管理额度。

2.1 获取 API Key

打开 TaoToken 官网（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=），注册登录后进入控制台，在 API Keys 页面创建一个新的 Key。建议给这个 Key 起一个能识别用途的名字，比如opencode-dev，方便后续排查问题时定位。

创建完成后你会看到一串以sk-开头的字符串，这就是你的 API Key。复制下来，后面配置 OpenCode 时要用。注意：这个 Key 只在创建时完整显示一次，关掉页面就看不到了，所以务必先存到安全的地方。

2.2 确认 Base URL 和可用模型

TaoToken 的 API 端点地址是https://taotoken.net/api，这是 OpenAI 兼容格式的接口。你可以在控制台的模型列表页面看到当前支持的模型 ID，常见的比如gpt-4o、claude-sonnet-4-20250514、deepseek-chat等。记下你打算用的模型 ID，后面写配置文件时要填进去。

如果你不确定该选哪个模型，可以先用gpt-4o或claude-sonnet-4-20250514这类通用能力较强的模型来测试指令体系是否生效。等流程跑通后再根据实际需求切换。

2.3 OpenCode 的安装确认

确保你本地已经装了 OpenCode。如果还没装，可以通过 npm 全局安装：

npm install -g opencode-ai

安装完成后在终端执行opencode --version，能看到版本号就说明装好了。接下来我们要在项目里配置模型通道和指令文件。

3. 可复制配置：AGENTS.md 模板与 opencode.json 接入片段

这一节是整篇文章的核心操作部分。我会给出完整的 AGENTS.md 模板、opencode.json 的配置片段，以及 CLAUDE.md 的兼容写法。你直接复制到项目里改改就能用。

3.1 AGENTS.md 项目指令模板

在项目根目录创建AGENTS.md文件。这个文件的内容会被 OpenCode 在每次会话开始时自动加载，作为模型的系统级指令。下面是一个针对 TypeScript monorepo 项目的模板，你可以根据自己项目的实际情况调整：

# 项目指令 ## 项目概述 这是一个基于 TypeScript 的 monorepo 项目，使用 bun 作为包管理器。 主要包含三个部分：`packages/` 存放共享库，`apps/` 存放可执行应用，`infra/` 存放基础设施定义。 ## 构建与测试命令 - 安装依赖：`bun install` - 构建全部：`bun run build` - 运行测试：`bun test` - 类型检查：`bun run typecheck` - 代码格式化：`bun run format` 执行顺序很重要：先 `bun install`，再 `bun run build`，最后才能跑测试。 如果类型检查失败，不要继续执行构建命令，先修复类型错误。 ## 代码规范 - 所有 TypeScript 文件必须开启 strict 模式 - 禁止使用 `any` 类型，必要时用 `unknown` 加类型守卫 - 共享代码放在 `packages/core/` 下，通过 workspace 名称导入，例如 `@my-app/core/utils` - 每个导出函数必须有 JSDoc 注释，说明参数和返回值 - 使用 2 空格缩进，字符串统一用单引号 ## 目录结构约定 - `packages/core/` — 核心工具函数和类型定义 - `packages/ui/` — 共享 UI 组件 - `apps/web/` — Web 应用入口 - `apps/api/` — API 服务入口 - `infra/` — 基础设施代码，按服务拆分文件 新增文件时，先判断它属于哪个包，不要直接在根目录创建源文件。 ## 已知的坑 - `packages/core` 的构建产物在 `dist/` 目录，修改源码后必须重新构建才能被其他包引用 - 环境变量通过 `.env.local` 加载，不要硬编码任何密钥 - 数据库迁移文件一旦提交就不要修改，新增迁移请创建新文件 ## 外部规则引用 TypeScript 代码风格详见 `docs/typescript-guidelines.md`。 API 设计规范详见 `docs/api-conventions.md`。

这个模板的关键在于：它不只是告诉模型“做什么”，还告诉它“按什么顺序做”以及“什么情况下不要做”。比如“类型检查失败时不要继续构建”这一条，能避免模型在错误的基础上继续生成代码。

3.2 opencode.json 引入外部规则文件

如果你的团队已经有现成的规范文档，比如CONTRIBUTING.md或者.cursor/rules/下的文件，不需要把内容复制到 AGENTS.md 里。直接在opencode.json中声明即可：

{ "$schema": "https://opencode.ai/config.json", "instructions": [ "CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md", "packages/*/AGENTS.md" ] }

路径支持 glob 模式，packages/*/AGENTS.md会自动匹配每个子包下的指令文件。这对于 monorepo 特别有用——每个子包可以有自己的 AGENTS.md，描述该包特有的约定，而根目录的 opencode.json 负责把它们全部聚合起来。

同样也支持远程 URL：

{ "$schema": "https://opencode.ai/config.json", "instructions": [ "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md" ] }

远程文件拉取有 5 秒超时限制，不会阻塞 OpenCode 启动。所有通过instructions声明的文件，最终都会和 AGENTS.md 的内容合并后一起喂给模型。

3.3 CLAUDE.md 兼容配置

如果你之前用的是 Claude Code，项目里已经有CLAUDE.md文件，OpenCode 会自动读取它作为后备。全局层面的后备路径是~/.claude/CLAUDE.md，技能文件目录是~/.claude/skills/。

如果团队不希望混用两套规则，可以用环境变量精确控制：

# 禁用所有 .claude 支持 export OPENCODE_DISABLE_CLAUDE_CODE=1 # 仅禁用全局 CLAUDE.md export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # 仅禁用 skills 目录 export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1

优先级逻辑是：从当前目录向上找，最先找到的本地文件（AGENTS.md 或 CLAUDE.md）生效；全局层面~/.config/opencode/AGENTS.md优先于~/.claude/CLAUDE.md。简单说就是“近的盖远的，专用的盖通用的”。

3.4 在 AGENTS.md 里教模型按需加载引用

OpenCode 不会自动解析 AGENTS.md 里类似@docs/typescript-guidelines.md的引用。但你可以通过显式指令让模型自己去读：

## 文件引用规则 当你遇到以 @ 开头的文件引用时（例如 @rules/general.md）， 使用 Read 工具按需加载，不要预先加载所有引用。 加载后的内容视为强制指令，覆盖默认行为。 需要时递归跟随引用。 ## 开发规范 TypeScript 代码风格参见：@docs/typescript-guidelines.md

这种“懒加载”方式让 AGENTS.md 保持精简，详细规范独立维护，甚至可以跨项目共享。

4. 验证指令生效与请求链路

配置写好了，怎么确认模型真的读到了这些指令？怎么确认请求确实走了 TaoToken 的通道？这一节给出具体的验证步骤。

4.1 验证模型通道连通性

先用一个最简单的 curl 请求确认 TaoToken 的 API 能通：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "回复OK两个字母"}], "max_tokens": 10 }'

如果返回的 JSON 里choices[0].message.content包含 “OK”，说明 Key 和通道都没问题。如果返回 401，说明 Key 不对或者没带上；如果返回 404，检查 URL 是不是写成了https://taotoken.net/api后面多加了/v1导致路径重复。

4.2 在 OpenCode 中验证指令加载

启动 OpenCode 后，先执行一个简单的指令测试。比如在对话里输入：

请告诉我这个项目的构建命令是什么，以及执行顺序。

如果 AGENTS.md 生效了，模型应该能准确说出bun install→bun run build→bun test这个顺序，而不是泛泛地回答“通常用 npm run build”。如果模型答不出来，检查 AGENTS.md 是否在项目根目录、文件名大小写是否正确（必须是全大写AGENTS.md）。

4.3 验证请求确实走了 TaoToken

在 OpenCode 的配置文件中，模型提供商的配置通常写在~/.config/opencode/config.json或项目级的opencode.json里。一个典型的 TaoToken 接入配置如下：

{ "$schema": "https://opencode.ai/config.json", "provider": { "taotoken": { "npm": "@ai-sdk/openai-compatible", "name": "TaoToken", "options": { "baseURL": "https://taotoken.net/api", "apiKey": "sk-你的Key" }, "models": { "gpt-4o": { "name": "GPT-4o via TaoToken" }, "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4 via TaoToken" } } } }, "model": "taotoken/gpt-4o" }

配置完成后，在 OpenCode 里发一条消息，然后去 TaoToken 控制台的用量页面查看请求记录。如果能看到对应的请求条目，说明链路已经通了。这一步很关键——很多人配置完了以为通了，实际上请求打到了别的地方。

4.4 验证指令优先级

如果你同时有项目级 AGENTS.md 和全局~/.config/opencode/AGENTS.md，可以做一个简单的冲突测试：在项目级文件里写“使用单引号”，在全局文件里写“使用双引号”。然后让模型生成一段代码，看它用哪种引号。如果用了单引号，说明项目级覆盖了全局级，优先级逻辑正确。

5. 本篇常见错误排查

这一节整理几个实际配置过程中最容易踩的坑，每个都给出报错原文和解决方法。

5.1 401 Unauthorized

报错原文：

Error: 401 Unauthorized {"error":{"message":"Invalid API key provided","type":"invalid_request_error"}}

原因通常是 Key 复制不完整、Key 被删除、或者配置文件里apiKey字段名写错了。检查opencode.json里options.apiKey的值是否以sk-开头且没有多余空格。如果用的是环境变量引用，确认环境变量名拼写正确。

5.2 local proxy failed / connection refused

报错原文：

Error: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused

这个报错说明 OpenCode 尝试走本地代理端口但失败了。检查你的终端环境变量里是否有HTTP_PROXY或HTTPS_PROXY指向了一个没有运行的本地端口。如果有，取消这些环境变量再试：

unset HTTP_PROXY unset HTTPS_PROXY

5.3 reading choices: unexpected end of JSON input

报错原文：

Error: reading choices: unexpected end of JSON input

这通常意味着 API 返回了空响应或者非 JSON 格式的内容。可能的原因：Base URL 写错了导致请求打到了错误的端点；或者模型 ID 不存在。检查baseURL是否为https://taotoken.net/api，以及model字段里的模型 ID 是否在 TaoToken 控制台的模型列表中。

5.4 OAuth 相关报错

报错原文：

Error: OAuth token expired, please re-authenticate

如果你之前用 OAuth 方式登录过其他提供商，OpenCode 可能还在尝试用旧的认证方式。检查~/.config/opencode/下是否有残留的认证文件，清理后重新用 API Key 方式配置。

5.5 AGENTS.md 不生效

如果模型完全没有读取到 AGENTS.md 的内容，按以下顺序排查：文件是否在项目根目录；文件名是否为全大写AGENTS.md；文件是否有读取权限；opencode.json里是否意外设置了OPENCODE_DISABLE_CLAUDE_CODE之类的环境变量导致规则被禁用。另外，如果你在 monorepo 的子目录里启动 OpenCode，它会从当前目录向上找最近的 AGENTS.md，确认你启动的目录层级是否正确。

6. 把规则沉淀成团队资产：TaoToken 与 OpenCode 的长期配合

配置跑通之后，真正有价值的事情是持续维护这套指令体系。AGENTS.md 不是写一次就完事的文件，它应该跟代码一起演进。每次发现模型犯了一个重复的错误，就把对应的规则补进去；每次项目结构调整，就更新目录说明。时间长了，这份文件就成了团队里“AI 能读懂的那部分共识”。

TaoToken 在这个流程里的角色是提供稳定的模型通道。你不需要在 OpenCode 里配置多个提供商的 Key，一个 TaoToken Key 就能切换不同模型。比如日常编码用gpt-4o，遇到复杂重构切到claude-sonnet-4-20250514，只需要改opencode.json里的model字段，不用动其他配置。

如果你还没有 TaoToken 的 Key，可以去官网（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=）注册一个，然后在 API Keys 页面创建。接入文档在 https://taotoken.net/doc 可以查到最新的模型列表和参数说明。想先试试模型对话效果的话，https://taotoken.net/chat 可以直接体验。如果你打算长期在 OpenCode 里用 AI 辅助编码，Coding Plan 页面（https://taotoken.net/coding-plan）有更详细的套餐说明。

最后说一个实际经验：AGENTS.md 里最值得写的不是“用什么框架”这种一眼能看出来的信息，而是那些“不看代码就不知道”的约定。比如“这个目录下的文件不要手动改，是自动生成的”“这个函数虽然叫 delete 但实际上是软删除”“测试环境的数据不要清空”。这些才是模型最容易踩坑的地方，也是你写指令时最该优先覆盖的内容。