给 WorkBuddy 配置 OpenCode 模型
把一个模型的供应商（网关）完整接进 WorkBuddy 或其他桌面 Agent：先探活，再按目标客户端的真实 schema 写配置，最后从运行时验证生效。不做「照着文档抄一份」这种事——文档和真实可用的模型经常对不上。
何时使用
- 用户说「给 WorkBuddy / ZCode / opencode 接上 XX 的模型」
- 用户想「把某个网关的模型全部加进来」或「模型列表更新一下」
- 模型能配但报错（401/403/400/模型不存在），需要定位是密钥、地区限制还是协议问题
- 换客户端后要迁移已有的供应商配置
前置条件
- Node.js ≥ 18（脚本用全局
fetch，无需安装依赖） - 供应商的 base URL 和 API key
- 知道目标客户端是哪一个（决定最后写哪个文件）
密钥只从环境变量读取，不要在脚本参数里明文传。Windows 下 bash：
export MODEL_API_KEY='sk-...'
工作流
第 1 步：探目录
先拿供应商自己的模型清单，不要凭记忆或客户端内置列表：
node scripts/probe_models.mjs --base-url https://host/v1 --api-key-env MODEL_API_KEY --out probe-report.json
脚本会 GET /models 拿到每个模型的 limit.context、limit.output、
modalities.input、capabilities.tools 等真实元数据。若该端点不可用，用
--models-file ids.txt 指定 id 列表继续。
第 2 步：逐个探活
同一支脚本接着对每个模型发一次最小 chat/completions 请求（max_tokens: 4），
把结果分成 models（可用）和 failed（带 HTTP 状态与错误体）两部分。
不要跳过这一步。 常见陷阱：
- 密钥有效但部分模型被地区限制（403
unsupported_country_region_territory） - 网关要求额外的会话头，缺了全部 400（OpenCode 需要
x-opencode-session） - 目录里标注为
messages/responses/generate-content的模型，未必不能走
/chat/completions——很多网关按 model id 统一路由。探了才知道。
需要自定义请求头时：
--header "x-opencode-session=<uuid>"
<uuid> 会被替换为随机 UUID。
第 3 步：确认目标客户端的 schema
读客户端自己的东西，不要读网上的教程。 优先顺序：
- 客户端内置的 schema 或模板文件（最可靠，且能反映当前版本）
- 客户端源码里校验模型条目的那段逻辑
- 官方文档（可能落后于实际版本）
WorkBuddy 的模型配置是 ~/.workbuddy/models.json，字段语义、协议限制和验证方法见
references/workbuddy-models-json.md。
opencode CLI 与 ZCode 的格式差异见 references/other-clients.md——这两者都出现过
新旧 schema 并存、旧写法被静默忽略的情况。
第 4 步：写入
WorkBuddy 用附带脚本合并，只替换同一 url 下的条目，别的供应商原样保留，并在写之前自动备份：
node scripts/apply_workbuddy_models.mjs \
--report probe-report.json \
--base-url https://host/v1 \
--api-key-env MODEL_API_KEY
其他客户端没有现成脚本时，手写 JSON 并遵守三条：
- 先备份，并在回复里给出一行可执行的回滚命令
- 只写探活通过的模型，不可用的单独列出原因，不要混进去
- 写之前确认目标程序是否在运行——多数 Electron 客户端退出时会把内存配置写回磁盘
第 5 步：验证生效
写入不等于生效。要求用户完全退出客户端再重新打开，然后从运行时确认，而不是只看文件：
- WorkBuddy：
~/.workbuddy/logs/daemon.log里有wb:models:list且无相邻报错；
~/.workbuddy/cache/acc-product-config-v3-*.json的models数组里出现对应条目
（自定义模型带custom-local:前缀），条数应与写入数一致 - 其它客户端：找到它落盘的运行时配置或缓存，统计自定义模型条数
具体命令见 references/workbuddy-models-json.md。
交付时说明什么
- 可用 / 不可用的模型数量，以及不可用的具体原因（地区限制、协议不支持、模型已下线）
- 改了哪些文件、备份在哪、怎么回滚
- 需要用户执行的唯一动作（通常是重启客户端）
- 密钥是明文存储这一事实，以及是否需要收紧文件权限
常见失败
| 现象 | 判因 | 处置 |
|---|---|---|
| 全部 401 | 密钥错或没带上 | 检查 Authorization: Bearer 头 |
| 全部 400 且提示缺 header | 网关要求自定义头 | 加 --header，查 references/opencode-gateway.md |
| 部分 403 | 地区或套餐限制 | 排除该模型，在交付说明里列出 |
| 配置写了但列表没变 | 客户端还在跑 / schema 版本不对 | 完全退出重启；核对新旧字段 |
| 文件被还原 | 客户端启动时重写了配置 | 关掉客户端再写，或改完立即重启 |
参考文件
references/workbuddy-models-json.md— WorkBuddymodels.json字段、协议限制、验证命令references/opencode-gateway.md— OpenCode Go/Zen 端点、必需的会话头、失败码references/other-clients.md— opencode CLI 新旧 schema 对照、ZCode 配置结构
