> ## Documentation Index > Fetch the complete documentation index at: https://docs.haitoken.ai/llms.txt > Use this file to discover all available pages before exploring further. # WorkBuddy > 通过 HaiToken 网关接入 WorkBuddy WorkBuddy 支持通过自定义模型接入 HaiToken。最常用的接入方式有两种： 1. 在 WorkBuddy 界面里直接新增自定义模型，适合先快速验证 2. 通过本地 `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` | 填写 HaiToken 接入信息 ### 步骤 4：按需调整高级配置 如果当前界面还提供能力开关，按模型实际能力调整： * 支持工具调用时开启 `Tool Call` 或类似选项 * 支持推理模式时开启 `Reasoning` 或类似选项 * 如果当前模型不支持图像输入，不要勾选图片能力 ### 步骤 5：返回聊天界面验证 保存后回到聊天界面，切换到刚刚添加的模型，发送一条简单测试消息，例如 `hi` 或 `介绍一下自己`。 如果可以正常返回内容，说明接入成功。 ### 自检清单 完成后按顺序检查这 3 项： 1. 模型下拉框里已经能看到你刚添加的模型 2. 发送一条测试消息后可以正常返回内容 3. 如果当前场景支持流式输出，回复会逐步出现，而不是最后一次性返回 ### 常见问题 #### 模型没有出现在列表里 优先检查下面几项： * 模型名称填写的是否是 HaiToken 实际支持的模型 ID * 接口地址是否填写为完整的 `https://api.haitoken.ai/v1/chat/completions` * 保存后是否重新进入过模型列表，或重新打开过 WorkBuddy #### 报认证错误 确认你在界面中填写的 API Key 是否有效，是否有多复制空格，或者是否误填成了其他平台的密钥。 #### 能发送请求，但模型无响应 优先检查模型 ID 是否存在、接口地址是否完整，以及当前模型是否支持你勾选的高级能力。 界面快速添加更适合临时验证。若你需要批量维护多个模型、按项目区分模型列表，建议继续使用下面的 `models.json` 方式。 ## 方式二：通过本地 `models.json` 配置 这条路径适合长期维护模型列表，或者想按项目保留固定配置时使用。 WorkBuddy / CodeBuddy 当前常见有两种配置范围： * 用户级：`~/.codebuddy/models.json` * 项目级：`/.codebuddy/models.json` 如果你只想让当前项目使用 HaiToken，优先使用项目级配置；如果希望所有项目都可见，使用用户级配置。 ### 步骤 1：确定配置范围并创建 `models.json` 先决定要把配置放在哪个范围，再新建或编辑 `models.json`： 请保存为 UTF-8 无 BOM 编码。部分桌面版本读取带 BOM 的 `models.json` 时可能会失败。 ### 步骤 2：写入 HaiToken 模型配置 下面是一份可直接参考的最小示例： ```json theme={null} { "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： ```powershell theme={null} $env:HAITOKEN_API_KEY = "YOUR_API_KEY" ``` macOS / Linux： ```bash theme={null} export HAITOKEN_API_KEY="YOUR_API_KEY" ``` ### 步骤 4：保存并重新加载 WorkBuddy 保存配置后，先观察 WorkBuddy 是否自动刷新模型列表。 如果模型没有立即出现，完全退出 WorkBuddy 再重新打开一次，通常会更稳妥。 ### 关键配置说明 #### `url` 必须填写完整接口路径 无论你是通过界面新增模型，还是通过 `models.json` 注册模型，`url` 都必须直接指向完整接口： ```text theme={null} https://api.haitoken.ai/v1/chat/completions ``` 下面这些写法都不建议使用： ```text theme={null} https://api.haitoken.ai https://api.haitoken.ai/v1 ``` #### `apiKey` 对应 Bearer Token WorkBuddy 这条链路期望发送的是： ```http theme={null} 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 能看到哪些模型： ```bash theme={null} curl https://api.haitoken.ai/v1/models \ -H "Authorization: Bearer YOUR_API_KEY" ``` 然后把返回结果里的 `id` 原样写入界面中的模型 ID，或者写入 `models[].id`，再决定是否把它加入 `availableModels`。 #### `relatedModels` 什么时候有用 如果你希望主模型在不同场景下自动切到更快或更强的模型，可以给主模型配置 `relatedModels`。常见做法是： * `lite` 指向更快、更省成本的模型 * `reasoning` 指向推理能力更强的模型 ### 自检清单 完成配置后，建议按下面顺序检查： 1. WorkBuddy 的模型下拉框里能看到 `HaiToken DeepSeek V4 Flash` 或你配置的模型名称 2. 发起一条简单对话后可以正常返回内容，没有认证失败或模型不存在报错 3. 开启流式输出时，回复会持续增量出现，而不是一直卡住到最后一次性返回 如果当前入口支持流式输出，第 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 输出，并对部分客户端流式请求的兼容头做了适配。