接入 WorkBuddy

一句话结论：WorkBuddy 走 OpenAI 兼容协议。 在「设置 → 模型 → 添加模型」里选 自定义 / Custom，填 URL、API Key、模型名三样，保存即生效。

项目	值
入口	设置 → 模型 → 添加模型 → 自定义 / Custom
URL	https://api.ziai.lol/v1
协议	OpenAI Chat Completions（标准 /chat/completions 路径）
配置存储	本地 workbuddy/models.json（不上传云端）
生效方式	保存即生效

前提

• 已安装 WorkBuddy（官方文档）
• 已有 ZiAI 密钥与模型 ID

配置步骤

1. 打开模型设置

   进入 设置 → 模型。这里可以图形化管理自定义模型，无需手动编辑配置文件。

   

   图片来源：WorkBuddy 官方文档

2. 点击「添加模型」

   弹出添加模型对话框。接入方式分三类：提供商接入（内置预设）、本地部署（Ollama）、自定义。

   

   图片来源：WorkBuddy 官方文档

3. 选择「自定义 / Custom」

   ZiAI 不在 WorkBuddy 的内置厂商预设列表里，选自定义手动填写。

   

   图片来源：WorkBuddy 官方文档

4. 填写三项配置

   字段	填什么
   URL	https://api.ziai.lol/v1
   API Key	sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   模型名	从 ZiAI 逐字复制的模型 ID

5. 确认「自定义协议」开关保持关闭

   见下方详解。ZiAI 路径规范，不需要开启。

6. 确认能力标记

   选择标准供应商时，工具调用、图片输入、推理模式等能力标记会自动写入； 自定义模型需要你自己确认，缺失时表现为不触发工具调用或图片被忽略。

7. 保存

   配置自动持久化到本地 workbuddy/models.json。回到对话界面，在模型选择器里即可看到自定义模型分组， 并支持快捷跳转到配置界面编辑。

「自定义协议」开关

这是 WorkBuddy 接入中转站时唯一需要判断的选项，位于高级配置中：

状态	行为
关闭（默认）	使用标准 /chat/completions 路径，自动校验并补全接口地址
开启	直接按你填写的接口地址发起请求，跳过路径校验与自动补全

ZiAI 应该选哪个

保持关闭，URL 填到 /v1

ZiAI 对外就是 https://api.ziai.lol/v1/chat/completions。 开关关闭 + URL 填 https://api.ziai.lol/v1，WorkBuddy 自动补上 /chat/completions，正好命中。

什么时候才需要开启

官方说明：当模型服务使用非标准 URL 路径（如经过网关或代理层封装）时，才开启此开关。 例如上游要求的路径不是 /chat/completions，或带多层前缀。

开启后必须把完整端点地址填进 URL（因为不再自动补全）。 判断方法：先用 curl 打通，把能通的那个完整地址原样填进去，再开启开关。

curl https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

模型模式与参数

WorkBuddy 提供三档模型模式，按任务复杂度选择。这个选择直接影响 Token 消耗：

模式	适用场景	特点
快速模式	日常问答、格式转换、小段代码修改、文案润色	响应最快，消耗最低
均衡模式	写文档、分析数据、多文件代码改动	效果与速度兼顾，不确定选哪档时用它
极致模式	跨模块重构、多步骤推理、需反复验证的分析	响应稍慢，消耗更高，复杂任务更稳定

思考强度

对应模型给出答案前的推理投入，可选等级取决于模型自身支持的档位。 强度越高，模型做更多分析与自我检查，适合逻辑链条长、容易出错的任务；强度越低倾向直接作答，响应更快。 默认值已适合绝大多数任务，一般无需单独调整。

上下文窗口

默认 200K，适用于绝大多数任务。

上下文窗口不是越大越好

每一轮对话都会把当前完整上下文发送给模型，上下文越大单轮消耗的额度就越多。 开到 1M 不会让模型变聪明，只会让每轮消耗成倍增加。

建议保持默认 200K。只有在处理超长文档、或需要模型完整记住大量历史内容时才调大。 详见省 Token 建议。

Max 模式

状态	行为
关闭（默认，推荐）	系统在合适时机自动触发上下文压缩，减少长对话中重复传输的内容，降低消耗
开启	全程完整保留上下文、不做压缩，细节一点不丢，代价是长对话消耗明显更快

仅在确实需要超长上下文时开启。

数据与隐私

官方说明的边界，接入前值得了解：

• 配置（含 API Key）仅保存在本地 workbuddy/models.json，不上传云端
• WorkBuddy 仅作为通信链路：把你的输入直接转发至所配置的模型，输出由该模型直接返回
• 除为完成请求、必要传输、安全审计、故障排查、依法留存所必需外，WorkBuddy 不读取、不存储相关内容
• 已通过旧路径 ~/.codebuddy/models.json 配置的自定义模型，在界面升级后仍可正常使用，并可通过 UI 查看、编辑或删除

费用由你直接向 ZiAI 结算

官方明确：自定义模型产生的全部费用（Token、订阅等）由你向第三方支付，WorkBuddy 不代收。 也就是说这些调用走的是你的 ZiAI 账户额度，请在 ZiAI 控制台日志页对账。

过程中可能持续触发模型调用，建议密切关注你在 ZiAI 的账户余额，避免超出预期支出。

密钥保管

• 请勿把 API Key 分享给他人 —— 它关联你的账户与额度，泄露会导致额度被盗用
• 避免在共享环境中填写或导出密钥
• 不再使用时，建议在 models.json 中清理，或直接在 UI 里删除该模型
• 接入前建议阅读 ZiAI 的服务协议与隐私政策，确认符合你的数据安全与合规要求

验证

保存后在对话界面的模型选择器里选中该自定义模型，发一句简单指令。能收到回复即成功。

命令行独立验证 ZiAI 侧：

curl https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

WorkBuddy 专属常见问题

现象	原因	解决
404 / 请求地址不对	URL 少填 /v1，或开了「自定义协议」却没填完整端点	关闭开关并填到 /v1；或开启开关并填完整路径
保存成功但选不到模型	模型名填错，或未保存成功	从 ZiAI /v1/models 逐字复制模型 ID 重新添加
不触发工具调用	自定义模型的能力标记未勾选	编辑模型，确认「工具调用」标记
发图片被忽略或报错	「图片输入」能力标记未勾选，或该模型不支持视觉	确认标记；换支持视觉的模型
401	密钥错误、过期、被禁用，或设了 IP 白名单	在 ZiAI 控制台确认密钥状态
账单比预期高	上下文窗口开太大或 Max 模式开启	窗口调回 200K、关闭 Max 模式、简单任务用快速模式
旧配置不见了	升级后路径变更	旧 ~/.codebuddy/models.json 仍兼容，可在 UI 中查看与编辑

下一步

• 其他客户端：配置速查表
• 用量与花费：计费、配额与限速
• 报错排查：常见报错速查