快速上手：走通第一条模型请求
本章带你走完最短的上手路径：在 OmniProxy 中准备一个可用模型，获取本机网关连接参数，从支持自定义模型服务的 AI 工具发送一条测试消息，最后回到监控台确认调用记录。
开始前，请从已确认的正式渠道获取适合当前设备的安装包。macOS 桌面端请直接打开 OmniProxy.app；如果你使用独立命令行版本，请参阅使用命令行与终端管理台。官网暂未开放下载入口时，请勿根据文档中的示例域名猜测下载地址。
1. 完成首次设置向导
首次打开 App 会进入五步引导流程：翻译模型 → 外部模型 → 网络搜索 → 确认 → 完成。如果你打开 App 后直接看到了左侧导航栏，说明已完成初始化，可直接跳到第 2 步；若启动报错，请先参阅启动与连接故障排查。
只想最快接通一个云端模型，可按以下步骤走完向导：
- 翻译模型：选择“不预装翻译模型”，点击继续。
- 外部模型：可在此直接添加你的供应商 API 来源（填写方法见添加云端模型服务），也可以先跳过，等进入工作台后再配。注意：向导中凡是已添加的来源，都必须点击测试并验证通过后才能继续；若修改了地址或密钥，须重新测试。
- 网络搜索：暂不添加，直接点击继续（若已添加来源，同样必须验证通过才能继续）。
- 确认：核对下载清单与来源摘要。如果清单里仍有不想下载的翻译模型，请点击上一步退回翻译模型页改选，不要直接开始下载。未选任何模型时，无需为了走完向导而凑数下载。
- 完成：点击确认并开始，等待执行完毕后点击进入工作台。
首次设置遇到失败怎么办？
- 尚未点击开始执行：点击上一步返回对应页面，修正来源地址或密钥后重新测试。
- 下载任务报错：在任务行查看具体错误；若提供重试按钮，请在排查网络或磁盘空间后点击重试。即使界面允许你先点击进入工作台，进入后仍需在任务区处理失败的下载，进入工作台不代表模型已下载成功。
- 既无法重试也无法继续：记下错误提示并重启 App；若问题依旧，请按启动与连接故障排查提取诊断信息，切勿通过手动删除应用资料库来强行重置。
2. 准备一个可调用的模型
在连接第三方工具前，先在 OmniProxy 里跑通至少一个模型（任选其一）：
- 使用云端 API（远程模型）：点击左侧导航栏的远程模型添加来源，填入供应商 API 地址与 API Key。保存后先测试读取模型列表，再对目标聊天模型执行一次调用测试，亲眼看到生成的回答后再继续。
- 使用本机算力（本地模型）：点击左侧导航栏的本地模型下载或识别模型，完成调用测试并按提示加入代理。部分受支持的 Mac 会显示由系统管理的 Apple 模型，无需额外下载权重文件，但同样需要先完成调用测试以确认当前可用。
注意：“保存了来源配置”、“模型文件下载完成”和“模型能正常生成回答”是三件事。请务必在 OmniProxy 内看到实际的测试回答后，再去配置外部工具。
3. 从监控台获取连接参数
点击左侧导航栏的监控台，确认网关状态显示为运行中。
上图为原生 App 的监控台初始界面（尚未配置代理密钥、也暂无调用记录的起始状态）。第三方工具需要连接的是这里的网关地址，切勿把上游供应商的 API 网址直接填进工具。
- 复制网关地址：点击网关地址旁的复制图标，获取当前连接地址。
- 生成并复制代理密钥：首次接入建议先配置代理密钥。在“代理密钥”一行点击生成密钥图标，随后点击复制密钥图标获取当前值。
- 如果此前已经生成过代理密钥，直接点击复制密钥即可，接入新工具时无需重新生成。重新生成会轮换密钥，所有正在使用旧密钥的工具都必须同步更新。
- 未设置代理密钥时，仅“本机监听”模式允许无认证访问；若你的工具强制要求填写 API Key，请先按上述步骤生成代理密钥，不要随便填入上游供应商密钥或编造占位符。
- 若要将监听范围切换到所有网络，则必须先配置代理密钥，且所有请求都必须携带该密钥。
接下来，在你的第三方 AI 工具中准备填写以下三项参数：
| 工具中的配置项 | 应填写的值 |
|---|---|
| Base URL / 服务地址 | 从监控台复制的网关地址。请根据工具的路径拼接规则保留或去掉末尾的 /v1，避免重复拼接成 /v1/v1。 |
| API Key | OmniProxy 监控台生成的代理密钥（不是上游供应商的 API Key）。 |
| Model / 模型 ID | 从模型列表点击复制拿到的模型名称，或已启用的用途映射名称（如 chat）。 |
跨设备访问提示：
127.0.0.1仅代表运行该工具的那台设备自身，另一台电脑无法通过127.0.0.1找到你的 Mac。如需让局域网内的其他设备调用，请先参阅接入第三方 AI 工具了解监听范围与认证配置，不要为了排错而随意向所有网络开放无认证端口。
4. 在工具中发送一条测试消息
打开你的 AI 工具，找到“自定义服务”或“OpenAI 兼容接口”设置，填入上述三项参数并保存。注意：如果某个工具强制要求厂商私有协议，哪怕界面上有模型名称输入框，也不能直接当作兼容接口使用，详见接入第三方 AI 工具。
选择你刚才验证过的文本聊天模型，发送一句简短的测试提问：
请用一句话解释什么是网关。
收到回复后，请检查回答内容是否正常回应了提问。请注意，部分工具在后台还会发起工具调用（Tool Call）、图片识别等附加请求，普通文本聊天跑通不代表这些高级能力也已全部兼容。
5. 回到监控台核对调用记录
返回 OmniProxy 的监控台，在“最近调用”列表中按时间找到刚刚产生的那条记录。核对它的执行状态（成功/失败）、实际命中的来源与实际执行的模型，并点开详情查看完整的请求与响应内容。更详细的日志排查方法见查看调用记录与管理网关。
如果第一次请求没有跑通，请按以下现象快速定位：
| 遇到的现象 | 排查第一步 |
|---|---|
| 工具提示连接不到网关 | 确认监控台网关处于“运行中”、Base URL 填写无误，且工具与网关处于同一可达网络。 |
| 提示认证失败 (401/403) | 核对工具里填的是否为监控台当前的代理密钥，检查是否误填了上游供应商密钥。 |
| 提示模型不存在或名称有歧义 | 重新从模型列表复制名称，或配置明确的按用途映射（如使用 chat）以消除同名冲突。 |
| 返回能力不支持错误 | 更换为已实际测通对应能力（如看图、工具调用）的模型，不要仅凭模型名字判断能力。 |
| 工具报错，但监控台没有任何记录 | 请求在到达网关前就已失败。请检查工具是否真的向当前网关地址发出了请求，以及路径或本地网络是否被拦截。 |
跑通第一条请求后，建议前往用固定名称映射模型将常用模型绑定到 chat 入口；这样日后在 OmniProxy 里切换底层模型时，就无需再去修改各个外部工具的配置了。