外部唤起（qomicex-launcher://）
其他程序——网页、浏览器书签、桌面快捷方式、脚本——可以用qomicex-launcher:// 链接直接唤起启动器，并让它自动做一件事：启动某个实例、加入联机房间、安装插件或整合包、跳转到指定页面。
典型用法：
- 资源站/同学群里的「点这里一键进服」按钮 → 直接加入联机房间
- 整合包介绍页的「用 QML 安装」→ 自动装整合包并命名
- 插件作者官网的「安装到 QML」→ 自动装插件
- 自己做的快捷方式 → 一键启动常用实例
qomicex:// 是启动器内部用于前后端通信的私有协议（IPC 管道传输），不是给外部程序调用的接口。对外统一使用 qomicex-launcher://，两者互不影响。
动作总览
「需要确认弹窗」指的是从网页触发时的保护措施，见下方 安全须知。
语法规则
链接的结构固定为：- 动作名写在
//之后的第一段，大小写不敏感（浏览器会把这一段统一转成小写）。 - 参数值大小写敏感。例如实例名
1.20.1-Forge与1.20.1-forge是两个不同的名字。 - 参数里若含
/、?、&、空格、中文等字符，需要做 URL 编码（percent-encode）。 例如实例名我的 整合包要写成%E6%88%91%E7%9A%84%20%E6%95%B4%E5%90%88%E5%8C%85。 - 无法识别的动作、缺少必需参数、或路由不在白名单内的链接会被静默忽略（启动器不会弹错误框打扰你）。
启动实例
target 参数可以填三种写法，启动器按下述顺序匹配：
如果你在不同游戏目录下建了同名实例，只写名字是无法确定要启动哪个的——启动器会明确拒绝并提示你改用
目录:实例名，而不会猜一个。
这不是吹毛求疵：实例列表的先后顺序在启动器扫描过实例后会变化，如果「猜一个」，同一个链接今天可能启动 A、明天启动 B，而你不会收到任何提示。
写「目录:实例名」的注意事项
- 分隔符是最后一个冒号，所以 Windows 盘符不会被切错：
C:\mc\inst:MyPack会正确解析成目录C:\mc\inst+ 实例名MyPack。 - 目录里的
:、?、&、空格、中文都要 URL 编码。C:\mc\inst:MyPack编码后是C%3A%5Cmc%5Cinst%3AMyPack。 - 正斜杠
/与反斜杠\等价，C:/mc/inst:MyPack同样可用。 - 目录末尾的斜杠可以省略。
- 如果实例名本身含冒号（Linux 上理论上可能），请改用实例 ID。
打开页面
上表路由及其子路径都允许（例如
/instances/abc 合法）。不在此列的路径会被忽略。
加入联机房间
code 参数就是房主给你的房间码（形如 U/XXXX-XXXX-XXXX-XXXX，需 URL 编码）。触发后启动器会先切到「联机」页，再发起加入，并弹窗让你确认。
安装插件
从插件商店安装（推荐给网站作者）
slug：商店里的插件标识（商店页面地址最后一段）。version：可选。不填则装最新版。- 商店安装带 SHA256 校验 + 签名验证 + 依赖预检，是最安全的路径。
- 由于 slug 无法证明来源（任何网页都能编一个 slug），这条恒需你确认。
从直链安装
url必须是http/https，且指向一个.qplugin包。- 官方域（
api.qomicex.top、qomicex.top，且必须是 https）免确认；其他来源一律弹窗，窗口里会显示来源主机名与完整地址。 - 其他来源在你确认后，允许安装未签名的包（与设置页「手动上传 + 风险确认」口径一致）。签名无效的包仍会被拒绝。
- 下载体积上限 64 MiB。
- 出于安全考虑，指向内网/本机地址（
127.0.0.1、localhost、192.168.x.x等）的地址会被拒绝。 - 不跟随重定向：下载地址必须直出文件。若服务器返回 301/302 等跳转，会报「下载地址返回了重定向」而失败——请改用最终地址。这是防「先给一个公网地址再跳转到内网」的绕过手段。
- 证书必须有效：与「设置 → 网络 → 忽略 SSL 证书」无关，这条链路始终校验证书。原因很直接：这里下载的是马上要被当作代码安装的插件包，若允许跳过证书校验，中间人就能把你要装的插件换成别的。
.qplugin——那条路你能亲眼看到装的是哪个文件。
安装整合包
projectId与fileId通常必须同时提供（只给项目 ID 无法确定要装哪个版本）；type=technic是例外，只需要projectId，不要传fileId。- 触发后会弹窗确认，确认后开始后台安装并自动跳到实例页，页面提示「已开始安装」——安装进度不会显示在下载中心。
- 出于安全考虑，不支持用链接指定本地文件路径。
安全须知
外部唤起链接可以被任意网页触发，任何人都能写一个qomicex-launcher:// 链接放到自己的页面里。因此启动器遵循两条规则：
- 凡是会往你机器上落代码的动作，默认都要你点确认。 涉及：安装插件、安装整合包、加入联机房间。
- 只有官方域可以免确认安装，且判定条件是「https + 主机名精确匹配
api.qomicex.top或qomicex.top」。evil-qomicex.top这类后缀相同的域名不会被放行。
排障
点了链接没反应
按顺序排查：- 启动器装过吗？ 协议关联在启动器首次运行时自动注册到当前用户（不需要管理员权限）。从未运行过启动器的机器上没有关联。
- 浏览器拦截。部分浏览器只允许在用户点击时跳转外部协议，脚本自动跳转会被拦。请改用真实的可点击链接。
- 协议被别的程序占用。检查系统里是否有其他程序注册了
qomicex-launcher。 - 确认协议名拼写。必须是
qomicex-launcher://，不是qomicex://。
协议注册可以在 设置 → 网络设置 → 系统集成 中开关。如果这里被关闭，重启启动器后也不会再自动注册，链接同样会「点了没反应」。
弹窗问「此请求来自 xxx」
这是预期行为，不是错误：该链接的来源不在官方域白名单里。核对来源后再决定。手动测试链接
不想写网页时，可以直接用命令行触发（排障必备）：Windows
Linux
macOS
start qomicex-launcher://launch?target=1.20.1-Forge。
平台注册机制
启动器在不同系统上的关联方式不同，这决定了一些行为差异：单实例行为
启动器同一时间只运行一个实例，这样点链接不会开出一堆窗口：- 启动器没开 → 正常启动，并执行链接里的动作。
- 启动器已经开着 → 新进程把链接转交给已有窗口，自己退出；已有窗口会被拉到前台并执行动作。
--debug <端口> 参数启动（供 qomicex debug 与自动化调试使用）时不启用单实例——该模式必须每次开新进程才能暴露调试端口。此模式下重复启动会开出多个启动器，属预期。
限制
- 本地文件路径不支持。为了让链接无法指定磁盘上任意文件，
install/*只接受 URL 或平台项目 ID。 - 动作无法串行执行。一条链接只做一件事。
- 无法传任意命令行参数给游戏。需要自定义 JVM 参数请在实例设置里配置。
- 未识别的链接被静默忽略，不会给出错误提示（避免网页探测本机是否装了启动器）。
给第三方开发者
如果你在做资源站、启动器联动或插件分发，可以直接构造上面的链接，无需任何 SDK 或权限申请：- 想要「一键启动某实例」→ 用
launch?target=<实例ID>或launch?target=<目录:实例名>，但实例是用户本地的，应引导用户自己去看自己的实例（详情页地址栏的 ID），而不是替他拼名字——用户可能有重名实例，纯名字会启动失败。 - 想要「一键装你的插件」→ 首选上架插件商店后用
install/plugin?slug=…（有签名校验，用户信任度更高）。 - 想要「不经过商店直链分发」→ 用
install/plugin?url=…，但每次都会弹窗要求用户确认来源，请把包托管在稳定的 https 地址上，并尽量提供有效签名。 - 想要「整合包一键安装」→ 用
install/modpack?type=…&projectId=…&fileId=…。
POST /api/plugins/install-url。