核心概念辨析
在使用 OmniProxy 的过程中，分清以下五组核心概念，可以帮助你快速配置路由并准确判断故障原因。
1. AI 工具、网关与模型来源
- AI 工具（客户端）：你日常用来聊天、写代码或运行 Agent 的软件。
- 网关（OmniProxy）：运行在你电脑上的中间枢纽，负责接收 AI 工具发来的请求，并按你的规则转发给目标模型或服务。
- 模型来源（上游）：真正执行推理计算的本机引擎或远程云端 API 服务。
关键边界：在 AI 工具里填好 OmniProxy 的网关地址，仅仅是把工具连上了网关；你仍然需要在 OmniProxy 中添加并验证好至少一个模型来源，请求才能真正得到回答。
2. 代理密钥与供应商 API 密钥
OmniProxy 涉及两把用途完全不同的密钥，切勿混填：
| 密钥类型 | 保存在哪里 | 交给谁使用 | 作用与轮换影响 |
|---|---|---|---|
| 供应商 API 密钥 | 保存在 OmniProxy 的远程模型 / 搜索 / MCP 来源配置中 | 由 OmniProxy 在向云端发起请求时使用 | 用于向云端厂商证明你的账号与计费权限。在厂商后台更换密钥后，只需更新 OmniProxy 里的来源配置，外部工具不受影响。 |
| 网关代理密钥 | 在 OmniProxy 监控台生成并管理 | 填写到你本机或局域网的第三方 AI 工具中 | 用于允许外部工具访问你的 OmniProxy 网关。轮换代理密钥后，所有连接网关的工具都必须同步更新，但无需改动上游供应商密钥。 |
3. 模型名称、用途名称与实际执行目标
- 模型名称（
modelRef）：在模型列表中点击复制获取的标识符（例如本地模型的local/...或远程模型的具体名称）。注意：部分上游模型的完整名称本身就包含斜杠/（如org/model-name），使用时请保持完整，不要自行截断只留最后一段；当多个远程来源提供同名裸名称时，直接填写裸名称会产生歧义，系统不会替你随机盲猜一个来源。 - 用途名称（如
chat）：你在用固定名称映射模型中启用的稳定入口代号。 - 实际执行目标：当外部工具请求
chat或某个虚拟模型名时，网关在后台真正调用的那个来源与具体模型。在监控台查调用记录、或在统计页核对 Token 消耗时，一律以实际执行目标为准。
4. 模型目录、受管存储与外部模型文件夹
- 模型目录（Catalog）：OmniProxy 内置的在线候选清单，帮你按任务发现可下载的模型。在目录里看到某个模型，不代表它已下载到本机。
- 默认下载位置（受管模型存储）：由 OmniProxy 直接管理的本地磁盘目录，所有新下载的模型都会写入此处。更改默认下载位置需要执行正式的存储迁移流程，待新位置校验通过后才会切换。
- 更多模型文件夹（外部挂载目录）：你电脑上其他软件已经下载好的模型目录。将其登记到 OmniProxy 只做原地识别，不会复制或搬移原文件；移除登记也不会删除磁盘上的文件。无论模型来自哪里，识别出文件都不等于已经通过了实际加载与运行测试。
5. 区分四个不同阶段的“成功”
排查问题时，请勿将前一阶段的成功当成后一阶段的保证：
| 你看到的“成功”提示 | 它实际证明了什么 | 它还不能证明什么 |
|---|---|---|
| 配置已保存 | 表单格式合法，设置已写入本地存储 | 远程服务地址可达，或 API 密钥有效 |
| 来源验证通过 / 读出模型目录 | 网络连通、认证有效，且成功拉取到模型列表 | 你的账号对该列表中的某个具体模型拥有调用额度，或该模型能正常生成回答 |
| 单次调用测试返回成功 | 该模型在当前协议下能正确处理这一条测试输入 | 该模型同样支持图片识别、工具调用（Tool Call）、超长上下文等所有扩展能力 |
| 统计页面显示有 Token 数字 | 历史汇总账本中记录了该时段的消耗量 | 对应的原始请求与响应正文此刻仍保留在日志中（旧正文可能已按容量上限清理） |
请根据你实际要运行的任务，按顺序补齐下一层验证；从零走通完整闭环请参阅快速上手：走通第一条模型请求。