OmniProxy 手册

启动与连接故障排查

遇到报错时，最高效的做法是先判断问题卡在下面哪一层：桌面端 App 能否正常打开 → 本机网关是否在运行 → 上游来源能否连通 → 目标模型能否完成推理。集中解决最先报错的那一层，远比盲目重置所有开关管用。

1. 系统状态与异常速查表

界面提示或看到的现象	第一步处理方式
仍在加载	耐心等待当前初始化或后台任务完成，切勿同时双击启动第二个实例。
需要目录访问 / 模型位置离线	重新插好外置移动硬盘或连接 NAS，并通过应用内的正式目录选择器重新授予访问权限。
内部数据迁移需要处理	保留现有数据目录不动，运行当前版本提供的诊断工具并按界面提示处理；切勿直接删除或重命名数据库文件。
Runtime 未启动 / 连接中断	查看界面展示的具体错误与诊断信息，确认当前操作的是桌面端 App 还是独立 CLI 实例，再点击正式的重试入口。
端口冲突	查明当前占用该端口的进程身份，优先调整你正在测试的实例端口，不要盲目强制杀死身份不明的系统进程。
来源未验证	回到远程模型、网络搜索或 MCP 服务页面，对当前保存的地址和密钥重新执行一次测试。
模型需要重新测试	回到本地模型页面，针对当前模型和所选调用方案重新运行一次调用测试。

如果外部 AI 工具提示无法连接到网关（Connection Refused / Timeout）：

打开 OmniProxy 监控台，确认网关状态为运行中，并重新点击复制图标获取最新的网关地址。
核对工具与网关所处的网络位置：如果 AI 工具运行在另一台电脑、手机、Docker 容器或远程服务器上，它眼里的 127.0.0.1 是它自己，绝不是你这台运行 OmniProxy 的 Mac。跨设备或容器接入请严格按照接入第三方 AI 工具配置局域网 IP 或 host.docker.internal，并核对监控台的监听范围与系统防火墙设置。
排错建议：请先在网关所在的 Mac 本机用最小请求确认入口正常，再排查跨设备网络问题；建议避免在排错过程中随意清空代理密钥或向所有网络开放无认证端口。

分清两把密钥的 401/403 错误：如果网关直接拒绝请求，请检查工具里填的是否为监控台当前的代理密钥；如果请求已进入网关但上游报错，请前往来源页面检查供应商 API Key、模型调用权限与账号状态。
能拉取模型目录，但生成回答失败：能读出目录只代表认证通过。调用具体模型报错时，请检查上游账户余额、免费额度是否过期、并发速率限制（429），以及所选协议是否匹配。
扩展能力报错：普通纯文本聊天跑通，不代表该模型同样支持图片识别、语音处理或工具调用（Tool Call）。遇到能力不支持报错时，请更换已实际测通对应能力的模型。

打开左侧设置 → 关于 → 报告问题，点击生成报告：

诊断报告完全在本机生成，包含当前应用版本、系统环境信息、Runtime 状态快照以及界面已捕获的错误摘要（它不会把你的全部历史日志或调用账本打包进去）。
生成后请先在界面上审阅内容，再按需点击保存报告或复制报告（点击写邮件仅负责唤起系统邮件客户端，点击发送前仍请亲自核对收件人与正文内容）。

如果你使用的是独立 CLI 实例，请先查看帮助，再运行结构化诊断命令：

omniproxy doctor --help
omniproxy doctor --output json

注意：omniproxy doctor 诊断的是当前独立 CLI 实例，并非桌面端 App。请先检查返回 JSON 中的 ok 字段与具体检查项结果，若失败请保留错误码。

当遇到端口冲突、需要确认究竟是哪个进程正在监听网关端口时（假设你在界面上看到的实际端口为 56788），可在 macOS 终端运行以下只读命令：

lsof -nP -iTCP:56788 -sTCP:LISTEN

请将 56788 替换为你实际看到的端口号，从输出结果中核对进程名称（COMMAND）和进程号（PID）。
如果命令没有任何输出，可能是该端口当前确实无人监听，也可能是当前终端用户权限不足以查看其他用户的进程。在没有完全确认占用进程的真实身份前，请勿盲目执行 kill 等强制终止命令（lsof 仅做只读查询，不会自动替你修复端口冲突）。

更新或恢复前先做记录：在进行版本更新或故障恢复前，请先记下具体的错误提示、当前版本号与操作发生时间。备份数据时只备份确有恢复价值的配置或文件，并明确恢复路径（注意：把本地模型权重文件拷到别的硬盘，不等于已经备份了来源配置和系统凭据库里的 API Key）。
遇到“内部数据迁移需要处理”时的处理方法：
- 当前版本针对内部数据库迁移失败不提供任何通用的手工修库步骤。
- 如果桌面端 App 仍能进入设置页面，请按上文步骤点击关于 → 报告问题 → 生成报告；如果启动时直接卡在报错窗口无法进入工作台，请完整截图或复制启动窗口的错误信息与版本号，通过官方支持渠道提交。
- 操作建议：请勿为强行进入应用而手动删除、移动或重命名私有数据库文件，亦不要试图用独立 CLI 的 doctor 命令去修复桌面端 App 的数据库。此时正确的处理动作为完整保留现场数据并提交明确错误报告。
提交问题前清理隐私：向支持渠道提交最小复现步骤、报错信息和已做过的排查动作时，请务必剔除 API 密钥、业务原文、含个人姓名的本地路径及私密附件；切勿将整个工作数据目录直接打包上传来代替诊断报告。