FreeRouter

兼容 OpenRouter 的 API 网关，将请求路由到不同来源的 LLM 服务。

功能

• 兼容 OpenAI 和 Anthropic API 格式
• 支持 streaming（SSE）和非 streaming 请求
• 两个虚拟模型：free-model（文本）和 free-model-vision（视觉）
• 429 限流自动重试：当一个模型返回 429 时，自动切换到下一个免费模型
• 免费模型每小时自动更新，按自定义排序规则排列
• 支持配置文件和环境变量两种配置方式
• 支持 HTTP 代理
• 配置文件热加载：修改配置后自动生效
• 自动发现配置文件：当前目录 > ~/.freerouter/config.toml > 自动生成

快速开始

安装依赖

cargo build

配置

启动时会按以下顺序查找配置文件：

1. 命令行 -c 参数指定的路径
2. 当前目录下的 config.toml
3. ~/.freerouter/config.toml
4. 如果都没找到，自动在 ~/.freerouter/ 生成默认配置

# 方式一：指定配置文件
cargo run -- -c config.toml

# 方式二：使用自动发现的配置文件
cargo run

配置文件格式

推荐先复制示例配置：

cp config.example.toml config.toml

[backend]
# 后端类型，可选 openai 或 anthropic，默认 openai
# type = "openai"
# 指定模型（可选，留空则自动选择免费模型）
# model = "minimax/minimax-m2.5:free"

[server]
port = 3721
host = "0.0.0.0"

# HTTP 代理（可选）
# proxy = "http://127.0.0.1:7890"

# API Key 配置（支持多个来源，4xx 错误时自动轮换）
# source 可选: openrouter / zai / custom
# 自定义来源 (source = "custom") 必须填写 base_url

[[api_keys]]
source = "openrouter"
key = "sk-or-v1-xxx"

# [[api_keys]]
# source = "zai"
# key = "your-zai-key"

# [[api_keys]]
# source = "custom"
# base_url = "https://your-endpoint.com/v1"
# key = "your-custom-key"

环境变量一览

变量	默认值	说明
FREEROUTER_PORT	3721	服务监听端口
FREEROUTER_HOST	0.0.0.0	服务监听地址
FREEROUTER_BACKEND_TYPE	openai	后端类型：openai 或 anthropic
FREEROUTER_MODEL	空	指定模型（留空则自动选择）
FREEROUTER_API_KEY	-	单个 API Key
FREEROUTER_API_SOURCE	openrouter	API Key 对应来源
FREEROUTER_BASE_URL	-	custom 来源时的 base URL
FREEROUTER_CONFIG	-	配置文件路径
FREEROUTER_PROXY	-	HTTP 代理地址

API 端点

端点	方法	说明
/v1/chat/completions	POST	OpenAI 聊天补全（文本模型）
/v1/chat/completions:vision	POST	OpenAI 聊天补全（视觉模型）
/v1/messages	POST	Anthropic 消息（文本模型）
/v1/messages:vision	POST	Anthropic 消息（视觉模型）
/v1/models	GET	列出可用模型
/health	GET	健康检查

模型选择规则

• free-model：使用支持 text 输入的免费模型，按 minimax → zai → qwen → 其他(创建时间倒序) 排序
• free-model-vision：使用支持 image 输入的免费模型，排序规则同上

如果配置中指定了 model，则优先使用配置的模型，不再自动轮换。

429 限流自动重试

当后端返回 429 时，FreeRouter 自动按排序顺序尝试下一个模型，直到成功或所有模型都用尽。

模型列表自动更新

• 启动时自动从 OpenRouter 获取所有 :free 模型
• 每小时自动刷新模型列表
• 模型列表缓存到 ~/.freerouter/models.json
• Provider 列表缓存到 ~/.freerouter/provider.json

配置热加载

修改配置文件后，FreeRouter 每 10 秒检测一次变更，自动重新加载。

目录结构

~/.freerouter/
├── config.toml       # 配置文件
├── models.json       # 缓存的免费模型列表
└── provider.json     # 缓存的 Provider 列表