添加自定义服务商
按服务商的接口类型连接 Anthropic Messages、OpenAI Responses、Chat Completions 或 Gemini，填写真实模型 ID，并验证文字与工具请求。
开始使用何时使用自定义连接#
当团队给你一个 API 地址和密钥，或服务不在内置预设列表中时，使用 自定义服务。已有预设时优先选择预设，通常只需填写 API Key。
自定义聊天可以选择 Anthropic Messages、OpenAI Responses、OpenAI Chat Completions 或 Google Gemini。关键是与供方实际接口一致；不能只看模型叫 GPT、Claude 还是 Gemini，就猜连接类型。
向供方确认三件事#
- 接口与地址：支持哪种接口，以及对应的 API 根地址。官网、控制台和代理服务器地址都不能代替它。
- 认证：使用哪种 API Key；Anthropic 兼容接口还要确认是
x-api-key还是 Bearer。 - 模型：账户可用的真实模型 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（图像）；图像服务单独配置。
| 字段 | 填什么 |
|---|---|
| 名称 | 易于区分的名字，例如“团队网关” |
| 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 地址”为准。
真实组件的隔离示例：填写名称、Claude 兼容根地址和原始密钥；图中使用虚构密钥。
例子：手动填写 DeepSeek 连接#
有 DeepSeek 账户时可以直接用预设。这里用手动配置说明字段的关系，目标是让聊天和后台任务都使用 deepseek-flash。
- 名称填
DeepSeek 手动配置，连接类型选 Anthropic Messages（兼容 Claude Code）。 - API 地址填
https://api.deepseek.com/anthropic，API Key 填自己的原始 Key。 - 打开高级选项，将 认证方式 设为 Bearer Token。
- 在 Claude Code 模型替换 中，将 Opus、Fable、Sonnet、Haiku、Subagent 都填为
deepseek-flash。 - 备用模型 留空，额外环境变量保留
{}，保存连接。 - 在该连接的 管理模型 中，添加或核对模型 ID
deepseek-flash，显示名称可填DeepSeek V4.1 Flash，至少启用一个模型并保存。 - 回到聊天，在 DeepSeek 手动配置 分组中选中它，再按下方步骤验证。
这是普通上下文的配置例子。预设会为主要任务配置 deepseek-flash[1m]，并为后台任务配置 deepseek-flash。使用预设时保留它的配置即可，不要把展示名称填成 ID，也不要仅添加 [1m] 就假定其他模型支持长上下文。
下图是旧版高级选项示例；当前请使用上面的 deepseek-flash，并补齐 Fable 等实际显示的角色。
滚动后的真实高级字段：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 兼容连接的额外环境变量会覆盖同名角色配置。例如：
{
"ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-flash"
}
这会优先于 Sonnet 角色输入框。通常保留 {}；若改了角色却没生效，检查当前会话的模型和高级 JSON 中的同名设置。不要在 JSON 中放密钥，也不要把这里当作任意 HTTP 请求头编辑器。
验证实际请求#
- 点击记录旁的听诊器图标 检查配置，解决本地地址、认证和模型问题。它不会验证上游 Key 或额度。
- 新建会话，确认选中的连接和模型，发送“只回复：已收到”。确认文字回复成功。
- 在测试项目里请求一次只读操作：
只读取项目根目录的 README.md，概括其中的运行步骤。
如果不存在就说明，不要创建或修改文件，也不要执行命令。
检查实际的文件读取工具和结果。需要子 Agent、图像或渠道时，再分别验证；能填写一个模型 ID，不代表已验证该模型的所有能力。
按现象排错#
| 现象 | 处理方法 |
|---|---|
| 401 | 核对原始 Key、账户、地区和认证方式；检查是否误加 Bearer 前缀 |
| 路径不存在或协议错误 | 核对连接类型和根地址；Responses、Chat Completions、Anthropic Messages 不能混用 |
| 模型不存在 | 核对 Model ID 和账户权限；Anthropic 兼容连接还需检查各角色映射 |
| 改了角色仍使用旧模型 | 检查当前会话所选模型和高级 JSON 覆盖；原生 API 连接应在管理模型中修改 |
| 文字正常，工具失败 | 查看上游错误，确认该接口和模型支持任务需要的工具调用 |
| 请求超时 | 检查网络与 设置 → 网络代理；调整超时不能修复认证或协议错误 |
| 需要另一连接 | 先添加并验证新记录，再切换目标会话、渠道或自动化；断开连接会删除记录 |