WorkBuddy 集成指南

将 KOPRouter 添加为 WorkBuddy 的自定义模型服务后，即可在 WorkBuddy 中使用 KOPRouter 已配置的模型，并统一通过 KOPRouter 的 API Key 进行鉴权和用量结算。

**开始前请准备**

已安装并登录 WorkBuddy
一个状态正常且余额充足的 KOPRouter 账户
准备接入的 KOPRouter 模型名称，例如 deepseek-flash

核心配置

接入 KOPRouter 需要三个参数：

Base URL / 接口地址：https://koprouter.kopglobal.com/v1（KOPRouter 的 OpenAI 兼容根地址）
API Key：你的 KOPRouter API Key（sk- 开头）
模型名称：KOPRouter 中的完整模型名称，例如 deepseek-flash

方式一：写入 models.json（推荐）

WorkBuddy 读取本地配置文件 ~/.workbuddy/models.json，把上面三个参数一次填好即可，无需在界面里逐项点击。

文件路径为 `~/.workbuddy/models.json`。若 `.workbuddy` 目录不存在，先创建：

```bash
mkdir -p ~/.workbuddy
nano ~/.workbuddy/models.json
```

文件路径为 `%USERPROFILE%\.workbuddy\models.json`（通常为 `C:\Users\<用户名>\.workbuddy\models.json`）。以 CMD 为例：

```bat
if not exist "%USERPROFILE%\.workbuddy" mkdir "%USERPROFILE%\.workbuddy"
notepad "%USERPROFILE%\.workbuddy\models.json"
```

写入以下内容（文件需保存为 UTF-8 编码、无 BOM）：

{
  "models": [
    {
      "id": "MODEL_ID",
      "name": "KOPRouter - MODEL_ID",
      "vendor": "Custom",
      "url": "https://koprouter.kopglobal.com/v1/chat/completions",
      "apiKey": "sk-..."
    }
  ],
  "availableModels": ["MODEL_ID"]
}

其中 MODEL_ID 换成 KOPRouter 中的完整模型名称。

* `url` 必须是完整接口地址，以 `/chat/completions` 结尾；只写 `https://koprouter.kopglobal.com/v1` 会导致请求失败。 * `id` 必须与 KOPRouter 提供的模型名称**完全一致**（含大小写、连字符、版本号），否则会提示模型不存在。 * `apiKey` 直接填 Key 本身，**不要**加 `Bearer` 前缀。 * 保存后需**完全退出并重启 WorkBuddy**（仅关闭窗口可能不够，请检查系统托盘 / 任务管理器中是否仍有残留进程）。 * 内联 Key 以明文存储，建议执行 `chmod 600 ~/.workbuddy/models.json` 且勿提交进 git。 * 可选字段：`maxInputTokens`、`maxOutputTokens`、`supportsToolCall`、`supportsImages` 可按所选模型实际能力填写；不确定时省略。 * `availableModels` 控制模型下拉列表中显示的模型 ID，只列出你希望出现的 ID。 * 若不想把 Key 明文写进文件，`apiKey` 支持 `${变量名}` 语法，从同名环境变量读取（变量缺失时该占位符会原样保留并导致请求失败）。

方式二：界面配置

API Key 通常以 sk- 开头。请妥善保存，不要通过聊天、截图或公开文档分享给他人。

在 KOPRouter 的 API 密钥页面创建并复制 API Key — 在 KOPRouter 的“API 密钥”页面创建并复制密钥

打开 WorkBuddy，在对话输入框右下角点击当前模型名称，展开模型列表，然后点击列表底部的 配置自定义模型。

在 WorkBuddy 模型列表中点击配置自定义模型 — 在模型列表底部进入“配置自定义模型”

在自定义模型页面点击 添加模型。打开“供应商”下拉列表，在其他分类中选择 自定义。KOPRouter 提供 OpenAI 兼容接口，因此不需要选择某个具体的官方供应商。

按照下面的内容填写模型配置：

Base URLhttps://koprouter.kopglobal.com/v1 API Key填写第 1 步复制的 KOPRouter API Key 模型名称填写 KOPRouter 中的完整模型名称，例如 deepseek-flash

模型名称必须与 KOPRouter 提供的模型名称完全一致，包括大小写、连字符和版本号，否则会提示模型不存在。

建议保持 自定义协议 关闭。关闭时，WorkBuddy 会在 Base URL 后自动补全标准的 /chat/completions 路径。工具调用、图片输入和推理模式等能力，请根据所选模型的实际能力开启。

确认无误后点击保存。如 WorkBuddy 提供连接测试，可先完成测试再返回对话页面。

返回 WorkBuddy 对话页面，再次打开模型列表，在自定义模型分组中选择刚刚添加的模型。确认输入框旁显示的是该自定义模型名称后，即可开始对话。

建议首次发送一句简短内容（例如“请回复 OK”），然后在 KOPRouter 的 用量明细 中确认出现了对应模型的调用记录。

常见问题

需完全退出并重启 WorkBuddy（仅关闭窗口可能不够，请检查系统托盘 / 任务管理器中是否仍有残留进程）。确认文件保存为 UTF-8 编码、无 BOM，且 JSON 格式正确。先确认发送消息时实际选择的仍然是自定义模型。WorkBuddy 会话重启或恢复后可能切回内置模型；重新选择自定义模型并新建对话后，再发送一条简短消息测试。重新从 KOPRouter 的“API 密钥”页面复制完整密钥，检查前后是否带有空格，并确认该密钥没有被禁用或删除；使用 models.json 方式时，确认 `apiKey` 未添加 `Bearer` 前缀。检查 WorkBuddy 中填写的模型名称，确保它与 KOPRouter 中的模型名称完全一致。模型的显示名称和实际模型 ID 不一致时，应填写实际模型 ID。界面方式推荐使用 https://koprouter.kopglobal.com/v1 并关闭“自定义协议”。如果启用了“自定义协议”，WorkBuddy 不会自动补全路径，此时必须填写完整接口地址 https://koprouter.kopglobal.com/v1/chat/completions；models.json 方式则必须填写完整地址 https://koprouter.kopglobal.com/v1/chat/completions。集成完成后，WorkBuddy 发起的模型调用会和其他 API 调用一样记录在 KOPRouter 的“用量明细”中，并按照 KOPRouter 配置的模型价格扣除积分。 **无法连接（网络受限）？**

若所在网络无法直连 KOPRouter（如中国大陆），请在 WorkBuddy 的「设置 → 网络 / 代理」里填写 HTTP 代理地址（7890 只是示例端口，请换成你自己的代理端口），无需设置环境变量；或开启系统代理（TUN / 全局模式），详见「网络与代理配置」。