1. OpenCode 启动时 JsonMigration 回调注入到底在做什么如果你正在用 OpenCode 这类 Agent 工具或者自己写过带配置迁移的 CLI大概率遇到过这种情况升级版本后旧的settings.json或config.toml没有自动迁移启动日志里也看不到任何迁移动作程序却照常跑起来了。表面看没事实际上你的旧配置被静默忽略Agent 行为跟预期完全对不上。OpenCode 在启动阶段会走一个 JsonMigration 模块它的核心设计是回调注入Callback Injection。简单说迁移引擎只负责把数据从旧结构搬到新结构至于迁移过程中要不要显示进度、怎么显示、显示给谁看全部交给调用方决定。迁移引擎内部只做一件事产生进度事件。调用方通过注入一个progress回调来消费这些事件。这个机制能做什么它让同一份迁移代码可以适配完全不同的运行环境CLI 终端里画 ANSI 进度条CI 流水线里打纯文本日志单元测试里收集事件数组做断言Web 端通过 WebSocket 推送 JSON。迁移引擎一行都不用改。适合谁看正在排查 OpenCode 启动迁移未生效的开发者以及想在自己项目里实现类似回调注入模式的 Node.js / TypeScript 工程师。下面我会从配置骨架、TaoToken 统一 Key 通道、启动日志验证三个角度拆开讲最后给出可复制的排障清单。2. TaoToken 前置统一 Key 与 API 通道配置在拆迁移回调之前先把模型通道配好否则 OpenCode 启动后即使配置迁移成功Agent 也调不通模型。TaoToken 提供统一的 API 入口你只需要一个 Key 就能对接多种模型。官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api操作路径很直接先到控制台创建 API Key然后在 OpenCode 的配置里把 base URL 指向 TaoToken 的 API 地址。如果你用的是 Claude Code 这类工具TaoToken 也提供了对应的接入文档把 Anthropic 风格的请求转发到统一通道。注意API 地址不要加 UTM 参数只有官网链接才带推广参数。配置里填https://taotoken.net/api即可。创建 Key 的入口在控制台的 API Keys 页面。拿到 Key 之后建议先不要急着写进 OpenCode 配置而是用一条 curl 验证通道是否通。这一步能帮你排除掉「Key 无效」「网络不通」「模型名写错」三类问题避免后面排查迁移回调时被干扰。3. 可复制配置settings.json 与 config.toml 骨架OpenCode 的配置迁移通常涉及两个文件settings.json和config.toml。旧版本可能把模型配置放在settings.json的顶层新版本要求迁移到config.toml的[model]段。JsonMigration 就是负责这个结构转换的。先看settings.json的骨架这是迁移前的旧结构{ version: 1, model: { provider: taotoken, name: claude-sonnet, apiKey: sk-你的Key, baseUrl: https://taotoken.net/api }, agent: { maxTurns: 20, autoApprove: false } }迁移后的config.toml新结构version 2 [model] provider taotoken name claude-sonnet api_key sk-你的Key base_url https://taotoken.net/api [agent] max_turns 20 auto_approve falseJsonMigration 的触发时机在启动阶段当它检测到settings.json的version小于当前期望版本时就会执行迁移。迁移过程中它会通过注入的progress回调上报每一步的状态。如果你在启动日志里看不到迁移动作通常是三个原因版本号已经是最新、迁移回调没有被注入、或者迁移结果被写到了你没注意的路径。回调注入的接口类型大致是这样type Progress { current: number total: number label: string } type Options { progress?: (event: Progress) void } async function run(db: Database, options?: Options) { // 迁移逻辑 options?.progress?.({ current: i, total: n, label: migrating model config }) }注意progress是可选参数调用方不传就完全静默没有任何性能开销。这就是零成本抽象。4. 验证请求启动日志与迁移回调确认配置写好后怎么确认迁移回调真的生效了最直接的办法是看启动日志。OpenCode 启动时会输出迁移相关的 stderr 信息因为进度和诊断信息走的是 stderr 而不是 stdout这样不会污染数据流。你可以用下面这条命令启动把 stderr 单独重定向到文件opencode start 2 migration.log然后查看migration.logcat migration.log | grep -i migrat如果迁移回调被正确注入你会看到类似这样的输出[migration] current1 total3 labelmigrating model config [migration] current2 total3 labelmigrating agent config [migration] current3 total3 labelmigrating plugins如果日志里什么都没有说明回调没被注入或者版本号已经是最新导致迁移被跳过。这时候你可以手动把settings.json的version改回 1再启动一次强制触发迁移。另一个验证方式是直接调模型确认迁移后的配置能被正确读取curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping}] }返回正常的话说明 Key 和通道没问题迁移后的config.toml也能被 OpenCode 正确加载。如果这一步失败先别怀疑迁移逻辑优先检查 Key 和 base URL。5. 本篇常见错排查迁移回调未生效的几种情况情况一版本号判断逻辑反了。有些实现里迁移条件是version CURRENT但如果你手动把version改成了比当前更大的值迁移会被跳过。检查settings.json里的version字段确保它小于当前期望版本。情况二回调注入被条件分支绕过。如果调用方在options里传了progress但迁移引擎内部有个if (isTTY)判断非 TTY 环境下直接不调用回调那你在 CI 里就看不到任何进度。检查迁移引擎源码里options?.progress?.()的调用位置确认它没有被包在环境判断里。情况三迁移结果写到了错误路径。JsonMigration 默认可能写到~/.config/opencode/config.toml但你的 OpenCode 实际读取的是项目目录下的./config.toml。用strace或者lsof看进程实际打开了哪个文件或者直接在启动日志里搜索config.toml的绝对路径。情况四stderr 被吞了。如果你用opencode start output.log 21stderr 和 stdout 混在一起grep 时可能被其他日志淹没。建议分开重定向stderr 单独存一个文件。情况五Key 无效导致启动提前退出。如果 TaoToken 的 Key 配置错误OpenCode 可能在迁移之前就退出了你自然看不到迁移日志。先用 curl 验证 Key再排查迁移。提示排查顺序建议从外到内——先确认 Key 和通道通再确认配置文件路径对最后才看迁移回调注入逻辑。这样能避免在错误的层面上浪费时间。6. 语义一致 CTA按场景选择入口如果你是在排查接入问题比如 Key 无效、base URL 写错、迁移后配置读不到优先看 API Keys 和接入文档API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你只是想验证某个模型在迁移后是否还能正常对话直接用模型对话页面测一条消息最快模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你在做长期编码或 Agent 开发需要稳定的通道和额度管理看 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台入口在这里创建 Key、查看用量、管理配置都在这控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentClaude Code 用户走这个接入页Claude Code 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content我自己的习惯是每次升级 OpenCode 版本后先把settings.json的version手动降一级启动一次看迁移日志确认回调注入正常再把版本号改回去。这样能提前发现迁移逻辑的回归问题比等到 Agent 行为异常了再回头查要省事得多。