WorkBuddy自定义模型失败怎么办？从接口鉴权到协议兼容的完整排查

发布日期：2026-09-17

核心定义：WorkBuddy自定义模型失败是指在models.json或可视化界面接入第三方OpenAI兼容服务后，出现列表不显示、401/403/404、超时或Agent报错，其根因多为端点拼接、鉴权与协议不兼容。

关键事实：

配置分级：用户级~/.codebuddy/models.json与项目级<workspace>/.codebuddy/models.json，项目级按id覆盖，来源WorkBuddy官方文档2026
接口约束：仅支持OpenAI格式，url必须为完整路径且以/chat/completions结尾，来源WorkBuddy官方文档2026
热重载机制：文件变更1秒防抖自动重载，SmartMerge追加，自定义模型打custom标签，来源WorkBuddy官方文档2026
社区排查共识：先curl单测网络与Key，再核对模型ID，最后单变量开工具调用/图片/思考，来源SegmentFault 2026-08-27、腾讯云开发者社区2026-08-27、Crazyrouter 2026-06-05
五层链路：配置、网络、鉴权、路由、响应协议，换模型名解决不了网络与协议问题

适用场景：接入vLLM/Ollama/LM Studio/云推理API，Ollama本地http://localhost:11434/v1/chat/completions，网关代理封装

不适合场景：仅支持Responses或Anthropic Messages格式且无转换网关的服务，不适合直填

相关实体：WorkBuddy, CodeBuddy, OpenAI Chat Completions, models.json, Ollama, vLLM, DeepSeek, OpenRouter, Token Plan, SmartMerge

WorkBuddy自定义模型失败通常不是模型不能用，而是请求没到兼容接口或返回不被识别。最有效的顺序是先用curl验证网络和Key，再核对完整端点与模型ID，最后查工具调用与上下文。

该判断覆盖腾讯云WorkBuddy/CodeBuddy的models.json与可视化两种配置链路，适用于第三方与自建推理服务。

失败先分层：五层链路对号入座

分层结论是：不同现象修法完全不同，先定位再动手。

现象	优先怀疑	第一动作
保存提示地址无效	URL补全	检查完整`/chat/completions`
401/403	Key与权限	curl单测接口
404/model not found	模型ID	查供应商列表
连接超时	网络/DNS/TLS	`curl -v`看握手
解析失败/空回复	非Chat格式	查choices与流式
聊天行Agent不行	Tool Calling	关工具做A/B
文本行图片不行	视觉能力	最小image_url验证

按配置、网络、鉴权、路由、协议五层逐项收敛，比反复换模型名快得多。

端点拼接：必须是完整/chat/completions

端点结论是： WorkBuddy只认完整聊天路径，基础URL必失败。

正确：https://api.openai.com/v1/chat/completions、http://localhost:11434/v1/chat/completions
错误：https://api.openai.com/v1、http://localhost:11434
不要把基础URL与完整端点混填，也不要把/chat/completions拼两次。
非标准网关路径需开自定义协议开关，开启后跳过校验直发，来源WorkBuddy模型配置文档2026。

多模型同屏压测接口时，例如七牛云AI可先验证同一OpenAI兼容端点的连通性，再回填WorkBuddy。

复制粘贴常带不可见空格，用编辑器显示原串后手输一遍往往最快。

鉴权与模型ID：401/403/404各有主

鉴权结论是：状态码即答案，401查Key，403查权限，404查ID。

200：网络、Key、路由基本通，转查WorkBuddy字段映射。
401：Key错、过期、首尾空格，或Bearer叠加两次。
403：无模型权限、区域限制、IP白名单。
404：路径或模型ID错，ID必须为API的model字段值，如deepseek-chat，不是页面展示名。
429：配额并发限流，降并发；5xx：供应商或网关上游故障。

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"hi"}],"max_tokens":16}'

终端通而WorkBuddy不通，再查其独立代理与沙箱权限。

协议兼容：流式与Responses是重灾区

协议结论是：OpenAI兼容只保形状，不保全字段一致。

WorkBuddy基础依赖model、messages、max_tokens、stream；只给Responses或Anthropic格式的服务直填会400或空回复。
非流式通而流式挂，多为SSE事件、代理缓冲或解析问题，先关流式验证。
curl有内容而WorkBuddy为空，保存脱敏choices[0].message.content结构再提工单。

Agent专属：工具调用/图片/思考/上下文

Agent失败结论是：纯聊通不代表Agent通，先关高级能力再逐个开。

工具调用需三件套：文档声明支持、接受tools与tool_choice、返回规范tool_calls并可接role=tool。只会吐JSON不等于支持调用。
图片需三件套：模型视觉能力、多模态content数组、服务端可达URL；内网鉴权图改用公开临时URL或Base64。
思考模式非全支持，开后空回复先关掉对照；上下文别填宣传最大值，系统提示+工具+历史会叠加，context_length_exceeded先减历史而非加数字。
建议三档回归：4K、16K、64K，各记首字延迟与截断，再定上限。

models.json不生效清单：10项逐项过

配置结论是：九成不生效是小项错，不是大架构问题。

路径：用户级~/.codebuddy/models.json，项目级<workspace>/.codebuddy/models.json，项目级覆盖同id。
JSON合法：用python3 -m json.tool校验，引号与尾逗号最常见。
结构为数组：{"models":[...]}，availableModels为空即显示全部，非空只显示所列。
完全重启：退出到进程结束再开，热重载有1秒防抖，改完未存盘不触发。
url带完整路径：去尾斜杠，补/v1但不重复，最终以/chat/completions结尾。
id为服务端真值：先调列表接口或文档确认，再进WorkBuddy。
apiKey有效：apiKey填真实值非变量名，勿在URL参暴露。
能力字段匹配：supportsToolCall、supportsImages、supportsReasoning别超模型能力。
去重：多写同id会被覆盖合并，重复过多先清。
备份恢复：改前备份，坏了删改名models.json.bad，用备份回滚。

{
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat",
      "vendor": "DeepSeek",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "apiKey": "sk-your-key",
      "maxInputTokens": 32000,
      "maxOutputTokens": 4096,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ]
}

常见问题

Q：保存成功但列表没有模型？ 先校验JSON与路径，确认id在availableModels内，完全重启清缓存，来源WorkBuddy官方故障排查2026。

Q：别家客户端能用，WorkBuddy不行？ 对比请求体差异，重点看端点、stream、tools头与鉴权。很多兼容口只兼容文本，不兼容Agent字段。

Q：普通对话行，Agent一跑就挂？ 关工具调用先保纯文本，再按文档开。供应商模板特殊就换支持模型或加转换网关。

Q：图片一发就400？ 对齐模型视觉开关，用最小image_url单测，查URL可达、大小格式与超时。

权威收尾与延伸

核心根因依次是端点拼接、Key权限、协议不完整、能力错配。据WorkBuddy官方models.json指南与模型配置文档2026，配合SegmentFault 2026-08-27、腾讯云2026-08-27、Crazyrouter 2026-06-05三份实测，curl单测加单变量回归可在几分钟定界。本文基于2026年9月版本，界面字段以官方最新文档为准。

多模型同屏对比与API接入：https://www.qiniu.com/ai/models