1. 子包版本漂移Monorepo 里 OpenCode Agent 配置最容易踩的坑在单仓多包的项目里做 OpenCode Agent 配置最先暴露出来的问题往往不是模型能力而是子包版本漂移。同一个仓库里packages/agent-core、packages/agent-tools、apps/agent-web各自维护一份package.json每份里都有version字段也各自可能带一份.opencode配置。只要有人手动改了一个子包的版本号或者某个子包单独升级了依赖Agent 在加载配置时就会读到不一致的约定表现为工具注册失败、模型 ID 找不到、甚至直接报reading choices这类看起来和配置无关的错误。我先把场景说清楚。假设你有一个典型的 Monorepomy-monorepo/ ├── package.json ├── pnpm-workspace.yaml ├── opencode.json ├── packages/ │ ├── agent-core/ │ │ ├── package.json │ │ └── .opencode/ │ │ └── config.json │ ├── agent-tools/ │ │ ├── package.json │ │ └── .opencode/ │ │ └── config.json │ └── agent-shared/ │ ├── package.json │ └── .opencode/ │ └── config.json └── apps/ └── agent-web/ ├── package.json └── .opencode/ └── config.json每个子包都有自己的package.json其中version严格代表该子包自身的语义化版本。根目录的version通常代表整个 Monorepo 脚手架或开发环境的版本业务代码一般不依赖它。OpenCode 这类 Agent 工具在启动时会从当前工作目录向上查找配置文件如果子包目录里存在.opencode/config.json它会优先加载子包级配置再合并根级约定。这个「就近优先」的规则本身没问题问题出在版本号不统一时合并逻辑会以哪个为准。我实测下来最稳妥的做法是让所有子包的version保持一致也就是锁定版本模式。这不是 Monorepo 的强制规定而是一种主动选择的版本管理策略。内部包强耦合时比如my-org/agent-core和my-org/agent-tools属于同一套 Agent 运行时它们必须同时发布、同时升级。如果版本不一致使用者就会困惑装了 2.0 的 core能不能匹配 1.5 的 toolsAgent 配置里引用的工具 schema 一旦对不上运行时就可能静默失败。你可以用一条命令快速检查所有子包的版本号是否统一find . -name package.json -not -path */node_modules/* -not -path */dist/* -exec grep -H version {} \;输出里如果出现1.2.27、1.2.28、1.3.0混在一起就说明已经漂移了。这时候不要急着改先确认是锁定版本还是独立版本模式。像 Babel、Next.js 这种大型开源项目子包版本是完全独立的my-org/utils可能一年才更新一次而my-org/web-app每天都在迭代强行锁版本会导致 utils 产生大量无意义的版本跳跃。但内部 Agent 配置这种强耦合场景锁定版本更省心。还有一个关键认知Git 里的版本 ≠ npm 上的版本。你在仓库里看到的package.json中的version往往只是一个基准版本或占位符。现代 Monorepo 发布工具Changesets、Nx Release的流程是开发者日常提交代码不修改version字段有变更时创建一个 changeset 文件描述改了什么执行发布命令时工具读取所有 changesets自动计算要发布的包应该 bump 到什么版本工具在临时目录中修改package.json的版本号打包、发布到 npm、打 Tag而 Git 主分支上的版本号可以保持不变。所以代码库里看到的永远是整齐统一的版本号npm 上的实际版本可能是按需递增的。这个机制对 OpenCode Agent 配置的影响在于如果你在配置里硬编码了某个子包的版本号比如agent-core: 1.2.27那么发布后实际安装的可能是1.2.28配置和运行时就会对不上。正确做法是让配置引用工作区协议比如workspace:*由包管理器在安装时解析成实际版本。2. TaoToken 前置给 OpenCode Agent 准备可用的模型接入点在拆解子包配置之前得先有一个能跑通的模型接入点。OpenCode 本身是 Agent 框架它需要调用大模型来完成推理和工具编排。我这边用的是 TaoToken 提供的兼容接口它支持 OpenAI 风格的/v1/chat/completions也能对接 Anthropic 风格的调用适合在 Monorepo 里作为统一的模型网关。先拿 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台里创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建时建议给 Key 起一个能区分环境的名称比如monorepo-dev、monorepo-ci这样后面排查哪个子包在调用时能快速定位。拿到 Key 之后API 基地址是https://taotoken.net/api注意这个地址不带 UTM 参数是纯 API 端点。模型 ID 需要根据你实际开通的模型来填常见的有gpt-4o、claude-3-5-sonnet这类。如果你不确定有哪些可用模型可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 先手动试一次确认模型能正常返回再写进配置。这里要强调一个安全边界TaoToken 是合规的 API 接入服务不要把它和任何非法中转混为一谈。我们在 Monorepo 里使用它只是把它当作一个统一的模型调用入口所有请求都走标准 HTTPSKey 通过环境变量注入不写进代码仓库。对于长期做 Agent 开发的团队可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要持续调用模型、跑 Agent 编排的场景比按次调用更可控。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明和示例。在 Monorepo 里我建议把模型接入信息放在根级配置子包通过继承或环境变量覆盖的方式使用。这样做的原因是模型 Key 和 Base URL 属于基础设施不应该每个子包都维护一份。子包级配置只关心自己需要的模型 ID、温度、工具白名单这些业务参数。具体来说根目录放一个.env文件不提交到 Git里面写TAOTOKEN_API_KEYsk-xxxxxxxxxxxxxxxx TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o然后在根级opencode.json里引用这些环境变量。子包的.opencode/config.json只覆盖自己需要的字段。这样版本漂移的风险就集中在子包的业务参数上基础设施部分不会因为某个子包改了版本而失效。如果你用的是 Claude Code 这类工具接入方式类似Base URL 填https://taotoken.net/apiKey 填上面创建的 KeyModel ID 填你开通的模型。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 里面有专门的配置说明。3. 可复制配置根级约定与子包覆盖的完整片段这一节给出可以直接复制的配置。先看根目录的opencode.json它定义全局约定{ $schema: https://opencode.ai/schema/config.json, version: 1.0.0, model: { provider: openai-compatible, baseURL: ${TAOTOKEN_BASE_URL}, apiKey: ${TAOTOKEN_API_KEY}, model: ${TAOTOKEN_MODEL}, temperature: 0.2 }, tools: { allow: [read, write, bash, grep], deny: [rm, curl] }, workspace: { packages: [packages/*, apps/*] } }这里的${TAOTOKEN_BASE_URL}等变量从环境变量读取不会把 Key 写死在仓库里。tools.allow和tools.deny是根级安全约定子包可以在此基础上追加但不能放开被根级 deny 的工具。再看pnpm-workspace.yaml它定义了工作区范围packages: - packages/* - apps/*然后是子包packages/agent-core/package.json注意version字段{ name: my-org/agent-core, version: 1.2.27, private: true, main: dist/index.js, dependencies: { my-org/agent-shared: workspace:* } }workspace:*是关键它让包管理器在安装时解析成工作区内的实际版本而不是去 npm 上找。这样即使发布后 npm 上的版本是1.2.28工作区内引用依然指向本地代码不会出现版本对不上的情况。子包级.opencode/config.json只覆盖自己需要的部分{ extends: ../../opencode.json, model: { temperature: 0.1 }, tools: { allow: [read, write, grep] }, agent: { name: agent-core, systemPrompt: You are the core agent for package resolution. } }extends指向根级配置表示继承根级的所有约定然后只覆盖temperature和tools.allow。注意子包的tools.allow是[read, write, grep]没有bash这是子包自己的选择根级的deny依然生效。再看packages/agent-tools/.opencode/config.json{ extends: ../../opencode.json, model: { temperature: 0.3 }, tools: { allow: [read, bash, grep] }, agent: { name: agent-tools, systemPrompt: You are the tools agent. Execute shell commands carefully. } }这个子包允许bash因为它的职责就是执行工具命令。但根级deny里的rm和curl依然被禁止所以即使子包允许bash也不能执行rm和curl。这就是根级约定和子包覆盖的边界。对于apps/agent-web它可能是一个前端应用配置更简单{ extends: ../../opencode.json, model: { temperature: 0.5 }, tools: { allow: [read] }, agent: { name: agent-web, systemPrompt: You are a frontend assistant. Only read files. } }如果你用的是 Cline MCP 或者 Codex 的auth.json配置方式略有不同。Cline MCP 需要在settings.json里配置 MCP serverCodex 的auth.json则放在~/.codex/auth.json。无论哪种三件套都是Base URL、Key、Model ID。Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 填开通的模型。这三者缺一不可少一个就会报 401 或模型找不到。还有一个细节子包的package.json里可以加一个opencode字段声明自己的配置路径{ name: my-org/agent-core, version: 1.2.27, opencode: { config: .opencode/config.json } }这样 OpenCode 在加载时能明确知道去哪个文件读配置而不是靠默认查找。对于子包较多的 Monorepo这个字段能减少歧义。4. 验证请求逐包加载与成功结果确认配置写完之后必须逐包验证。不要一次性启动整个 Monorepo那样出错时很难定位是哪个子包的配置有问题。我的做法是进入每个子包目录单独跑一次 OpenCode 的加载命令。先验证根级配置能否被正确解析cd my-monorepo opencode config validate如果根级配置有问题这条命令会直接报错比如Invalid schema: model.baseURL is required。确认根级没问题后进入子包cd packages/agent-core opencode config validate预期输出是Loaded config from: /my-monorepo/packages/agent-core/.opencode/config.json Extended from: /my-monorepo/opencode.json Agent name: agent-core Model: gpt-4o (temperature: 0.1) Tools allowed: read, write, grep Tools denied: rm, curl这里能看到Extended from指向根级配置说明继承生效了。Tools allowed是子包自己的read, write, grepTools denied是根级的rm, curl。两者合并后实际可用的工具是read, write, grepbash被排除rm和curl被禁止。接着发一个真实的请求确认模型能通opencode run --agent agent-core List the files in the current directory and summarize what this package does.如果配置正确你会看到 Agent 调用read和grep工具读取package.json和源码文件然后返回一段总结。返回内容里应该包含my-org/agent-core这个包名说明它读到了正确的文件。再验证agent-tools子包cd ../agent-tools opencode run --agent agent-tools Run a safe shell command to print the current working directory.预期 Agent 会调用bash执行pwd返回当前路径。注意它不能执行rm或curl如果你尝试让它执行curl https://example.com应该被拒绝并提示Tool curl is denied by root config。对于apps/agent-webcd ../../apps/agent-web opencode run --agent agent-web Read the package.json and tell me the package name.预期只调用read返回包名。如果它尝试调用bash应该被拒绝因为子包只允许read。验证过程中我建议打开详细日志opencode run --agent agent-core --log-level debug test日志里会打印配置加载顺序、合并结果、模型请求的 Base URL 和 Model ID。确认 Base URL 是https://taotoken.net/apiModel ID 是你开通的模型。如果 Base URL 显示为空或undefined说明环境变量没注入检查.env是否被正确加载。还有一个验证点是版本一致性。在根目录跑find . -name package.json -not -path */node_modules/* -not -path */dist/* -exec grep -H version {} \;确认所有子包的version都是1.2.27。如果有不一致先统一版本号再重新验证配置。因为 OpenCode 在合并配置时可能会根据版本号判断兼容性版本不一致时合并结果可能不符合预期。成功的结果是每个子包都能独立加载配置继承根级约定覆盖自己的业务参数模型请求正常返回工具权限符合预期。这时候再跑整个 Monorepo 的集成测试就不会出现配置层面的意外。5. 常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给出排查路径。这些错误我在不同项目里都遇到过原因往往不在 OpenCode 本身而在配置的某个环节。401 Unauthorized报错长这样Error: Request failed with status code 401 {error:{message:Invalid API key,type:invalid_request_error}}原因通常是 Key 没注入或注入错了。检查步骤第一确认.env文件在根目录且被 OpenCode 加载。可以在opencode.json里显式指定envFile{ envFile: .env }第二确认环境变量名和配置里的占位符一致。配置里写的是${TAOTOKEN_API_KEY}.env里就必须是TAOTOKEN_API_KEYsk-xxx大小写不能错。第三确认 Key 没有多余空格或换行。可以用echo $TAOTOKEN_API_KEY检查如果输出为空说明没加载。如果 Key 确认没问题还是 401检查 Base URL 是否写成了https://taotoken.net/api/末尾多了斜杠。有些 HTTP 客户端会把//v1/chat/completions拼成错误路径。正确写法是https://taotoken.net/api不带末尾斜杠。local proxy failed报错长这样Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:7890这个错误说明 OpenCode 尝试走本地代理但代理没启动。检查环境变量里是否有HTTP_PROXY或HTTPS_PROXY指向127.0.0.1:7890。如果有且你不需要代理直接 unsetunset HTTP_PROXY unset HTTPS_PROXY然后重新跑。如果确实需要代理确认代理服务在运行端口正确。注意TaoToken 的 API 是标准 HTTPS 端点不需要额外代理就能访问。如果你在 CI 环境里遇到这个错误检查 CI 的全局环境变量是否注入了代理配置。reading choices报错长这样TypeError: Cannot read properties of undefined (reading choices)这个错误通常发生在模型返回的响应结构不符合预期时。OpenCode 期望 OpenAI 风格的响应{ choices: [ { message: { role: assistant, content: ... } } ] }如果返回的是 Anthropic 风格{ content: [ { type: text, text: ... } ] }OpenCode 就会读不到choices。解决办法是在配置里指定正确的 provider 类型。TaoToken 同时支持两种风格如果你用的是 Anthropic 风格的模型配置里要写{ model: { provider: anthropic, baseURL: ${TAOTOKEN_BASE_URL}, apiKey: ${TAOTOKEN_API_KEY}, model: claude-3-5-sonnet } }如果你用的是 OpenAI 兼容风格就写provider: openai-compatible。provider 类型和模型 ID 必须匹配否则响应结构对不上。还有一种可能是模型 ID 写错了服务端返回了一个错误对象里面没有choices。检查 Model ID 是否和 TaoToken 控制台里开通的模型一致。可以先用模型对话页面手动发一条消息确认模型能正常返回再把 Model ID 复制到配置里。OAuth 相关错误报错长这样Error: OAuth token expired Error: Failed to refresh OAuth token如果你用的是 Claude Code 或 Codex 这类带 OAuth 的工具可能会遇到这个。OAuth 和 API Key 是两种认证方式不要混用。如果你用 TaoToken 的 API Key就不需要 OAuth。检查配置里是否同时存在 OAuth 相关字段和 API Key 字段如果有删掉 OAuth 部分。对于 Codex 的auth.json正确格式是{ openai: { apiKey: sk-xxxxxxxxxxxxxxxx, baseURL: https://taotoken.net/api } }不要在里面写accessToken或refreshToken那是 OAuth 的字段。如果你之前登录过 Codex 的官方账号auth.json里可能有 OAuth 残留清空后重新写入 API Key 配置。版本漂移导致的配置合并错误报错长这样Error: Config merge conflict: version mismatch between root (1.2.27) and package (1.2.28)这是最隐蔽的一类错误。OpenCode 在合并根级和子包配置时如果发现版本号不一致可能会拒绝合并或按错误顺序合并。解决办法就是统一版本号。在根目录跑find . -name package.json -not -path */node_modules/* -not -path */dist/* -exec grep -H version {} \;找到不一致的子包手动改成统一版本。如果子包较多可以用脚本批量替换find . -name package.json -not -path */node_modules/* -not -path */dist/* -exec sed -i s/version: 1\.2\.28/version: 1.2.27/g {} \;改完后重新验证配置加载。注意这个操作只改 Git 仓库里的基准版本不影响 npm 上的实际版本。发布时由 Changesets 或 Nx Release 动态计算。排查完这些错误后建议把验证命令写进 CI每次提交都跑一遍配置校验和逐包加载测试。这样版本漂移和配置冲突能在合并前就被发现而不是等到运行时才暴露。6. 把配置固化下来让 Monorepo 里的 Agent 稳定运行配置验证通过之后下一步是把它固化到开发流程里。我在项目里通常做三件事把验证命令写进package.json的 scripts把环境变量模板提交到仓库把版本一致性检查加进 CI。先看根目录package.json的 scripts{ name: my-monorepo, private: true, scripts: { opencode:validate: opencode config validate, opencode:validate:all: pnpm -r exec opencode config validate, opencode:check-version: find . -name package.json -not -path */node_modules/* -not -path */dist/* -exec grep -H \version\ {} \\;, opencode:test: pnpm -r exec opencode run --agent $npm_package_name test } }opencode:validate:all会递归进入每个子包逐个校验配置。opencode:check-version用来检查版本一致性。这两个命令可以在提交前手动跑也可以放进 CI。环境变量模板提交为.env.exampleTAOTOKEN_API_KEYyour-api-key-here TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o真正的.env不提交加进.gitignore。新成员克隆仓库后复制.env.example为.env填入自己的 Key 即可。这样既保证了配置的可复制性又不会泄露 Key。CI 配置以 GitHub Actions 为例name: opencode-config-check on: [push, pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv4 with: version: 9 - run: pnpm install - run: pnpm opencode:check-version - run: pnpm opencode:validate:all env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} TAOTOKEN_BASE_URL: https://taotoken.net/api TAOTOKEN_MODEL: gpt-4o这样每次提交都会检查版本一致性和配置有效性。如果某个子包的版本漂移了或者配置合并失败CI 会直接报错阻止合并。还有一个实践是给每个子包的.opencode/config.json加一个version字段和package.json的版本保持一致{ extends: ../../opencode.json, version: 1.2.27, model: { temperature: 0.1 } }这样 OpenCode 在加载时能直接对比配置版本和包版本不一致时给出明确提示。虽然多维护一个字段但在子包较多的项目里这个提示能省下不少排查时间。对于长期做 Agent 开发的团队可以考虑把模型调用统一走 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要持续调用模型、跑 Agent 编排的场景比按次调用更可控。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明和示例。API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 建议给 CI 和本地开发分别创建 Key方便排查和轮换。最后说一个我踩过的坑子包的.opencode/config.json里不要写绝对路径。比如extends: /Users/xxx/my-monorepo/opencode.json这样在 CI 或其他机器上会直接失败。始终用相对路径../../opencode.json让配置跟着仓库走。同理package.json里的workspace:*也不要改成具体版本号否则发布后工作区引用会失效。把这些都固化下来之后Monorepo 里的 OpenCode Agent 配置就能稳定运行了。版本漂移有 CI 拦截配置合并有逐包验证模型接入有统一网关新成员上手只需要复制.env.example填 Key。剩下的就是业务逻辑本身而不是在配置层面反复折腾。