1. 为什么要在 Node.js 里折腾 FreeLLMAPI 这层网关如果你手头攒了 Groq、Mistral、OpenRouter、GitHub Models 这些平台的免费 Key大概率会遇到同一个问题每个平台的 SDK 不一样、限流规则不一样、模型名不一样写个小工具得在四五个base_url之间来回切。FreeLLMAPI 这个开源项目干的事就是把这些免费额度聚合成一个 OpenAI 兼容的端点你只改base_url和api_keyLangChain、LlamaIndex、Continue 这类工具基本不用动代码。它适合谁适合想统一管理多家 LLM 免费额度、又不想自己写路由层的开发者。项目本身定位是个人实验和学习别往生产环境上怼。我这次的做法是在本地跑 FreeLLMAPI 做聚合再把上游统一指向 TaoToken 的 API 通道这样国内网络环境下不用额外折腾就能稳定拿到模型响应同时保留 FreeLLMAPI 的故障转移和优先级调度能力。下面按「环境准备 → 克隆安装 → 配置骨架 → 接入 TaoToken → 验证聚合 → 排错」的顺序走一遍命令和配置都能直接复制。2. 前置准备Node.js 20 与 TaoToken 统一 KeyFreeLLMAPI 基于 Node.js 构建版本要求 20 以上。macOS 用brew install node22Windows 建议直接上 WSL2装完用node -v确认。Git 用来克隆仓库各平台免费 Key 提前在后台生成好首次配置建议先注册三家Groq、Mistral、OpenRouter就够跑通链路。TaoToken 这边你需要先拿到统一 Key。打开 https://taotoken.net/api-keys 创建 API Key这个 Key 后面会作为 FreeLLMAPI 的上游凭证写进配置。TaoToken 的 API 地址是 https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions格式所以它能直接当成 FreeLLMAPI 的一个 Provider 来用。注意TaoToken 的 Key 只在服务端配置里出现不要写进前端代码或提交到 Git 仓库。FreeLLMAPI 用 AES-256-GCM 加密存储上游 Key但你自己也别把明文 Key 散落在.env之外的地方。如果你还没决定用哪些模型可以先到 https://taotoken.net/models 看一眼支持的模型列表再决定 FreeLLMAPI 里 Provider 的优先级顺序。3. 克隆安装与 config.toml / settings.json 配置骨架3.1 克隆仓库并安装依赖git clone https://github.com/tashfeenahmed/freellmapi.git cd freellmapi npm install3.2 生成加密密钥FreeLLMAPI 用一个 64 位十六进制密钥加密上游 API Key存在.env里cp .env.example .env echo ENCRYPTION_KEY$(node -e console.log(require(crypto).randomBytes(32).toString(hex))) .envWindows 下如果命令不兼容直接用编辑器打开.env把ENCRYPTION_KEY后面手动填一个 64 位十六进制字符串。3.3 config.toml 配置骨架FreeLLMAPI 的 Provider 和路由策略可以通过config.toml声明。下面这份骨架把 TaoToken 放在回退链首位后面接 Groq 和 OpenRouter 作为补充[server] port 3001 dashboard_port 5173 [router] strategy dynamic_penalty sticky_session_ttl 1800 max_retries 3 [[providers]] name taotoken type openai_compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY priority 1 models [gpt-4o-mini, claude-3-5-sonnet] [[providers]] name groq type openai_compatible base_url https://api.groq.com/openai/v1 api_key_env GROQ_API_KEY priority 2 models [llama-3.3-70b-versatile] [[providers]] name openrouter type openai_compatible base_url https://openrouter.ai/api/v1 api_key_env OPENROUTER_API_KEY priority 3 models [meta-llama/llama-3.1-8b-instruct:free]3.4 settings.json 配置骨架管理面板的部分行为由settings.json控制放在项目根目录{ dashboard: { auth_required: true, session_timeout: 3600 }, routing: { health_check_interval: 60, penalty_decay_seconds: 300, fallback_on_status: [429, 500, 502, 503] }, logging: { level: info, log_routed_via: true } }log_routed_via打开后每次请求的响应头里会带x-routed-via方便你确认这次到底走了哪个 Provider。3.5 把 TaoToken Key 写进环境变量echo TAOTOKEN_API_KEY你的TaoToken密钥 .env echo GROQ_API_KEY你的Groq密钥 .env echo OPENROUTER_API_KEY你的OpenRouter密钥 .env3.6 启动服务npm run dev启动后你会看到两个地址后端 API 在http://localhost:3001管理面板在http://localhost:5173。浏览器打开面板首次访问创建一个管理员账户。4. 验证 16 家额度聚合是否生效4.1 在面板里确认 Provider 健康状态登录 Dashboard 后进 Keys 页面逐个添加 Provider。TaoToken 选openai_compatible类型base_url 填https://taotoken.net/api粘贴 Key 后系统会自动做健康检查。绿色代表可用红色代表 Key 无效或被限流。把 16 家都加完后Fallback Chain 页面能看到完整的优先级队列。4.2 获取统一 API Key配置完至少一个 Provider 后Keys 页面顶部会生成一个freellmapi-xxxx格式的统一 Key。复制保存后面所有客户端都用这个 Key 认证。4.3 用 curl 验证链路curl http://localhost:3001/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer freellmapi-你的统一Key \ -d { model: auto, messages: [{role: user, content: 用一句话介绍你自己}] }正常返回是一个包含模型回复的 JSON。重点看响应头里的x-routed-via字段它会告诉你这次请求实际由哪个 Provider 处理。如果显示taotoken说明 TaoToken 通道已经生效。4.4 用 Node.js 脚本批量验证const BASE http://localhost:3001/v1; const KEY freellmapi-你的统一Key; async function check(model) { const res await fetch(${BASE}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${KEY} }, body: JSON.stringify({ model, messages: [{ role: user, content: ping }] }) }); const routed res.headers.get(x-routed-via); console.log(${model} - ${res.status} via ${routed}); } (async () { await check(auto); await check(gpt-4o-mini); await check(llama-3.3-70b-versatile); })();跑完这个脚本你能清楚看到每个模型实际走了哪条通道。如果某个 Provider 返回 429路由器会自动把它下沉下次请求换下一个健康的。5. 本篇常见错排查5.1 ENCRYPTION_KEY 缺失或长度不对报错通常是Invalid encryption key length。检查.env里的ENCRYPTION_KEY是不是 64 位十六进制。用node -e console.log(process.env.ENCRYPTION_KEY?.length)确认长度是 64。5.2 Provider 健康检查一直红色先确认 Key 本身有效再确认 base_url 没写错。TaoToken 的 base_url 是https://taotoken.net/api不要多加/v1FreeLLMAPI 会自己拼路径。如果还是红色看后端日志里的具体错误码。5.3 请求返回 401 但统一 Key 是对的检查Authorization头是不是Bearer freellmapi-xxxx格式中间有空格。另外确认你用的是统一 Key 而不是某个上游 Provider 的 Key。5.4 429 频繁触发说明某个 Provider 的免费额度被打满了。进 Fallback Chain 页面把它的优先级调低或者临时禁用。settings.json里的penalty_decay_seconds可以调小让惩罚分衰减更快。5.5 多轮对话上下文断裂这是模型切换导致的。确认sticky_session_ttl设成了 1800 秒并且在请求头里带上X-Session-Id。FreeLLMAPI 会在 TTL 内把同一会话路由到同一个模型。5.6 面板打不开检查npm run dev是否两个服务都起来了。后端 3001、前端 5173端口被占用的话改config.toml里的port和dashboard_port。6. 长期编码场景的接入建议如果你打算把 FreeLLMAPI 当成日常编码的模型入口建议把 TaoToken 放在回退链首位再配合 Coding Plan 使用。Coding Plan 的接入地址是 https://taotoken.net/coding-plan适合需要长期稳定调用、跑 Agent 任务的场景。FreeLLMAPI 负责聚合和故障转移TaoToken 负责提供稳定的上游通道两者叠起来就是一个能扛住日常开发节奏的专属 AI 网关。接入文档在 https://taotoken.net/doc里面有完整的参数说明和示例。模型对话测试可以直接用 https://taotoken.net/chat 快速验证 Key 是否正常。配置过程中遇到路由问题先看x-routed-via响应头再对照后端日志基本能定位到是哪个 Provider 出的问题。 FreeLLMAPI 详细安装指南：用 Node.js 聚合 16 家 LLM 免费额度，接入 TaoToken 打造专属 AI 网关
1. 为什么要在 Node.js 里折腾 FreeLLMAPI 这层网关如果你手头攒了 Groq、Mistral、OpenRouter、GitHub Models 这些平台的免费 Key大概率会遇到同一个问题每个平台的 SDK 不一样、限流规则不一样、模型名不一样写个小工具得在四五个base_url之间来回切。FreeLLMAPI 这个开源项目干的事就是把这些免费额度聚合成一个 OpenAI 兼容的端点你只改base_url和api_keyLangChain、LlamaIndex、Continue 这类工具基本不用动代码。它适合谁适合想统一管理多家 LLM 免费额度、又不想自己写路由层的开发者。项目本身定位是个人实验和学习别往生产环境上怼。我这次的做法是在本地跑 FreeLLMAPI 做聚合再把上游统一指向 TaoToken 的 API 通道这样国内网络环境下不用额外折腾就能稳定拿到模型响应同时保留 FreeLLMAPI 的故障转移和优先级调度能力。下面按「环境准备 → 克隆安装 → 配置骨架 → 接入 TaoToken → 验证聚合 → 排错」的顺序走一遍命令和配置都能直接复制。2. 前置准备Node.js 20 与 TaoToken 统一 KeyFreeLLMAPI 基于 Node.js 构建版本要求 20 以上。macOS 用brew install node22Windows 建议直接上 WSL2装完用node -v确认。Git 用来克隆仓库各平台免费 Key 提前在后台生成好首次配置建议先注册三家Groq、Mistral、OpenRouter就够跑通链路。TaoToken 这边你需要先拿到统一 Key。打开 https://taotoken.net/api-keys 创建 API Key这个 Key 后面会作为 FreeLLMAPI 的上游凭证写进配置。TaoToken 的 API 地址是 https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions格式所以它能直接当成 FreeLLMAPI 的一个 Provider 来用。注意TaoToken 的 Key 只在服务端配置里出现不要写进前端代码或提交到 Git 仓库。FreeLLMAPI 用 AES-256-GCM 加密存储上游 Key但你自己也别把明文 Key 散落在.env之外的地方。如果你还没决定用哪些模型可以先到 https://taotoken.net/models 看一眼支持的模型列表再决定 FreeLLMAPI 里 Provider 的优先级顺序。3. 克隆安装与 config.toml / settings.json 配置骨架3.1 克隆仓库并安装依赖git clone https://github.com/tashfeenahmed/freellmapi.git cd freellmapi npm install3.2 生成加密密钥FreeLLMAPI 用一个 64 位十六进制密钥加密上游 API Key存在.env里cp .env.example .env echo ENCRYPTION_KEY$(node -e console.log(require(crypto).randomBytes(32).toString(hex))) .envWindows 下如果命令不兼容直接用编辑器打开.env把ENCRYPTION_KEY后面手动填一个 64 位十六进制字符串。3.3 config.toml 配置骨架FreeLLMAPI 的 Provider 和路由策略可以通过config.toml声明。下面这份骨架把 TaoToken 放在回退链首位后面接 Groq 和 OpenRouter 作为补充[server] port 3001 dashboard_port 5173 [router] strategy dynamic_penalty sticky_session_ttl 1800 max_retries 3 [[providers]] name taotoken type openai_compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY priority 1 models [gpt-4o-mini, claude-3-5-sonnet] [[providers]] name groq type openai_compatible base_url https://api.groq.com/openai/v1 api_key_env GROQ_API_KEY priority 2 models [llama-3.3-70b-versatile] [[providers]] name openrouter type openai_compatible base_url https://openrouter.ai/api/v1 api_key_env OPENROUTER_API_KEY priority 3 models [meta-llama/llama-3.1-8b-instruct:free]3.4 settings.json 配置骨架管理面板的部分行为由settings.json控制放在项目根目录{ dashboard: { auth_required: true, session_timeout: 3600 }, routing: { health_check_interval: 60, penalty_decay_seconds: 300, fallback_on_status: [429, 500, 502, 503] }, logging: { level: info, log_routed_via: true } }log_routed_via打开后每次请求的响应头里会带x-routed-via方便你确认这次到底走了哪个 Provider。3.5 把 TaoToken Key 写进环境变量echo TAOTOKEN_API_KEY你的TaoToken密钥 .env echo GROQ_API_KEY你的Groq密钥 .env echo OPENROUTER_API_KEY你的OpenRouter密钥 .env3.6 启动服务npm run dev启动后你会看到两个地址后端 API 在http://localhost:3001管理面板在http://localhost:5173。浏览器打开面板首次访问创建一个管理员账户。4. 验证 16 家额度聚合是否生效4.1 在面板里确认 Provider 健康状态登录 Dashboard 后进 Keys 页面逐个添加 Provider。TaoToken 选openai_compatible类型base_url 填https://taotoken.net/api粘贴 Key 后系统会自动做健康检查。绿色代表可用红色代表 Key 无效或被限流。把 16 家都加完后Fallback Chain 页面能看到完整的优先级队列。4.2 获取统一 API Key配置完至少一个 Provider 后Keys 页面顶部会生成一个freellmapi-xxxx格式的统一 Key。复制保存后面所有客户端都用这个 Key 认证。4.3 用 curl 验证链路curl http://localhost:3001/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer freellmapi-你的统一Key \ -d { model: auto, messages: [{role: user, content: 用一句话介绍你自己}] }正常返回是一个包含模型回复的 JSON。重点看响应头里的x-routed-via字段它会告诉你这次请求实际由哪个 Provider 处理。如果显示taotoken说明 TaoToken 通道已经生效。4.4 用 Node.js 脚本批量验证const BASE http://localhost:3001/v1; const KEY freellmapi-你的统一Key; async function check(model) { const res await fetch(${BASE}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${KEY} }, body: JSON.stringify({ model, messages: [{ role: user, content: ping }] }) }); const routed res.headers.get(x-routed-via); console.log(${model} - ${res.status} via ${routed}); } (async () { await check(auto); await check(gpt-4o-mini); await check(llama-3.3-70b-versatile); })();跑完这个脚本你能清楚看到每个模型实际走了哪条通道。如果某个 Provider 返回 429路由器会自动把它下沉下次请求换下一个健康的。5. 本篇常见错排查5.1 ENCRYPTION_KEY 缺失或长度不对报错通常是Invalid encryption key length。检查.env里的ENCRYPTION_KEY是不是 64 位十六进制。用node -e console.log(process.env.ENCRYPTION_KEY?.length)确认长度是 64。5.2 Provider 健康检查一直红色先确认 Key 本身有效再确认 base_url 没写错。TaoToken 的 base_url 是https://taotoken.net/api不要多加/v1FreeLLMAPI 会自己拼路径。如果还是红色看后端日志里的具体错误码。5.3 请求返回 401 但统一 Key 是对的检查Authorization头是不是Bearer freellmapi-xxxx格式中间有空格。另外确认你用的是统一 Key 而不是某个上游 Provider 的 Key。5.4 429 频繁触发说明某个 Provider 的免费额度被打满了。进 Fallback Chain 页面把它的优先级调低或者临时禁用。settings.json里的penalty_decay_seconds可以调小让惩罚分衰减更快。5.5 多轮对话上下文断裂这是模型切换导致的。确认sticky_session_ttl设成了 1800 秒并且在请求头里带上X-Session-Id。FreeLLMAPI 会在 TTL 内把同一会话路由到同一个模型。5.6 面板打不开检查npm run dev是否两个服务都起来了。后端 3001、前端 5173端口被占用的话改config.toml里的port和dashboard_port。6. 长期编码场景的接入建议如果你打算把 FreeLLMAPI 当成日常编码的模型入口建议把 TaoToken 放在回退链首位再配合 Coding Plan 使用。Coding Plan 的接入地址是 https://taotoken.net/coding-plan适合需要长期稳定调用、跑 Agent 任务的场景。FreeLLMAPI 负责聚合和故障转移TaoToken 负责提供稳定的上游通道两者叠起来就是一个能扛住日常开发节奏的专属 AI 网关。接入文档在 https://taotoken.net/doc里面有完整的参数说明和示例。模型对话测试可以直接用 https://taotoken.net/chat 快速验证 Key 是否正常。配置过程中遇到路由问题先看x-routed-via响应头再对照后端日志基本能定位到是哪个 Provider 出的问题。