FreeLLMAPI 部署指南｜免费 LLM 聚合路由网关本地部署与多客户端接入手册

FreeLLMAPI 是一个本地优先的免费 LLM 聚合路由网关：把多家免费提供方与数百个模型端点统一到一个 OpenAI 兼容 /v1 接口，内置智能路由、自动回退、提供商密钥加密与用量面板；支持一键脚本、Docker Compose、本地源码开发与桌面应用四种部署方式，并可接入 Claude Code、Codex CLI、Gemini CLI 等主流编程智能体。

1 项目简介

1.1 项目定位与开源信息

FreeLLMAPI 是一个自托管、OpenAI 兼容的 LLM 聚合路由网关（gateway / router），以 MIT 许可开源。它把多家上游免费模型额度，以及任意自建 OpenAI 兼容的聊天、嵌入、图像、音频端点聚合到一个统一的 /v1 端点之后；上游提供商密钥使用 AES-256-GCM 静态加密，路由器按实时可靠性、速度与智能度为每个请求选择模型，遇到 429 限流或 5xx 错误时自动冷却当前密钥并回退到链路上的下一家。

项目面向个人实验、学习与原型验证，采用单用户、local-first 设计：面板、密钥、链路配置与用量记录都保存在本机，不依赖厂商云服务。路由器本体永久免费，付费项仅为 Premium 实时目录订阅。

说明：本文命令、路径、端口、环境变量、模型族与端点均以官方仓库 main 分支文档为准；如本文与官方最新文件存在差异，以仓库当前版本为准。

1.2 免费额度与目录口径

项目同时存在两套目录口径，分别对应免费安装内置的签名快照目录与 Premium 实时目录，两者更新频率不同，本文分列使用、不混为同一数字：

表 1 两套目录口径对照

• 免费安装不携带实时目录：系统内置月度签名快照，新模型滞后约 30 天；功能不因此阉割，模型与提供商仍可手动添加。
• Premium 目录由目录服务器每日两次同步，签名目录使用固定 Ed25519 公钥验签；目录服务器看不到提示词、补全内容与提供商密钥。

• 实时目录浏览入口：https://freellmapi.co/models.html （页面 308 跳转到 /models）。 Premium 定价与权益：

• 价格：19 美元 / 年，或 49 美元一次性终身；Stripe 支付，可随时在自助管理页取消订阅。

• 一个 fla_ 前缀密钥覆盖全部路由器：桌面应用、家庭服务器、树莓派共用同一密钥，在仪表盘 Premium 页完成激活。
• Premium 自助管理：https://freellmapi.co/manage ；路由器本体 MIT 永久免费，Premium 仅出售实时目录订阅。

1.3 核心能力

• OpenAI 兼容全套接口：聊天补全、Responses、旧式 Completions、图像生成、文本转语音、嵌入向量、模型清单，支持流式与非流式响应。
• Anthropic Messages 面：/v1/messages 与主链路同路由，Claude Code 与官方 Anthropic SDK 可直接接入。
• 原生 Gemini 面与可选 Ollama 模拟面：/v1beta 原生路径供 Gemini CLI 使用；/api/* Ollama 模拟供 Zed、JetBrains AI 等本地客户端使用。
• Fusion 多模型合成：虚拟 fusion 模型并行分发一组免费模型起草，再由裁判模型合成最终答案。
• 图像、语音、视频跨提供方路由；图像与语音同时支持接入自定义 OpenAI 兼容媒体端点。
• 工具调用与结构化输出：tools / tool_choice 在提供商之间往返；纯文本形式的工具调用可被救援为真实 tool_calls 结构。
• 六档智能路由与自动回退：按实时速度、稳定性、能力评分排序；429 / 5xx 冷却当前密钥后切下一家，单请求最多尝试 20 次，并记录完整回退轨迹。
• 统一模型条目与命名回退链：同一模型的多家提供方合并为一个条目；面板可切换命名回退链，请求级也可用 auto:<profile> 指定。
• 按密钥限流跟踪：以（平台、模型、密钥）维度记录 RPM / RPD / TPM / TPD 计数，学习各提供商公布的上限。
• 自更新签名目录：每日两次拉取签名目录，新模型、额度变更与兼容性修复自动生效；用户自行启用 / 停用的选择与自定义提供方不被覆盖。
• 粘性会话与上下文交接：会话在 30 分钟内粘着同一模型；中途更换模型时可向新模型注入交接 system 消息。
• 可选提示词压缩：在缓存查找与路由前去重、过滤工具输出、压缩重复 JSON 结构、裁剪过时上下文。
• 密钥加密存储：对外仅暴露一个 freellmapi- 前缀 Bearer 令牌，提供商密钥不落明文配置。
• 管理面板与用量分析：管理密钥、链路顺序、试验台，查看 24 小时至 90 天窗口的请求量、成功率、进出 token、平均 / P95 延迟与 TTFT；面板带登录保护、明暗主题与 60 种语言。
• MCP 服务与交互式 OpenAPI 文档：/mcp 端点可接入 MCP 客户端；/v1/docs 提供交互式 OpenAPI 查看器，/v1/openapi.json 提供规格文件。
• 运维便利：可选响应缓存、加密数据库备份、定期密钥健康检查、密钥批量导入导出、声明式启动配置。
• 跨平台：Windows、macOS、Linux 服务器以及 ARM 单板机（含树莓派）均可运行。

1.4 技术架构

网关由 Express 服务端进程承载，React / Vite 面板与 API 共用同一个 3001 端口；面板会话与 API 密钥分两套鉴权，数据落本地 SQLite 文件，提供商密钥加密后入库。整体组件关系如下（依据官方架构文档整理）：

OpenAI SDK / curl / any OpenAI client
        |  Bearer freellmapi-...
        v
Express proxy (:3001) - /v1/chat/completions
        |
        v
Router: healthy key, under limits; decrypt key, call SDK
        |  429/5xx: cooldown and retry next model
        v
Google . Groq . Cerebras . OpenRouter . HF . ...29 more

• 服务端：Express 进程，对外提供 API、面板静态资源与 MCP 端点；空闲约 40 MB RSS，可由 PM2、systemd、Docker 等任意守护进程托管。
• 面板：React / Vite / shadcn/ui，管理密钥、模型链路、试验台、用量分析与 Premium 激活；服务端安装需邮箱 + 密码，桌面应用无需账号密码。
• 存储：单文件 SQLite；提供商密钥使用 ENCRYPTION_KEY 派生的 AES-256-GCM 密钥加密；数据库备份经密钥指纹校验，跨密钥不可恢复。

2 资源下载与官方跳转

2.1 下载渠道

表 2 官方下载与入口渠道

2.2 官方文档跳转

表 3 官方文档索引

2.3 版本、协议与运行环境

• 协议：MIT；路由器本体永久免费，Premium 仅为实时目录订阅。
• 当前版本：v0.16.9（2026-10-23）；Docker 镜像标签 latest、main、v..* 与 sha-<commit>。
• 服务端运行环境：Node.js 20+；Docker 路径需要 Docker 或 Podman 与 Compose 插件；镜像提供 linux/amd64 与 linux/arm64 两种架构，可在树莓派等 ARM 单板机运行。
• 桌面端：macOS 12 Monterey 及以上（Apple Silicon 选 arm64，Intel 选 x64）；Windows 提供安装包与便携压缩包；Linux 提供 AppImage、deb、rpm 与 tar.xz。
• 内存占用：服务端空闲时常驻约 40 MB RSS；面板与数据库在同一进程内运行。

3 部署前准备

3.1 环境要求

表 4 各部署路径环境要求

网络说明：网关需要访问各上游提供方的 API 域名；若本机需要经过代理出网，请先确认代理客户端允许局域网连接，再按 4.5 节配置容器出站代理。

3.2 默认端口、绑定地址与数据位置

表 5 端口与绑定地址

服务端 Docker 部署的数据卷名为 freellmapi-data，挂载到容器内 /app/server/data；可用 FREEAPI_DB_PATH 自定义数据库文件路径。桌面端数据位置如下表，复制 freeapi.db 与 config.json 即可在同一平台内迁移数据：

表 6 桌面应用数据目录

桌面端日志按 1 MB 滚动：保留当前 freeapi.log 与上一个 freeapi.log.1；旧日志会被覆盖，不会无限增长。

3.3 加密密钥说明

• ENCRYPTION_KEY 为 64 位十六进制字符串，用于 AES-256-GCM 静态加密提供商密钥；非 production 模式下未设置该变量时，服务端会自动生成开发密钥并存于数据库旁的 .encryption-key 文件（权限 0600），真实部署不可依赖该兜底。
• 升级、重建容器或迁移时，必须保留同一个 .env 中的 ENCRYPTION_KEY 与同一个数据卷；更换二者之一，已加密的提供商密钥将无法解密。
• 如需轮换加密密钥，在服务停止状态下按 10.10 节执行官方轮换命令，并先备份数据库；轮换失败时旧密钥校验不通过，进程不会写入数据库。

4 部署方式一：一键脚本（Docker / Podman，推荐）

4.1 macOS 与 Linux 一键命令

在已安装 Docker 或 Podman 与 Compose 插件的主机上，执行官方一键脚本：

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

脚本执行过程与默认行为：

• 检查 Docker / Podman 引擎与 Compose 插件是否可用，缺失时直接报错退出。
• 创建安装目录（默认 ~/freellmapi，可用 FREELLMAPI_DIR 覆盖），生成 64 位十六进制 ENCRYPTION_KEY 写入 .env。
• 生成 docker-compose.yml，拉取 ghcr.io/tashfeenahmed/freellmapi:latest 镜像并启动容器。
• 轮询 GET /api/ping 健康检查，服务就绪后输出面板地址与 API 端点。
• 重复执行安全：保留现有 .env 与加密密钥，仅把容器镜像更新到 :latest；不会重置数据库。

  执行前可先下载脚本审阅：curl -fsSL https://freellmapi.co/install.sh -o install.sh，确认内容后再 bash install.sh。

4.2 可覆盖的环境变量

表 7 一键脚本可覆盖变量

覆盖方式示例（先设置变量再执行脚本）：

FREELLMAPI_DIR=/opt/freellmapi PORT=3001 HOST_BIND=127.0.0.1 \
  curl -fsSL https://freellmapi.co/install.sh | bash

4.3 Windows PowerShell 引导

Windows 环境可在 PowerShell 中执行官方引导脚本：

irm https://freellmapi.co/install.ps1 | iex

• 该脚本为引导 shim，内部拉取官网安装脚本；Windows 上最省事的路径是直接使用 Releases 中的桌面安装包（见 7.2 节）。
• 需要 Docker 路径时，可在 WSL 或任意 bash shell 中执行 4.1 节的 Linux 命令。

4.4 启动后核验

• 浏览器打开 http://localhost:3001 ，按提示注册服务端面板账号（邮箱 + 密码）。
• 进入 Keys 页，添加上游提供商密钥；观察状态点与最近一次健康检查结果。
• 在 Fallback Chain 中确认模型顺序，从顶部复制统一的 freellmapi- 前缀 Bearer 密钥，供客户端接入使用。
• 服务端健康检查端点：GET http://localhost:3001/api/ping；API 基础地址：http://localhost:3001/v1。

4.5 局域网暴露与容器网络排障

仅在可信局域网内需要被其他设备访问时，把绑定地址改为 0.0.0.0：

HOST_BIND=0.0.0.0 docker compose up -d

• 单用户设计下，面板仅由统一密钥保护；不要把默认配置直接暴露到公网。
• 容器内访问上游需要经过宿主机代理时，在 .env 中设置：

PROXY_URL=socks5h://host.docker.internal:7890

• Compose 已映射 Docker host gateway；普通 Linux Docker 同样生效。代理客户端必须允许局域网连接（例如 Clash 配置 allow-lan: true）。
• IPv6-only 主机需在 /etc/docker/daemon.json 中开启 ipv6、ip6tables 与 fixed-cidr-v6 后重启 Docker。 容器内连通性探针（替换为实际上游域名）：

docker compose exec freellmapi node -e \
  "fetch('https://generativelanguage.googleapis.com/').then(r=>console.log('ok',r.status)).catch(e=>{console.error(e);process.exit(1)})"

5 部署方式二：Docker Compose 手动部署

5.1 前置条件

• 已安装 Docker 与 Compose 插件；macOS / Linux 可使用 openssl 生成随机密钥，Windows 使用 PowerShell 随机数生成器。
• 已从 Releases 或仓库 README 确认当前镜像标签；生产环境可把 :latest 固定为具体版本标签。

5.2 macOS 与 Linux（Bash）步骤

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# 生成 64 位十六进制加密密钥并写入 .env
cat > .env <<EOF
ENCRYPTION_KEY="$(openssl rand -hex 32)"
PORT=3001
HOST_BIND=127.0.0.1
EOF

docker compose up -d

5.3 Windows（PowerShell）步骤

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# 生成 32 字节随机数并转 64 位十六进制
$bytes = New-Object Byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
$key = [BitConverter]::ToString($bytes) -replace '-', ''

@"
ENCRYPTION_KEY="$key"
PORT=3001
HOST_BIND=127.0.0.1
"@ | Set-Content -Encoding UTF8 .env

docker compose up -d

5.4 持久化、备份变量、运维命令与可选自动更新

数据持久化：Compose 卷 freellmapi-data 挂载到容器内 /app/server/data；升级时必须保留同一数据卷与同一 .env 中的 ENCRYPTION_KEY。可用 FREEAPI_DB_PATH 自定义数据库文件路径。

表 8 数据库备份环境变量

表 9 常用 Compose 运维命令

可选自动更新：在 .env 中设置 WATCHTOWER_TOKEN，再启动 autoupdate 配置档：

WATCHTOWER_TOKEN="$(openssl rand -hex 32)"
docker compose --profile autoupdate up -d

• 面板 Settings 中的 Check for updates 触发检查；旁车仅保护 freellmapi 容器，不对外挂端口，也不按计划定时更新。
• 自动更新旁车需要挂载 Docker socket，等价于 root 权限；该配置档默认关闭，仅在确认需要时启用。

5.5 卸载

连同数据库一起清除（-v 同时删除数据卷）：

docker compose down -v
docker image rm ghcr.io/tashfeenahmed/freellmapi:latest
rm -rf ~/freellmapi

• 去掉 -v 参数可保留数据库卷，供重装后恢复使用；重装时仍需沿用同一个 ENCRYPTION_KEY。

6 部署方式三：本地源码开发与生产构建

6.1 前置条件

• Node.js 20+ 与 npm；git 用于获取源码。
• 开发模式下服务端运行在 3001，Vite 开发面板运行在 5173；生产构建后服务端与面板同跑在 3001。

6.2 macOS 与 Linux 开发模式

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install

# 生成 64 位十六进制密钥写入 .env
echo "ENCRYPTION_KEY=$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')" > .env

npm run dev

• 普通 npm run dev -- --host 不生效；需要局域网开发访问时使用 npm run dev:lan。
• 非 production 环境未设置 ENCRYPTION_KEY 时，服务端自动生成开发密钥存于数据库旁 .encryption-key（权限 0600），不得用于真实提供商密钥。 Windows PowerShell 开发模式：

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install
$bytes = New-Object Byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
$key = [BitConverter]::ToString($bytes) -replace '-', ''
"ENCRYPTION_KEY=$key" | Set-Content -Encoding UTF8 .env
npm run dev

6.3 生产构建

npm install
npm run build
node server/dist/index.js

• 构建产物同时包含服务端与面板静态资源，进程对外只占用 3001 端口。
• 生产环境建议由 PM2、systemd 或其他守护进程托管进程，并配置开机自启与日志轮转。

6.4 声明式启动配置

通过 FREEAPI_CONFIG_PATH 指向 JSON 文件，或用 FREEAPI_CONFIG_JSON 内联 JSON；每次启动迁移完成后幂等应用，可用于容器化部署与配置即代码：

FREEAPI_CONFIG_PATH=/path/to/freellmapi.config.json

表 10 声明式配置主要字段

配置文件中若包含明文密钥，其保护等级等同于 ENCRYPTION_KEY；不要把含密钥的配置文件提交到公开仓库。

6.5 Android Termux 实验性安装

该路径为实验性、社区维护支持，FreeLLMAPI 在 Android 设备本地运行；Android 上服务端使用 Node 内置 SQLite 驱动，无需原生 better-sqlite3 编译工具链。

pkg update
pkg upgrade -y
pkg install -y nodejs-lts git

# 确认 Node 版本不低于 22.13（推荐 Node 24 LTS）
node --version

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install --no-audit --no-fund
npm run dev

• Termux 必须从 F-Droid 渠道安装，Google Play 商店版本已过时；不要混用不同商店的 Termux 与插件包。

7 部署方式四：桌面应用

7.1 应用特点

• 原生托盘应用，无需注册账号密码：面板使用隐藏本地账号自动登录，没有可遗忘的密码。
• 从托盘图标打开 Dashboard，或在本机任意浏览器访问 http://127.0.0.1:31415 ，两种方式均自动登录。
• 另一台设备经局域网访问桌面应用时，仍会看到登录表单；桌面端的本地账号不会自动签发外部会话。

7.2 分平台下载（v0.16.9）

下列直链对应 v0.16.9 Release 资产，2026-10-25 已逐个核验可访问；macOS 要求 12 Monterey 及以上，Apple Silicon 选择 arm64，Intel 选择 x64，两种 Mac 构建同时提供 ZIP 压缩包。

表 11 v0.16.9 桌面端分平台资产

• Releases 总入口：https://github.com/tashfeenahmed/freellmapi/releases/latest ；最新版本号以上述页面为准。

7.3 数据目录

桌面端数据目录见 3.2 节表 6；迁移时复制 freeapi.db 与 config.json，日志文件不需要迁移。

7.4 更新机制与源码构建限制

• macOS、Windows Setup 安装包与 Linux AppImage 支持自动更新：检查到新版本后后台下载，下次重启或退出时安装；应用不会自行重启进程。
• 安装前会先写入 Pre-update 备份；deb、rpm、tar.xz 与 Windows 便携 zip 不参与自动更新，需手动下载新版覆盖。
• 本地源码构建桌面端时，Windows 需要 Visual Studio Build Tools 的 Desktop development with C++ 工作负载与 Python；本地构建产物未经签名，Windows SmartScreen 首次运行可能弹出警告，选择 More info → Run anyway 继续；macOS 本地构建不会触发 Gatekeeper 提示。

8 初始化配置与面板使用

8.1 首次账号与找回密码

• 服务端安装（Docker、一键脚本、npm run dev / 生产构建）使用邮箱 + 密码账号；桌面应用无账号密码，由隐藏本地账号自动登录。
• 忘记密码：在登录页选择 Forgot password? → Send reset code，一次性重置码打印在服务端日志中（形如 Password-reset code: HWNHPU5QGZ）。
• 重置码有效期 15 分钟；请求新码会使旧码失效；接口带限流，不要连续重复点击。
• 服务端日志位置见 10.9 节；Docker 部署用 docker compose logs -f freellmapi 查看重置码。

8.2 添加上游密钥与自定义端点

• 进入 Keys 页，添加上游提供商密钥；状态点与最近健康检查时间标识当前连通性。
• 支持批量粘贴 .env 格式导入，也支持导出 JSON、.env 与 CSV 格式。
• 自定义 OpenAI 兼容端点（Ollama、llama.cpp、LM Studio、vLLM、内部网关等）可作为独立提供商加入链路，端点的 base URL、模型 id 与密钥按该服务要求填写。

8.3 Models 面板与六档路由策略

表 12 面板六档路由策略

请求模型字段可使用以下路由取值（大小写不敏感）：

表 13 请求级路由后缀

• 同义词可解析：auto:fastest、auto:speed、auto:smartest、auto:cheapest、auto:budget 分别映射到对应策略。
• 面板右上角实时权重示例：reliability 50%、speed 25%、intelligence 25%；命名回退链定义见 fallback 官方文档。

8.4 Keys 面板与统一密钥

• 统一密钥：freellmapi- 前缀 Bearer 令牌，所有 OpenAI 兼容客户端与 SDK 使用该密钥接入；面板顶部一键复制。
• 客户端配置档密钥：sk-cp- 前缀，在 Profiles 页创建，可注入强制 system prompt 与独立配置，供不同下游工具隔离使用。
• 无头 URL 令牌：/v1/t/<token>/ 路径下的独立密钥单独哈希存储，可即时吊销；统一密钥绝不要放进 URL 路径。

8.5 Playground 试验台

• 试验台用于不配置客户端即可验证链路、模型与附件能力；图片附件支持 PNG、JPEG、WebP、GIF，浏览器先缩小再作为图像内容块发送给视觉模型。
• 文本附件 TXT、MD、CSV、JSON、LOG 以内联代码块形式发送；PDF、DOCX、XLSX 与二进制、URL 附件的限制见 10.2 节。

8.6 Analytics 用量面板

• 指标包含请求量、成功率、输入 / 输出 token、平均延迟、P95 延迟、平均 TTFT 与估算节省 token，可按提供方细分。
• 留存默认 90 天或 100,000 行，先到先清；REQUEST_ANALYTICS_RETENTION_DAYS 设 0 关闭天数限制，REQUEST_ANALYTICS_MAX_ROWS 设 0 关闭行数限制。

8.7 Premium 实时目录

• Premium 订阅价格与权益见 1.2 节；激活入口为面板 Premium 页，激活后一个 fla_ 密钥覆盖桌面、家庭服务器与树莓派。
• 目录签名经固定 Ed25519 公钥验签后每日两次同步；用户自行添加的自定义提供方与手动启用 / 停用选择，不会被目录同步覆盖。
• Premium 密钥的购买、续费与随时取消在 https://freellmapi.co/manage 自助完成。

9 API 接入与客户端配置

9.1 通用接入

服务端启动后，API 基础地址为 http://localhost:3001/v1 ；所有请求使用 Authorization: Bearer freellmapi-<统一密钥>。Python OpenAI SDK 示例：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-替换为统一密钥",
)

resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "你好，介绍一下你自己"}],
)
print(resp.choices[0].message.content)

curl 示例：

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-替换为统一密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto:balanced",
    "messages": [{"role": "user", "content": "ping"}]
  }' 

• 模型字段取值：auto、auto:fast 等路由后缀、目录中的具体模型 id、auto:<profile> 命名链，或虚拟 fusion。
• 模型清单：GET /v1/models；?available=true（别名 connected、ready）仅列出当前可调用模型；?execution_status=ready|needsKey|exhausted 按状态过滤。

9.2 协议兼容面总览

表 14 协议兼容面总览

9.3 Claude Code

Claude Code 的 base URL 指向根路径（客户端自带 /v1/messages）：

# macOS / Linux
export ANTHROPIC_BASE_URL=http://localhost:3001
export ANTHROPIC_AUTH_TOKEN=freellmapi-替换为统一密钥
# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "http://localhost:3001"
$env:ANTHROPIC_AUTH_TOKEN = "freellmapi-替换为统一密钥"

• 禁止设置 ANTHROPIC_API_KEY：该变量会被识别为冲突的一方凭证，导致 Claude Code 拒绝启动；应使用 ANTHROPIC_AUTH_TOKEN。
• 可用通用生成器 npx freellmapi setup-claude 自动写入配置；npx freellmapi launch 为不落盘凭证的启动器。

9.4 Codex CLI

• Base URL：http://localhost:3001/v1；协议面为 Responses，wire_api = "responses"。
• 通用生成器：npx freellmapi setup-codex 自动写入配置；npx freellmapi launch-codex 为不落盘凭证启动器。

9.5 Gemini CLI

export GOOGLE_GEMINI_BASE_URL=http://localhost:3001
export GEMINI_API_KEY=freellmapi-替换为统一密钥

• 网关对外暴露原生 /v1beta 面，Gemini CLI 无需改写协议；鉴权接受 x-goog-api-key、Bearer 与 ?key= 查询参数，请求头优先。
• 在 Keys → Agents（Gemini model mapping）中把 Pro / Flash / Flash-Lite 家族映射到 Auto 或固定模型。

9.6 其余 OpenAI 兼容 Agent

通用生成器命令格式：

npx freellmapi setup-<agent> --url http://localhost:3001 --api-key <统一密钥>

• --dry-run 先查看将要写入的配置差异，不修改文件；--profile <name> 追加第二套配置；--model <id> 钉死模型；环境变量 FREELLMAPI_API_KEY 可替代 --api-key。
• 真实写入前会生成时间戳备份，并合并现有配置；Agents 面板展示已填好密钥的同款命令。 表 15 受支持编程智能体一览

9.7 无请求头客户端：URL 令牌与 Ollama 模拟面

不支持自定义 Authorization 请求头的客户端，使用 /v1/t/<token>/ 前缀：

• 支持的路径：/v1/t/<token>/chat/completions、/v1/t/<token>/responses、/v1/t/<token>/models；同前缀暴露 /api/chat 与 /api/tags。

• URL 会进入 shell 历史、代理日志与客户端遥测，应按敏感信息对待；泄露后在面板即时吊销。 Ollama 模拟面默认关闭，两种模式：

• open-loopback：仅本机回环访问；桌面局域网不扩大该范围；Docker 内 peer 是网桥 IP 而非回环，该模式会拒绝经发布端口的本机流量。

• key-required：Bearer 统一密钥鉴权；Docker 部署必须使用该模式。
• Zed、JetBrains AI 等 Ollama 客户端指向 http://localhost:3001 即可；流式响应为 NDJSON 格式。

9.8 MCP 服务

• /mcp 端点新装默认关闭；升级前已配置密钥的旧安装保留开启状态。
• 开启方式：Keys → Agents 切换开关，或调用 PUT /api/settings/enable-mcp；关闭状态下 /mcp 所有动词返回 403 JSON-RPC 错误。 Claude Code 注册示例（其他 Streamable HTTP MCP 客户端同口径）：

claude mcp add --transport http freellmapi \
  http://localhost:3001/mcp \
  --header "Authorization: Bearer freellmapi-替换为统一密钥"

• ChatGPT 经私有 Secure MCP Tunnel 暴露 ask_freellmapi 工具，三项配置分离：tunnel-client 的 mcp.server_urls[].url、环境变量 FREELLMAPI_MCP_AUTHORIZATION（含 Bearer 前缀）、MCP_INFERENCE_DEFAULT_MODEL；样例见仓库 examples/chatgpt/tunnel-client.yaml.example。
• 私有隧道是 local-first 路径；公网插件部署需要稳定 HTTPS 端点与独立鉴权，不在本指南展开。

9.9 Continue 编辑器补全配置

models:
  - name: FreeLLMAPI
    model: auto
    apiBase: http://localhost:3001/v1
    useLegacyCompletionsEndpoint: true
    roles:
      - autocomplete

9.10 会话上下文交接

• 设置 FREELLMAPI_CONTEXT_HANDOFF=on_model_switch 后，会话中途更换模型时，向新模型注入交接 system 消息。
• 会话内存 TTL 3 小时，仅保存在进程内存，不落盘；会话键取 X-Session-Id 请求头，缺省时取首条用户消息 SHA-1。
• 仅在同一 session key 所选模型发生变化时注入；首请求、同模型续聊、已有交接消息时不注入。
• 交接只能携带可见对话与网关层状态，不能恢复提供商内部隐藏状态，也不能还原未发送到网关的消息。

10 进阶能力与运维

10.1 路由、回退与配额

• 收到 429 或 5xx 后冷却当前密钥，重试链上下一模型；单请求最多 20 次尝试，同时受墙钟预算约束。
• 会话粘着同一模型 30 分钟；额度按 UTC 每月 1 日 00:00 重置。
• 嵌入向量不跨模型降级：不同模型向量空间不兼容，嵌入请求按家族路由，仅在同家族提供商之间回退。 表 16 嵌入向量家族

10.2 工具调用、视觉、文档附件与媒体生成

• OpenAI 风格 tools / tool_choice 在提供商之间往返；纯文本形式的工具调用被救援为真实 tool_calls；Gemini 协议翻译为 functionDeclarations 与 functionResponse。
• 工具名 google_search 触发 Google 搜索接地，前提是请求钉在 Google 模型；工具请求只会路由到真正支持工具的模型。
• 含图片请求自动限制到 Vision 模型；链上无视觉模型时返回 422 no_vision_model；/v1/responses 暂不支持图片输入，请改用 /v1/chat/completions。
• Anthropic document 块仅接受文本源；PDF、DOCX、XLSX 的 base64 与 url 源返回 400，网关不代为抓取 URL，路由前即拒绝、不消耗配额。
• 图像与语音支持自定义 OpenAI 兼容媒体端点，视频不支持；视频平台仅 pollinations 与 huggingface（VIDEO_PLATFORMS 配置）。
• 视频任务 5 分钟上限（VIDEO_FETCH_TIMEOUT_MS），超时返回 504；客户端中途断开经 socket close 事件中止任务，不再轮询，也不向第二提供商回退。
• Hugging Face 经 fal 队列处理，每 500ms 轮询 COMPLETED；视频返回二进制 MP4，响应头携带 X-Provider 与 X-Model。

10.3 Fusion 多模型合成

• 虚拟 fusion 模型并行扇出一组免费模型起草，再由裁判模型合成最终答案。
• 在面板 Fusion 页或请求 fusion 字段配置裁判模型、参与起草的模型集合与策略；子调用走正常路由、配额与分析，子调用遵守密钥 cap，聚合错误格式予以保留。

10.4 提示词压缩

表 17 提示词压缩四档模式

• 启动变量 FREELLMAPI_COMPRESSION=off|lossless|standard|aggressive；面板保存后覆盖环境值。
• 请求头 X-FreeLLM-Compress: off|on|lossless|standard|aggressive 只能关闭或把服务端档位下调，不能上调；on 表示使用服务端配置模式。
• 响应头回传有效模式与估算节省量，形如 X-FreeLLM-Compress: standard; saved~=1840；估算按字符数 / 4 折算。
• 保真门限：全部独立数字字面量与 diff hunk 存活；显式约束、安全指令与错误行存活；JSON key 存活率 ≥90%；其他受保护片段存活率 ≥95%；工具调用信封保持有效。压缩失败即放行（fail-open），不调用另一个模型重写图像。
• 管理接口：GET / PUT /api/settings/compression、POST /api/compression/preview、GET /api/compression/stats；MCP 侧提供 compression_stats 工具。

10.5 响应头与响应缓存

表 18 关键响应头

• 任务类型权重份额默认 0.3，经 GET / PUT /api/settings/task-weight-share 调整；0 关闭、null 复位默认值，下一次请求生效，无需重启。

10.6 用量与预算 API

• GET /v1/usage 仅统一密钥可调，client-profile 密钥返回 403；返回当月 month、resetsAt、requests、tokens、byPlatform、byKey。
• byKey 含 requestCap 与 tokenCap，null 表示不限；超支不截断请求，下一次返回 429 quota_exceeded 与 Retry-After；已删除密钥记录在 platform 的 removed 分组中、无 cap。
• GET /api/free-tier 需面板会话鉴权，返回池去重后的月度概览；kind ∈ documented / credits / unpublished；quota 携带实时观察到的 limit、remaining、reset 与 metric，metric 优先级 tokens → credits → neurons → requests。
• 月度密钥上限经 PATCH /api/keys/:id 设置 monthlyRequestCap 与 monthlyTokenCap，非负整数，0 表示不限；作用于上游密钥跨聊天、嵌入与媒体，不作用于下游 client-profile；失败尝试释放预留额度；媒体不计 token；预留只在单进程内协调。
• 80% 与 100% 阈值各触发一次结构化 key_budget_threshold 日志；BUDGET_ALERT_WEBHOOK_URL 可同时向 Slack / Discord workflow POST JSON 告警。

10.7 数据库备份

表 19 备份 API 端点

• 备份 SQL dump 头部携带 sha256 密钥指纹；备份环境变量见 5.4 节表 8；启动时主库缺失会先从备份路径恢复，再执行迁移。

10.8 出站代理

• forward 模式（默认）：PROXY_URL 显式配置 → 面板 Keys 出站代理设置 → ALL_PROXY → HTTPS_PROXY → HTTP_PROXY（小写拼写同样读取）；scheme 支持 http、https、socks4、socks4a、socks5、socks5h，h / a 后缀在代理端解析 DNS；NO_PROXY 配置绕过名单；支持按密钥覆盖。
• 未配置代理时，链路回落到系统代理探测：macOS 读取 scutil --proxy，Windows 读取 Internet Options 注册表，Linux 读取 GNOME gsettings manual 配置；探测为尽力而为，2 秒超时，不抛错。
• fetch-relay 模式：PROXY_MODE=fetch-relay、PROXY_URL、FETCH_RELAY_TOKEN；relay 鉴权与提供商鉴权分离，使用 Fetch-Relay-Authorization 与 Fetch-Relay-Target 两个跳专属头，协议细节见 Fetch Relay 官方文档。
• TRUST_PROXY 控制入站反向代理：默认 false，不信任 X-Forwarded-For / X-Forwarded-Proto；true 信任全部；数字表示信任的跳数；逗号分隔的 addr / CIDR 列表只信任指定来源；用于 Caddy、nginx、Traefik 反代后让分析与限流看到真实客户端 IP。

10.9 日志位置

表 20 日志位置一览

10.10 加密密钥轮换

• 轮换必须在服务停止状态下进行；先完整复制数据库文件备份。
• 在 server 目录先以 --dry-run 预览：

cd server
ENCRYPTION_KEY=<旧密钥> npm run rotate-encryption-key \
  -- --new-key "$NEW_KEY" --dry-run

• 确认预览无误后去掉 --dry-run 实转；支持 --old-key 与 --db 指定参数；旧密钥错误时命令非零退出且不写库。
• 轮换完成后在 .env 写入新密钥再启动；Docker 部署需在容器内对挂载库执行轮换，随后用新 .env 重启容器。

11 使用边界与合规提示

11.1 能力局限

• 目录中虽出现 GPT-5.x、Grok 4.x、Kimi K3、DeepSeek V4 Pro、Gemini 3.x 等免费行，但这些模型日常额度最小、队列最长，最可能短期被收回或转为付费；应按容量与可用性规划，而不是按模型等级规划。
• 智能度随当天时间下降：头部模型（通常为 Gemini 3.6 Flash、DeepSeek V4、Kimi K2.6 一类）日额度最先耗尽，路由逐级降到更小或更弱的模型；额度在 UTC 午夜重置。
• 延迟高度不稳定：Cerebras、Groq 一类端点极快，其余提供商延迟不一；免费条款可无通知变更，项目不提供 SLA。
• 单用户、local-first 设计：不要把服务端暴露到公网；多用户、按租户计费与横向扩展不在支持范围内。

11.2 尚不支持项

• 不支持 /v1/moderations 内容审核端点。
• 不支持 n>1 的多次补全（completions 批量生成）。
• 不支持多租户与按用户计费；网关为单用户设计。

11.3 上游服务条款分级参考

下表为架构文档 2026 年 5 月逐家审查口径，仅作信息参考，不构成法律意见；实际使用前应自行阅读各上游最新服务条款。

表 21 上游 ToS 分级（2026 年 5 月审查口径）

• 2026-04 审查后已移除：Moonshot（转付费）、MiniMax 直连（由 OpenRouter minimax/minimax-m2.5:free 路线取代）。

11.4 合规经验法则

• 每家提供商只注册一个账号，不倒卖额度，不与他人共享端点或统一密钥。
• 不要把免费层当作付费产品的生产后端；正式产品上线前应切换到付费 API。
• 以上分级为公开条款的整理与解读，不构成法律意见；变更订阅、商用或对外提供服务前，应咨询专业意见并复核上游最新条款。

11.5 免责声明

FreeLLMAPI 定位为个人实验、学习与原型验证工具，不用于生产环境；各上游提供商服务条款在代理流量下依然适用，合规责任由部署者与使用者自行承担。项目作者与维护方不对任何因使用本软件导致的上游账号封禁、额度损失、数据问题或第三方纠纷承担责任。

12 常见问题

忘记服务端面板密码怎么办？

在登录页选择 Forgot password? 并发送重置码；一次性码打印在服务端日志中，15 分钟内有效，过期或发起新码后旧码失效。Docker 部署用 docker compose logs -f freellmapi 查看。

容器内能访问上游，宿主机浏览器正常但网关报上游错误？

通常是容器出站代理未配置：在 .env 设置 PROXY_URL=socks5h://host.docker.internal:7890，并确认代理客户端允许局域网连接；IPv6-only 主机还需按 4.5 节调整 Docker 网络配置。

局域网其他设备打不开面板？

服务端默认绑定 127.0.0.1；仅在可信网络内设置 HOST_BIND=0.0.0.0 后重新 up -d；不要把单用户网关直接暴露到公网。

升级后提供商密钥全部解密失败？

ENCRYPTION_KEY 或数据卷被更换。升级必须沿用同一个 .env 密钥与同一个数据卷；若密钥已丢失，只能恢复最近备份数据库，无法单独解密旧密钥。

目录里看不到最新免费模型？

免费安装使用月度签名快照目录，新模型滞后约 30 天；Premium 实时目录同日更新。也可在面板手动添加自定义 OpenAI 兼容端点。

访问 /mcp 返回 403？

新装默认关闭 MCP。在 Keys → Agents 中开启，或调用 PUT /api/settings/enable-mcp；关闭状态下 /mcp 所有动词返回 403 JSON-RPC 错误。

发送图片返回 422 no_vision_model？

当前链上未启用视觉模型；在 Models 面板启用带 Vision 徽章的模型。注意 /v1/responses 暂不支持图片输入，图片请求请使用 /v1/chat/completions。

Windows 桌面端首次运行 SmartScreen 警告？

官方 Releases 安装包由发布流水线签名；本地源码构建产物未经签名，在警告窗口选择 More info → Run anyway 继续即可。

端口 3001 被其他程序占用？

通过一键脚本的 PORT 变量或 .env 修改端口；Compose 部署同步调整端口映射与代理转发规则。

视频生成返回 504？

视频任务上限为 5 分钟（VIDEO_FETCH_TIMEOUT_MS），超时返回 504；请缩短提示词与时长，或切换到另一视频平台后重试。

更换嵌入模型后检索结果失效？

嵌入向量不跨模型降级，也不能混用于同一个向量库；一个向量库固定一个家族，切换模型需重建索引。

如何备份与迁移整套配置？

服务端使用备份 API 导出加密 dump；桌面端复制 freeapi.db 与 config.json；服务端迁移时保留 .env 中的 ENCRYPTION_KEY 与数据卷。

附录 A 环境变量清单

下表汇总官方安装文档、Docker README、API 参考与代理文档中出现的主要变量；完整高级变量以仓库 main 分支对应文档为准。

表 22 主要环境变量汇总

系统约定代理变量 ALL_PROXY、HTTPS_PROXY、HTTP_PROXY、NO_PROXY 按标准环境变量名读取，含小写拼写；不属于网关注册的专属变量。

附录 B 参考来源

本文事实核验日期为 2026-10-25；以下官方来源用于核对命令、端口、环境变量、端点与限制条款。如本文与官方最新文件存在差异，以仓库 main 分支为准。

英文 README：https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

中文 README：https://github.com/tashfeenahmed/freellmapi/blob/main/README.zh-cn.md

安装与部署文档：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md

API 参考：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/api/01-rest-api.md

客户端与编程智能体：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md

受支持 Agent 总表：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/02-supported-agents.md

架构与局限说明：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/architecture/00-high-level-index.md

提示词压缩管线：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/compression/01-compression-pipeline.md

Docker 指南：https://github.com/tashfeenahmed/freellmapi/blob/main/docker/README.md

命名回退链：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/fallback/01-named-chains.md

Fetch Relay 传输：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/proxy/01-fetch-relay.md

Android Termux 指南：https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/02-android-termux.md

一键安装脚本源码：https://freellmapi.co/install.sh

最新 Release v0.16.9：https://github.com/tashfeenahmed/freellmapi/releases/latest

官网中文站：https://freellmapi.co/zh-CN/