> ## Documentation Index > Fetch the complete documentation index at: https://docs.hairoute.ai/llms.txt > Use this file to discover all available pages before exploring further. # WorkBuddy > 通过 HaiRoute 网关接入 WorkBuddy WorkBuddy 支持通过自定义模型接入 HaiRoute。最常用的接入方式有两种： 1. 在 WorkBuddy 界面里直接新增自定义模型，适合先快速验证 2. 通过本地 `models.json` 统一维护模型，适合长期使用或按项目管理 两种方式的核心配置完全一致： * 请求地址填写完整接口 `https://api.hairoute.ai/v1/chat/completions` * 模型名称填写 HaiRoute 实际可用的模型 ID * API Key 使用你的 HaiRoute API Key ## 协议说明 WorkBuddy 的自定义模型接入只支持 OpenAI Chat Completions 协议，不支持 Anthropic Messages 协议。因此本文档只覆盖 OpenAI 模式，请求地址固定为完整接口 `https://api.hairoute.ai/v1/chat/completions`。 WorkBuddy 的界面快速接入步骤在 Windows、macOS、Linux 下通常差异不大；真正更容易受系统影响的是 `models.json` 路径、环境变量写法，以及 `~` 代表的用户主目录位置。 ## 先准备好这些信息 * HaiRoute API Key * 至少一个可用模型 ID，例如 `gpt-5.4` * 完整聊天补全地址：`https://api.hairoute.ai/v1/chat/completions` ## 配置关系速览 | 项目 | 说明 | | ------------- | --------------------------------------------- | | 实际请求 endpoint | `https://api.hairoute.ai/v1/chat/completions` | | 协议类型 | OpenAI Chat Completions | | 鉴权头 | `Authorization: Bearer YOUR_API_KEY` | | 模型来源 | 界面新增的自定义模型或本地 `models.json` 中注册的模型 | WorkBuddy 这里填写的不是通用 `Base URL`，而是完整接口地址 `https://api.hairoute.ai/v1/chat/completions`。 WorkBuddy 里无论是界面快速添加，还是 `models.json`，模型字段都应该填写 HaiRoute 首页或模型列表里的**模型编号（model ID）**，不要填展示名称。展示名称可以自定义，但真正请求时匹配的是模型编号。 ## 方式一：在 WorkBuddy 界面中快速添加 适合先跑通一次接入。照着下面 5 步做即可。 ### 步骤 1：打开自定义模型入口 进入聊天界面，点击当前模型，在下拉菜单中选择 **配置自定义模型**。 打开自定义模型入口 ### 步骤 2：选择 `自定义 / Custom` 进入“添加模型”弹窗后，在提供商列表中选择 **自定义 / Custom**。 选择自定义 Provider ### 步骤 3：填写 HaiRoute 配置 按下面的值填写： | 字段 | 推荐填写值 | | -------- | --------------------------------------------- | | Provider | `Custom` | | Endpoint | `https://api.hairoute.ai/v1/chat/completions` | | API Key | 你的 HaiRoute API Key | | 模型名称 | HaiRoute 实际支持的模型 ID，例如 `gpt-5.4` | 填写 HaiRoute 连接表单 ### 步骤 4：按需调整高级能力 如果当前界面提供高级能力开关，请根据模型真实能力来勾选： * 只有模型支持工具调用时再开启 `Tool Call` * 只有模型支持推理模式时再开启 `Reasoning` * 如果模型不支持图片输入，就不要开启图片相关能力 ### 步骤 5：返回聊天界面测试 切换到刚刚新增的模型，发送一条简单消息，例如 `hi`。 如果可以正常返回内容，说明接入成功。 ### 自检清单 1. 模型已经出现在 WorkBuddy 的模型下拉框中。 2. 发送一条简单测试消息后能够正常返回。 3. 如果当前入口支持流式输出，回复应该是逐步显示，而不是最后一次性出现。 ### 常见问题 | 问题 | 解决方案 | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | 模型没有出现在列表里 | 优先检查模型名称是否就是 HaiRoute 实际支持的模型 ID、接口地址是否填写为完整的 `https://api.hairoute.ai/v1/chat/completions`，以及保存后是否重新进入过模型列表或重新打开过 WorkBuddy。 | | 报认证错误 | 确认你在界面中填写的 API Key 是否有效，是否多复制了空格，或者是否误填成了其他平台的密钥。 | | 能发送请求，但模型无响应 | 优先检查模型 ID 是否存在、接口地址是否完整，以及当前模型是否支持你勾选的高级能力。 | 界面快速添加更适合先验证连通性。如果你要长期维护多个模型，或者想按项目区分模型配置，建议使用下面的 `models.json` 方式。 ## 方式二：配置本地 `models.json` 这种方式更适合长期维护模型。 WorkBuddy / CodeBuddy 当前常见有两种配置范围： * 用户级：`~/.codebuddy/models.json` * 项目级：`/.codebuddy/models.json` 不同系统下可以这样理解： * Windows：`~` 通常对应 `%USERPROFILE%`，因此用户级路径常见可理解为 `%USERPROFILE%\.codebuddy\models.json` * macOS：`~` 通常对应 `/Users/<你的用户名>` * Linux：`~` 通常对应 `/home/<你的用户名>` 如果你只想让当前项目使用 HaiRoute，优先使用项目级配置；如果希望所有项目都可见，使用用户级配置。 ### 步骤 1：选择作用范围并创建 `models.json` 先决定这份配置是放在用户级还是项目级，然后在对应目录下创建或编辑 `models.json`。 文件编码建议使用 UTF-8 无 BOM。某些桌面版本在读取带 BOM 的 `models.json` 时会失败。 ### 步骤 2：写入 HaiRoute 模型 参考示例： ```json theme={null} { "models": [ { "id": "gpt-5.4", "name": "HaiRoute GPT-5.4", "vendor": "HaiRoute", "url": "https://api.hairoute.ai/v1/chat/completions", "apiKey": "${HAIROUTE_API_KEY}", "maxInputTokens": 128000, "maxOutputTokens": 8192, "supportsToolCall": true, "supportsImages": false, "supportsReasoning": true }, { "id": "gpt-5.4", "name": "HaiRoute GPT-5.4", "vendor": "HaiRoute", "url": "https://api.hairoute.ai/v1/chat/completions", "apiKey": "${HAIROUTE_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：设置环境变量 如果你使用 `${HAIROUTE_API_KEY}`，请在启动 WorkBuddy 之前先设置这个环境变量。 Windows PowerShell： ```powershell theme={null} $env:HAIROUTE_API_KEY = "YOUR_API_KEY" ``` macOS / Linux： ```bash theme={null} export HAIROUTE_API_KEY="YOUR_API_KEY" ``` ### 步骤 4：保存后重新加载 WorkBuddy 保存文件后，先观察 WorkBuddy 是否已经自动刷新模型列表。 如果模型仍然没有出现，再完全退出 WorkBuddy 并重新打开一次。 ### 关键说明 #### `url` 必须填写完整接口地址 无论是界面新增还是 `models.json`，`url` 都应写成： ```text theme={null} https://api.hairoute.ai/v1/chat/completions ``` 不要写成： ```text theme={null} https://api.hairoute.ai https://api.hairoute.ai/v1 ``` #### `apiKey` 实际会变成 Bearer 鉴权 WorkBuddy 这里走的是： ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` 如果你在 `models.json` 中写的是 `${HAIROUTE_API_KEY}`，WorkBuddy 会先读取环境变量，再按 Bearer 方式发送，不是 `X-Api-Key`。 #### `availableModels` 是做什么的 如果你走的是 `models.json` 路径，`availableModels` 控制的是哪些模型会出现在 WorkBuddy 的可选列表里；它不决定 HaiRoute 是否真的支持这个模型。 #### `availableModels` 和 `/v1/models` 是什么关系 这两者很容易混淆： * `GET /v1/models` 代表当前 API Key 在 HaiRoute 侧实际可见的模型集合 * `models[].id` 是你在本地给 WorkBuddy 注册的模型 ID，必须和 HaiRoute 返回的模型 ID 对得上 * `availableModels` 只是本地决定哪些模型要显示在 WorkBuddy 下拉框中 你可以这样理解：本地 `models.json` 决定 WorkBuddy 展示和尝试调用哪些模型，而 HaiRoute 的 `GET /v1/models` 决定你的 API Key 实际能访问哪些模型。 如有需要，可以先检查模型列表： ```bash theme={null} curl https://api.hairoute.ai/v1/models \ -H "Authorization: Bearer YOUR_API_KEY" ``` 然后把返回结果里的 `id` 原样写入界面中的模型 ID，或者写入 `models[].id`，再决定是否把它加入 `availableModels`。 #### `relatedModels` 什么时候有用 如果你希望一个主模型在不同场景下自动切换到更快或更强的模型，可以配置 `relatedModels`。 * `lite` 通常指向更快、更省钱的模型 * `reasoning` 通常指向推理更强的模型 ### 自检清单 1. WorkBuddy 的模型下拉框里能看到 `HaiRoute GPT-5.4` 或你配置的模型名称。 2. 发起一条简单对话后，能够正常返回内容，且没有认证失败或模型不存在的报错。 3. 如果当前入口支持流式输出，回复应逐步显示，而不是最后一次性出现。 ## 常见问题 | 问题 | 解决方案 | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 模型没有出现在列表里 | 如果你走的是界面快速添加，优先检查模型 ID 是否与 HaiRoute `GET /v1/models` 返回值完全一致、`url` 是否填写成完整接口地址、保存后是否已经重新打开 WorkBuddy 或重新进入模型列表；如果你走的是 `models.json` 方式，再额外检查 `models.json` 是否放在正确路径、JSON 格式是否有效，以及 `availableModels` 是否漏掉了你的模型 ID。 | | 报认证错误 | 确认你填写的 API Key 有效，或者确认 `HAIROUTE_API_KEY` 已经在启动 WorkBuddy 的同一环境中生效。 | | 报 `404` 或连接错误 | 通常是 `url` 写错了。WorkBuddy 这里必须填写完整接口路径 `https://api.hairoute.ai/v1/chat/completions`。 | | 能返回结果，但不是流式输出 | 先确认你当前使用的 WorkBuddy 功能入口本身支持流式；如果支持但表现异常，优先换一个模型再测一次。HaiRoute 网关支持流式 SSE 输出，并对部分客户端流式请求的兼容头做了适配。 | ### VPN 或代理导致连接异常 使用 VPN、系统代理或 TUN 模式时出现连接错误或请求超时，请查看 [VPN 与代理连接排障](/docs/zh/others/vpn-proxy)。其中说明了系统代理与 TUN 模式的差异，以及 WorkBuddy 的对应设置。 ## 下一步 * 查看 [获取 API Key](/docs/zh/quickstart/get-api-key) * 查看 [OpenAI 格式 API 文档](/docs/zh/api-reference/chat/openai-format) * 查看 [模型列表](/docs/zh/api-reference/models/list-models)