ghcr.io/tashfeenahmed/freellmapi:v0.13.3

FreeLLMAPI

每月 74 亿 Token、34 个免费 LLM 服务商、635 个免费模型端点，仅需一个兼容 OpenAI 的端点即可接入。

聚合数十个服务商的免费额度，以及自定义的兼容 OpenAI 的对话、嵌入、图像和音频端点，所有能力统一通过 /v1 API 对外提供。密钥全部加密存储，路由模块会为每一条请求选择当前可用的最优模型：当某一服务商触发限流时，自动故障转移至下一个可用服务商，同时跟踪每个密钥的使用量，确保你不会超出任何一个免费额度的上限。

freellmapi.co · 可浏览完整模型目录：共 474 个模型系列、635 个免费端点

English · 简体中文

路由服务会从经过签名的数据源自动更新自身的模型目录：新增免费模型、配额调整、兼容性修复都无需执行 git pull 即可完成更新。免费安装版本每月获取一次目录快照，新加入实时数据源的模型会在 30 天后同步到实例；高级版路由服务可获取实时更新，新模型当日即可生效。 前往 freellmapi.co 开通 （每年 19 ***，可随时取消订阅）。

---

目录

• 项目背景
• 支持的服务商
• 兼容的 CLI 工具与代码代理
• 同类方案对比
• 功能特性
• 快速开始
• 桌面端应用
• 兼容所有适配 OpenAI 接口的客户端
• 支持语言
• 高级版（实时目录）
• API 使用说明
• 截图展示
• 工作原理
• 常见问题
• 使用限制
• 贡献指南
• 免责声明

相关指南： 安装与部署 · API 参考 · 客户端与代码代理 · 提示词压缩 · 架构与内部实现 · 文档总索引 · 贡献者指南

项目背景

当前主流的 AI 厂商都提供了免费额度，大多是每月数百万 Token、每日数千次请求的规格。单独使用某一个服务商的免费额度几乎没有实用价值，但把所有免费额度整合到一起，就能形成总计约 每月 74 亿 Token 的可用推理能力，覆盖 474 个模型系列 / 635 个服务商端点，从轻量快速的小模型到能力较强的大模型一应俱全。

但手动整合这些免费资源的过程十分繁琐：你需要对接 34 种不同的 SDK、适配 34 套不同的限流规则、还要处理 34 种可能导致请求失败的异常场景。FreeLLMAPI 将所有这些复杂度封装起来，对外仅提供一个兼容 OpenAI 的端点。你只需将任意 OpenAI 客户端指向本地部署的 FreeLLMAPI 服务，它就会在你已经配置密钥的所有服务商之间自动完成透明路由。

而且免费额度的生态每周都在变化：服务商可能无预警上线新模型、下线旧模型、调整配额规则，FreeLLMAPI 会帮你同步跟踪所有这些变动。路由服务会自动从 freellmapi.co 拉取经过签名的模型目录，你的部署实例无需执行 git pull 就能保持数据最新。关于更新时效的详细说明可参考高级版（实时目录）章节。

支持的服务商

Google Groq Cerebras OpenCode Zen

Mistral OpenRouter Cloudflare Cohere

Z.ai（智谱） NVIDIA HuggingFace

ModelScope Qwen3 · DeepSeek V4 · GLM-5（需绑定阿里云中国区账号）

……以及其余 22 家免费服务商

除此之外还支持自定义服务商：你可以在密钥配置页面将对话、嵌入、图像或音频类型的模型接入任意兼容 OpenAI 接口的端点，包括 llama.cpp、LM Studio、vLLM、本地 Ollama 实例或者远程网关。

完整的实时更新列表可访问 freellmapi.co/models 查看，页面提供了每个模型的限流规则、上下文窗口大小和免费 Token 配额信息。

兼容的 CLI 工具与代码代理

Claude Code Codex CLI Gemini CLI Cursor

Cline Roo Code OpenCode Aider

……此外还兼容 Continue、Goose、Qwen Code、Kilo Code、Crush、Zed、JetBrains AI、DeepSeek Harness、MiMo Code、AtomCode、OpenClaw、Hermes Agent、Pi、Reasonix，以及所有适配 OpenAI、Anthropic、Gemini 或 Ollama 接口的客户端。

绝大多数代码代理工具只需执行一条命令即可完成配置，该命令会自动读取当前实例的实时模型目录、备份原有配置并完成合并：

npx freellmapi setup-claude --url http://localhost:3001 --api-key

查看所有支持的代理工具及其配置命令 → · 各工具适配教程、MCP 服务器与 URL 令牌说明 →

同类方案对比

数据基于 2026 年 7 月公开文档整理，欢迎提交勘误。

功能特性

• 所有 OpenAI 风格接口 — 涵盖 /v1/chat/completions、Codex CLI 所需的 /v1/responses、支持编辑器文本自动补全的 /v1/completions、/v1/images/generations、/v1/videos/generations、/v1/audio/speech、/v1/audio/transcriptions、/v1/embeddings 以及 /v1/models，同时支持流式与非流式调用，可通过官方 SDK 或任意兼容 OpenAI 的客户端直接使用。API 参考 →
• Anthropic Messages API — 同一路由器上的 /v1/messages 接口完全兼容 Anthropic 传输协议，因此 Claude Code 与 Anthropic 官方 SDK 可直接对接您的免费模型资源池。详情 →
• 原生 Gemini 与 Ollama 接口 — Gemini CLI 可通过 /v1beta 路径使用 generateContent、流式输出、Token 计数、模型查询等能力；可选开启的 Ollama 模拟服务可提供 NDJSON 格式的聊天/生成接口、标签、元数据与嵌入向量能力，适配 Zed、JetBrains 等所有本地模型客户端。
• 融合（多模型综合生成） — 调用虚拟的 fusion 模型时，路由器会将您的提示并行分发至一组不同类型的免费模型，再由一个评判模型从所有返回草稿中整合输出统一结果。详情 →
• 图像、视频与语音生成 — /v1/images/generations、/v1/videos/generations 和 /v1/audio/speech 会自动路由到提供对应媒体模型的上游服务；图像与语音接口同时支持对接自定义的兼容 OpenAI 规范的媒体端点。视频任务会对同步和异步排队的上游服务输出做统一标准化处理，最终返回完整的 MP4 文件。
• 工具调用与结构化输出 — OpenAI 风格的 tools 参数可在所有上游提供商间正常往返（纯文本格式的工具调用会自动校正为标准的 tool_calls 格式），同时完整透传 response_format、seed、logprobs、各类惩罚系数以及其余所有采样参数。
• 智能路由，六种调度策略 — 系统会实时统计每个模型的速度、能力、可靠性得分，对可用模型链做动态优先级排序；触发 429/5xx 错误时会自动故障转移，在下一个模型上重试，同时配套冷却机制与密钥轮换能力。路由机制详情 →
• 统一模型与配置集 — 同一模型的多个上游提供商实例会被合并为单一条目，组内支持严格的故障转移；您可自定义命名故障转移链配置集（例如编码专用链、视觉处理专用链），既可以从控制台直接切换，也可以在请求中通过 auto: 前缀指定，自定义链也可在链管理器中直接就地重命名。
• 按密钥速率追踪 — 以 (平台, 模型, 密钥) 为维度维护 RPM/RPD/TPM/TPD 计数器，会自动学习上游提供商声明的配额上限，确保路由请求永远不会超出任意配额限制。
• 自动更新的模型目录 — 路由器每日两次从 freellmapi.co 同步签名目录：新模型上线、配额变更、上游适配问题修复都会自动生效。免费安装版本会同步月度快照，新模型在正式线上 feed 上线 30 天后才会进入免费版目录；高级版路由器可当日同步所有更新。高级版 →
• 粘性会话与上下文交接 — 单场对话会默认绑定在同一模型上保持 30 分钟；可选启用的轻量交接标记功能可在对话中途切换模型时，保证会话上下文连贯。详情 →
• 提示压缩（可选） — 具备故障开放特性的共享请求流水线可自动对提示去重、过滤工具输出、压缩重复 JSON、裁剪过期上下文，整个过程发生在缓存查询与路由调度之前。详情 →
• 加密密钥，统一单令牌输出 — 上游服务商密钥在 SQLite 中以 AES-256-GCM 标准加密存储，仅在单次请求处理时在内存中解密；您的所有应用仅需使用单个统一的 freellmapi-… 格式 Bearer 令牌即可完成所有调用。
• 管理控制台与统计分析 — 基于 React 的可视化 UI 可管理密钥、调整模型链顺序、运行接口调试沙箱、查看 24 小时至 90 天区间内的 p50/p95/首 Token 延迟统计；支持登录鉴权、明暗双主题，已内置 60 种语言。
• 原生支持 *** 的 MCP 服务端与交互式文档 — *** 与其他 MCP 客户端可通过 /mcp 接口调用 FreeLLMAPI 推理能力、查询可用模型列表、查看上游服务状态/使用量/缓存/路由元数据，还可直接调整路由策略；无依赖的 OpenAPI 文档托管在 /v1/docs 路径。*** 与编码智能体对接 →
• 运维优化特性 — 可选启用响应缓存、加密数据库备份、定期密钥健康检查、批量密钥导入导出、声明式启动配置。安装与部署 →
• 兼容所有 Node 20+ 运行环境 — 可部署在 Windows、macOS、Linux 服务器，甚至小型 ARM 单板计算机（包括树莓派）上。闲置运行内存仅约 40 MB，可对接 PM2、systemd 或任意您偏好的进程托管工具。

本项目功能边界做了明确限定，详情可查看暂不支持的功能列表。

快速开始

一键安装命令（需提前安装 Docker — 自动创建 ~/freellmapi 目录、生成加密密钥、拉取镜像并启动容器）：

curl -fsSL https://freellmapi.co/install.sh | bash

倾向于先查看脚本内容再执行？安装脚本地址可在此查看。重复执行该脚本是安全的：您的 .env 文件（包含加密密钥）会被完整保留，容器将自动更新到 :latest 版本。

安装完成后打开 http://localhost:3001，在 密钥 页面添加您的上游服务商密钥，按需调整 故障转移链 的顺序，最后从 密钥 页面顶部获取您的统一 API 密钥。该统一密钥就是对接 OpenAI SDK 所需的凭证。

在 Windows 平台，最简单的部署方式是使用桌面端 **https://github.com/tashfeenahmed/freellmapi/releases/latest**（下文将详述）。在 Android 设备上可参考实验性的 Termux 部署指南。

其余部署方式说明，包括 Docker Compose、本地开发、声明式启动配置、生产环境构建、局域网访问与备份方案，均收录在 docs/en/install/01-install.md 中。

桌面客户端

原生菜单栏应用位于仓库 desktop/ 目录：完整的路由与控制台能力在本地后台运行，托盘悬浮弹窗可实时展示请求统计数据。

https://github.com/tashfeenahmed/freellmapi/releases/latest — 每个正式发布版本都会附带 macOS .dmg 和 Windows .exe 安装包。首次使用无需注册账号或设置密码：唯一需要的凭证就是托盘弹窗中显示的统一 API 密钥。源码构建步骤与数据存储位置说明见 docs/en/install/01-install.md#desktop-app。

针对 macOS 12 Monterey 及以上系统，请根据您的硬件选择 arm64（Apple Silicon） 或 x64（Intel） 版本。两个 macOS 构建版本同时还提供 ZIP 格式下载包。

可兼容所有支持 OpenAI 协议的客户端

任何能够自定义 OpenAI 兼容接口基础地址的工具都可正常对接：将接口基础地址设置为 http://localhost:3001/v1，填入控制台获取的统一密钥即可。所有生成器都支持 --dry-run 试运行模式；npx freellmapi launch（适配 Claude Code）与 launch-codex（适配 Codex）命令可完全避免将凭证写入本地配置文件。该路由器同时可作为 MCP 服务端运行，智能体可在会话过程中直接内省获取运行状态。

******* 通过专用的 Secure MCP 隧道连接到同一台本地路由器。ask_freellmapi MCP 工具会将 *** 发起的任务请求路由到 /v1/chat/completions 接口，并返回结果，其中包含实际提供服务的模型、回退策略、缓存、执行情况以及 Token 元数据。基础 URL 和 Bearer 认证信息存储在隧道客户端配置中；默认模型通过环境变量 MCP_INFERENCE_DEFAULT_MODEL 设置（未设置时为 auto）。请勿将任何密钥提交到 Git，也不要将密钥写入 MCP URL。***** 配置指南 →**

您也可以通过终端管理提供商密钥，操作时需使用控制台会话令牌（FREELLMAPI_DASHBOARD_TOKEN 或参数 --token）：运行命令 npx freellmapi keys add|list|remove|test，其中 keys test 子命令会重新校验所有已存储的密钥。详细说明请参考 cli/README.md。

FreeLLMAPI 在设计上优先支持本地运行，且默认仅为单用户场景。您的所有提供商密钥都会保存在本地 SQLite 数据库中，且会进行静态加密，所有请求均从您的本机发往您已启用的上游提供商。

多语言支持

本产品内置的控制面板支持 60 种语言（桌面托盘菜单支持 6 种）。UI 在首次加载时会自动检测浏览器/系统语言，您也可以随时点击 ⋯ → 设置 切换语言，选择结果会被自动保存。从右至左书写的语言（阿拉伯语、希伯来语、波斯语、乌尔都语）会自动调整整体布局方向，且系统仅会加载当前使用语言的词典，剩余语言资源完全不会占用您的带宽。

完整的语言区域列表可查看文件 client/src/i18n/locale-config.ts。

最初的 6 种语言区域经过人工审核，后续新增语言均为机器翻译版本，后续会随着母语用户提交修正内容不断优化 —— 仅修改单条文本的 PR 是非常适合新手的首次贡献方式。

所有翻译内容均以扁平化 JSON 文件形式存储在 client/src/i18n/locales/ 目录下。如需修改某条翻译文本，直接编辑对应语言 JSON 文件中的值即可；如需新增语言，先复制 en.json 文件，翻译其中所有值，然后在 client/src/i18n/locale-config.ts 中注册新增的语言区域（如果需要同时支持桌面托盘多语言，还需在 desktop/src/i18n.ts 中完成注册）。运行 npm test 命令可校验所有语言区域的键名与占位符是否与基准版本完全一致，我们欢迎所有相关 PR 提交。

高级版（实时目录）

路由器会自动更新其模型目录：每日从 freellmapi.co 拉取两次经过签名的目录数据，并将新增模型、配额变动、提供商适配修复同步到您的本地数据库中。您手动设置的启用/禁用状态以及自定义提供商配置完全不会被改动，且所有下载内容在生效前都会通过预先固定的 Ed25519 密钥完成签名校验。

当前目录已收录 34 个提供商、474 个模型系列、635 个免费提供商/模型端点（其中包含 584 个对话端点、41 个 Embeddings 端点、7 个语音转文字端点、3 个视频处理端点），覆盖的免费层级总 Token 容量约为 每月 74 亿。您可以在 freellmapi.co/models 页面浏览完整的目录内容。

免费安装版本同样会拉取经过签名的目录，但使用月度快照源：新模型会在进入实时目录 30 天后才加入月度快照，因此免费版本的目录当前比实时版本少约 303 个模型。免费版本的所有功能均不会过期，也没有任何功能阉割，只是目录更新延迟更久。

高级版可在您运行的每台路由器上启用实时同步目录：当某个提供商上线优质免费模型、悄悄收紧配额、或者修改接口传输格式时，运行实时同步的路由器会在我们发布更新的当日收到同步内容。

前往 freellmapi.co 开通实时目录 →

• 19 ***/年，或一次性 49 ***获得终身授权。通过 Stripe 完成支付，可随时自助取消订阅。
• 一个以 fla_ 开头的密钥可覆盖您所有运行中的路由器实例，包括桌面端、家庭实验室设备、树莓派。
• 在控制面板的 高级版 页面中完成激活，您也可以访问 freellmapi.co/manage 自助管理账单、取消订阅。
• 路由器本体始终采用 MIT 许可协议，完全免费开源。高级版仅提供实时目录服务，相关收入全部用于支持每日模型测试与目录维护，保障目录可用。

目录服务器绝对不会获取您的提示词、生成结果或提供商密钥，无论是否开通高级版，路由器都保持完全自托管的运行模式。

使用 API

from openai import OpenAI

client = OpenAI(
base_url="http://localhost:3001/v1",
api_key="freellmapi-your-unified-key",
)

resp = client.chat.completions.create(
model="auto", # 让路由器自动选择，也可填写 "auto:fast"、"auto:smart"、自定义路由配置文件或具体模型 ID
messages=[{"role": "user", "content": "用一句话总结罗马帝国的衰落。"}],
)
print(resp.choices[0].message.content)
print("实际路由至：", resp.headers.get("x-routed-via"))

流式输出、auto:* 系列路由策略、工具调用、视觉输入、Gemini 谷歌搜索 grounding、Embeddings 以及 Anthropic Messages 接口适配相关内容，均附带 curl 和 Python 使用示例，完整文档请查阅 docs/en/api/01-rest-api.md。所有响应都会返回 X-Routed-Via: / 响应头，您可以通过它查看实际处理请求的提供商。

界面截图

模型页面

选择路由策略，即可查看所有接入提供商的月度 Token 总使用进度。每个模型都会显示实时可靠性、响应速度和智能度评分 — 页面从上到下的排序，就是当前生效的请求路由优先级。

密钥页面

管理所有提供商凭证，同时获取供您应用连接使用的统一 API 密钥。每个密钥都会显示健康状态标识点，以及上次完成健康检查的时间。

测试面板

通过路由器发送对话补全请求，即可直接在返回消息上查看实际处理请求的提供商、对应模型 ID 和延迟数据。您可通过按钮选择、拖拽、粘贴三种方式上传文件：上传的图片（PNG/JPEG/WebP/GIF）会在浏览器端完成降采样后，作为图像内容部分发送给支持视觉能力的模型；上传的文本文件（TXT/MD/CSV/JSON/LOG）会自动以代码块格式内嵌到提示词中。

统计面板

展示 24 小时 / 7 天 / 30 天 / 90 天时间窗口内的请求量、成功率、输入输出 Token 数量、平均延迟，以及按提供商维度拆分的明细数据。

运行原理

一条请求进入后，系统就会输出最优可用的免费模型响应：路由器会自动选择优先级最高、密钥状态正常、且未超出所有速率限制的模型，在内存中解密密钥后调用上游提供商接口 — 如果收到 429 或 5xx 错误，系统会将该密钥暂时标记为冷却状态，自动重试路由链中的下一个可用模型。组件详解、路由内部逻辑和运行细节文档请查看 docs/en/architecture/00-high-level-index.md。

常见问题

我需要设置密码吗？ 桌面端应用无需设置密码 — 控制面板会通过本地隐藏账号自动完成登录，无需额外配置也无需记忆密码。您可点击托盘图标 → 打开控制面板 直接访问。通过服务器方式部署的实例（Docker、一键部署脚本、npm run dev）仍需配置***和登录密码。

服务器安装环境下忘记密码：点击登录页面的Forgot password?。由于系统不会发送邮件链接，一次性验证码会直接打印到服务器日志中，你可以通过 docker compose logs -f freellmapi 读取（也可在运行服务器的终端或桌面版日志文件中查看），随后在重置表单中输入该验证码即可。验证码有效期为 15 分钟。

日志存放在哪里？ Docker 部署的日志位于容器日志中，源码运行的日志直接输出到终端，桌面版应用的日志路径为 /logs/freeapi.log，可通过托盘菜单的打开日志文件夹选项访问。

如何卸载？ 移除应用（macOS 拖入废纸篓、Windows 进入设置 → 应用、Docker 部署执行 docker compose down -v），之后删除数据目录：Windows 路径为 %APPDATA%\FreeLLMAPI\、macOS 路径为 ~/Library/Application Support/FreeLLMAPI/、Linux 路径为 ~/.config/FreeLLMAPI/。卸载操作本身不会自动删除该文件夹。

各安装方式对应的详细说明请查看 docs/en/install/01-install.md#faq-passwords-logs-uninstall。

局限性

叠加多个免费层级服务存在明显的权衡：不支持前沿模型、延迟不稳定、没有 SLA 保障；且在当日晚些时候，主流模型达到每日调用上限后，端点的实际可用能力会下降，直到 UTC 午夜才会重置。在基于本项目搭建任何实际业务前，请先阅读 docs/en/architecture/00-high-level-index.md#limitations 中的完整说明清单。

贡献

我们非常欢迎所有贡献者！请参阅 CONTRIBUTING.md 了解开发流程、PR 提交规范以及 AI/大模型辅助贡献的相关政策（简言之：这类贡献同样受欢迎，且和其他 PR 遵循相同的质量标准）。适合新手的 PR 方向包括：

• 新增服务提供商：复制 server/src/providers/openai-compat.ts 作为模板，将其接入 server/src/providers/index.ts，在 server/src/db/index.ts 中预置对应的模型，并在 server/src/__tests__/providers/ 中添加测试用例。
• 新增端点：实现内容审核接口以及其他 OpenAI 兼容的接口。你可以在服务提供商基类中扩展新方法，由适配器声明自身支持哪些接口。
• 优化路由：实现成本感知路由（在“最经济-健康可用-最低延迟”之间做权衡）、优化延迟加权优先级、添加区域绑定功能。
• 仪表盘优化：为分析页面添加图表、优化密钥轮换用户体验、支持从 .env 文件批量导入密钥。
• 文档完善：补充更多使用示例、提供 Go/Rust 等语言的客户端代码片段、新增 Docker 或 Fly 的部署方案。

执行 npm install && npm run dev 后，服务器会运行在 :3001 端口，仪表盘运行在 :5173 端口，两者均支持热模块替换（HMR）。如果需要可复现的开发环境，Bash 用户可运行 ./scripts/dev-bootstrap.sh，PowerShell 用户可运行 .\scripts\dev-bootstrap.ps1，两个脚本都会保留现有的 .env 文件。提交的 PR 必须包含测试用例，保证现有测试套件全部通过（执行 npm test 验证），且符合仓库中已有的 .editorconfig 和 tsconfig 默认配置。数据库迁移工作流和完整贡献流程请查看 CONTRIBUTING.md。

贡献者

免责声明

[!IMPORTANT] 本项目仅用于个人实验和学习用途，不得用于生产环境。

各类云服务商的免费层级面向的是开发者原型验证场景，本身并非稳定、受支持的推理服务基座，不应被当作生产级服务对待。如果你基于 FreeLLMAPI 搭建实际业务，请在正式发布前切换为付费 API。你与每个上游服务商的关系受你创建账号时同意的服务条款约束，即使流量经过本项目代理，这些条款仍然生效，你需要自行承担遵守相关条款的责任。

2026 年 5 月我们逐一审核了各服务商针对个人单用户代理场景的服务条款说明，相关内容请查看 docs/en/architecture/00-high-level-index.md#terms-of-service-review。

许可证

MIT