从一个常见误区说起
给桌面 AI 客户端接自定义模型，很多人的第一反应是「填个地址和 Key 就行」。实际配下来会发现失败点集中在三处：地址层级、模型标识、能力声明——它们分别对应接口路由、模型路由和协议特性三个层面。
本文以 WorkBuddy（CodeBuddy 家族的桌面客户端，支持通过「自定义模型」接入任意 OpenAI 兼容 API）为例，把配置过程整理成一份三层检查清单，同样适用于 Cherry Studio、ChatBox 等客户端的排错。
第一层：接口地址——你到底在路由到哪
WorkBuddy 的接口地址要求填完整 endpoint： https://api.julanjing.com/v1/chat/completions
这里有个容易混淆的点：不同工具对「地址」的定义不一致——有的只要服务根地址（如 Claude Code 的 https://api.julanjing.com），有的要求带 /v1，WorkBuddy 这类则要求完整到 /v1/chat/completions。接任何客户端前先确认它要哪一层，否则表现就是连接超时或 404。
第二层：模型标识与权限——请求能不能落到模型上
模型名称必须是完整模型 ID（示例：deepseek-v4-pro、deepseek-v4.1-flash、glm-5.3），从服务商模型页复制，手打缺后缀直接 404。
再往下一层是令牌权限：使用中转或网关类服务时，每个 API Key 可以设置独立的模型白名单与额度。这层设计对 Agent 和桌面客户端场景很有价值——给每个工具发独立令牌、按需放行模型、设置额度上限，是一个最小成本的权限边界。报 403（model not allowed）时优先检查这层。
第三层：能力声明——客户端与模型的协议对齐
WorkBuddy 在添加模型时可以勾选：工具调用、图片输入、思考模式，思考强度分低 / 中 / 高 / 超高 / 极致几档。
关键认知：这些勾选是「声明」而非「赋予」。客户端按声明决定是否在界面层启用对应交互（比如思考过程展示、工具调用链路），模型本身不具备的能力勾了只会报错。所以正确做法是逐项对照模型文档勾选，不确定的能力先关，配通后再逐个开启验证——这也是排查 400 类错误的标准路径。
最后一步：切换生效
配置保存后，在对话输入框右下角的模型菜单中选中新增的自定义模型。保存 ≠ 切换——不手动选中，对话仍走原模型，这是「配了但不生效」类问题里占比最高的原因。
验证时建议交叉核对：客户端回复正常后，查看服务商控制台日志确认请求落在预期模型，再逐项验证能力开关。
排错速查表（按三层归类）
| 现象 | 所属层 | 处理 |
|---|---|---|
| 连接超时 / 404（路径） | 接口地址 | 确认地址层级，完整到 /v1/chat/completions |
| 404（模型） | 模型标识 | 复制完整模型 ID |
| 403 / model not allowed | 令牌权限 | 放行该模型 |
| 401 | 凭证 | 重新生成 Key |
| 能力开启后 400 | 能力声明 | 逐个关闭高级参数定位 |
| 保存后仍走旧模型 | 切换 | 右下角手动选中模型 |
小结
自定义模型接入看似是「填表」，实际是接口路由、模型路由、协议特性三层的一次对齐。把这三层检查清单沉淀下来，换任何客户端、任何模型服务都能快速定位问题：先确认地址层级，再核对模型 ID 与令牌权限，最后对齐能力声明。
参考文档（WorkBuddy 图文配置）：https://docs.julanjing.com/docs/tutorial-workbuddy.html。欢迎交流各位在多客户端、多模型环境下的配置管理实践。