Workbuddy 接入模型聚合平台 API 时，Base URL、密钥、模型 ID 和能力开关该怎么填，按什么顺序验证才不会白配？

在 Workbuddy 里接入模型聚合平台，标准做法是把 Base URL 指向聚合平台的 OpenAI 兼容端点并填到 /v1 为止，填入平台签发的 API Key，再手动登记模型 ID，然后按文本、流式、参数、工具调用、图片的顺序逐层验证；只提供私有协议、或转发层不透传工具调用字段的平台，接上去也用不了。这条边界要先说清楚，因为它决定了后面一半的排错方向。 先分清聚合平台与官方直连的差别。聚合平台把多家国产模型的接口收敛到同一端点和同一套密钥体系，Workbuddy 侧只需要维护一组配置，换模型时改模型 ID 即可；代价是模型能力由平台的转发层决定，模型本身支持工具调用不代表平台一定透传 tool_calls 或视觉字段。所以配置的第一原则是：能连上不等于能用，凡是能力类配置都要单独验证一次。 Base URL 是接入失败率最高的一项。填写规则是只写到 /v1 这一级，后面不要再带 chat/completions 之类的具体路径，客户端会自己拼接；如果平台文档给的是完整接口地址，需要手动截断多余部分。若中间挂了自己的反向代理，要确认代理没有二次添加路径前缀，也没有把末尾斜杠吞掉或重复，否则表现是 404 而不是鉴权失败，很容易被误判成密钥问题。 API Key 应当单独签发，不要复用生产环境的全权限密钥。给 Workbuddy 用的密钥按用途建一个子账号，设置用量上限并绑定固定出口 IP，泄露后只吊销这一把，不影响其它业务；本地存储的配置目录不要同步到共享盘或网盘。密钥问题在日志里的表现是 401 或 403，此时不要急着重装客户端，先拿同一把密钥在命令行确认一次是否有效。 模型 ID 必须逐字复制平台的模型列表，不能按官方命名习惯去猜。聚合平台常给模型加前缀或版本后缀，Workbuddy 配置里通常有两个字段：显示用的名称和实际转发用的模型 ID，前者可以随意写，后者必须完全一致。填错的返回是 model not found 一类的 404，而不是密钥错误，这是区分问题归属的关键信号，先看报错码再动手改。 能力开关要按模型的真实情况勾选，不要全部打开。工具调用要求模型自身支持且平台透传，视觉输入要求选多模态模型，上下文长度建议按标称值填小一档以留出系统提示与历史记录的余量。全部打开最典型的症状不是报错，而是静默失败：工具调用返回空、超长对话被悄悄截断，排查时很难定位到是开关的问题。 验证顺序可以固定成六步，每步通过再进下一步。第一步用平台的模型列表接口确认密钥有效；第二步关闭流式与工具，只发一句短文本；第三步打开流式，观察是否逐字返回；第四步调整温度和最大输出长度这两个参数；第五步挂一个无参数的空工具，看模型能否正确返回调用结构；第六步传一张图片，确认视觉链路通。任何一步失败只回退一步排查，不要一次改多项配置。 常见报错可以按码对照。401 和 403 指向密钥或权限，404 多与 Base URL 或模型 ID 有关，429 是限流或额度用尽，5xx 一般是平台上游波动。判断归属的方法是拿同一端点、同一密钥在命令行复现：能复现就是平台侧或参数问题，复现不了才怀疑客户端配置与本地网络。这一条能省掉大部分来回试探。 成本结构要在验证阶段就控制住。聚合平台按 token 用量计费，验证期的消耗主要来自长输出和工具循环，而不是请求次数。做法是把最大输出长度压到两三百 token，关掉自动重试与多轮工具循环，工具调用设置次数上限；平台注册赠送的测试额度通常足够跑完上面六步，不必先充值再验证，等链路稳定后再按实际用量评估预算。 稳定性上不要把单平台单模型当成生产依赖。Workbuddy 里至少配两个模型条目，可以指向同一平台的不同模型，也可以配成两个供应商条目做互备；切换要保留人工确认环节，不要自动回退到能力更弱的模型上去接工具调用，否则出错的是业务逻辑而不是接口。模型下线与路径调整是聚合平台常见变更，配置清单要能支持快速回归。 合规边界也要在配置时一并确认。请求经过聚合平台转发，意味着对话内容会落到第三方节点，涉密信息、个人身份信息、未脱敏的业务数据不要放进对话；选平台时看清楚备案信息、日志留存说明和数据使用条款，企业场景还要确认平台能提供用量明细与合规票据。这一步在技术上不影响连通性，但决定了这套配置能不能长期留在公司环境里。 配置跑通后固化一份参数清单：端点地址、模型 ID、能力开关状态、最大输出长度、验证日期与验证人。换版本、换平台或平台调整路径时按清单逐项回归，比凭记忆重配可靠得多。最容易被忽略的是模型 ID 的有效期，平台下线某个版本时不会通知到客户端，表现为昨天能用今天报错，有清单才能五分钟内定位。