OpenCode 模型配置坑速查
> 由一次「修好又复发、连修三轮共八层根因」的真实排障沉淀整理，按【坑/现象 → 根因 → 解法 → 通用教训】组织。
坑 1：插件根本没加载（只认 .ts + 臆造 API）
【症状】会话持续报错，fallback 插件仿佛不存在；日志 WARN failed to load plugin。
【根因】两层：① OpenCode 插件加载器只认 .ts——.js 入口会 ENOENT 去找 .ts 兄弟文件，静默失败；② .js 里调用的 Plugin.getStorage 是臆造 API，真 API 是 ctx.storage.get/set。
【解法】插件一律写 .ts；照官方示例核对 API 面；旧 .js 备份后删除防双注册。注意 Bun 编译期拒 const 重复赋值，循环变量用 let。
坑 2：fallback 插件写死模型 ID = 定时炸弹
【根因】插件里写死一串免费模型 ID，其中若干已从上游名单退役；catch 兜底返回的也是死型号 → 会话卡死无限报错。
【解法】唯一模型来源 = 网关 /v1/models 实时拉取，拉取失败返回空数组并告警，绝不 fallback 到写死的型号；isDeadErr 判据覆盖 403/404/410 及 free tier / deprecated / not supported 消息，对死型号直接切 findBest()，不许「列表外不救」。
坑 3：动态池与声明名单不对齐，切换=白切
【症状】插件日志显示切换成功，但请求根本没发出（网关侧零请求记录）。
【根因】插件动态池 = 网关实时 ready 名单（含某模型 X），但配置只声明了模型 Y（不同版本号）→ switchModel(X) 落空，报 Model unavailable。
【解法】插件池与配置声明名单取交集（读 opencode.json 的 provider.<name>.models keys），单一事实来源，加模型只改配置一处。同理：想让某模型优先，最省事是把排在它前面且不可用的模型从声明列表删掉，而不是改插件排序。
坑 4：客户端报错先分「网关内 / 网关外」
【症状】同一堵墙换了刷法：先 403 FreeTierError，修完变 429 Rate limit——差点误判成网关限流。
【根因】会话 pin 的模型 providerID 是官方源，直连官方端点不走自建网关——网关 requests 表零记录不是「没请求」，是「请求没经过网关」。
【通用教训】排查三步：① 先看会话 pin 的 providerID；② requests/attempts 表当事实源；③ 判据绑「provider 身份 + 是否走本机网关」，别绑错误码字面——报错文案会变。
坑 5：配置默认模型 ≠ 新建会话默认模型（改 DB 只能赢一次）
【症状】凌晨修好，重开 App 新建会话又回到初始报错。
【根因】桌面版 UI 不读配置 default model，读自己的「最近使用」记忆，存在 ~/Library/Application Support/ai.opencode.desktop/drafts.sqlite（state 表 → opencode.global.dat → JSON 的 recent[0]/user[]）。手工改掉后，App 启动时用 models.dev catalog 刷新，把新出现的免费型号自动置顶回 recent（促销行为）——改记忆赢一次，赢不了启动。
【解法】从配置层一刀切掉不想被选中的 provider：
"disabled_providers": ["opencode"],
"small_model": "<你的小模型>"
small_model 必须一起改，否则标题生成这类小任务仍指向被禁 provider 的小模型。改完重启，recent 不再被重置。
坑 6：默认模型选型看限额结构与延迟曲线
【教训】
- api_keys 的 label 常带限额信息（如「每周 0.2」= 周限额）；同平台多模型共用一把 key = 一损俱损，一个被打爆全平台陪葬；
- 排查慢/timeout 看 attempts 表按 platform 聚类：5.9s → 131s → timeout 就是明确的劣化轨迹，别只看一次 success；
- 本机 ollama 模型当零限额压舱石：不碰外部限额、零网络抖动；云通道模型留给插件池按评分竞争。
坑 7：软链到外接盘的模型库是「易失资产」
【症状】报错「没有可用的 provider key」，极易误判成 key 失效。
【根因】模型库软链到外接盘，盘上模型被清理/盘没挂/盘换过 → 网关侧该模型 available=false, unavailable_reason=no_key——报错文案与真实原因完全对不上。
【解法】先 curl localhost:11434/api/tags 数模型，再看网关 models 表的 platform；报 no_key 时不要顺着文案去查 key。
排障速查链
- 看 opencode 日志有无
failed to load plugin（插件层）； - 看会话 pin 的 providerID + 网关 requests 表有无记录（路由层）；
- 对照 opencode.json 声明名单与插件动态池（注册表层）；
- 查 drafts.sqlite 的 recent[0]（记忆层）;
- 查上游模型名单是否退役（供给层）。
