自定义模型配置

Mogick APP 支持接入自定义的 OpenAI 兼容模型服务。配置时，API 地址应填写服务的基础地址，不要填写 /models、/responses 或 /chat/completions 等完整请求端点。

例如，服务提供以下接口：

GET  https://host.example/v1/models
POST https://host.example/v1/chat/completions

则 API 地址应填写：

https://host.example/v1

Mogick 会在该地址后自动拼接接口路径。目前自定义模型服务使用 OpenAI Chat Completions 兼容协议；仅提供 Responses API（/responses）的服务暂不能直接使用。

配置前检查

服务需要同时满足以下条件：

• GET <baseUrl>/models 返回可用模型目录；
• POST <baseUrl>/chat/completions 接受 OpenAI Chat Completions 请求；
• 两个接口使用同一个 Bearer API Key；
• 不依赖 Mogick 设置页无法配置的额外请求头。

模型目录应返回 2xx 状态码和 JSON，且顶层包含 data 数组：

{
  "data": [
    { "id": "model-a" },
    { "id": "model-b" }
  ]
}

设置中填写的模型 ID 必须与 data[].id 完全一致，包括大小写。请使用接口返回的真实 ID，不要填写产品宣传名称或自行猜测名称。

添加自定义模型

1. 打开「设置 → 模型」。
2. 点击「添加自定义模型服务」。
3. 选择接口类型和模型提供商，并填写 Provider 名称。
4. 填写基础 API 地址、API Key 和至少一个模型 ID。
5. 如需使用多个模型，点击「添加模型」继续填写。
6. 点击「保存并验证」，等待验证完成，不要重复提交。
7. 返回会话，在输入框的模型菜单中选择新模型，发送一条简短消息完成实际对话验证。

保存成功后，新模型才会出现在会话的模型菜单中。目录验证成功只能证明地址、凭据和模型 ID 可识别；仍需发送消息确认 Chat Completions 和流式输出均可正常工作。

“保存并验证”会检查什么

点击「保存并验证」后，Mogick 会依次执行：

1. 检查 Provider 名称、HTTP/HTTPS API 地址、API Key 和模型 ID；模型 ID 不能包含空白字符。
2. 将 API 地址作为基础地址处理，清除查询参数和锚点。
3. 请求 GET <baseUrl>/models，并携带 Bearer API Key。
4. 检查请求是否在 8 秒内完成；最多允许 3 次同源重定向，响应体不能超过 1 MiB。
5. 检查响应是否为 2xx、是否为合法 JSON，以及顶层是否包含 data 数组。
6. 检查每个已填写的模型 ID 是否精确存在于目录中。
7. 全部通过后，保存凭据并将配置提交给 Mogick runtime。

验证失败时，当前编辑内容会保留，之前已确认可用的配置不会被未验证的草稿替换。设置页目前可能只显示「模型设置未生效」，可根据下表继续定位原因。

查询真实模型 ID

可以先在 PowerShell 中请求模型目录。输入 API Key 时不会回显：

$secureKey = Read-Host "请输入 API Key" -AsSecureString
$apiKey = [System.Net.NetworkCredential]::new('', $secureKey).Password
try {
  curl.exe https://host.example/v1/models `
    -H "Authorization: Bearer $apiKey"
} finally {
  Remove-Variable apiKey, secureKey
}

从响应的 data[].id 中复制需要使用的模型 ID。不要将 API Key 写入文档、聊天消息、截图或代码仓库。

常见问题

现象	常见原因	处理方法
地址包含 /responses 或 /chat/completions 后验证失败	Mogick 继续拼接 /models，形成错误路径	改填公共基础地址，例如 https://host.example/v1
返回 401 或 403	API Key 无效、过期、权限不足，或有地区/IP 限制	重新签发密钥，并检查白名单和模型权限
返回 404 或 405	服务不提供 GET /models，或基础路径错误	核对服务文档；当前版本不能跳过目录验证
返回 200 仍无法保存	JSON 结构不符合要求，或模型 ID 不在目录中	检查原始响应并复制准确的 data[].id
保存成功但对话失败	服务不支持 /chat/completions、流式协议或当前请求参数	直接测试 Chat Completions 接口；仅支持 Responses API 的服务暂不兼容
约 8 秒后失败	网络、DNS、代理、防火墙或服务响应速度异常	检查本机网络和服务状态
重定向失败	出现跨域跳转，或同源重定向超过 3 次	直接填写最终的同源基础地址

编辑、删除与密钥安全

• 编辑已有 Provider 时，界面不会回传 API Key 明文；只有明确输入新密钥时才会替换旧密钥。
• API Key 保存在本机安全存储中，不会显示在普通设置页面或配置文件中。
• 删除或停用 Provider 前，请确认没有会话仍依赖其中的模型。
• 第三方网关还可能限制地区、IP、额度、并发和模型权限，请同时遵守服务商规则。

验收清单

• API 地址是公共基础路径，末尾不是 /models、/responses 或 /chat/completions；
• GET <baseUrl>/models 使用当前密钥可返回 2xx；
• 响应符合 { "data": [{ "id": "..." }] } 结构；
• 设置中的模型 ID 与 data[].id 完全一致；
• 服务确实支持 POST <baseUrl>/chat/completions；
• 保存后模型出现在会话模型菜单中；
• 使用该模型发送最小消息可以收到正常响应。

以上项目全部满足，才表示自定义模型的完整对话链路可用。

返回模型管理与选择。