免费 API 不用挨个试：Windows 与 Mac 自动换模型
初步构建 · 预览版 · 当前可下载 v0.4.58 · 目录 2026.09.02.1
文中标注为 0.4.59 的功能已经进入下一版代码，但截至 2026-09-04 尚未公开发布。
昨天我在自己的 Windows 机器上从零装了一遍黑粉盒子，装完第一件事是点「一键核验」——43 条路由，数字只掉了 1，然后一动不动。
先说结论：这不是核验坏了，是我自己写的批量核验碰到第一个限流就把整批停了。修完之后顺手把三个系统的现状也捋了一遍，结果是——**三个系统都有安装包，但只有 macOS 有应用内自动更新，三个系统都没有商业代码签名。**下面把每一条的原因写清楚。
▍它解决的不是“收集”，而是四个重复动作
黑粉盒子做的事很窄：你自己去各家平台申请免费 API Key，它把这些 Key 收进系统的安全存储，然后在你本机开一个地址 http://127.0.0.1:17688/v1。你把这一个地址填进 Cursor、Cline、OpenCode，它负责在背后挑哪家、哪个模型现在还能用。
Key 不上传，提示词和模型回答从你的电脑直连提供商，不经过任何中转。这是整个方案的前提。它真正省掉的是四个重复动作：查免费条件、保存 Key、逐条真测、把可用模型写进客户端。
▍三个系统各自是什么状况
先摆事实。这是当前正式发行版里实际存在的安装包：
| 系统 | 安装包 | 体积 |
|---|---|---|
| macOS 13+ | HyphenBox_x.y.z_universal.dmg |
9.8 MB |
| Windows 10/11 x64 | HyphenBox_x.y.z_x64-setup.exe |
3.5 MB |
| Windows 10/11 x64 | HyphenBox_x.y.z_x64_en-US.msi |
4.7 MB |
| Linux x64 | HyphenBox_x.y.z_amd64.AppImage |
76.9 MB |
| Linux x64 | HyphenBox_x.y.z_amd64.deb |
5.5 MB |
| Linux x64 | HyphenBox-x.y.z-1.x86_64.rpm |
5.5 MB |
macOS 那个包是 universal，Apple Silicon 和 Intel 共用一份。AppImage 明显胖，因为它把运行时打包进去了，免安装的代价就在这里。
功能上的差别只有三处，其余完全一致：
| 能力 | macOS | Windows | Linux |
|---|---|---|---|
| 应用内自动更新 | 有 | 无 | 无 |
| 密钥存储 | 钥匙串 | 凭据管理器 | 桌面密钥环 |
| 首次打开 | 右键→打开 放行一次 | SmartScreen 点「仍要运行」 | 直接跑 |
Linux 那格要单独说一句：密钥保险箱依赖 Secret Service，也就是 GNOME Keyring 或 KWallet。主流桌面发行版开箱就有；但如果你想丢在一台没有桌面环境的纯服务器上跑，密钥功能是不可用的。这不是没做，是这条路本来就走不通。
Windows 侧的凭据存储我这次实地验过：保存两把 Key 之后，凭据管理器里对应多出两条 Generic 凭据，服务名 top.hyphentech.hyphenbox，和数据库里的引用一一对应。本地服务也确认只监听回环——监听表里只有 127.0.0.1:17688，我从同一台机器的局域网地址 192.168.0.151 访问，连不上；不带令牌请求 /v1/models，返回 401。
▍为什么自动更新只有 macOS 有
这个问题的答案有点绕，但它决定了后面很长一段时间的发布节奏。
更新包必须用一把离线私钥签名，客户端拿内置公钥验签通过才肯安装。这把私钥的纪律是不上 CI——放上去等于把它交给一台我不控制的机器。而 Tauri 官方不支持从 macOS 交叉编译 Windows 包，Windows 的安装包只能在 Windows 机器上打出来。
两条合起来就成了死结：签名私钥在 Mac 上，Windows 包在 Windows 机器上，谁也够不着谁。CI 出的 Windows 包因此是刻意不带更新器签名的预览件，只能手动下载覆盖安装。
这次我把 Windows 这一侧的构建和发行链在本机补齐了，也就是说结只剩最后一环：把私钥挪到 Windows 机器上。做不做、怎么挪，是另一个安全权衡，还没定。
顺带记一个坑，给同样用 Tauri 的人：Tauri v2 在 Windows 上没有单独的更新包。我原本按 v1 的印象去找 .nsis.zip，找不到；实际跑一遍打包才看到它是直接给 NSIS 安装器本身签名，产出 ..._x64-setup.exe.sig，更新清单里的地址指向的就是那个 setup.exe。这种事光看文档看不出来，得真跑一次。
客户端这边我顺手改了个设计。原来是把「哪些平台支持自动更新」写死在代码里，现在改成按更新清单降级：清单里没有当前平台，就落回「手动下载」那一条，不报错；哪天清单补上了 Windows，客户端一行代码不用改就自动生效。
这套剧本早在 0.4.57 就演过一次：那一版 Windows 真机首页顶着一行英文红字 None of the fallback platforms … were found，其实只是更新器在清单里找一个不存在的平台条目，什么功能都没坏，但用户看见红字就以为程序废了。当时的处置是把平台写死成 macOS——红字没了，顺序陷阱留下了：之后先改清单还是先改代码，都会再错一次。
▍下一版准备补齐的三件事（0.4.59）
下面三项已经在 0.4.59 源代码里完成，但还不属于当前公开下载的 v0.4.58。先写进草稿，是为了把功能逻辑说清楚；正式对外发布时仍应以 GitHub Release 为准。
第一件：免费模型排到最前，并且写清为什么说它免费。
以前拉取模型列表只看提供商自己给的价格，问题是绝大多数平台的接口根本不返回价格字段。结果就是硅基流动那 16 个明明在目录清单里核对过的免费模型，全显示「价格未标」，按字母序混在几百个 ID 里，而它们在路由表里又标着「免费额度」——软件自己跟自己打架。
现在判定统一成三种依据，界面分别写出来：
- 整家免费档：这家的免费档覆盖全部模型，比如 Groq；
- 标价 $0：提供商自己在接口里标了零价，比如 OpenRouter 那些
:free后缀的； - 目录清单核对过：我这边逐条核对过官方文档、带出处和核对日期的清单。
三种可信度不一样，所以不合并成一个含糊的「免费」。没有任何一种背书的，仍然只标「价格未标」——查不到价格不等于不要钱，把「没说」写成「免费」，用户照着选，撞的是自己的钱包。
列表按免费、未标价、收费三段排序，加了「只看免费」开关和「一键加入全部免费」。顺手修了个旧毛病：原来的批量加入只吃屏幕上显示的那 60 条，超出的静默丢掉，用户以为都加了。
第二件：一键核验撞限流不再整批中止。
这就是开头那个「数字不动」的真相。原实现碰到第一个 429 就 break，后面 30 多条一条都没碰。
改完之后的处置是：撞限流按提供商给的 Retry-After 等一次再试同一条，然后继续；对回过 429 的提供商自动放慢到约 20 RPM；同一家连续三次仍限流才放弃它剩下的路由，别家照跑。
这里有个更早的教训值得一提。0.4.41 那版，我把「用途不支持自动核验」和「撞了限流」共用了同一个状态字符串，结果队列头一条图像模型被当成限流，整批当场中止，后面排队的向量模型根本没轮到。**一个字符串扛两种语义，就会这样。**这次改限流，第一件事就是把两者彻底分开。
那个「连续三次就放弃」的上限不是拍脑袋定的。OpenRouter 官方文档写得很清楚：:free 模型 20 RPM；账户累计充值不足 10 美元时，每天只有 50 次请求，充过 10 美元才是 1000 次。我这边 24 条 OpenRouter 免费路由，每条核验最多发两次探针——不设上限的话，一轮批量核验能把当天额度全烧在 429 上。限流请求也是要算次数的。
第三件：客户端里的模型名把模型 ID 放到最前面。
原来写进 OpenCode 配置的名字是「提供商/模型｜费用档」，看着挺全。实际打开下拉框才发现，它只显示前二十几个字符，几十条全是「openrouter/…」，模型名和费用档位一个都看不见。现在改成「模型ID｜档位 · 提供商」。
这条改动没有任何技术含量，但它是这次改动里最该早点做的一个——设计的时候看的是数据结构，用的时候看的是那个宽度有限的下拉框。
同一个位置早前还栽过一次：0.4.48 我按「不知道的字段就不写」的直觉，给模型规格只写了上下文没写输出上限，而 OpenCode 的规范要求这两个值同时存在，整份配置被判非法，用户连模型都选不出来。写别人家的配置文件，得守别人家的规矩，不能按自己的直觉省字段。
▍还没做完的，和它现在的样子
必须承认的部分：
- **限流那条还有个体验缺口。**现在撞到限流会按上游给的时间等，最长 60 秒。真实场景里 OpenRouter 给的就是 60 秒，于是按钮上会出现「限流，等 60s 再试」然后干等一分钟。正确的做法应该是直接跳过、把这家挂起、先去核验别家，最后再回头补——这个还没写。
- **三个系统都没有商业代码签名。**macOS 用的是自签名证书，Windows 完全没签，所以两边首次打开都会被系统拦一次。这是「没花钱买证书」的拦截，不是安全检测结果。但你不该因为我这么说就放行——每个包都附了
.sha256，自己核对。 - **免费额度会变。**目录里每条免费模型都带官方出处和核对日期，日期比清单本身重要。还有个具体的坑：硅基流动在账户余额为 0 时，连标着免费的模型也会一并拒绝，返回的是余额不足。这种事只有真发一次请求才知道，所以软件坚持「必须真跑通一次才算数」。
▍谁在这条链上赚钱
免费 API 这个生意，钱的流向其实不复杂。
平台放免费额度是拉新和占入口，等你把工作流搬过去、把 Key 填进十几个客户端之后，迁移成本就替它说话了。聚合商赚的是按量抽成，所以它有动机让你多调用、少纠结——你不会看到聚合商主动提醒你「这个活用免费额度就够了」。
真正沉默的是那些把免费额度设计成漏斗的一方：**没有人有动机告诉你，哪些活其实不需要付费模型。**这也是我做这个软件的动机——不是替谁省钱，是让「现在到底哪个能用、要不要花钱」这件事，别再靠人一个个试。
而黑粉盒子自己不赚这里的钱：它不碰你的 Key，不做中转，没有任何按量计费的位置可以插进去。代价是所有验证成本都压在你自己的额度上——每一次核验都是一次真实请求，花的是你的免费额度。这个交换我认为划算，但它确实是个交换。
▍下载与上手
| 你的系统 | 下载哪个 |
|---|---|
| macOS 13+ | universal.dmg，Apple Silicon 和 Intel 通用 |
| Windows 10/11 | x64-setup.exe（推荐），需要 MSI 部署时用 .msi |
| Linux 桌面 | AppImage 免安装；Debian/Ubuntu 用 .deb，Fedora 系用 .rpm |
装完之后的四步：
- 去任意一家平台申请一把免费 Key，填进「密钥保险箱」；
- 到「模型与路由」拉取模型列表，勾「只看免费」，点「一键加入全部免费」；
- 点「一键核验」，等它逐条真跑一遍——撞限流会自己放慢，不用管；
- 到「一键连接」把地址和令牌填进你的客户端。
如果你只想用不想挑，客户端里选 auto，每次请求它自己按额度和工具支持情况换。
日志在这三个位置，遇到问题直接把文件发来：
- Windows：
%LOCALAPPDATA%\top.hyphentech.hyphenbox\logs\hyphenbox.log - macOS：
~/Library/Logs/top.hyphentech.hyphenbox/hyphenbox.log - Linux：
~/.local/share/top.hyphentech.hyphenbox/logs/hyphenbox.log
回到开头那个「数字不动」的问题：它现在会动了。但更值得说的是，这个 bug 只有把软件装到一台真机上、拿真实的 Key 点一次按钮才会暴露——在我自己的开发机上，路由表里只有两三条，永远撞不到限流。
黑粉科技自制软件
| 产品 | 一句话 | 状态 |
|---|---|---|
| 黑粉剪辑 HyphenCut | 对话式视频剪辑器，自带 MCP 可被 agent 驱动 | 正式迭代 |
| 黑粉盒子 HyphenBox | 免费大模型 API 雷达 + 本地统一路由 | 初步构建 · 预览版 |
| LocalBrain | 把电脑变成私有 AI 盒子：转写／配音／生图／视频／MCP 一站管理 | 正式迭代 |
| ScreenLex 光影词库 | 本地电影字幕变可复习英语词库，全程离线 | 正式迭代 |