WorkBuddy - HaiToken Doc

WorkBuddy 支持通过自定义模型接入 HaiToken。最常用的接入方式有两种：

在 WorkBuddy 界面里直接新增自定义模型，适合先快速验证
通过本地 models.json 统一维护模型，适合长期使用或按项目管理

两种方式的核心配置完全一致：

请求地址填写完整接口 https://api.haitoken.ai/v1/chat/completions
模型名称填写 HaiToken 实际可用的模型 ID
API Key 使用你的 HaiToken API Key

先准备好这些信息

HaiToken API Key
至少一个可用模型 ID，例如 deepseek-v4-flash
完整聊天补全地址：https://api.haitoken.ai/v1/chat/completions

配置关系速览

项目	说明
实际请求 endpoint	`https://api.haitoken.ai/v1/chat/completions`
协议类型	OpenAI Chat Completions
鉴权头	`Authorization: Bearer YOUR_API_KEY`
模型来源	界面新增的自定义模型或本地 `models.json` 中注册的模型

WorkBuddy 这里填写的不是通用 Base URL，而是完整接口地址 https://api.haitoken.ai/v1/chat/completions。

方式一：在 WorkBuddy 界面中快速添加

适合先跑通一次接入。照着下面 5 步做即可。

步骤 1：打开自定义模型入口

进入聊天界面，点击当前模型，在下拉菜单中选择 配置自定义模型。

步骤 2：选择 `自定义 / Custom`

进入“添加模型”弹窗后，在提供商列表中选择 自定义 / Custom。

步骤 3：填写 HaiToken 接入信息

按下面的方式逐项填写，然后点击保存：

字段	推荐填写值
提供商	`自定义 / Custom`
接口地址	`https://api.haitoken.ai/v1/chat/completions`
API Key	你的 HaiToken API Key
模型名称	HaiToken 实际支持的模型 ID，例如 `deepseek-v4-flash`

步骤 4：按需调整高级配置

如果当前界面还提供能力开关，按模型实际能力调整：

支持工具调用时开启 Tool Call 或类似选项
支持推理模式时开启 Reasoning 或类似选项
如果当前模型不支持图像输入，不要勾选图片能力

步骤 5：返回聊天界面验证

保存后回到聊天界面，切换到刚刚添加的模型，发送一条简单测试消息，例如 hi 或 介绍一下自己。如果可以正常返回内容，说明接入成功。

自检清单

完成后按顺序检查这 3 项：

模型下拉框里已经能看到你刚添加的模型
发送一条测试消息后可以正常返回内容
如果当前场景支持流式输出，回复会逐步出现，而不是最后一次性返回

常见问题

模型没有出现在列表里

优先检查下面几项：

模型名称填写的是否是 HaiToken 实际支持的模型 ID
接口地址是否填写为完整的 https://api.haitoken.ai/v1/chat/completions
保存后是否重新进入过模型列表，或重新打开过 WorkBuddy

报认证错误

确认你在界面中填写的 API Key 是否有效，是否有多复制空格，或者是否误填成了其他平台的密钥。

能发送请求，但模型无响应

优先检查模型 ID 是否存在、接口地址是否完整，以及当前模型是否支持你勾选的高级能力。

界面快速添加更适合临时验证。若你需要批量维护多个模型、按项目区分模型列表，建议继续使用下面的 models.json 方式。

方式二：通过本地 `models.json` 配置

这条路径适合长期维护模型列表，或者想按项目保留固定配置时使用。 WorkBuddy / CodeBuddy 当前常见有两种配置范围：

用户级：~/.codebuddy/models.json
项目级：<project-root>/.codebuddy/models.json

如果你只想让当前项目使用 HaiToken，优先使用项目级配置；如果希望所有项目都可见，使用用户级配置。

步骤 1：确定配置范围并创建 `models.json`

先决定要把配置放在哪个范围，再新建或编辑 models.json：请保存为 UTF-8 无 BOM 编码。部分桌面版本读取带 BOM 的 models.json 时可能会失败。

步骤 2：写入 HaiToken 模型配置

下面是一份可直接参考的最小示例：

{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "HaiToken DeepSeek V4 Flash",
      "vendor": "HaiToken",
      "url": "https://api.haitoken.ai/v1/chat/completions",
      "apiKey": "${HAITOKEN_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": true
    },
    {
      "id": "deepseek-v4-pro",
      "name": "HaiToken DeepSeek V4 Pro",
      "vendor": "HaiToken",
      "url": "https://api.haitoken.ai/v1/chat/completions",
      "apiKey": "${HAITOKEN_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": true,
      "relatedModels": {
        "lite": "deepseek-v4-flash",
        "reasoning": "deepseek-v4-pro"
      }
    }
  ],
  "availableModels": [
    "deepseek-v4-flash",
    "deepseek-v4-pro"
  ]
}

步骤 3：设置环境变量

如果你使用 ${HAITOKEN_API_KEY} 这种写法，需要在启动 WorkBuddy 前先设置环境变量。 Windows PowerShell：

$env:HAITOKEN_API_KEY = "YOUR_API_KEY"

macOS / Linux：

export HAITOKEN_API_KEY="YOUR_API_KEY"

步骤 4：保存并重新加载 WorkBuddy

保存配置后，先观察 WorkBuddy 是否自动刷新模型列表。如果模型没有立即出现，完全退出 WorkBuddy 再重新打开一次，通常会更稳妥。

关键配置说明

`url` 必须填写完整接口路径

无论你是通过界面新增模型，还是通过 models.json 注册模型，url 都必须直接指向完整接口：

https://api.haitoken.ai/v1/chat/completions

下面这些写法都不建议使用：

https://api.haitoken.ai
https://api.haitoken.ai/v1

`apiKey` 对应 Bearer Token

WorkBuddy 这条链路期望发送的是：

Authorization: Bearer YOUR_API_KEY

如果你把 apiKey 写为 ${HAITOKEN_API_KEY}，WorkBuddy 实际发请求时会把它解析后放进 Authorization: Bearer ... 请求头，而不是发送 X-Api-Key。

`availableModels` 的作用

如果你使用 models.json，可以通过 availableModels 控制 WorkBuddy 下拉框展示哪些模型。未配置时通常会显示当前可解析到的全部模型。

`availableModels` 和 `/v1/models` 的关系

这两个概念容易混淆，可以直接按下面理解：

GET /v1/models 是 HaiToken 网关返回的“当前 API Key 可见模型集合”
models[].id 是你在本地给 WorkBuddy 注册的模型 ID，必须和 HaiToken 返回的模型 ID 对得上
availableModels 是 WorkBuddy 本地下拉框的显示白名单，只负责“展示哪些”，不负责“网关是否真的支持”

实际可用关系可以理解为：本地 models.json 决定 WorkBuddy 展示和尝试调用哪些模型；而 HaiToken GET /v1/models 更适合在排障时帮助你确认当前 API Key 是否有权访问这些模型。建议你在保存配置前，先用下面命令检查当前 API Key 能看到哪些模型：

curl https://api.haitoken.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

然后把返回结果里的 id 原样写入界面中的模型 ID，或者写入 models[].id，再决定是否把它加入 availableModels。

`relatedModels` 什么时候有用

如果你希望主模型在不同场景下自动切到更快或更强的模型，可以给主模型配置 relatedModels。常见做法是：

lite 指向更快、更省成本的模型
reasoning 指向推理能力更强的模型

自检清单

完成配置后，建议按下面顺序检查：

WorkBuddy 的模型下拉框里能看到 HaiToken DeepSeek V4 Flash 或你配置的模型名称
发起一条简单对话后可以正常返回内容，没有认证失败或模型不存在报错
开启流式输出时，回复会持续增量出现，而不是一直卡住到最后一次性返回

如果当前入口支持流式输出，第 3 点可以作为附加验证项；只要模型可见、请求能正常返回内容、Bearer 鉴权通过，就可以认为基础接入链路已经打通。

常见问题

模型没有出现在列表里

如果你走的是界面快速添加，优先检查：

模型 ID 是否与 HaiToken GET /v1/models 返回值完全一致
url 是否填写成完整接口地址
保存后是否已经重新打开 WorkBuddy 或重新进入模型列表

如果你走的是 models.json 方式，再额外检查：

models.json 是否放在正确路径
JSON 格式是否有效
availableModels 是否漏掉了你的模型 ID

报认证错误

确认你填写的 API Key 有效，或者确认 HAITOKEN_API_KEY 已经在启动 WorkBuddy 的同一环境中生效。

报 404 或连接错误

通常是 url 写错了。WorkBuddy 这里必须填写完整接口路径 https://api.haitoken.ai/v1/chat/completions。

能返回结果，但不是流式输出

先确认你当前使用的 WorkBuddy 功能入口本身支持流式；如果支持但表现异常，优先换一个模型再测一次。HaiToken 网关支持流式 SSE 输出，并对部分客户端流式请求的兼容头做了适配。

​先准备好这些信息

​配置关系速览

​方式一：在 WorkBuddy 界面中快速添加

​步骤 1：打开自定义模型入口

​步骤 2：选择 自定义 / Custom

​步骤 3：填写 HaiToken 接入信息

​步骤 4：按需调整高级配置

​步骤 5：返回聊天界面验证

​自检清单

​常见问题

​模型没有出现在列表里

​报认证错误

​能发送请求，但模型无响应

​方式二：通过本地 models.json 配置

​步骤 1：确定配置范围并创建 models.json

​步骤 2：写入 HaiToken 模型配置

​步骤 3：设置环境变量

​步骤 4：保存并重新加载 WorkBuddy

​关键配置说明

​url 必须填写完整接口路径

​apiKey 对应 Bearer Token

​availableModels 的作用

​availableModels 和 /v1/models 的关系

​relatedModels 什么时候有用

​自检清单

​常见问题

​模型没有出现在列表里

​报认证错误

​报 404 或连接错误

​能返回结果，但不是流式输出

先准备好这些信息

配置关系速览

方式一：在 WorkBuddy 界面中快速添加

步骤 1：打开自定义模型入口

步骤 2：选择 `自定义 / Custom`

步骤 3：填写 HaiToken 接入信息

步骤 4：按需调整高级配置

步骤 5：返回聊天界面验证

自检清单

常见问题

模型没有出现在列表里

报认证错误

能发送请求，但模型无响应

方式二：通过本地 `models.json` 配置

步骤 1：确定配置范围并创建 `models.json`

步骤 2：写入 HaiToken 模型配置

步骤 3：设置环境变量

步骤 4：保存并重新加载 WorkBuddy

关键配置说明

`url` 必须填写完整接口路径

`apiKey` 对应 Bearer Token

`availableModels` 的作用

`availableModels` 和 `/v1/models` 的关系

`relatedModels` 什么时候有用

自检清单

常见问题

模型没有出现在列表里

报认证错误

报 404 或连接错误

能返回结果，但不是流式输出