> 内容来源：Onevium 官方文档
> 文章: 添加自定义服务商
> 原文: https://onevium.com/zh/docs/providers/custom
> 语言：简体中文
> 更新于: 2026-09-09
> 适用版本: 1.1.22+

---

# 添加自定义服务商

为 Claude 兼容网关填写地址、认证和真实模型 ID，配置角色映射，并核对高级环境变量的覆盖关系。

## 何时使用自定义连接

当团队提供 Claude 兼容网关，或需要手动配置预设之外的地址与认证时，使用 **自定义厂商**。如果供方已经出现在[内置预设列表](https://onevium.com/zh/docs/providers#supported-providers)，优先使用预设，减少字段错误。

自定义连接使用 Anthropic/Claude 兼容协议。只有 OpenAI Chat Completions 或 Responses 接口的服务，不能直接填进来；需要由网关提供 Claude 兼容接口。修改服务商名称不会转换协议。

## 向供方确认三件事

1. **地址**：用于 Claude/Anthropic 兼容接入的 API 根地址，而不是官网、控制台或完整消息路径。
2. **认证**：使用 `x-api-key`，还是 `Authorization: Bearer`；以及对应的原始凭据。
3. **模型**：账户实际可用的模型 ID，以及它是否支持流式回复和任务所需的工具调用。

例如，DeepSeek 的兼容根地址是 `https://api.deepseek.com/anthropic`。不要追加 `/v1/messages`；请求流程会处理消息路径。也不要把网络代理地址当作模型 API 根地址。

## 逐项填写字段

打开 **设置 → 服务商 → 添加服务商 → 自定义厂商 → 连接**。

| 字段或位置                 | 填什么                                                           | 注意事项                                                          |
| --------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
| Name / 名称             | 有辨识度的连接名，例如“团队网关”                                             | 用于区分账户或网关，不能代替模型 ID                                           |
| Provider Type / 服务商类型 | `Custom`                                                      | 普通自定义聊天使用这一项；`Google Gemini (Image)` 是独立图像功能                  |
| Base URL              | 供方给出的 Claude 兼容 API 根地址                                       | 自定义表单初始为空，需要填写；不要填写完整 `/v1/messages` 或 `/chat/completions` 路径 |
| API Key               | 供方给出的原始凭据                                                     | 不加 `Bearer ` 前缀；不粘贴 Claude 登录缓存中的 OAuth token                 |
| 高级选项 → 认证字段           | `API Key (x-api-key)` 或 `Bearer Token (ANTHROPIC_AUTH_TOKEN)` | 自定义初始值为 API Key；供方要求 Bearer 时必须改选                             |
| 高级选项 → 模型映射           | Opus、Sonnet、Haiku、Subagent 各自对应的真实模型 ID                       | 未明确配置时可能出现 Claude 默认模型；下一节说明这些角色的用途                           |
| 高级选项 → Fallback Model | 同一连接可用的备用模型 ID，或留空                                            | 留空关闭；不能与主模型相同，也不会自动切换到另一家服务商                                  |
| 高级选项 → 额外环境变量         | JSON 对象，值使用字符串                                                | 不需要覆盖时保留 `{}`；凭据使用上面的专门字段                                     |
| Notes / 备注            | 可选的用途说明                                                       | 不保存密钥或其他凭据                                                    |

编辑已有记录时，API Key 留空会保留已存密钥。只有明确点击移除并保存，才会清除它。

![自定义服务商基础配置](https://onevium.com/assets/docs/providers-custom-basic-zh.png "真实组件的隔离示例：填写名称、Claude 兼容根地址和原始密钥；图中使用虚构密钥。")

## 例子：手动填写 DeepSeek 连接

这个例子使用真实的预设地址和模型标识，演示自定义字段的关系。已有 DeepSeek 预设时，可以直接使用预设；手动配置不是必需步骤。

先确认自己的 DeepSeek 账户可以使用 `deepseek-v4-flash`，再按以下填写。如果账户提供的 ID 不同，使用供方确认的 ID，不照抄展示名称。

1. 名称填 `DeepSeek 手动配置`，类型保持 `Custom`。
2. Base URL 填 `https://api.deepseek.com/anthropic`。
3. API Key 填自己的原始 Key。
4. 在高级选项中，将认证字段改为 **Bearer Token**。
5. 此例让四个角色都使用同一模型：Opus、Sonnet、Haiku、Subagent 均填 `deepseek-v4-flash`。
6. Fallback Model 留空，额外环境变量保留 `{}`，点击 **添加服务商**。
7. 回到聊天模型菜单，找到 **DeepSeek 手动配置** 分组，选择 **DeepSeek V4 Flash**。如果需要手动补充模型条目，按下一节操作。

这里的模型 ID 用于说明填写方式，不是对账户权限的实时检查。保存完成后仍需发送实际请求。

![自定义认证方式与模型映射](https://onevium.com/assets/docs/providers-custom-advanced-zh.png "滚动后的真实高级字段：Bearer 认证、四个模型角色、降级模型和额外环境变量。示例不代表账户已获模型权限。")

## 区分模型条目和角色映射

**模型条目**决定模型菜单显示哪些选择。在已连接记录旁点击 **Models / 模型**，可调整可见性、添加条目，或展开一行的 **Advanced / 高级**：

| 模型字段              | 用途             | 推荐填法                                                |
| ----------------- | -------------- | --------------------------------------------------- |
| Model ID          | 实际选择和请求使用的模型标识 | 直接填写供方确认的真实 ID，例如 `deepseek-v4-flash`               |
| Display name      | 界面中显示的名称       | 可填便于识别的名称，例如 `DeepSeek V4 Flash`                    |
| Upstream model ID | 高级上游标识字段       | 本指南使用真实 Model ID，保持此项为空；不要仅在这里填真实 ID，就假定任意自定义别名都能转换 |
| Shown / Hidden    | 是否显示在模型菜单      | 至少保留一个可见模型，然后保存                                     |

**角色映射**决定 Claude Code 请求某个角色时使用什么模型：

- **Opus、Sonnet**：对应这些模型角色的请求。映射到其他厂商后，实际运行的是填写的模型，不是 Claude。
- **Haiku（后台）**：也用于部分标题、摘要等后台工作。不要只配置主模型，而让后台请求落到供方不支持的 Claude ID。
- **Subagent**：用于创建的子 Agent。按所需能力选择，并验证一次真实委派任务。
- **Fallback Model**：交给 SDK 在主模型过载等适用条件下使用，不是针对所有错误的自动重试方案。

模型 ID 可用，也不代表该模型支持图片、全部推理等级或所有工具。模型高级选项里的能力与价格配置不会改变上游实际能力。

**额外环境变量会覆盖同名角色配置。** 一般保留 `{}`，通过模型映射表配置角色。只有需要明确覆盖时才设置，例如：

```json
{
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash"
}
```

这会优先于模型映射表的 Sonnet 值。已连接预设的高级 JSON 可能带有默认模型变量；如果改了映射却没生效，检查并移除冲突的同名变量。优先关系是：当前额外环境变量 → 旧环境变量配置 → 角色映射 → 预设补缺值。

不要在 JSON 中放 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `GEMINI_API_KEY`；这些密钥项会被表单移除。此表单也不是任意自定义 HTTP 请求头编辑器。

## 验证实际请求

1. 点击记录旁的 **Provider 诊断**，先解决地址、认证和模型配置问题。它只检查本地配置，不验证上游 Key 或额度。
2. 新建会话，确认选中的连接名和模型，发送“只回复：已收到”。确认文字回复成功。
3. 在测试项目里请求一次只读操作：

```text
只读取项目根目录的 README.md，概括其中的运行步骤。
如果不存在就说明，不要创建或修改文件，也不要执行命令。
```

检查真实的文件读取工具和结果。若任务需要子 Agent、图像或渠道投递，再分别验证这些路径；不要用文字回复代替这些检查。

## 按现象排错

| 现象         | 处理方法                                                          |
| ---------- | ------------------------------------------------------------- |
| 401        | 核对认证字段、原始 Key、账户与地区；检查是否误加 `Bearer ` 前缀                       |
| 路径不存在或协议错误 | 核对根地址，不要重复追加 `/v1/messages`；确认接口确实兼容 Anthropic，而不只是 OpenAI 兼容 |
| 模型不存在      | Model ID 填真实上游 ID；检查主模型及 Haiku/Subagent 映射，不要把展示名称当 ID        |
| 改了角色仍使用旧模型 | 检查当前会话所选模型，以及高级 JSON 中同名模型环境变量的覆盖                             |
| 请求超时       | 检查网络与 **设置 → 网络代理**；调整 timeout 不能修复认证或协议错误                    |
| 需要另一连接     | 先添加新记录并验证，再在目标会话、渠道或自动化中切换；不要用 Disconnect 当暂停按钮               |

## 下一步

回到[服务商总览](https://onevium.com/zh/docs/providers#models)管理模型和连接。开始实际工作前，了解[权限与计划](https://onevium.com/zh/docs/permissions)及[设置与数据](https://onevium.com/zh/docs/settings-and-data)。