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

---

# 添加自定义服务商

按服务商的接口类型连接 Anthropic Messages、OpenAI Responses、Chat Completions 或 Gemini，填写真实模型 ID，并验证文字与工具请求。

## 何时使用自定义连接

当团队给你一个 API 地址和密钥，或服务不在[内置预设列表](https://onevium.com/zh/docs/providers#supported-providers)中时，使用 **自定义服务**。已有预设时优先选择预设，通常只需填写 API Key。

自定义聊天可以选择 **Anthropic Messages、OpenAI Responses、OpenAI Chat Completions 或 Google Gemini**。关键是与供方实际接口一致；不能只看模型叫 GPT、Claude 还是 Gemini，就猜连接类型。

## 向供方确认三件事

1. **接口与地址**：支持哪种接口，以及对应的 API 根地址。官网、控制台和代理服务器地址都不能代替它。
2. **认证**：使用哪种 API Key；Anthropic 兼容接口还要确认是 `x-api-key` 还是 Bearer。
3. **模型**：账户可用的真实模型 ID，是否支持流式回复及任务所需的工具调用。

填写根地址，不要自行追加 `/v1/messages`、`/responses` 或 `/chat/completions`。例如 DeepSeek 兼容接口使用 `https://api.deepseek.com/anthropic`；使用 OpenAI 官方预设时则为 `https://api.openai.com/v1`。

## 选择连接类型，再填写字段

打开 **设置 → 服务商 → 添加 AI 服务 → 自定义服务 → 连接**。先选 **连接类型**，再填地址和密钥。

| 供方提供的接口                   | 连接类型                               | 模型在哪里配置                        |
| ------------------------- | ---------------------------------- | ------------------------------ |
| Claude / Anthropic 兼容消息接口 | Anthropic Messages（兼容 Claude Code） | 保存后进入 **管理模型**；需要时设置高级选项里的角色映射 |
| OpenAI Responses          | OpenAI Responses                   | 保存后进入 **管理模型**，填写该接口可用的模型 ID   |
| OpenAI Chat Completions   | OpenAI Chat Completions            | 保存后进入 **管理模型**，填写该接口可用的模型 ID   |
| Google Gemini             | Google Gemini                      | 保存后进入 **管理模型**，填写 Gemini 模型 ID |

旧记录可能显示 **旧版自定义连接**，它沿用 Anthropic 兼容方式。新增普通聊天连接不要选择 OpenAI（图像）或 Google Gemini（图像）；[图像服务](https://onevium.com/zh/docs/providers#supported-providers)单独配置。

| 字段                      | 填什么                                              |
| ----------------------- | ------------------------------------------------ |
| 名称                      | 易于区分的名字，例如“团队网关”                                 |
| API 地址                  | 与连接类型匹配的 API 根地址                                 |
| API Key                 | 原始凭据，不加 `Bearer ` 前缀，不粘贴 Claude 登录缓存里的 token     |
| 高级选项 → 认证方式             | 仅 Anthropic 兼容连接需要选 `x-api-key` 或 Bearer；按供方说明填写 |
| 高级选项 → Claude Code 模型替换 | 仅 Anthropic 兼容连接显示；按需要配置各角色的真实模型 ID              |
| 高级选项 → 备用模型             | Anthropic 兼容连接可选；同一连接可用且不同于主模型的 ID，留空关闭          |
| 高级选项 → 额外环境变量           | Anthropic 兼容连接需要覆盖设置时使用；一般保留 `{}`                |
| 备注                      | 可选的用途说明，不写密钥                                     |

OpenAI Responses、Chat Completions 和 Gemini 连接使用填写的地址、密钥与模型。其 **已保留的环境变量** 只读保留旧配置，不参与这些请求，也不需要填写 Claude 角色映射。

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

下图保留较早版本的示例，字段名称和位置可能不同；以当前的“连接类型”和“API 地址”为准。

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

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

有 DeepSeek 账户时可以直接用预设。这里用手动配置说明字段的关系，目标是让聊天和后台任务都使用 `deepseek-flash`。

1. 名称填 `DeepSeek 手动配置`，连接类型选 **Anthropic Messages（兼容 Claude Code）**。
2. API 地址填 `https://api.deepseek.com/anthropic`，API Key 填自己的原始 Key。
3. 打开高级选项，将 **认证方式** 设为 **Bearer Token**。
4. 在 **Claude Code 模型替换** 中，将 Opus、Fable、Sonnet、Haiku、Subagent 都填为 `deepseek-flash`。
5. **备用模型** 留空，额外环境变量保留 `{}`，保存连接。
6. 在该连接的 **管理模型** 中，添加或核对模型 ID `deepseek-flash`，显示名称可填 `DeepSeek V4.1 Flash`，至少启用一个模型并保存。
7. 回到聊天，在 **DeepSeek 手动配置** 分组中选中它，再按下方步骤验证。

这是普通上下文的配置例子。预设会为主要任务配置 `deepseek-flash[1m]`，并为后台任务配置 `deepseek-flash`。使用预设时保留它的配置即可，不要把展示名称填成 ID，也不要仅添加 `[1m]` 就假定其他模型支持长上下文。

下图是旧版高级选项示例；当前请使用上面的 `deepseek-flash`，并补齐 Fable 等实际显示的角色。

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

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

**模型条目**决定聊天菜单出现什么。在服务商记录旁点击 **管理模型**，添加条目或展开一行的 **高级**：

| 模型字段                        | 用途与填法                                   |
| --------------------------- | --------------------------------------- |
| 模型标识 / Model ID             | 填供方确认的真实 ID，例如 `deepseek-flash`；不要填展示名称 |
| 显示名称 / Display name         | 便于辨认的名称，例如 `DeepSeek V4.1 Flash`        |
| 上游模型 ID / Upstream model ID | 本例已在 Model ID 填真实值，因此留空；内置预设已有映射时保留它    |
| 启用状态                        | 控制模型是否出现在菜单里，至少保留一个并保存                  |

**Claude Code 角色映射**只用于 Anthropic 兼容连接；OpenAI Responses、Chat Completions 和 Gemini 连接直接在管理模型中配置。

- **Opus、Fable、Sonnet**：这些角色请求实际使用的模型。填入其他厂商的 ID 后，运行的是该厂商模型。
- **Haiku（后台）**：部分标题、摘要等后台任务也使用它，别让后台请求落到供方不支持的 Claude ID。
- **Subagent**：子 Agent 使用的模型；需要协作任务时单独验证。
- **备用模型**：交给 SDK 在适用的主模型过载场景下使用，不会自动切换另一家服务商，也不是针对所有错误的补救。

在 **管理模型 → 默认推理力度** 中可以设置新会话的默认选择；修改即时保存，已有会话保留自己的选择。菜单中的力度与模型能力有关，不是每个模型都有相同选项。

Anthropic 兼容连接的额外环境变量会覆盖同名角色配置。例如：

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

这会优先于 Sonnet 角色输入框。通常保留 `{}`；若改了角色却没生效，检查当前会话的模型和高级 JSON 中的同名设置。不要在 JSON 中放密钥，也不要把这里当作任意 HTTP 请求头编辑器。

## 验证实际请求

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

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

检查实际的文件读取工具和结果。需要子 Agent、图像或渠道时，再分别验证；能填写一个模型 ID，不代表已验证该模型的所有能力。

## 按现象排错

| 现象         | 处理方法                                                          |
| ---------- | ------------------------------------------------------------- |
| 401        | 核对原始 Key、账户、地区和认证方式；检查是否误加 `Bearer ` 前缀                       |
| 路径不存在或协议错误 | 核对连接类型和根地址；Responses、Chat Completions、Anthropic Messages 不能混用 |
| 模型不存在      | 核对 Model ID 和账户权限；Anthropic 兼容连接还需检查各角色映射                     |
| 改了角色仍使用旧模型 | 检查当前会话所选模型和高级 JSON 覆盖；原生 API 连接应在管理模型中修改                      |
| 文字正常，工具失败  | 查看上游错误，确认该接口和模型支持任务需要的工具调用                                    |
| 请求超时       | 检查网络与 **设置 → 网络代理**；调整超时不能修复认证或协议错误                           |
| 需要另一连接     | 先添加并验证新记录，再切换目标会话、渠道或自动化；断开连接会删除记录                            |

## 下一步

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