126、【Agent】【OpenCode】项目配置（composite）：TaoToken 统一 Key 接入 settings.json 骨架

1. OpenCode 在 Monorepo 里到底卡在哪OpenCode 是一个跑在终端里的 Agent 编码工具能读你的仓库、改文件、跑命令适合把重复性的编码任务交给它。它跟普通补全插件最大的区别是它需要理解整个项目的结构尤其是 Monorepo 里多个子包互相引用的关系。如果你只在一个单包里用随便配配就能跑但一旦仓库里有packages/utils、packages/core、packages/app这种结构Agent 在跨包改代码时就会频繁出现「找不到类型」「引用解析失败」「改了 utils 但 app 没感知」的问题。我试过在一个三包 Monorepo 里直接让 OpenCode 改core里的一个导出函数结果它只改了coreapp里调用处没动类型检查直接红一片。根因不是 Agent 笨而是项目配置没告诉它包与包之间的边界在哪。TypeScript 的compositereferences就是专门解决这个问题的机制每个子包有自己的tsconfig.json通过references显式声明依赖编译器就能按包独立做类型检查和增量构建而不是把整个仓库的源码全塞进一个编译上下文。这篇要解决的就是在 OpenCode 的 Agent 场景下怎么把composite项目配置搭起来同时把模型请求统一走 TaoToken 的 Key 通道让 Agent 的每一次调用都可控、可查、可切换模型。适合已经在用 Monorepo、想让 Agent 真正参与多包协作的开发者。下面从配置骨架到验证动作一步步来命令和 JSON 都能直接复制。2. 先把 TaoToken 的 Key 和通道准备好OpenCode 本身不绑定某一家模型服务它通过配置里的 provider 决定请求发到哪里。我们要做的是让 OpenCode 的所有 Agent 请求都经过 TaoToken 的统一通道这样你只需要维护一个 Key换模型、看用量、排查请求都在一个地方。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后在控制台左侧找到 API Keys 入口新建一个 Key。建议按项目命名比如opencode-monorepo方便以后区分是哪个仓库在用。第二步记下两个地址。API 基地址是https://taotoken.net/api这个不带任何查询参数直接填进配置。模型对话页面在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 你可以在这里先确认要用的模型名称比如claude-sonnet-4-20250514这类标识配置里要写对。第三步如果你打算长期在 OpenCode 里跑 Agent 任务建议看一下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对的就是这种持续编码场景比按次调用更划算。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到字段不确定时以文档为准。注意Key 只存在本地配置文件或环境变量里不要提交到 Git。下面配置里我用sk-xxxx占位你替换成自己的。3. 可复制的 settings.json 与 tsconfig 骨架OpenCode 的配置分两块一块是 Agent 的模型通道配置一块是 Monorepo 的 TypeScript 项目配置。先看 OpenCode 侧的settings.json骨架。这个文件一般放在用户配置目录比如~/.config/opencode/settings.json具体路径以你系统为准。{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: sk-xxxx, models: { claude-sonnet-4-20250514: { name: claude-sonnet-4-20250514 } } } }, agent: { defaultModel: taotoken/claude-sonnet-4-20250514, workspaceRoot: ., respectTsconfig: true } }这里type用openai-compatible是因为 TaoToken 的 API 通道兼容这套协议baseURL填https://taotoken.net/api不要多加斜杠或路径。agent.respectTsconfig打开后OpenCode 在做类型相关操作时会参考仓库里的tsconfig.json这对 Monorepo 很关键。接着是 Monorepo 的 TypeScript 配置。假设目录结构是repo/ tsconfig.json packages/ utils/ tsconfig.json src/index.ts core/ tsconfig.json src/index.ts app/ tsconfig.json src/index.ts根目录tsconfig.json只做引用聚合不编译任何文件{ files: [], references: [ { path: ./packages/utils }, { path: ./packages/core }, { path: ./packages/app } ] }packages/utils/tsconfig.json作为被依赖方必须开composite{ compilerOptions: { composite: true, declaration: true, rootDir: src, outDir: dist, strict: true }, include: [src] }packages/core/tsconfig.json依赖 utils通过references声明{ compilerOptions: { composite: true, declaration: true, rootDir: src, outDir: dist, strict: true }, references: [ { path: ../utils } ], include: [src] }packages/app/tsconfig.json依赖 core{ compilerOptions: { composite: true, declaration: true, rootDir: src, outDir: dist, strict: true }, references: [ { path: ../core } ], include: [src] }composite: true会强制生成.d.ts和.tsbuildinfo前者让下游包能消费类型后者是增量构建的基础。rootDir约束所有源文件都在include范围内避免产物结构漂移导致下游缓存失效。references.path用的是磁盘相对路径不是包名这点和package.json的workspaces不一样workspaces管的是依赖安装和运行时模块解析references管的是类型检查和编译构建两者互补Monorepo 里通常都要有。4. 启动 OpenCode 验证请求与引用解析配置写完后先验证 TypeScript 侧的项目引用是否生效。在仓库根目录执行npx tsc --build --verbose如果配置正确你会看到 tsc 按拓扑顺序依次编译 utils、core、app并且第二次执行时因为.tsbuildinfo存在只会重编改动过的包。改一行packages/utils/src/index.ts再跑一次输出里应该只有 utils 和依赖它的 core、app 被重编而不是全量。接着验证 OpenCode 的请求是否走了 TaoToken 通道。启动 OpenCodeopencode进入交互后让它做一个跨包操作比如「在 core 里新增一个函数并在 app 里调用它」。观察终端输出如果配置生效Agent 的模型请求会发往https://taotoken.net/api。你也可以在 TaoToken 控制台的用量页面看到这次请求记录模型名、时间、token 数都能对上。再验证引用解析让 OpenCode 在app里引用core导出的类型保存后跑npx tsc --build如果没有报「Cannot find module」或「has no exported member」说明references和composite的链路是通的。实测下来这一步能过Agent 后续跨包改代码的准确率会明显提升因为它拿到的类型信息是完整的。如果你更想先单独确认模型通道没问题可以打开模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条测试消息确认 Key 和模型名可用再回到 OpenCode 里跑 Agent 任务。5. 本篇常见错排查报错一Referenced project must have setting composite: true这是最常见的。原因是被references指向的子包没开composite。检查packages/utils/tsconfig.json里compilerOptions.composite是否为true。注意composite会隐式开启declaration但显式写上更清晰。报错二File is not under rootDir说明某个源文件不在include范围内或者rootDir设得比实际源码目录小。比如源码在src/rootDir却写成了src/core就会报这个。把rootDir对齐到include的根即可。报错三OpenCode 请求 401 或 404先确认baseURL是https://taotoken.net/api没有多余路径。再确认apiKey是完整的sk-开头字符串没有多余空格。如果 404多半是模型名写错了去模型对话页面核对准确的模型标识。如果 401去 API Keys 页面确认 Key 没被删除或过期。报错四改了 utils 但 app 没重新检查先跑npx tsc --build --force强制全量一次确认不是.tsbuildinfo状态错乱。如果强制后正常说明增量缓存有问题删掉各包的dist和.tsbuildinfo再重建。另外确认 OpenCode 的respectTsconfig是打开的否则它可能不读你的项目引用配置。报错五tsgo --noEmit和tsc --build结果不一致OpenCode 用 Bun 直接跑.ts源码类型检查走的是更快的tsgo --noEmit它不一定完整支持--build增量模式。所以composite和references主要是给tsc --build和 IDE 用的OpenCode 运行时靠 Bun 的原生 TS 执行和package.json的exports解析模块。两者不冲突但排查时要分清是编译期问题还是运行期问题。6. 把 Key 和项目配置固定下来到这里OpenCode 的 Agent 请求已经统一走 TaoToken 通道Monorepo 的composite项目引用也搭好了。日常使用中你只需要维护一个 Key换模型时改settings.json里的defaultModel即可不用动项目代码。如果后续要加新的子包记得三件事新包tsconfig.json开composite在依赖它的包的references里加路径在根tsconfig.json的references里也加一条。漏掉任何一步tsc --build的拓扑排序就会断。长期在 OpenCode 里跑 Agent 任务的话建议把 Coding Plan 用起来地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配合接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 把字段对齐。Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要轮换或按项目拆分时在这里操作。控制台总入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 用量和请求记录都在里面。最后留一个实用习惯每次改完tsconfig的references先跑一次npx tsc --build --verbose看拓扑顺序对不对再启动 OpenCode。这一步花十秒能省掉后面半小时的「为什么 Agent 改不动跨包代码」的排查。