1. 为什么要把14个免费通道塞进一个入口

第一次看到“14个免费通道并成1个入口”这个说法，我脑子里蹦出来的画面是家里那堆乱七八糟的充电线——每个设备一根线，插排上挤得满满当当，找一根合适的线得翻半天。免费模型通道也是这个道理：这个平台送点额度，那个平台有免费调用次数，另一个平台又搞限时活动，单独用哪个都还行，但真到干活的时候，你得记住哪个模型在哪个平台、额度还剩多少、哪个通道今天又抽风了，光是切换和试错就耗掉一半精力。

WorkBuddy 这个项目要解决的就是这个事。它本质上是一个本地网关，把多个免费模型通道统一收拢到一个入口后面，你只需要跟一个地址打交道，剩下的路由、切换、降级、重试全部由网关自己处理。标题里说的“按任务自动路由”是核心——不是简单地把请求轮询分发出去，而是根据任务类型、模型能力、通道健康状态来做决策。

这个方案适合谁？我觉得有三类人值得认真看看。第一类是个人开发者或者小团队，预算有限但又需要频繁调用模型能力，手头攒了一堆免费额度不知道怎么高效利用。第二类是喜欢折腾本地化部署的人，对数据流向有要求，不想把每个请求都直接暴露给不同的外部服务。第三类是正在做 AI 应用原型验证的人，需要快速对比不同模型在同一个任务上的表现，手动切换太慢，有个统一入口会舒服很多。

关键词里的models.json是这个项目的配置核心，所有通道信息、模型映射、路由规则都写在这个文件里。本地网关是它的运行形态，跑在你自己的机器上，不依赖外部中转。自动路由是它的行为逻辑，也是整个方案里最值得拆开讲的部分。

我先把结论放在前面：这个方案的价值不在于“免费”两个字，而在于把碎片化的资源整合成可管理的服务。免费额度是诱饵，统一入口和自动路由才是真正省时间的地方。下面我会从设计思路、配置细节、实操步骤、问题排查几个角度把它拆干净，尽量让不同基础的人都能照着搭起来。

2. 整体架构与路由逻辑拆解

2.1 本地网关到底在做什么

很多人第一次听到“网关”这个词会觉得抽象，其实你可以把它理解成一个前台接待。你所有的请求都先交给前台，前台根据你递过来的单子内容，决定这个单子该转给哪个部门处理。你不需要知道后面有多少个部门、每个部门今天忙不忙、哪个部门今天请假了，前台会帮你搞定。

WorkBuddy 的本地网关跑在你自己的机器上，监听一个本地端口，比如http://127.0.0.1:8787。你的编辑器、脚本、客户端工具全部指向这个地址，请求进来之后，网关做几件事：

• 解析请求内容：判断这是对话补全、代码生成、文本摘要还是其他任务类型。
• 匹配路由规则：根据models.json里定义的规则，选出最合适的通道和模型。
• 转发并处理响应：把请求发给选中的通道，拿到结果后统一格式返回给调用方。
• 记录状态：哪个通道失败了、哪个通道额度快用完了、哪个通道响应特别慢，这些信息会被记录下来，影响后续的路由决策。

这个架构最大的好处是解耦。你的调用方不需要知道后面有几个通道，通道换了、加了、挂了，调用方完全无感。你只需要维护好models.json这一个配置文件。

2.2 为什么是14个通道而不是更多或更少

14 这个数字不是随便定的。我实际梳理下来，免费通道大致可以分成几类：

14 个通道并成一个入口，意味着你在models.json里维护 14 条通道配置，每条配置包含地址、密钥、支持的模型列表、权重、健康检查参数等。通道数量太少，路由没有腾挪空间，一个挂了就影响整体可用性；通道太多，维护成本上升，而且很多通道能力重叠，意义不大。14 个是一个比较平衡的数字，既有足够的冗余，又不至于管不过来。

2.3 自动路由的三种策略

“按任务自动路由”这句话展开来讲，至少包含三种策略，我在实际配置中把它们组合使用：

第一种是按任务类型路由。比如代码补全任务优先走代码能力强的模型通道，文本摘要任务走长上下文通道，翻译任务走多语言支持好的通道。这个策略在models.json里通过任务标签来匹配。

第二种是按通道健康度路由。网关会定期对各个通道做健康检查，记录响应时间和失败率。当某个通道连续失败或者响应时间超过阈值，自动降低它的权重，把流量导向更健康的通道。这个策略是动态的，不需要手动干预。

第三种是按额度余量路由。免费通道最怕的就是额度用完了还不知道，请求发出去直接报错。网关可以记录每个通道的已用额度和剩余额度，优先把请求分配给余量充足的通道，快用完的通道降级为备用。

这三种策略叠加在一起，才是完整的“自动路由”。单独用任何一种都有明显短板：只按任务类型路由，通道挂了不会自动切换；只按健康度路由，可能把代码任务发给一个不擅长代码的通道；只按额度路由，任务质量没法保证。

2.4 方案选型的几个关键取舍

在搭建这个网关的时候，有几个决策点值得说一下我为什么这么选。

为什么用本地网关而不是云端中转？云端中转的好处是随时随地能用，但坏处是你的请求要经过第三方服务器，而且免费通道的密钥要交给别人保管。本地网关跑在自己机器上，密钥不出本地，数据流向可控，代价是只能在本地网络使用。对于个人开发者来说，这个取舍是划算的。

为什么用 JSON 配置而不是数据库？models.json是纯文本文件，改起来方便，版本管理也方便，出问题了直接回滚文件就行。数据库虽然查询能力强，但对于十几个通道的配置来说属于杀鸡用牛刀。JSON 的缺点是并发写入需要加锁，但网关配置的修改频率很低，这个问题可以忽略。

为什么不做成图形界面？图形界面看起来友好，但维护成本高，而且不同人的使用习惯差异很大。配置文件加命令行工具的组合，虽然上手门槛稍高，但灵活性和可脚本化程度更好。你可以在 CI/CD 流程里直接改配置、重启网关，图形界面反而不好自动化。

3. models.json 配置细节与实操要点

3.1 配置文件的基本结构

models.json是整个网关的核心，它的结构设计直接决定了路由的灵活度。我用的结构大致是这样的：

{ "gateway": { "port": 8787, "host": "127.0.0.1", "healthCheckInterval": 300, "defaultTimeout": 30000 }, "channels": [ { "id": "channel-a", "name": "通道A", "baseUrl": "https://api.example-a.com/v1", "apiKey": "sk-xxxxxxxx", "models": ["model-x", "model-y"], "weight": 10, "maxRetries": 2, "timeout": 20000, "tags": ["code", "chat"], "quota": { "dailyLimit": 1000, "used": 0, "resetAt": "00:00" } } ], "routing": { "rules": [ { "taskType": "code", "preferredChannels": ["channel-a", "channel-c"], "fallback": "any" } ] } }

这个结构里，gateway段是网关自身的运行参数，channels是通道列表，routing是路由规则。每个通道的tags字段用来标记它擅长的任务类型，weight是初始权重，quota用来跟踪额度使用情况。

注意：apiKey直接写在 JSON 里是有泄露风险的。如果配置文件会提交到版本库，建议用环境变量替换，或者把密钥单独放在一个不纳入版本管理的文件里，启动时合并加载。

3.2 通道配置的六个关键参数

每个通道的配置里，有六个参数是我踩过坑之后觉得必须认真对待的：

baseUrl是通道的接口地址。这里有个细节：有些通道的地址末尾带/v1，有些不带，写错了会直接 404。我的做法是先在浏览器或者 curl 里手动测一次，确认地址正确再写进配置。

apiKey是身份凭证。免费通道的密钥通常有有效期，过期了需要重新申请。我建议在配置里加一个keyExpiresAt字段，到期前一周提醒自己更换。

models是这个通道支持的模型列表。不同通道对同一个模型的命名可能不一样，比如有的叫gpt-3.5-turbo，有的叫gpt-3.5。这个字段要跟通道文档对齐，写错了路由会匹配不到。

weight是初始权重。权重高的通道会被优先选中，但权重不是固定的，健康检查结果会动态调整它。我一般把稳定性最好的通道权重设为 10，一般的设为 5，备用通道设为 1。

timeout是超时时间。免费通道的响应速度波动很大，设太短会频繁超时，设太长会拖慢整体响应。我的经验值是 20 到 30 秒之间，具体看通道的历史表现。

maxRetries是重试次数。一个请求失败了，网关会自动重试。重试次数不是越多越好，因为重试会消耗额度，而且如果通道本身挂了，重试只是浪费时间。我一般设 2 次，配合健康检查来快速剔除故障通道。

3.3 路由规则的写法与优先级

路由规则决定了请求怎么分配。我用的规则结构是“任务类型 + 优先通道列表 + 兜底策略”：

{ "taskType": "code", "preferredChannels": ["channel-a", "channel-c", "channel-f"], "fallback": "any", "maxLatency": 15000 }

这条规则的意思是：代码类任务优先走 channel-a，如果 a 不可用走 c，再不行走 f，如果都不行就任意可用通道兜底。maxLatency是延迟上限，超过这个值的通道会被跳过。

规则的优先级从高到低排列，匹配到第一条符合条件的规则就停止。所以写规则的时候，把最具体的规则放在前面，最宽泛的放在后面。比如：

1. 代码补全任务 → 优先代码通道
2. 长文本摘要任务 → 优先长上下文通道
3. 翻译任务 → 优先多语言通道
4. 其他任务 → 任意可用通道

这样写的好处是，特殊任务有专门优化，普通任务也不会没着落。

3.4 健康检查与动态权重调整

健康检查是自动路由的“眼睛”。没有健康检查，路由就是瞎子摸象，通道挂了都不知道。我的做法是每 5 分钟对所有通道做一次轻量级探测，发一个很短的请求，记录响应时间和状态码。

探测结果会影响通道的动态权重，计算方式大致是：

• 连续成功且响应快 → 权重上调，最高不超过初始权重的 1.5 倍
• 偶尔失败 → 权重不变，继续观察
• 连续失败 3 次以上 → 权重降到最低，标记为“不健康”
• 恢复成功 → 权重逐步回升

这个机制的好处是，通道出问题的时候，流量会自动绕开它，不需要手动改配置。等它恢复了，流量又会慢慢回来。

实操心得：健康检查的请求要尽量轻，不要用真实的业务请求去探测，否则会白白消耗额度。我一般用一个固定的短提示词，比如“hi”，只检查连通性和响应时间。

3.5 额度跟踪与预警

免费通道的额度是有限资源，用完了就得等刷新。网关需要跟踪每个通道的额度使用情况，我的做法是在每次请求成功后，根据返回的 token 用量累加到quota.used字段。当used接近dailyLimit的 80% 时，降低该通道的权重；达到 95% 时，标记为“额度告急”，只在其他通道都不可用时才使用。

额度重置时间也要记录，到点自动把used归零。有些通道的额度是按小时刷新的，有些是按天，配置的时候要区分清楚。

4. 从零搭建的完整实操流程

4.1 环境准备与依赖安装

搭建这个网关不需要特别复杂的运行环境，我用的是一台普通的开发机，配置如下：

• 操作系统：Linux 或者 macOS 都可以，Windows 建议用 WSL2
• 运行时：Node.js 18 以上，或者 Python 3.10 以上，看网关的实现语言
• 内存：至少 2GB 可用，如果本地还跑模型，需要更多
• 网络：能正常访问各个通道的接口地址

依赖安装这一步，不同实现方式差别很大。如果是 Node.js 版本，核心依赖通常包括 HTTP 服务框架、HTTP 客户端、JSON 解析库。我建议用npm init初始化项目，然后按需安装，不要一次性装一大堆用不上的包。

mkdir workbuddy-gateway && cd workbuddy-gateway npm init -y npm install express axios

如果是 Python 版本，用pip安装对应的包：

mkdir workbuddy-gateway && cd workbuddy-gateway python3 -m venv venv source venv/bin/activate pip install fastapi httpx uvicorn

注意：不要用 root 权限跑网关，也不要把网关暴露在公网上。本地网关监听127.0.0.1就够了，需要局域网访问再改成0.0.0.0，但一定要加访问控制。

4.2 通道信息的收集与整理

在写models.json之前，先把 14 个通道的信息整理清楚。我建议用一个表格来管理，字段包括：通道名称、接口地址、密钥、支持模型、额度限制、刷新周期、备注。

收集信息的时候有几个坑要注意：

• 接口地址要确认版本路径：有些通道的文档写的是https://api.xxx.com，实际调用要加/v1/chat/completions，少一段就报错。
• 密钥的权限范围要确认：有些密钥只能调特定模型，调其他模型会返回权限错误。
• 额度限制要区分类型：有的是请求次数限制，有的是 token 总量限制，有的是并发数限制，配置的时候要对应不同的跟踪逻辑。
• 刷新周期要确认时区：有些通道按 UTC 刷新，有些按本地时区，搞错了会提前或延后重置。

整理完信息之后，先不要急着全部写进配置。我的做法是先写 3 到 5 个通道，跑通整个流程，确认网关工作正常，再把剩下的通道加进去。一次性配 14 个通道，出问题了很难定位是哪个通道的问题。

4.3 网关服务的启动与验证

配置文件写好之后，启动网关服务。以 Node.js 版本为例：

node gateway.js --config ./models.json --port 8787

启动之后，先做几个基础验证：

验证一：网关是否正常监听。用 curl 访问健康检查接口：

curl http://127.0.0.1:8787/health

返回{"status":"ok"}就说明网关起来了。

验证二：通道是否可达。网关通常会提供一个通道状态接口：

curl http://127.0.0.1:8787/channels/status

这个接口会返回每个通道的健康状态、当前权重、额度使用情况。如果某个通道显示不可达，先单独用 curl 测一下那个通道的接口地址，确认是网络问题还是配置问题。

验证三：路由是否生效。发一个测试请求：

curl -X POST http://127.0.0.1:8787/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"auto","messages":[{"role":"user","content":"写一个快速排序"}]}'

注意model字段填auto，表示让网关自动选择模型。如果返回了正常结果，说明路由链路是通的。

4.4 调用方接入与模型映射

网关跑起来之后，把常用的工具接进来。大部分支持自定义接口地址的客户端都可以接入，只需要把接口地址改成http://127.0.0.1:8787/v1，密钥随便填一个非空值（网关自己会替换成真实密钥）。

模型映射是接入时容易出问题的地方。调用方可能请求的是gpt-4，但你的通道里只有gpt-3.5，这时候网关需要做映射。我在models.json里加了一个modelMapping段：

{ "modelMapping": { "gpt-4": ["channel-a:model-x", "channel-b:model-z"], "gpt-3.5-turbo": ["channel-c:model-y", "channel-d:model-w"] } }

这样调用方请求gpt-4的时候，网关会去找支持这个映射的通道，而不是直接报错。

4.5 自动化脚本与日常维护

网关跑起来之后，日常维护主要是几件事：检查通道状态、更新失效密钥、调整路由规则、清理日志。

我写了一个简单的巡检脚本，每天早上跑一次，输出各通道的健康状态和额度余量：

#!/bin/bash curl -s http://127.0.0.1:8787/channels/status | \ python3 -c " import sys, json data = json.load(sys.stdin) for ch in data['channels']: status = 'OK' if ch['healthy'] else 'FAIL' quota = ch['quota']['used'] / ch['quota']['dailyLimit'] * 100 print(f\"{ch['name']}: {status}, 额度使用 {quota:.1f}%\") "

这个脚本输出很直观，哪个通道挂了、哪个通道额度快满了，一眼就能看到。

5. 常见问题与排查技巧实录

5.1 请求全部失败但通道单独测试正常

这是最常见的问题之一。网关转发失败，但直接用 curl 调通道接口又是通的。原因通常有三个：

第一个是请求格式不一致。网关转发的时候可能多加了或者少加了字段，导致通道拒绝。排查方法是打开网关的调试日志，把转发出去的原始请求打印出来，跟手动 curl 的请求对比。

第二个是密钥替换没生效。调用方传过来的密钥是占位符，网关应该替换成真实密钥，但替换逻辑有 bug。检查网关日志里实际使用的密钥前缀是否正确。

第三个是超时设置太短。网关的超时时间比通道的实际响应时间短，请求还没回来就被网关掐断了。把timeout调大再试。

5.2 路由总是选中同一个通道

自动路由应该根据任务类型和健康状态动态选择，但如果发现所有请求都走同一个通道，说明路由规则没生效。可能的原因：

• 规则匹配顺序有问题，第一条规则太宽泛，把所有请求都截胡了
• 通道的tags字段没填对，任务类型匹配不上
• 动态权重计算有 bug，某个通道的权重被异常拉高

排查的时候，先把路由规则简化成只有一条，确认基本路由能工作，再逐步加规则。

5.3 额度消耗比预期快

免费额度用得快，除了实际调用量大的原因，还有几个隐蔽的消耗点：

• 健康检查请求也在消耗额度：如果健康检查用的是真实模型调用，每次探测都会消耗 token。改成轻量探测或者用不计费的接口。
• 重试机制导致重复消耗：一个请求失败后重试，如果失败原因是通道已经扣了额度但返回错误，重试会再扣一次。把maxRetries调小，或者对特定错误码不重试。
• 并发请求没有限流：短时间内大量并发请求打到一个通道，额度瞬间见底。在网关层加一个简单的令牌桶限流。

5.4 常见问题速查表

5.5 几个我踩过的坑

坑一：配置文件里的注释。JSON 标准不支持注释，但很多人习惯性加//注释，导致解析失败。如果确实需要注释，用JSON5或者JSONC格式，或者把注释写在单独的说明文档里。

坑二：密钥里的特殊字符。有些密钥包含+、/、=等字符，在 shell 脚本里直接拼接会出问题。用环境变量传递，或者用 base64 编码后再解码。

坑三：日志文件无限增长。网关跑久了，日志文件会越来越大，占满磁盘。加一个日志轮转策略，比如每天切割一次，保留最近 7 天。

坑四：通道更新后配置没同步。免费通道的接口地址和模型列表可能会变，如果配置没跟着更新，路由会失败。我养成的习惯是每周检查一次各通道的官方公告，有变更及时改配置。

坑五：本地端口冲突。8787 这个端口可能被其他程序占用，启动时报EADDRINUSE。换个端口，或者在启动前检查端口占用情况。

6. 进阶玩法与扩展思路

6.1 按任务复杂度分级路由

基础的自动路由是按任务类型分的，进阶玩法是按任务复杂度分级。简单的任务走轻量模型，复杂的任务走能力更强的模型。判断复杂度的方法可以是提示词长度、是否包含代码块、是否要求多步推理等。

我在models.json里加了一个complexityRules段：

{ "complexityRules": [ { "name": "simple", "condition": "promptLength < 200 && !containsCode", "channels": ["channel-light-1", "channel-light-2"] }, { "name": "complex", "condition": "promptLength >= 200 || containsCode", "channels": ["channel-heavy-1", "channel-heavy-2"] } ] }

这样简单任务不会占用宝贵的高能力通道额度，复杂任务也能得到足够的算力支持。

6.2 多通道结果对比与择优

有些场景下，同一个任务发给多个通道，然后从结果里选最好的。这个玩法适合对质量要求高、对延迟不敏感的任务。网关可以并发发给 2 到 3 个通道，拿到结果后用简单的评分规则（比如长度、格式完整性、是否包含错误信息）选一个返回。

这个模式的代价是额度消耗成倍增加，所以只建议在关键任务上使用。

6.3 对话上下文与缓存

多轮对话场景下，上下文管理是个麻烦事。每个通道对上下文长度的限制不一样，有的支持 4K token，有的支持 32K。网关可以在转发前检查上下文长度，超过通道限制就自动截断或者摘要压缩。

缓存也值得做。相同的请求如果短时间内重复出现，直接返回缓存结果，不消耗额度。缓存的 key 可以用请求内容的哈希值，设置一个合理的过期时间。

6.4 把网关做成系统服务

每次手动启动网关太麻烦，可以把它做成系统服务，开机自启。Linux 下用 systemd，macOS 下用 launchd。以 systemd 为例：

[Unit] Description=WorkBuddy Gateway After=network.target [Service] Type=simple User=youruser WorkingDirectory=/home/youruser/workbuddy-gateway ExecStart=/usr/bin/node gateway.js --config ./models.json Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target

配好之后systemctl enable workbuddy-gateway，以后就不用管了，网关挂了会自动重启。

6.5 监控与告警

网关跑在生产环境的话，监控是必须的。我用的方案很简单：网关暴露一个/metrics接口，输出各通道的请求量、成功率、平均延迟、额度余量。然后用一个轻量的监控工具定时抓取，异常时发通知。

告警规则我设了三条：某个通道连续 5 分钟不可达、整体成功率低于 90%、某个通道额度使用超过 90%。这三条覆盖了大部分需要人工介入的情况。

7. 一些实际使用中的体会

这套方案我断断续续用了几个月，最大的感受是：免费资源的价值不在于免费，而在于可管理。14 个通道如果各自为战，管理成本高到让人放弃；并成一个入口之后，维护工作量降到了可以接受的程度。

另一个体会是，自动路由的规则不要一开始就写得太复杂。我最初写了十几条规则，结果调试的时候根本不知道请求走了哪条路径。后来简化成三条核心规则，跑稳定了再逐步加，反而效率更高。

还有一点，免费通道的稳定性预期要放低。今天能用的通道明天可能就挂了，这是常态。网关的容错机制要做好，但心理上也要接受“随时可能有通道失效”这个事实。定期巡检、及时替换，比追求一劳永逸更现实。

最后分享一个小技巧：把models.json纳入版本管理，每次修改都提交一次。这样出问题了可以快速回滚，也能看到配置的演变过程。配合一个简单的变更日志，记录每次改了哪个通道、为什么改，过一段时间回头看会很有帮助。