给 DSH 配置自定义 Provider
将公司网关、自建模型服务或目录外服务商接入 DSH。准备好连接地址、API 协议、凭证和模型 ID，再通过设置页面添加。
本页内容
如果“添加服务商”列表中已有目标服务，DSH 会提供连接地址、协议和模型目录。使用自定义端点时，需要按服务端文档核对这些值。
什么时候应该使用自定义 Provider
公司网关
公司统一提供一个 OpenAI-compatible 地址，而不是让客户端直接访问上游模型厂商。
自建服务
模型服务运行在自己的服务器或内网，需要 DSH 指向指定 Base URL。
目录中没有
在 Add provider 中找不到目标服务，需要自行填写协议、凭据与模型。
在设置 → 模型中添加服务商
打开 Settings → Models → Add a custom provider，填写小写 Provider ID、显示名称、Base URL、API 协议和至少一个模型。协议必须与端点一致，可选 openai-completions、openai-responses 或 anthropic-messages。
请求、会话记录和凭证引用都使用这个 ID。需要更名时先创建新服务商、验证连接并更新默认模型；确认不再需要旧配置后再删除。
配置凭据
最简单的是在 Web UI 输入凭据并保存。DSH 会把托管凭据与普通 Settings 分开保存，浏览器只拿到脱敏后的描述。
apiKeyEnv 填的是“环境变量名称”，不是密钥本身。环境变量必须在 DSH 启动前存在；修改后重新启动 DSH。
apiKeyEnv: GATEWAY_API_KEY添加或发现模型
点击 Fetch available models 获取模型列表，选择需要的条目后保存。DSH 会按所选协议请求模型发现接口；OpenAI 兼容协议使用 GET /models。
获取失败时先检查状态码和返回信息。端点不提供模型列表，但已确认支持聊天请求时，可以按服务商文档手动填写模型 ID。401 等认证错误仍需修复凭证，手动填写模型不会绕过认证。
在界面中为每个自定义 API 模型设置推理等级
对于在自定义模型 API下手动添加的模型，现在不必手改 YAML。打开 设置 → 模型，编辑对应 Provider，在该模型的自定义设置 → 模型选项中展开设置，并打开推理等级。
- 01
选择支持的等级
编辑器默认提供
off、low、medium、high四行。只保留端点实际支持的等级，并至少保留一个不是off的等级。 - 02
填写 API 值
每行把 DSH 等级映射为发给服务商的值，默认值与等级名称相同。只有服务商使用其他写法时才修改，例如使用
xhigh。 - 03
保存后选择等级
保存模型设置，创建新会话，在模型选择器中选中该模型，再选择它的推理等级。
内置目录模型沿用服务商目录声明的推理等级。新的界面入口只适用于自定义模型 API Provider 中手动添加的模型；它不会让端点凭空获得并不支持的推理能力。
保存后用新会话测试
保存配置，在模型选择器中选中目标模型，新建会话并选择不含敏感信息的测试工作区。发送：
只回复“custom provider connected”，不要修改文件，也不要运行命令。收到回复只能确认这次文本请求接通，不能证明工具调用或图片输入也可用。服务商配置修改会在下一次请求生效；已发过请求的旧会话仍保留原模型，因此切换模型后要新建会话验证。
服务端拒绝角色或输出长度字段
部分 OpenAI 兼容网关不接受推理模型的 developer 角色，或只接受 max_tokens 而不接受 max_completion_tokens。返回错误明确指向这些字段时，可在 $DSH_HOME/settings.yaml 的对应服务商下配置兼容项。
以下是结构示例，需替换网关 ID、地址、模型 ID 和凭证变量名。编辑前备份配置，将所需字段合入已有服务商，不要覆盖整个文件。
llm-pi-ai:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: my-model这些设置改变实际请求结构；没有相应报错时，不需要预先添加。
图片输入需要显式声明
手工添加的模型默认按文本模型处理。确认服务端确实支持图片后，在对应模型上添加 input: [text, image]。
如果后端实际上不支持图片，即使 DSH 允许上传，Provider 仍会拒绝请求。
常见问题
MISSING_CREDENTIAL
在设置 → 模型中保存凭证，或确认 apiKeyEnv 引用的变量在启动时已存在。
UNKNOWN_MODEL
选择已配置的模型，或按服务商文档添加缺失的模型 ID。
Fetch available models 返回 401
先修复模型发现请求的凭证或认证方式。手动添加模型只能替代列表发现，不能解决认证失败。
只有推理模型失败
检查返回错误是否涉及 developer 角色、输出长度或推理参数，再按端点文档设置兼容项。
删除服务商后提示 Select model
默认模型可能仍指向已删除的配置，重新选择一个可用模型。
自定义模型 API 的模型字段依据 官方模型配置指南与适配器参考；界面设置推理等级依据 v0.2.1-alpha.4 发布说明。源码参考版本 0.1.5-rc.2，不同网关仍需单独验证。