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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_CODE1 # 仅禁用全局 CLAUDE.md export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT1 # 仅禁用 skills 目录 export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS1优先级逻辑是从当前目录向上找最先找到的本地文件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_PROXY5.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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册一个然后在 API Keys 页面创建。接入文档在 https://taotoken.net/doc 可以查到最新的模型列表和参数说明。想先试试模型对话效果的话https://taotoken.net/chat 可以直接体验。如果你打算长期在 OpenCode 里用 AI 辅助编码Coding Plan 页面https://taotoken.net/coding-plan有更详细的套餐说明。最后说一个实际经验AGENTS.md 里最值得写的不是“用什么框架”这种一眼能看出来的信息而是那些“不看代码就不知道”的约定。比如“这个目录下的文件不要手动改是自动生成的”“这个函数虽然叫 delete 但实际上是软删除”“测试环境的数据不要清空”。这些才是模型最容易踩坑的地方也是你写指令时最该优先覆盖的内容。