给 DSH 配置自定义 Provider
当模型服务不在 DSH 内置 Provider 列表中时再用这篇。先通过 Web UI 配置，只有界面无法表达的高级选项才修改 YAML。
本页内容
自定义 Provider 主要用于公司网关、自建服务或未收录服务。内置 Provider 已带有 endpoint、protocol 和模型目录信息，配置更简单。
什么时候应该使用自定义 Provider
公司网关
公司统一提供一个 OpenAI-compatible 地址，而不是让客户端直接访问上游模型厂商。
自建服务
模型服务运行在自己的服务器或内网，需要 DSH 指向指定 Base URL。
目录中没有
在 Add provider 中找不到目标服务，需要自行填写协议、凭据与模型。
在 Settings → Models 创建 Provider
打开 Settings → Models → Add a custom provider，填写小写 Provider ID、显示名称、Base URL、API protocol 和至少一个模型。
请求、已保存会话、默认模型和凭据引用都会使用这个 ID。改名不是直接编辑，而是新建 Provider 后删除旧 Provider。
配置凭据
最简单的是在 Web UI 输入凭据并保存。DSH 会把托管凭据与普通 Settings 分开保存，浏览器只拿到脱敏后的描述。
apiKeyEnv 填的是“环境变量名称”，不是密钥本身。环境变量必须在 DSH 启动前存在；修改后重新启动 DSH。
apiKeyEnv: GATEWAY_API_KEY添加或发现模型
如果网关实现了 OpenAI-compatible GET /models，可用 Fetch available models。如果聊天接口能用但模型发现失败，很可能只是网关没有实现该接口，确认模型 ID 后手工填写即可。
保存后用新会话测试
保存 Provider，在模型选择器里选中它的模型，再创建一个新的测试会话。
Provider 修改会在下一次请求生效，通常不需要重启服务器。已经发送过请求的旧 Session 会保留它自己的模型记录，因此验证模型切换时建议新建 Session。
Key 和 URL 都对，但所有请求仍被拒绝
“OpenAI-compatible” 不代表所有字段完全一致。部分网关不接受 reasoning 模型的 developer role，或只认识 max_tokens 而不接受 max_completion_tokens。
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只有在凭据、Base URL 和模型 ID 已确认无误后再修改 $DSH_HOME/settings.yaml。兼容字段会改变实际请求结构，不要盲目添加。
图片输入需要显式声明
手工添加的模型默认按文本模型处理。确认服务端确实支持图片后，在对应模型上添加 input: [text, image]。
如果后端实际上不支持图片，即使 DSH 允许上传，Provider 仍会拒绝请求。
常见问题
MISSING_CREDENTIAL
在 Settings → Models 保存凭据，或确认 apiKeyEnv 指向的环境变量在 DSH 启动时已经存在。
UNKNOWN_MODEL
选择已配置模型，或把缺失模型 ID 添加到 Provider。
Fetch available models 返回 401
检查模型发现请求使用的凭据；如果网关没有 GET /models，直接手工添加模型。
只有 reasoning 模型失败
网关可能不接受 developer role，按官方 Provider 文档核对 compat 设置。
删除 Provider 后页面提示 Select model
默认模型仍可能指向被删除的 Provider ID，重新选择一个当前可用模型。