WorkBuddy 自定义模型接入失败：从接口、鉴权到协议兼容的完整排查指南

WorkBuddy 自定义模型接入失败，通常不是“模型不能用”，而是请求没有正确到达兼容接口，或接口返回格式无法被 WorkBuddy 识别。最有效的排查顺序是：先用 curl 验证网络和 API Key，再核对完整端点与模型 ID，最后检查工具调用、图片输入、思考模式和上下文参数。本文将常见现象映射到具体检查命令，帮助你区分配置错误、供应商限制和 WorkBuddy 侧兼容问题。

先看错误属于哪一层

接入问题可以按请求链路分成五层：WorkBuddy 配置、网络连接、鉴权、模型路由和响应协议。不同层的修复方法完全不同，反复更换模型名称通常解决不了网络或协议问题。

第一步：确认 WorkBuddy 保存的是正确配置

WorkBuddy 的自定义模型表单通常至少需要接口地址、API Key 和模型名称。接口地址应以供应商实际文档为准；如果界面要求完整端点，就填写类似下面的地址：

https://api.example.com/v1/chat/completions

不要同时把“基础 URL”和“完整聊天端点”填入同一个字段，例如把 https://api.example.com/v1 误填成完整端点，或把 /chat/completions 重复拼接两次。若界面提供“自定义协议/原样发送”选项，只有在供应商端点不是标准 OpenAI Chat Completions 路径时才启用。

模型名称必须是供应商 API 接收的 model 字段值，而不是网页展示名称。大小写、连字符和版本后缀都可能影响路由，例如 deepseek-chat 与 DeepSeek Chat 不是同一个值。

配置文件排查

如果图形界面保存后模型消失，可以关闭 WorkBuddy 后检查本地配置文件是否写入成功。不同版本路径可能变化，以下路径仅作为常见示例，先以官方版本说明为准：

# macOS / Linux 示例
ls -l ~/.workbuddy/models.json
python3 -m json.tool ~/.workbuddy/models.json

如果 json.tool 报错，说明 JSON 有多余逗号、引号不成对或文件被截断。API Key 不要提交到 Git，也不要把完整配置文件发到公开论坛。

第二步：用 curl 把 WorkBuddy 排除在外

最重要的诊断动作是直接请求供应商端点。将 YOUR_API_KEY、MODEL_ID 和 URL 替换为真实值：

curl -sS -i 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": "ping"}],
    "max_tokens": 16,
    "stream": false
  }'

观察 HTTP 状态码和响应体：

• 200：网络、Key、模型路由基本正常，继续检查 WorkBuddy 字段映射。

• 401：Key 无效、过期、带了空格，或供应商要求不同的鉴权头。

• 403：账号没有该模型权限、地区限制或 IP 白名单未通过。

• 404：端点路径或模型 ID 错误。

• 429：配额、并发或速率限制，不是 WorkBuddy 配置错误。

• 5xx：供应商服务端故障或网关上游异常。

如果命令本身超时，再运行：

curl -v --connect-timeout 10 --max-time 30 https://api.example.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

重点看 DNS、TLS 握手、代理和证书错误。终端能访问而 WorkBuddy 不能访问时，再检查 WorkBuddy 是否使用独立网络环境、系统代理或沙箱权限。

如果不想分别维护多家供应商的地址和密钥，也可以把七牛云的多模型 API 作为一个 OpenAI 兼容端点进行验证；关键仍是以平台返回的真实模型 ID 和接口文档为准，先完成上面的 curl 单测，再填入 WorkBuddy。

第三步：区分协议不兼容和模型能力不足

“OpenAI 兼容”只代表接口形状相近，不保证所有字段和流式事件完全一致。WorkBuddy 常见的基础请求通常依赖 model、messages、max_tokens、stream 等字段；供应商若只支持 Responses API、Anthropic Messages API 或自定义 JSON，直接填写地址可能会出现 400、空回复或流式解析失败。

用下面的 Python 代码打印响应结构，确认是否包含 choices[0].message.content：

import json
import os
import requests

url = "https://api.example.com/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['MODEL_API_KEY']}",
    "Content-Type": "application/json",
}
payload = {
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "stream": False,
    "max_tokens": 16,
}
r = requests.post(url, headers=headers, json=payload, timeout=30)
print(r.status_code)
print(json.dumps(r.json(), ensure_ascii=False, indent=2))

如果非流式请求正常、流式请求失败，问题多半在 SSE 事件格式、代理缓冲或 WorkBuddy 的流式解析。可先关闭流式输出（如果 WorkBuddy 版本提供该选项）做验证，再决定是否需要兼容网关。

工具调用失败：先关闭，再逐项打开

普通聊天成功但 WorkBuddy Agent 报错，最常见原因是模型不支持 Function Calling，或供应商返回的 tool call 字段与 OpenAI 结构不同。建议先在模型设置中关闭“工具调用”，确认纯文本任务稳定后，再开启工具调用。

工具调用至少要验证三件事：

1. 模型文档明确声明支持 function/tool calling。

2. 接口能接受 tools 和 tool_choice 字段。

3. 返回内容包含规范的 tool_calls，并能携带 role=tool 的后续消息。

最小测试请求：

curl -sS 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": "查询北京天气"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询城市天气",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto",
    "stream": false
  }'

如果供应商只支持特定工具调用模板，不要在 WorkBuddy 中勾选工具调用后强行使用；换成支持该协议的模型，或使用明确提供格式转换的内部网关。不要把“模型会输出 JSON”误当成“模型支持工具调用”。

图片输入失败：检查字段、模型和大小

图片输入需要同时满足三个条件：模型具备视觉能力、接口接受多模态 content 数组、图片 URL 对服务端可访问。最小请求示例：

{
  "model": "VISION_MODEL_ID",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "描述图片内容"},
      {"type": "image_url", "image_url": {"url": "https://example.com/a.png"}}
    ]
  }]
}

如果文本请求成功、图片请求返回 400，先确认 WorkBuddy 的“图片输入”开关与模型能力一致。图片 URL 若需要登录、只能在内网访问，供应商服务器也可能无法下载；可用公开临时 URL 或按供应商要求传 Base64。图片过大、格式不支持和超时也会表现为“模型调用失败”。

思考模式和上下文设置导致的异常

思考模式不是所有模型都支持。打开后如果出现空回复、输出格式异常或超时，应先关闭思考模式做对照。上下文窗口也不能随意填写成模型宣传页上的最大值：WorkBuddy 还会叠加系统提示词、工具描述、历史消息和输出预算。

建议用三档输入做回归：4K、16K、64K token。每档记录首字延迟、完整响应时间和是否出现截断，再决定是否提高上下文上限。服务端返回 context_length_exceeded 时，应先减少历史消息和工具描述，而不是只提高客户端数字。

按错误信息快速定位

“模型不存在”

检查模型 ID 是否为供应商 API 的真实值，确认账号所在区域和套餐是否有权限。不要直接复制模型卡标题或控制台显示名称。

“Invalid URL” 或地址重复

检查是否重复填写 /v1、/chat/completions，以及 URL 中是否包含不可见空格。用 python3 -c 或文本编辑器显示原始字符串，重新手动输入通常比复制粘贴更快。

“Unauthorized”

重新生成 Key，去掉首尾空格，确认 WorkBuddy 没有把 Bearer 前缀和自身鉴权逻辑叠加两次。不要在 URL 查询参数中暴露 Key。

“Empty response”

先关闭流式、工具调用和思考模式，只保留纯文本请求。如果仍为空，检查供应商是否返回标准 choices；如果 curl 有内容而 WorkBuddy 为空，保存脱敏后的响应结构提交给 WorkBuddy 支持。

“Too many requests”

查看供应商配额、RPM/TPM 限制和 WorkBuddy 并发任务数。降低并发只能缓解 429，不能修复错误的 Key 或模型权限。

一套可复用的排查顺序

1. 在 WorkBuddy 中复制并核对 URL、模型 ID 和高级开关。

2. 用 curl 发一个非流式、纯文本、低 max_tokens 请求。

3. 用 Python 打印 JSON，确认 choices[0].message.content 是否存在。

4. 逐个开启流式、工具调用、图片输入和思考模式，每次只改一个变量。

5. 最后再提高上下文、并发和输出长度，并记录延迟与错误率。

这套顺序的核心是先验证“请求能不能成功”，再验证“WorkBuddy 能不能解析”，最后才验证“模型能力是否满足 Agent 任务”。

FAQ

Q1：为什么保存配置成功，但模型列表里没有？ 通常是配置文件写入失败、JSON 格式错误、模型 ID 为空或客户端缓存未刷新。先用 python3 -m json.tool 校验文件，再完全退出并重新打开 WorkBuddy。

Q2：同一个 API 在其他客户端能用，WorkBuddy 还是失败，怎么办？ 对比请求体和响应体，尤其是端点路径、stream、工具调用字段及鉴权头。许多“兼容接口”只兼容基础文本请求，不兼容 Agent 所需字段。

Q3：本地 Ollama 接入失败的第一检查点是什么？ 确认 Ollama 服务监听地址、模型名称和 WorkBuddy 与 Ollama 是否在同一网络环境。先用 curl http://localhost:11434/v1/models 验证服务，再在 WorkBuddy 中配置。

Q4：是否应该直接换一个 API 平台？ 只有在 curl 已确认端点、Key 和模型权限正常，并且响应协议与 WorkBuddy 不兼容时，才考虑更换兼容层或供应商。盲目更换平台会掩盖真正的配置问题。

结论

WorkBuddy 自定义模型接入失败，最常见的根因依次是端点拼接错误、Key 或模型权限问题、OpenAI 兼容协议不完整，以及工具调用/多模态能力与模型不匹配。按照“curl 单测 → JSON 结构 → 单变量开启高级能力 → 小规模压测”的顺序排查，通常能在几分钟内确定责任边界。本文配置字段和界面名称可能随 WorkBuddy 版本更新，最终以对应版本的官方文档为准。

参考资料：

• WorkBuddy 模型配置文档

• OpenAI Chat Completions API 格式说明

• Ollama OpenAI 兼容接口

• 七牛云 AI 模型 API