WorkBuddy

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

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

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

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

协议说明

WorkBuddy 的自定义模型接入只支持 OpenAI Chat Completions 协议，不支持 Anthropic Messages 协议。因此本文档只覆盖 OpenAI 模式，请求地址固定为完整接口 https://api.haitoken.ai/v1/chat/completions。

WorkBuddy 的界面快速接入步骤在 Windows、macOS、Linux 下通常差异不大；真正更容易受系统影响的是 models.json 路径、环境变量写法，以及 ~ 代表的用户主目录位置。

先准备好这些信息

HaiToken API Key
至少一个可用模型 ID，例如 gpt-5.4
完整聊天补全地址：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 里无论是界面快速添加，还是 models.json，模型字段都应该填写 HaiToken 首页或模型列表里的模型编号（model ID），不要填展示名称。展示名称可以自定义，但真正请求时匹配的是模型编号。

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

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

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

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

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

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

步骤 3：填写 HaiToken 配置

按下面的值填写：

字段	推荐填写值
Provider	`Custom`
Endpoint	`https://api.haitoken.ai/v1/chat/completions`
API Key	你的 HaiToken API Key
模型名称	HaiToken 实际支持的模型 ID，例如 `gpt-5.4`

步骤 4：按需调整高级能力

如果当前界面提供高级能力开关，请根据模型真实能力来勾选：

只有模型支持工具调用时再开启 Tool Call
只有模型支持推理模式时再开启 Reasoning
如果模型不支持图片输入，就不要开启图片相关能力

步骤 5：返回聊天界面测试

切换到刚刚新增的模型，发送一条简单消息，例如 hi。如果可以正常返回内容，说明接入成功。

自检清单

模型已经出现在 WorkBuddy 的模型下拉框中。
发送一条简单测试消息后能够正常返回。
如果当前入口支持流式输出，回复应该是逐步显示，而不是最后一次性出现。

常见问题

问题	解决方案
模型没有出现在列表里	优先检查模型名称是否就是 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

不同系统下可以这样理解：

Windows：~ 通常对应 %USERPROFILE%，因此用户级路径常见可理解为 %USERPROFILE%\.codebuddy\models.json
macOS：~ 通常对应 /Users/<你的用户名>
Linux：~ 通常对应 /home/<你的用户名>

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

步骤 1：选择作用范围并创建 `models.json`

先决定这份配置是放在用户级还是项目级，然后在对应目录下创建或编辑 models.json。文件编码建议使用 UTF-8 无 BOM。某些桌面版本在读取带 BOM 的 models.json 时会失败。

步骤 2：写入 HaiToken 模型

参考示例：

{
  "models": [
    {
      "id": "gpt-5.4",
      "name": "HaiToken GPT-5.4",
      "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": "gpt-5.4",
      "name": "HaiToken GPT-5.4",
      "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": "gpt-5.4",
        "reasoning": "gpt-5.4"
      }
    }
  ],
  "availableModels": [
    "gpt-5.4",
    "gpt-5.4"
  ]
}

步骤 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 鉴权

WorkBuddy 这里走的是：

Authorization: Bearer YOUR_API_KEY

如果你在 models.json 中写的是 ${HAITOKEN_API_KEY}，WorkBuddy 会先读取环境变量，再按 Bearer 方式发送，不是 X-Api-Key。

`availableModels` 是做什么的

如果你走的是 models.json 路径，availableModels 控制的是哪些模型会出现在 WorkBuddy 的可选列表里；它不决定 HaiToken 是否真的支持这个模型。

`availableModels` 和 `/v1/models` 是什么关系

这两者很容易混淆：

GET /v1/models 代表当前 API Key 在 HaiToken 侧实际可见的模型集合
models[].id 是你在本地给 WorkBuddy 注册的模型 ID，必须和 HaiToken 返回的模型 ID 对得上
availableModels 只是本地决定哪些模型要显示在 WorkBuddy 下拉框中

你可以这样理解：本地 models.json 决定 WorkBuddy 展示和尝试调用哪些模型，而 HaiToken 的 GET /v1/models 决定你的 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 GPT-5.4 或你配置的模型名称。
发起一条简单对话后，能够正常返回内容，且没有认证失败或模型不存在的报错。
如果当前入口支持流式输出，回复应逐步显示，而不是最后一次性出现。

常见问题

问题	解决方案
模型没有出现在列表里	如果你走的是界面快速添加，优先检查模型 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 输出，并对部分客户端流式请求的兼容头做了适配。

VPN 或代理导致连接异常

使用 VPN、系统代理或 TUN 模式时出现连接错误或请求超时，请查看 VPN 与代理连接排障。其中说明了系统代理与 TUN 模式的差异，以及 WorkBuddy 的对应设置。

快速开始

API文档

AI工具接入

其它

协议说明

先准备好这些信息

配置关系速览

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

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

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

步骤 3：填写 HaiToken 配置

步骤 4：按需调整高级能力

步骤 5：返回聊天界面测试

自检清单

常见问题

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

步骤 1：选择作用范围并创建 `models.json`

步骤 2：写入 HaiToken 模型

步骤 3：设置环境变量

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

关键说明

`url` 必须填写完整接口地址

`apiKey` 实际会变成 Bearer 鉴权

`availableModels` 是做什么的

`availableModels` 和 `/v1/models` 是什么关系

`relatedModels` 什么时候有用

自检清单

常见问题

VPN 或代理导致连接异常

下一步

​协议说明

​先准备好这些信息

​配置关系速览

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

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

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

​步骤 3：填写 HaiToken 配置

​步骤 4：按需调整高级能力

​步骤 5：返回聊天界面测试

​自检清单

​常见问题

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

​步骤 1：选择作用范围并创建 models.json

​步骤 2：写入 HaiToken 模型

​步骤 3：设置环境变量

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

​关键说明

​url 必须填写完整接口地址

​apiKey 实际会变成 Bearer 鉴权

​availableModels 是做什么的

​availableModels 和 /v1/models 是什么关系

​relatedModels 什么时候有用

​自检清单

​常见问题

​VPN 或代理导致连接异常

​下一步

协议说明

先准备好这些信息

配置关系速览

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

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

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

步骤 3：填写 HaiToken 配置

步骤 4：按需调整高级能力

步骤 5：返回聊天界面测试

自检清单

常见问题

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

步骤 1：选择作用范围并创建 `models.json`

步骤 2：写入 HaiToken 模型

步骤 3：设置环境变量

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

关键说明

`url` 必须填写完整接口地址

`apiKey` 实际会变成 Bearer 鉴权

`availableModels` 是做什么的

`availableModels` 和 `/v1/models` 是什么关系

`relatedModels` 什么时候有用

自检清单

常见问题

VPN 或代理导致连接异常

下一步