在腾讯云 WorkBuddy（及 CodeBuddy）中接入第三方大模型时，遇到列表不显示、报错 401/403/404、响应超时或 Agent 运行异常，绝大多数情况下并非模型本身不可用，而是请求未抵达兼容接口或返回格式未被客户端识别。

从技术底层来看，WorkBuddy 的自定义模型机制基于以下核心规则运行：

• 配置双层级与热重载：支持用户级（~/.codebuddy/models.json）与项目级（<workspace>/.codebuddy/models.json）配置，同名 id 由项目级覆盖；文件保存后触发 1 秒防抖热重载，并通过 SmartMerge 机制追加至模型列表（自动标记 custom 标签）。
• 强协议约束：原生仅支持标准 OpenAI Chat Completions 协议，请求端点必须为包含完整路径的 /chat/completions。纯 Anthropic Messages 或 OpenAI Responses 格式的接口无法直接填用。
• 五层排查逻辑：所有连接异常均可按配置层 → 网络层 → 鉴权层 → 路由层 → 响应协议层逐级定界，先用 curl 验证底层连通性，再核对模型 ID 与 Agent 能力开关，效率远高于盲目更换模型名称。

---

一、WorkBuddy 接入大模型 API 的两种标准路径

在排查故障前，需确保基础接入方式正确。WorkBuddy 支持通过可视化设置界面或直接编辑 models.json 接入外部算力，常见方案分为官方直连与国内托管中转接入两类。

1. 官方订阅与本地部署直连

适用于已开通官方 API 账号（如 DeepSeek、OpenAI），或通过 Ollama、vLLM、LM Studio 在本地/内网部署开源模型的开发者。

• 操作方式：在 WorkBuddy 模型设置中选择自定义添加，或直接写入 models.json。url 填写官方或本地服务的完整聊天端点（如 [https://api.deepseek.com/v1/chat/completions](https://api.deepseek.com/v1/chat/completions) 或 http://localhost:11434/v1/chat/completions），apiKey 填写官方后台生成的密钥（本地服务可填任意占位符）。
• 局限性：访问海外官方接口需自行解决终端与客户端的网络代理环境；同时接入多家厂商时，需分别管理多套 Key 与计费账户。

2. 国内托管 API 中转站接入（如 treerouter）

对于希望在境内网络环境下低延迟直连、或需要在 WorkBuddy 中调用 Claude、Gemini 等原生非 OpenAI 格式模型的开发者，通常会采用成熟的国内托管 API 中转网关（例如 treerouter）作为统一接入层。

• 操作方式：无需在本地部署协议转换工具，只需将中转站提供的标准聚合端点（通常为 https://treerouter.com/v1/chat/completions）与聚合 API Key 填入 WorkBuddy，并在 id 字段指定目标模型名称即可。
• 该方案的核心技术优势：
• 网络直连免折腾：国内节点直接响应，省去在系统代理或 WorkBuddy 沙箱环境中反复调试网络连通性的成本。
• 服务端协议自动对齐：中转网关在云端将 Anthropic、Responses 等异构协议统一转换为标准 OpenAI Chat Completions 格式，直接绕过 WorkBuddy 的协议兼容限制。
• 多模型单密钥治理：仅需维护一组 URL 和 Key，通过调整配置中的模型 ID 即可在 DeepSeek、GPT、Claude 等不同架构间平滑切换。

标准 models.json 配置参考

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

---

二、故障分层定界：五层排查定位模型

面对报错切忌盲目修改参数。根据报错表象直接锁定对应层级，可将排查时间缩短至几分钟内：

异常现象	优先怀疑层级	首选排查动作
保存时提示“地址无效”	配置层	检查 URL 是否补全至 /chat/completions
返回 401 或 403	鉴权层	剥离客户端，用 curl 单独测试 Key 与权限
返回 404 或 model not found	路由层	对照供应商 /v1/models 接口核对真实模型 ID
请求超时或连接被重置	网络层	执行 curl -v 检查 DNS 解析、TLS 握手与代理
解析失败、乱码或返回空内容	响应协议层	检查返回值是否符合标准 choices 结构，关闭流式测试
普通对话正常，Agent 报错	协议扩展层	关闭 Tool Calling 做 A/B 对照测试
纯文本正常，发送图片报错	多模态兼容	使用最小 image_url 载荷验证视觉能力开关

---

三、端点规范与状态码排查（401 / 403 / 404）

1. 端点拼接的“完整路径”原则

WorkBuddy 不会自动为 Base URL 补全后缀，填入基础域名必然导致请求失败。

• 正确写法：[https://api.openai.com/v1/chat/completions](https://api.openai.com/v1/chat/completions)、http://localhost:11434/v1/chat/completions
• 错误写法：[https://api.openai.com/v1](https://api.openai.com/v1)、http://localhost:11434

实操注意点：避免末尾多出斜杠或重复拼接 /v1；若接入私有网关的非标准路径，需在界面开启“自定义协议”开关以跳过前置校验直发请求。此外，从网页复制 Key 或 URL 时极易混入不可见空格，建议在纯文本编辑器中显示不可见字符后再粘贴。

2. HTTP 状态码诊断与 curl 最小化验证

状态码直接反映请求在链路中的具体卡点：

• 200：网络、鉴权与路由全通，若界面仍异常，问题出在 WorkBuddy 的响应字段解析或 Agent 能力映射。
• 401：API Key 错误、已过期、包含首尾空格，或网关层重复拼接了 Bearer 前缀。
• 403：账号余额不足、无对应模型调用权限、触发地域风控或未加入 IP 白名单。
• 404：请求路径拼写错误，或 id 填写了网页展示昵称而非 API 真实标识符（例如应填 deepseek-chat 而非 DeepSeek-V3）。
• **429 / 5xx**：前者为并发或 Token 速率触发限流，需降低请求频率；后者为上游算力或中转网关内部异常。

当终端报错时，优先在终端执行以下命令排除客户端干扰：

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}'

特殊情况：若 curl 返回正常而 WorkBuddy 依然超时，请重点检查 WorkBuddy 内部的独立代理设置，以及操作系统对应用沙箱的网络访问权限限制。

---

四、协议兼容与 Agent 高级能力调优

1. 基础协议与流式（SSE）陷阱

所谓“OpenAI 兼容”往往只保证基础对话结构相似，高级字段各有差异。WorkBuddy 依赖标准的 model、messages、max_tokens 与 stream 字段。若遇到非流式响应正常、开启流式即卡死或报错，通常是上游服务未严格按 data: [DONE] 规范输出 SSE 事件，或中间反向代理开启了响应缓冲（Buffering），可在配置中临时关闭流式输出进行交叉验证。

2. Agent 专属能力单变量回归

在 Agent 模式下，模型不仅需要生成文本，还需高频调用外部工具与解析多模态输入，建议采用“先关后开、逐项验证”的策略：

• Tool Calling（工具调用）：必须同时满足“模型原生支持、接口正常接收 tools/tool_choice 参数、返回规范 tool_calls 对象且支持回传 role: tool 消息”三个条件。仅能通过提示词输出 JSON 字符串的模型，无法支撑 WorkBuddy 的 Agent 闭环。
• Vision（视觉识别）：需确保模型具备视觉能力、接收数组形式的 content 结构，且图片 URL 对服务端公网可达。若图片位于内网鉴权环境中，需转换为 Base64 编码或临时公开链接后再传入。
• 思考模式与上下文上限：部分深度推理模型输出思考链（Reasoning）时结构特殊，若出现空回复可先关闭 supportsReasoning 开关对照。上下文窗口（maxInputTokens）切忌直接填满官方宣传最大值——系统提示词、工具定义 Schema 与多轮历史会持续叠加，触发 context_length_exceeded 时应清理会话历史，并按 4K → 16K → 64K 三档逐步压测首字延迟与截断表现。

---

五、models.json 配置不生效 10 项自检清单

若修改配置文件后界面无变化或参数未生效，可按以下清单逐项核对：

1. 文件路径与优先级：确认修改的是用户级 ~/.codebuddy/models.json 还是项目级 <workspace>/.codebuddy/models.json，同名 id 以项目级为准。
2. JSON 语法合法性：运行 python3 -m json.tool ~/.codebuddy/models.json 校验格式，排查多余的尾逗号或中文引号。
3. 根节点与白名单过滤：根节点必须包含 "models": [...] 数组；若配置了 availableModels 字段，需确保目标模型 id 已包含在该白名单内。
4. 进程彻底重启：热重载存在 1 秒防抖且依赖文件落盘事件；修改后若未触发加载，需完全退出 WorkBuddy 进程再重新启动。
5. URL 完整度：确认 url 无多余尾斜杠，且严格以 /chat/completions 结尾。
6. 模型 ID 真实性：通过供应商的 /v1/models 接口核对精确的 id 字符串，区分大小写与连字符。
7. 密钥明文规范：apiKey 需填入真实密钥字符串，避免直接写入未解析的环境变量名。
8. 能力标记匹配：supportsToolCall、supportsImages、supportsReasoning 需与模型实际能力一致，切勿强行开启不支持的特性。
9. 重复项清理：配置文件中存在多个相同 id 时会触发覆盖合并，排查并删除冗余的旧配置块。
10. 版本备份与回滚：修改前养成备份习惯，一旦配置损坏导致解析异常，可将原文件重命名为 models.json.bak 并恢复可用版本。

---

六、常见疑难解答（FAQ）

Q：配置文件保存成功，但模型下拉列表中找不到新增的模型？

先使用命令行工具校验 JSON 语法无误，确认没有被 availableModels 白名单过滤，随后彻底结束 WorkBuddy 进程并重启以刷新本地缓存。

Q：同样的 Key 和地址在其他客户端能用，为什么在 WorkBuddy 里报错？

对比两者的实际 HTTP 请求体差异。许多轻量级对话客户端仅发送基础的 messages 数组，而 WorkBuddy 在默认或 Agent 模式下会附带 tools、stream_options 等扩展字段，部分第三方兼容接口未对这些字段做容错处理。

Q：普通聊天对话完全正常，一开启 Agent 任务就报错中断？

这是典型的 Tool Calling 协议不兼容表现。先在模型配置中关闭 supportsToolCall 验证纯文本链路；若确认上游模型不支持标准工具调用协议，建议更换原生支持函数调用的模型，或通过支持协议标准化转换的 API 网关进行中转。

Q：模型支持识图，但一发送图片就返回 400 Bad Request？

核对配置中的 supportsImages 是否已设为 true，并用单张小尺寸公开图片进行测试，排除图片体积超限、格式不支持或服务端抓取图片 URL 超时的问题。

基于 2026 年最新版本的 WorkBuddy 配置规范，排查自定义模型故障的核心在于先隔离、后叠加——通过 curl 锁定网络与鉴权基线，利用标准化的接口端点（或借助成熟中转网关消除协议差异）打通基础对话，再逐步放开工具调用与多模态能力，即可系统性地解决绝大多数接入难题。