免费 API 不用挨个试：Windows 与 Mac 自动换模型

2026-10-02 更新：黑粉盒子已正式推出，从 1.0.0 开始正式迭代，Mac、Windows、Linux 安装包均已公开。下载最新正式版。

本文主体保留 2026-09-04 的开发实录：截图、包体积、0.4.58 / 0.4.59 的功能边界均属于当时版本。当前三平台更新清单已附带更新器签名；商业代码签名与更新器签名不是一回事。

昨天我在自己的 Windows 机器上从零装了一遍黑粉盒子，装完第一件事是点「一键核验」——43 条路由，数字只掉了 1，然后一动不动。

先说当时的结论：这不是核验坏了，是我自己写的批量核验碰到第一个限流就把整批停了。修完之后顺手把三个系统的现状也捋了一遍：**2026-09-04 时三个系统都有预览版安装包，但只有 macOS 配有应用内自动更新。**下面保留这次排查过程；正式版现状见上方更新说明。

▍它解决的不是“收集”，而是四个重复动作

黑粉盒子做的事很窄：你自己去各家平台申请免费 API Key，它把这些 Key 收进系统的安全存储，然后在你本机开一个地址 http://127.0.0.1:17688/v1。你把这一个地址填进 Cursor、Cline、OpenCode，它负责在背后挑哪家、哪个模型现在还能用。

Key 不上传，提示词和模型回答从你的电脑直连提供商，不经过任何中转。这是整个方案的前提。它真正省掉的是四个重复动作：查免费条件、保存 Key、逐条真测、把可用模型写进客户端。

▍三个系统各自是什么状况

先摆事实。这是 2026-09-04 预览版的安装包记录，体积不是 1.0.0 的包体积：

macOS 那个包是 universal，Apple Silicon 和 Intel 共用一份。AppImage 明显胖，因为它把运行时打包进去了，免安装的代价就在这里。

当时记录的三项平台差异如下；这不是当前正式版的功能对照表：

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 预览包没有更新器签名，只能手动覆盖安装。后来采用的办法是把 CI 产物带回 Mac 签名，不需要把私钥交给 CI 或迁到 Windows。

**2026-10-02 补记：1.0.0 的三平台更新清单已经包含签名，Mac 仍保留签名权。**清单和签名齐备不等于每台机器都完成了升级实测，安装与升级问题仍在正式迭代中收集。

顺带记一个坑，给同样用 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 开发过程中的改动说明，保留它们是为了讲清功能逻辑；现在下载请选 1.0.0 或后续正式版，不要把这一节当作当前版本预告。

第一件：免费模型排到最前，并且写清为什么说它免费。

以前拉取模型列表只看提供商自己给的价格，问题是绝大多数平台的接口根本不返回价格字段。结果就是硅基流动那 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，不做中转，没有任何按量计费的位置可以插进去。代价是所有验证成本都压在你自己的额度上——每一次核验都是一次真实请求，花的是你的免费额度。这个交换我认为划算，但它确实是个交换。

▍下载与上手

装完之后的四步：

1. 去任意一家平台申请一把免费 Key，填进「密钥保险箱」；
2. 到「模型与路由」拉取模型列表，勾「只看免费」，点「一键加入全部免费」；
3. 点「一键核验」，等它逐条真跑一遍——撞限流会自己放慢，不用管；
4. 到「一键连接」把地址和令牌填进你的客户端。

如果你只想用不想挑，客户端里选 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 点一次按钮才会暴露——在我自己的开发机上，路由表里只有两三条，永远撞不到限流。

黑粉科技自制软件

• 黑粉盒子 HyphenBox：下载与更新：黑粉盒子 HyphenBox（发行页）
• LocalBrain：下载与更新：LocalBrain（发行页）
• ScreenLex 光影词库：下载与更新：光影词库 ScreenLex（发行页）