添加云端模型服务
将云端模型供应商的 API 地址与密钥保存在 OmniProxy 中，可以让你的各类 AI 工具统一连接本机网关。日后供应商地址变更或轮换密钥时，只需在 OmniProxy 内修改并重新验证，外部工具无需逐一调整配置。
开始前请准备：
- 供应商提供的 API 服务地址（非网页版聊天首页网址）。
- 有效的 API Key，以及对应模型的调用与计费权限（普通网页版聊天会员通常不包含 API 计费额度）。
- 请注意：调用外部模型会将你的请求内容发送给对应的云端服务商。
1. 添加远程模型来源
- 在左侧导航栏打开远程模型。
- 点击来源列表左下角的加号（+），打开“添加来源”窗口。
- 选择来源模板：若有匹配的供应商模板请直接选用；没有则选自定义（空白）。
- 填写标识信息：“名称”填便于自己辨认的标签（如“工作模型服务”），“描述”可留空。切勿将 API Key 写在名称或描述栏里。
- 填写连接凭据：“网址”填入供应商的 API 地址，“密钥”填入供应商提供的 API Key。
- 高级设置（按需）：需要指定特定协议或供应商专有参数时再展开“高级设置”；不熟悉的 JSON 字段请保持默认，不要照抄其他供应商的配置。
- 点击保存后进入来源详情页，点击测试或刷新模型，验证当前配置能否正常读取上游模型列表。
上图为原生 App 的“添加来源”配置表单。图中的 https://api.example.com 仅为填写位置示意，并非真实服务地址；此时密钥栏为空，仅展示配置步骤，不代表已连接成功（当前表单无需填写“命名空间”）。
2. 分别验证目录读取与实际调用
“能拉取模型目录”仅证明服务地址、认证与目录接口畅通，不代表某个具体模型一定能处理你的任务。拿到模型列表后，请务必对目标模型做一次真实的调用测试：
- 在来源详情页找到打算使用的模型（可通过搜索或类别筛选快速定位）。
- 点击该模型行的调用测试入口，选择实际要使用的协议与能力。
- 输入一句不含敏感信息的简短测试词并运行（若测试图像、语音或视频模型，请提供对应类型的有效测试输入）。
- 检查返回结果：确认 HTTP 状态正常、回答非空且确实回应了你的输入。
- 打开左侧监控台，在调用记录中核对本次测试命中的实际来源与模型。
注意：模型出现在目录列表中，或者名字里带有某种字样，都不代表你的账号拥有该模型的调用权限，也不自动证明它支持看图、工具调用或视频生成。
3. 真实调用验证示例（以 DeepSeek 为例）
- 在“添加来源”时选择 DeepSeek 模板，系统会自动带入 API 地址
https://api.deepseek.com及对应连接方式（无需额外寻找“协议”下拉框；若在命令行测试，对应的是同一服务的/v1路径，请勿与网页版聊天网址混淆）。 - 填入你自己的 DeepSeek API Key，保存并刷新模型目录。
- 从实际返回的目录中选择目标模型（本例选用
deepseek-flash；若上游目录更新，请按你当前看到的列表选择）。 - 打开该模型的调用测试，输入以下测试指令并运行：
Reply exactly: Gateway connection successful.运行后请同时核对 HTTP 状态码与正文内容。本例实际返回 Gateway connection successful.，状态为 HTTP 200，监控台记录中的实际模型显示为 deepseek-flash。如果拉取目录成功但此处未返回有效回答，请根据报错排查权限或余额，不能把“目录验证通过”当作模型已可用。
上图为 CLI 真实返回字段的浏览器阅读视图（非原生 App 截图），用于对照调用成功时的状态码与输出内容。
4. 将第三方工具连接到网关
模型验证通过后，即可将外部工具指向 OmniProxy：
- 从监控台复制网关地址和代理密钥（上游供应商的 API Key 留在 OmniProxy 来源配置中，不要再分散填进各个工具）。
- 从模型列表点击复制按钮获取模型名称（
modelRef），填入工具的模型字段。
处理跨来源同名模型歧义： 点击“复制完整模型名称”复制的是当前列表提供的
modelRef，系统不保证为每个远程模型自动加上来源前缀（例如远程模型可能复制出裸名称qwen3、gemma3，本地模型则为local/...）。如果多个启用来源中存在同名模型，工具直接请求裸名称会产生歧义，网关不会替你随机盲猜一个来源。遇到同名情况，请前往用固定名称映射模型明确指定来源与模型，让工具改用chat等无歧义的固定入口，切勿自行拼接未经核实的模型 ID。
5. 更新凭据、停用或删除来源
在左侧远程模型中选中对应来源，即可修改连接设置：
- 更换 API Key：请使用页面提供的替换操作。不要把未展开编辑时的空白输入框误认为“旧密钥已被清空”，一切以保存后的状态和重新测试结果为准。注意：在 OmniProxy 中替换或删除密钥，不会自动去上游供应商控制台作废旧密钥；如需吊销泄露的密钥，请务必登录供应商后台操作。
- 平滑变更配置：修改地址、轮换密钥或停用来源前，请先等待工具中正在进行的请求结束。“停用来源”只会拦截后续新请求，不能取消已经发往上流供应商的请求（已发请求的最终结果可在调用记录中查看）。修改保存后，必须重新执行配置验证与小任务测试。
- 停用与删除：暂时不用某个来源时，直接关闭来源行的启用开关即可。如需彻底删除，请先检查模型映射中是否有用途或虚拟模型正在引用它，避免留下悬空的路由入口。
6. 常见故障排查
| 提示或现象 | 排查与处理步骤 |
|---|---|
| 连接失败、地址不可达 | 检查 API 地址拼写与本机网络；确认填的是 API 接口地址而非供应商官网首页。 |
| 认证或权限失败 (401/403) | 登录供应商控制台，检查 API Key 是否有效、是否开通了目标模型权限及账号状态。 |
| 额度不足或触发限流 (429) | 核对供应商账户余额、免费额度有效期及并发速率限制，充值或等待恢复后再试。 |
| 修改配置后状态变为“未验证” | 任何地址或凭据改动后都必须对当前配置重新测试，系统不会沿用修改前的验证结果。 |
| 能读取模型目录，但调用测试失败 | 打开该模型的调用测试窗口，排查所选协议、请求格式或输入能力是否受该模型支持。 |
| 多个来源存在同名模型冲突 | 前往模型映射明确绑定目标来源与模型，在工具中使用固定映射名称。 |
补充说明：如果你在本机或局域网自建了 Ollama 服务，在 OmniProxy 中同样作为远程模型来源接入——由你自行安装和启动 Ollama 进程，OmniProxy 通过其 API 地址进行连接，不负责托管外部 Ollama 进程。更多协议细节请参阅命令帮助与网关 API 参考。