1. 项目定位与用途
Free Router 是一款本地部署的 OpenAI 兼容网关，核心作用是为任意 OpenAI 兼容客户端提供统一的免费大模型调用入口。它可对接多个符合 OpenAI 规范的模型提供商，自动对当前可用的免费模型进行排名，在单个提供商出现速率限制、宕机或无可用模型时自动完成故障转移，无需用户手动切换服务商。所有服务商的 API 密钥仅存储在本地机器，不会上传至任何第三方，保障密钥安全。
项目档案应用项目
Free Router 本地OpenAI兼容网关使用指南：统一对接多提供商免费模型，自动故障转移，支持Docker部署
www222fff/free-router：Free Router 是一款本地 OpenAI 兼容网关，可统一对接多个提供商的免费模型，自动排名并故障转移，让任意 OpenAI 兼容客户端本页整理它解决什么问题、适用场景、安装方式和使用方法。
AI 总结
Free Router 是一款本地 OpenAI 兼容网关，可统一对接多个提供商的免费模型，自动排名并故障转移，让任意 OpenAI 兼容客户端无需修改配置即可稳定调用免费大模型。
中文项目介绍
Free Router 是本地部署的 OpenAI 兼容网关，核心定位是统一对接多个服务商的免费大模型资源，为任意 OpenAI 兼容客户端提供统一的调用入口。
它解决了多提供商免费模型使用时的 API 适配差异、手动切换服务商、单服务商故障/限流时的手动处理等痛点，自动对配置的免费模型做排名，在单个服务商速率限制、宕机或无可用模型时自动故障转移，缺失对应服务商密钥会自动跳过该服务商，不影响其他服务商使用。
它支持 OpenRouter、TokenRouter、B.AI、Google AI Studio Gemini 等多个主流免费模型提供商，也支持通过配置扩展更多符合 OpenAI 规范的提供商，所有密钥仅存储在本地，支持本地 Node.js 部署和 Docker 部署，还提供 Web UI 用于管理密钥、查看用量，适合个人开发者、小团队低成本调用免费大模型的场景。
详细信息与使用说明
2. 解决的问题
Free Router 解决了多提供商免费模型使用时的多重痛点：一是不同提供商的 API 规范存在差异，用户需要分别适配不同接口，使用成本高；二是免费模型普遍存在速率限制、服务不稳定等问题，手动切换服务商效率极低；三是多服务商密钥分散管理，容易遗漏或泄露。该网关通过统一 OpenAI 兼容接口、自动故障转移、本地统一密钥管理，大幅降低了免费大模型的使用门槛。
3. 适用场景
Free Router 适用于以下场景：个人开发者需要低成本调用多个提供商的免费大模型，无需分别对接不同 API；小团队需要统一管理多提供商免费模型的调用入口，避免单服务商故障影响业务；任意 OpenAI 兼容客户端（包括 Hermes、Cursor、curl、各类 SDK 等）需要无需修改配置即可调用免费模型的场景；对密钥安全性要求高，不希望密钥上传至第三方服务器的用户。
4. 安装方式
Free Router 运行环境要求 Node.js 20 及以上版本。本地部署步骤为：1. 克隆仓库到本地目录；2. 将 .env.example 复制为 .env，填写至少一个提供商的 API 密钥；3. 执行 ./start.sh 即可启动服务，执行 ./stop.sh 可停止服务。Docker 部署方式为执行 docker compose up -d，服务密钥会通过本地 .env 文件注入，不会 baked 进镜像，保障密钥安全。
5. 使用方式
启动服务后，任意 OpenAI 兼容客户端只需将 API 地址指向 http://127.0.0.1:8787/v1，模型参数填写 free-best 即可自动调用当前最优可用的免费模型。执行 ./models.sh 可查看当前 free-best 的模型排名，执行 ./models.sh --usage 可查看当日配额使用情况。打开 http://127.0.0.1:8787/ 可进入 Web UI，用于管理服务商密钥、查看用量统计。
6. 实现特点与补充说明
Free Router 支持可插拔的提供商配置，新增提供商只需在 config.json 中添加对应配置块，同时在 .env 中添加对应格式的 API 密钥即可扩展。项目提供基础功能测试脚本，执行 npm test 即可运行 smoke 测试验证核心功能。同时提供 systemd 服务配置文件 free-router.service，可配置为系统服务长期运行，无需手动启动。
思维导图
当前仓库信息不足，或结构不够稳定，暂时没有生成可靠的思维导图。
常见问题
Free Router 需要配置多少个服务商的密钥才能使用？
至少配置一个提供商的 API 密钥即可启动使用，未配置密钥的提供商会自动跳过，不影响其他提供商的正常使用。
使用 Free Router 需要修改客户端配置吗？
不需要，只需将任意 OpenAI 兼容客户端的 API 地址指向 http://127.0.0.1:8787/v1，模型参数填写 free-best 即可，无需额外修改客户端配置。
Free Router 的密钥会上传到第三方服务器吗？
不会，所有服务商的 API 密钥仅存储在本地机器，不会上传至任何第三方服务器，Docker 部署时密钥也会通过本地 env 文件注入，不会 baked 进镜像。
如何查看当前可用的免费模型排名和配额使用情况？
执行 ./models.sh 可查看当前 free-best 的模型排名，执行 ./models.sh --usage 可查看当日各提供商的配额使用情况，也可打开 Web UI 查看。
Free Router 支持自定义添加新的模型提供商吗？
支持，只需在 config.json 中添加对应提供商的配置块，同时在 .env 中添加对应格式的 API 密钥即可扩展新的符合 OpenAI 规范的提供商。