freellmpool

freellmpool

freellmpool 将 23 家大模型提供商收录为不同类别，涵盖定期免费额度、免密端点、有限试用、仅限固定路由和已禁用候选项。它提供 178 条已启用的聊天路由和 443 个已收录的聊天模型，并通过一个兼容 OpenAI 的端点，自动汇集你可以访问的已启用路由——可作为 CLI、Python 库或本地代理使用。只要有可用的已启用免密路由，即可在没有凭据的情况下启动。

常见问题：提示词发送到哪里、服务条款立场、故障转移、封禁和比较。

发布与分发状态

• 最新版本：0.13.0。 GitHub 发布版本和 PyPI 软件包均为 0.13.0；pip install freellmpool 和 uvx freellmpool 会安装经过审查的 提供商目录、有限流式传输和 sentinel 加固、Hermes 配置文件、 代理就绪状态与提供商 API、spread 路由，以及 OpenCode 注册表就绪状态加固。

• 注册表发布状态：待定。 截至 2026-08-29，opencode-freellmpool 和 opencode-freellmpool-tui 已通过测试，但尚未发布到 npm。暂时请使用仓库内的安装说明。

30 秒快速入门

在干净的 Linux/Python 3.12 环境中，从全新安装到收到首条免费模型回复，实测约需 19 秒，低于 30 秒目标；当免密提供商可用时，无需 API 密钥：

# One command when uv is installed; no checkout or manually managed virtualenv:
uvx freellmpool ask --max-tokens 32 "Reply with one short sentence: freellmpool is ready."

可移植的虚拟环境安装方式：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install freellmpool
freellmpool ask --max-tokens 32 "Reply with one short sentence: freellmpool is ready."

CI 会从当前检出目录运行相同流程： FREELLMPOOL_QUICKSTART_PACKAGE=. scripts/quickstart-test.sh。

目录涵盖由提供商运营的免费额度、免密路由，以及少数明确标记为有限试用或已禁用的候选项。各提供商的资格要求和限制有所不同。freellmpool 只会自动使用你可以访问的已启用路由；当某条路由被限流或不可用时会进行故障转移，并跟踪本地每日用量。

若干提供商（Pollinations、OVHcloud 和 Kilo Gateway）无需 API 密钥，LLM7 也可免密使用，因此只要有免密提供商可用，快速入门无需注册即可获得回复。

在接入工具前，若要检查本地提供商密钥、Agent CLI、代理配置和 Tailscale 状态，请运行仅打印信息的初始化向导：

freellmpool init --yes
freellmpool init --yes --agent opencode
freellmpool init --yes --agent metaswarm --tailnet

添加其他提供商的密钥，即可解锁更多模型和更高限额。

本地运行时（显式指定，仅限固定路由）

可从固定列表中预览 LM Studio、Ollama 和 llama.cpp 的字面环回端点，不会扫描局域网或进程：

freellmpool local discover
freellmpool local discover --name lm_studio
freellmpool local import --name lm_studio --yes
freellmpool ask --providers local_lm_studio --model "<model-from-discover>" "hello"

发现操作为只读。导入是单独的确认步骤，不会写入凭据，并会将所有导入模型排除在自动路由之外 （auto = false）。freellmpool local remove local_lm_studio --yes 只会撤销导入器管理的区块。自定义端点必须是规范的字面环回 URL，例如 http://127.0.0.1:1234/v1；主机名、局域网地址、重定向和大范围网络扫描都会被拒绝。

使用 freellmpool init 完成首次运行设置

freellmpool init 会检查提供商密钥、已安装的 Agent CLI、Tailscale 状态和代理配置，然后打印一条可复制粘贴的下一步操作说明，不会编辑文件。请先以仅检测模式运行：

freellmpool init --yes

--json 会以带版本的 JSON 格式输出相同的检测结果，供脚本和 Agent 使用。

Tailnet / 远程 Agent 网关

使用生成的 API 密钥，通过 Tailscale 100.x 地址提供代理服务：

freellmpool tailnet serve --port 8080

在远程机器上：

freellmpool tailnet connect <tailnet-ip> --port 8080

两端都支持 --api-key <shared-secret>，如果你想固定密钥，而不是使用生成的令牌。Tailnet 服务默认要求身份验证；请勿在非回环接口上运行未经过身份验证的服务。

Metaswarm Agent 通道

本项目使用一条 Umans/Kimi K2.7 工作通道、一条 MiniMax M3 通道、将 Codex 用作升级处理，并且仅在交付前最终审核时使用 Claude Opus。可安装的 Metaswarm 配置文件也遵循这一策略：通过本地代理提供一条免费/低成本工作通道、一条更强大的 freellmpool 审核通道，以及仅由用户明确付费使用的 Codex/Opus 升级处理/最终审核通道（绝不静默启用）。

freellmpool init --yes --agent metaswarm --tailnet
freellmpool profile install metaswarm
freellmpool tailnet serve --port 8080
freellmpool profile doctor metaswarm --dry-run

使用免费模型运行编码 Agent

freellmpool 的代理支持 OpenAI API，并包含一条实验性的 Anthropic 兼容路径，因此编码 Agent 可以使用汇集的免费套餐——只需将它们指向代理：

freellmpool proxy                       # starts http://localhost:8080
freellmpool code claude                 # prints the one-line setup for Claude Code
freellmpool profile list                # richer installable profiles
freellmpool profile show metaswarm      # Tailnet-aware Metaswarm profile
freellmpool profile install hermes       # Hermes custom-endpoint config
# (also: codex, aider, cline, continue, cursor, hermes, opencode, metaswarm)

Hermes 配置文件会打印（绝不会写入）以下受支持的自定义端点配置块；hermes model 提供交互式等效操作：

model:
  provider: custom
  default: quality
  base_url: http://localhost:8080/v1
  api_key: anything

也可以直接启动 Claude Code 网关模式：

ANTHROPIC_BASE_URL=http://localhost:8080 \
ANTHROPIC_AUTH_TOKEN=dummy \
ANTHROPIC_API_KEY=dummy \
ANTHROPIC_MODEL=auto \
ANTHROPIC_SMALL_FAST_MODEL=auto \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
claude

现有的 OpenAI 兼容应用也可以照常使用：设置 OPENAI_BASE_URL=http://localhost:8080/v1，代码保持不变。 Anthropic 兼容工具可以通过 ANTHROPIC_BASE_URL=http://localhost:8080 使用实验性桥接。

纯文本 /v1/responses 和 /v1/messages 请求会从选定的提供商逐步流式返回。工具调用和更丰富的内容则有意保留在缓冲式兼容路径中。浏览器仪表板和 Playground 共用一个公开且不含数据的外壳；启用代理身份验证后，它会提示输入 Bearer 令牌，并且只将令牌保存在页面内存中；受保护的状态、库存、模型和对战调用仍要求提供 Authorization 标头。

OpenCode 在 0.12.0 中获得了更深入的集成：实时编辑器内仪表板（路由模式、预计节省、免费提供的令牌数、提供商竞速、延迟）、通过模型选择器实现的逐请求 Agent 路由（freellmpool/agent|spread|auto|fast|quality|fair），以及 freellmpool_status / freellmpool_models 工具——请参阅 integrations/opencode-tui 和指南。 该插件会在受支持的 OpenCode 版本中自动注册其路由别名，不会重写用户配置。重启 OpenCode 并检查 opencode models freellmpool。 软件包 tarball 已在 CI 中通过验证，但尚未发布到 npm； 链接中的本地文件安装说明仍是可用的安装方式。

**0.11 新增：**容量工具——freellmpool capacity status 显示当前可用的免费套餐，freellmpool providers health 对其进行实时探测，而 freellmpool keys add 会引导你配置更多套餐（请参阅 容量与提供商健康状态和 docs/CAPACITY.md）。

**0.10 新增：**异步 API（AsyncPool）、MCP 服务（freellmpool mcp）、 使用 freellmpool benchmark 的延迟感知路由、可观测性钩子，以及用于自定义提供商的插件系统。请参阅更新日志。

安装

pip install freellmpool      # or: pipx install freellmpool

唯一的依赖项是 httpx。需要 Python 3.11+。

Docker 和 Open WebUI

已发布的容器以非特权用户身份运行本地代理。将配额、统计数据、路由健康状态、缓存和配置状态持久化到命名卷中：

docker volume create freellmpool-data
docker run --rm -p 127.0.0.1:8080:8080 \
  --volume freellmpool-data:/home/freellmpool/.config/freellmpool \
  --env GROQ_API_KEY \
  ghcr.io/0xzr/freellmpool:0.13.0

如果想要无需凭据即可启动，请省略 --env GROQ_API_KEY；只有在有可用的已启用免密钥路由时，代理才能响应。将已发布的端口限制为仅本机访问。如果你有意对外开放，请设置 FREELLMPOOL_PROXY_KEY，并要求客户端提供该 Bearer 令牌。

对于捆绑的 Open WebUI 技术栈，将任何提供商凭据放入 .env，然后运行 docker compose up -d。Compose 会等待代理健康检查通过，并将 freellmpool 和 Open WebUI 的状态保存在命名卷中；两项服务都健康后，打开 http://localhost:3000。

命令行

freellmpool ask "Write a haiku about sqlite"
git diff | freellmpool ask "Write a commit message for this"
freellmpool tokenmax "Hardest question you've got"  # 🌈 blast models, print answers, optional synthesis
freellmpool providers        # which providers are configured
freellmpool models           # cataloged provider/model ids
freellmpool stats            # lifetime tokens served free + estimated cost avoided
freellmpool badge -o badge.svg   # a shareable SVG badge of that total
freellmpool badge --summary -o summary.svg   # a larger usage summary card

freellmpool tokenmax 是一个戏谑地命名的最大努力模式：它会将你的提示词同时发送给许多可用模型，并打印每个回答。默认情况下，CLI 会额外生成一份综合结论，除非你传入 --no-synthesize；MCP 工具则会返回模型回答，由调用它的 Agent 进行综合。（参见 docs/MCP.md。）

freellmpool stats 统计的是持续累积的、永久保存的总量（重启和升级后仍会保留）。在 README 中嵌入 freellmpool badge，或使用 freellmpool badge --summary -o summary.svg 生成更大的卡片，其中包含令牌数、请求数、估算节省金额和提供商分布。当 FREELLMPOOL_PUBLIC_BADGE=1 允许嵌入公开徽章时，代理可以实时提供 /badge.svg 和 /summary.svg。

指定提供商或模型；常见的 OpenAI/Anthropic 模型名称会映射到免费的等效模型，因此现有脚本可以继续运行：

freellmpool ask -m groq/openai/gpt-oss-20b "hi"
freellmpool ask -p cerebras,groq "hi"
freellmpool ask -m gpt-4o-mini "hi"      # routed to a free model

角色

freellmpool roles 会列出提问角色预设（coder、critic、summarizer、grounded-reader、long-context、cheap、fast、second-opinion 等）。每个角色都会设置路由、令牌预算、温度、任务意图和系统提示词提示，而不会另行创建第二套路由引擎。显式标志（--model、--providers、--routing、--task、--max-tokens）优先于角色默认值。

freellmpool ask --role coder "write a pytest for this function"
freellmpool ask --role grounded-reader "read this Markdown file"
freellmpool ask --routing quality --task general "ignore automatic task classification"
FREELLMPOOL_MODE=wise freellmpool ask --role cheap "summarize this patch"

作为代理

运行一个讲 OpenAI API 的本地服务，然后将任何兼容 OpenAI 的工具指向它。在回环地址上，除非你配置了 FREELLMPOOL_PROXY_KEY 或传入 --api-key，否则任意占位 API 密钥都可使用；默认情况下，通过 Tailnet/LAN 提供服务需要真实的代理 bearer 令牌。

freellmpool proxy
export OPENAI_BASE_URL=http://localhost:8080/v1
export OPENAI_API_KEY=unused

from openai import OpenAI
client = OpenAI()
print(client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "hi"}],
).choices[0].message.content)

# audio → text (Whisper), same client:
print(client.audio.transcriptions.create(
    model="auto", file=open("audio.mp3", "rb"),
).text)

或者使用 curl（multipart 上传）：

curl -s http://localhost:8080/v1/audio/transcriptions \
  -F [email protected] -F model=auto

代理还实现了 OpenAI Responses API（供 Codex CLI 使用）和实验性的 Anthropic Messages API 路径（供 Claude Code 使用），因此编码 Agent 也能使用免费模型。freellmpool code <agent> 会打印准确的设置步骤，而 freellmpool profile install <agent> 会打印更完整、可直接复制粘贴的配置文件，且不会修改第三方配置：

freellmpool code aider       # also: claude, codex, cline, continue, cursor, hermes, opencode
freellmpool profile show opencode
freellmpool profile doctor opencode --dry-run

0.12.0 版代理提供的接口：

• /v1/chat/completions — 兼容 OpenAI 的聊天、令牌流式传输和工具调用。
• /v1/responses — Responses API 兼容层，支持增量文本流式传输；工具和丰富内容使用缓冲兼容路径。
• /v1/messages — 实验性的 Anthropic 兼容 Messages 路径，采用相同的增量文本／缓冲工具拆分方式。
• /v1/embeddings 和 /v1/audio/transcriptions — 兼容 OpenAI 的嵌入接口和 Whisper 风格的 multipart 转录接口。
• /v1/models — 路由别名及具体的 provider/model ID。
• /v1/models?ready=true — 相同格式，但仅包含本地已就绪的目标。
• /v1/providers — 经过身份验证、不含密钥的提供商／模型就绪状态详情。
• /freellmpool/battle 和 /playground — 有范围限制的浏览器／JSON 模型对比。
• /healthz 和 /livez — 公开的进程存活状态别名。
• /readyz — 公开的本地容量就绪状态参考信息（至少有一个提供商就绪时返回 200，否则返回 503）；它不会对上游进行实时探测。
• /dashboard、/status、/badge.svg 和 /summary.svg — 本地运维界面。

/、/dashboard 和 /playground 提供同一个不含数据的公开外壳。设置代理密钥后，外壳会提示输入密钥，并且只将密钥保存在页面内存中；状态、提供商／模型清单、对战和模型 API 调用仍受请求头身份验证保护。存活状态／就绪状态接口对编排探针保持公开；就绪状态是本地配额／冷却状态快照，并不保证上游健康。 特定工具的设置示例见 docs/INTEGRATIONS.md 和 docs/AGENTS.md。此仓库还包含一个实验性的 metaswarm 审查适配器，可将 freellmpool 用作外部工具审查者／第二意见来源。freellmpool profile show metaswarm 介绍了免费／低价工作者通道、更强大的审查者通道、Tailnet 客户端设置，以及仅作为由用户明确选择的升级路径的付费 Codex／Opus 通道。

作为库

from freellmpool import Pool

pool = Pool.from_default_config()
reply = pool.ask("Summarize the plot of Hamlet in 20 words.")
print(reply.text, "—", reply.provider_id)

vectors = pool.embed(["first document", "second document"]).vectors

with open("audio.mp3", "rb") as f:
    text = pool.transcribe(f.read(), "audio.mp3").text   # Whisper, failover across providers

异步版本使用相同的 API，只需添加 await：

from freellmpool import AsyncPool

async with AsyncPool.from_default_config() as pool:
    reply = await pool.aask("Summarize the plot of Hamlet in 20 words.")

向任一池传入 on_event=...，即可接收结构化路由／缓存事件（attempt／success／error／cooldown／cache_hit／cache_miss／exhausted），用于日志记录或跟踪。通过 register_provider(...) 添加自定义端点，或通过 register_adapter(name, fn) 添加新的请求格式。

对提供商进行基准测试

freellmpool benchmark 会对每个已配置的提供商各计时调用一次，并输出延迟和成功情况，方便你了解当前哪个免费套餐速度最快。路由器运行时会根据真实流量学习相同的延迟／成功信号；设置 FREELLMPOOL_ROUTING=fast 可优先选择延迟最低的提供商，而不是默认优先选择使用最少的提供商。

$ freellmpool benchmark
  provider/model            status   latency  note
  cerebras/gpt-oss-120b     ok        180 ms  6 tok
  groq/openai/gpt-oss-20b   ok        240 ms  6 tok
  ovh/Meta-Llama-3_3-70B-Instruct  FAIL    -  HTTP 429

容量与提供商健康状态

免费套餐会随时间变化——密钥过期、提供商宕机、每日限额用尽。这些命令会告诉你当前哪些可用，以及接下来该配置什么：

freellmpool capacity status --target 5   # who's healthy / near quota / missing a key
freellmpool capacity status --refresh    # explicitly refresh advisory provider metadata
freellmpool quota-wise status            # local headroom + recommended mode
freellmpool providers health             # send one tiny request to each, time it
freellmpool keys checklist --target 5    # which keys to add to reach N healthy providers
freellmpool keys add groq                # configure a key (and record metadata)

协议支持情况会与基本的提供商健康状态分开验证。运行 freellmpool conformance run，使用有界合成请求检查聊天、流式传输、工具、JSON 对象／架构、 视觉、Responses 和 Anthropic Messages，然后通过 freellmpool conformance status --json 查看 经过脱敏的证据。按功能自动路由仅使用已验证的目标；精确指定提供商／模型则是明确的覆盖方式。完整的运维与隐私约定： docs/PROTOCOL_CONFORMANCE.md。

capacity status 无需联网且优先使用缓存：它会读取你的目录、环境和 每日配额计数器，并将每个提供商标记为 healthy、low_quota、 exhausted、invalid_key 或 missing。来自建议性 外部目录 (mnfst/awesome-free-llm-apis) 的缓存元数据 可以推荐你添加的免费提供商；只有明确运行 freellmpool capacity status --refresh 或 freellmpool catalog sync 时，才会联网获取 这些元数据。它仅供参考；你的 providers.toml 仍是路由的事实来源。keys add <name> 可以从该目录导入 推荐的提供商，也可以创建 OpenAI 兼容的存根并自动发现其模型。代理的 /dashboard 会一目了然地显示相同的容量信息。完整参考：docs/CAPACITY.md。

FREELLMPOOL_MODE=wise 是保守的配额模式：ask 默认采用 较小的输出预算和分散路由，tokenmax 会缩小默认扇出范围，而广泛的多模型调用需要确认，除非你传入 --yes。 每条命令的 --mode normal|wise 会覆盖环境设置，在 config.toml 中使用 [settings] mode = "wise" 也同样有效。conserve 角色是注重配额的简写方式，可生成小型、分散路由的回答。

如需有界的第二意见，而非完整的 tokenmax 大范围调用：

freellmpool ask --second-opinion --opinions 3 "is this implementation plan sound?"
freellmpool ask --role second-opinion --synthesize "which release note is clearer?"

共享面板会询问几个不同的提供商，让各自的失败情况保持可见， 并可在你传入 --synthesize 时附加非致命的综合结果。

如需并排比较，并在终端或本地浏览器中查看：

freellmpool battle "which changelog entry is clearer?" --synthesize
freellmpool proxy --port 8080
freellmpool playground --port 8080

内置配方会将常见工作流封装成可供检查和运行的 JSON 文件：

freellmpool recipe list
freellmpool recipe run second-opinion "is this launch plan clear?" --synthesize
freellmpool recipe run pr-review --input patch.diff
freellmpool recipe run repo-summary --path 'src/freellmpool/*.py'
freellmpool recipe run metaswarm-worker-review --input worker.md --validation-output-file validation.txt

配方使用与 ask 和 battle 相同的角色预设和共享面板辅助工具； 它没有单独的路由引擎。

本地前台任务队列

对于缓慢且需考虑配额、不应阻塞实时会话的工作，可将任务排入配置目录下的仅追加 JSONL 日志（可通过 FREELLMPOOL_JOBS_PATH 覆盖）。该队列仅在前台运行：jobs run 会 一次处理一个任务，并记录已启动／已完成／已失败／已取消事件。 已完成的 ask 任务会将输出保留在任务日志中；已完成的配方任务还会通过与 freellmpool report 相同的报告辅助工具写入运行记录和 Markdown 报告。

# queue a recipe job
freellmpool jobs add --recipe pr-review --input patch.diff

# queue an ask job with a role preset
freellmpool jobs add --role summarizer "summarize the latest changelog"

freellmpool jobs list            # replayed state (idempotent across restarts)
freellmpool jobs watch           # one-shot refresh render, no daemon

freellmpool jobs run --dry-run   # print execution order, mutate nothing
freellmpool jobs run --max-failures 2   # halt after N consecutive failures
freellmpool jobs cancel <job-id> # append a cancel tombstone, not a mutation

freellmpool report list
freellmpool report last --markdown
freellmpool report last --html --path
freellmpool cost show <run-id>

取消操作会新增一条墓碑事件，而不是重写先前排队的记录——即使在 jobs run 完成前 发生崩溃，队列仍可重放；取消的任务在重启后也会保持取消状态。重复提交会创建不同的任务；传入 --dedupe 可拒绝 在任务仍待处理时重新提交相同配方或角色。

作为 MCP 服务

freellmpool mcp 会通过以换行符分隔的 JSON-RPC stdio 运行 Model Context Protocol 服务，让 Claude Desktop、Claude Code 或 Cursor 将子任务交给 免费模型。它提供 ask、panel／second-opinion、battle、recipe、roles、 Tailnet-info、quota-wise、route-preview、models、quota、stats 和 tokenmax 工具。参见 docs/MCP.md。其中包含一个 server.json， 供 MCP registry 使用。

在 Simon Willison 的 llm CLI 中

有一个插件：llm install llm-freellmpool → llm -m freellmpool "..."。 只要有启用的免密钥路由可用，就无需 API 密钥即可获得回答。 来源：plugins/llm-freellmpool。

提供商密钥

freellmpool 会从环境中读取密钥，并使用已设置的密钥。只要有启用的免密钥路由可用，就无需密钥；凭据可扩大可访问的路由范围。分步注册链接（包括验证和付款方式注意事项）见 docs/ACCOUNTS.md。

提供商	环境变量	备注
Pollinations	—	无需密钥
OVHcloud	—	无需密钥（匿名层级）
Kilo Gateway	—	无需密钥
LLM7	LLM7_API_KEY	可选
Groq	GROQ_API_KEY	当前免费计划路由；具体限制因模型而异
Cerebras	CEREBRAS_API_KEY	有限的 5 美元试用额度；当前路由是明确指定的固定路由，不是自动续期的额度
NVIDIA NIM	NVIDIA_API_KEY
OpenRouter	OPENROUTER_API_KEY	免费模型
Requesty	REQUESTY_API_KEY	仅限价格为零的模型；每个账户每天 200 次请求，无需银行卡
Google Gemini	GEMINI_API_KEY
Cloudflare	CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID
Hugging Face router	HF_TOKEN	路由免费层
OpenCode Zen	—	已列入目录，默认禁用，等待用户主动选择启用
Aion Labs	AION_API_KEY	每天 20K 个免费令牌，无需银行卡
ModelScope API Inference	MODELSCOPE_API_KEY	每天 2,000 次免费调用
Morph	MORPH_API_KEY	当前定价别名保持禁用，以便日后进行明确验证
Vercel AI Gateway	AI_GATEWAY_API_KEY	自动路由仅限公开价格验证为零价的 Poolside 路由；其他路由仅可固定指定或处于禁用状态；请设置网关侧预算
SiliconFlow	SILICONFLOW_API_KEY	免费模型；需要身份验证
Mistral、Cohere、SambaNova、Z.ai、Ollama Cloud	见 .env.example

config.toml（见 config.toml.example）可用于存储密钥、模型别名和设置，以替代环境变量。

本地诊断与运维

运行 freellmpool doctor，即可在不联网的情况下检查软件包版本、配置路径、已配置的提供商数量、路由模式、配额/缓存位置、外部目录缓存时长以及内置目录的有效性。

除非 FREELLMPOOL_CACHE_TTL（秒）或 [settings] cache_ttl 的值为正数，否则响应缓存处于关闭状态。启用后，缓存行会以 WAL 模式存储在 SQLite 中，并按 TTL 清理；FREELLMPOOL_CACHE_MAX_ENTRIES 用于限制保留的行数（默认为 10000，设为 0 可禁用数量清理）。

默认情况下，配额计数器会立即写入。长期运行的代理/MCP 进程可通过 FREELLMPOOL_QUOTA_FLUSH_EVERY=N 减少文件写入次数，该设置会在最多成功处理 N 个请求后批量刷新。关闭流程和 quota.snapshot() 会刷新待写入的计数，因此仪表板和进程退出时仍能看到最新总数。

最近的各路由健康状态会持久化到 ~/.config/freellmpool/route_health.json（可通过 FREELLMPOOL_HEALTH_FILE 覆盖）。有界的原子状态仅包含路由名称、耗时、计数器和标准化的失败类别，不包含提示词、响应、标头或凭据。/status 会报告每条已启用路由的熔断器状态、样本时长和重置时间。

路由机制

对于每个请求，freellmpool 都会构建你可访问的 (provider, model) 对列表，然后按照提供方使用量从低到高排序，并在选中的提供方内挑选使用量最低的模型。这样可以避免 NVIDIA 等拥有庞大模型目录的提供方，仅仅因为提供的模型更多就获得更多流量。返回 429 的提供方会在其声明的 Retry-After 或速率限制重置窗口内暂时搁置。重复发生的可用性故障会触发单条路由的熔断；冷却后，一次半开探测即可恢复该路由。每日计数保存在 ~/.config/freellmpool/quota.json 中，并在 UTC 午夜重置。

每次调用都会记录每个模型目标的延迟和成功情况。当前目标持续失败的提供方会自动降至列表末尾；使用 FREELLMPOOL_ROUTING=fast 时，则会优先选择实测速度最快的提供方。FREELLMPOOL_ROUTING=fair 会在提供方之间分配请求，以保留每日配额。freellmpool benchmark 可按需预热这些指标。若要恢复旧的逐模型均衡行为，请设置 FREELLMPOOL_ROUTING=legacy 或 FREELLMPOOL_ROUTING=model（若要恢复旧的逐模型最快优先排序，则设置 FREELLMPOOL_ROUTING=model-fast）。

质量路由（FREELLMPOOL_ROUTING=quality）。 免费层级中最强模型的每日限额最低，因此，朴素的模型池会随着一天中请求的增加而变弱。质量路由会将每个提示词的难度与各模型的能力相匹配：困难的提示词（输入较长、包含代码或推理线索）会发送给当前可用的最强模型，简单的提示词则发送给轻量模型——这样可以节省稀缺的强模型配额，让模型池在更长时间内保持出色表现。它还会在本地识别置信度高、有依据的 Markdown 阅读／提取请求。当存在候选模型确切身份对应的、来自已版本化且已清理的测试样例的重复证据时，一个有界的任务适配项会影响质量排序。未测量的模型仍可用；如果没有候选模型具备当前证据，则排序保持不变。能力评估基于真实基准数据，而非根据名称猜测；未被任何基准列表覆盖的模型则回退到名称启发式判断。

使用 --task grounded-reading 声明该意图，使用 --task general 禁用自动分类，或使用 --task auto 在本地进行分类。OpenAI 兼容、Responses 和 Anthropic 代理客户端可以发送请求体扩展字段 "task": "grounded-reading"，或发送 X-Freellmpool-Task 标头。显式意图优先于自动分类。任务证据仅存储汇总通过次数、测试样例哈希和分数——绝不存储提示词、文档、响应或提供方机密信息。

内置的离线分数来自 LMArena Elo（采用 MIT 许可的快照）和 Aider 代码编辑排行榜（Apache-2.0），并统一归一化为百分位数。如需覆盖范围更广的数据，可使用免费的 Artificial Analysis API 密钥（FREELLMPOOL_AA_API_KEY）运行 freellmpool capability sync——其 Intelligence Index 涵盖大多数当前模型和开放权重模型，并且具有更高优先级。获取的 AA 数据会使用你自己的密钥缓存在本地（根据 AA 条款，绝不会随软件捆绑）。freellmpool capability status 会显示当前覆盖范围。分数来自 LMArena 和 Aider；提供密钥后，智能指数来自 Artificial Analysis。

上下文窗口。 免费模型的上下文窗口通常较小。freellmpool 绝不会截断你的输入；当模型因请求过长而拒绝请求时，它会记住该模型的限制，并停止将超出限制的请求路由给它，仅转而使用窗口更大的模型。如果没有任何模型能够容纳请求，它会抛出清晰的 ContextWindowExceeded 错误（并提供输入大小估算），而不是返回通用错误——通过代理调用时，对应的状态码为 413。你可以在 providers.toml 中使用 context = N 声明模型的窗口大小，以便提前跳过该模型。

架构说明：docs/ARCHITECTURE.md。

限制

• 免费层模型小于前沿模型。它们适合起草、总结、分类、分诊和日常编码，但无法替代 GPT 级模型解决难题时的推理能力。
• 随着高容量层级的额度耗尽，质量和容量会随一天中的时段而变化。freellmpool 的本地每日计数器会在 UTC 午夜重置；上游提供商则使用各自的限制和重置时段。
• 免费层可能随时变更，恕不另行通知。模型 ID 或限制失效时，只需提交一个修改 providers.toml 的单行 PR，即可让所有人受益。
• 此代理面向本地／单用户使用。默认绑定到 127.0.0.1；如果将其公开，请设置密钥（--api-key）。
• Claude Code / Anthropic 路径仍处于实验阶段（支持文本和工具调用；不支持视觉）。
• 这些免费层由所有人共享，请勿滥用。
• 上游提供商会收到你的请求，并可能对请求标题进行提示或审核；发送敏感提示词前，请查阅 FAQ 中的隐私表格和各提供商当前的条款。
• 免费层的可用性、模型 ID 和速率限制可能随时变动，恕不另行通知。freellmpool 不会绕过提供商限制、轮换账号或规避配额。

对比

对比快照：2026-07-19。竞品行链接到用于支撑相关说法的确切 README 提交版本；各项目的范围变化很快，因此请将其视为带日期的概览，而非永久排名。

工具	免密钥启动	提供商数量	故障转移	MCP 服务	CLI	转录	本地/可自托管	许可证
freellmpool	是，前提是有可用的已配置免密钥提供商	本地目录收录了 23 个聊天提供商	是：可重试的提供商故障、空回复和传输错误	是：freellmpool mcp	单次调用 CLI，另提供配置档案、库和代理命令	是：/v1/audio/transcriptions 支持故障转移	是：小型 Python 包和本地代理	MIT
OpenRouter 免费模型	否：使用托管 API 需要账户/密钥	托管路由器；快照时，所链接的免费路由器列出了 22 个模型	是：托管提供商/模型回退	是：托管远程 MCP 服务	托管 API/SDK 和 Agent SDK，不提供本地网关 CLI	通过多模态聊天支持音频输入/转录	否：托管服务	专有服务
LiteLLM	否：需提供商或托管网关凭据	README 声称支持 100+ 个大模型/提供商	是：路由器重试/回退	是：AI Gateway 包含 MCP Gateway	Python SDK 和代理/网关 CLI	是：/audio/transcriptions	是：可自托管代理或托管服务	核心部分采用 MIT 许可证；企业功能为商业版
OmniRoute	是：其设置文档介绍了一个无需身份验证的 OpenCode 选项	README 声称支持 268 个集成/提供商和 90+ 个免费选项	是：分层回退/断路器路由	是：MCP 和 A2A 控制平面	功能广泛的管理 CLI 和一键式 Agent 设置	文档介绍了音频翻译；其他媒体功能因提供商而异	是：Node 应用，提供仪表板、Docker、桌面/PWA 方案	MIT
FreeLLMAPI	可通过一条 Docker 命令启动服务；之后配置推理容量	README 声称支持 28 个免费大模型提供商 和 339 个端点	是：提供商/密钥路由和回退	是：MCP（Streamable HTTP）	仪表板/服务端和桌面应用	未说明；支持音频语音/TTS	是：Node/Docker 服务端和桌面应用	MIT

FreeLLMAPI 早于本项目；两者的相似之处，是各自独立地聚焦于合法免费套餐。OmniRoute 致力于打造功能丰富的控制平面，支持多种协议；FreeLLMAPI 则侧重于以仪表板为核心、可自托管且具备加密密钥管理的路由器；freellmpool 则专注于最精简的 Python/CLI/库方案，并支持免密钥获取首次回复。这些是产品范围上的选择，并不意味着某个工具适用于所有部署场景。

常见问题

有免费的、兼容 OpenAI 的大模型 API 网关吗？ 有——freellmpool 是一个免费的 MIT 许可网关，可通过一个兼容 OpenAI 的端点，访问你能够使用的已启用路由。其目录收录了 23 个提供商组，涵盖持续提供的免费额度、无需密钥的端点、有限试用、仅供固定使用的路由，以及已禁用的候选项。运行 pip install freellmpool，然后将任何 OpenAI 客户端指向本地代理。

如何同时使用多个免费的大模型 API？ freellmpool 会将它们汇集起来：每个请求都会发送到你能够使用的某个提供商；如果该提供商触发速率限制或宕机，则会切换到下一个；它还会跟踪每日用量，让负载分散到各个免费额度中。

可以用免费模型运行 Claude Code 或 Codex 吗？ 可以——该代理支持 OpenAI API，并提供实验性的 Anthropic 兼容路径。对于兼容 OpenAI 的工具，设置 OPENAI_BASE_URL=http://localhost:8080/v1；对于兼容 Anthropic 的工具，设置 ANTHROPIC_BASE_URL=http://localhost:8080，然后使用 Codex、Claude Code、aider、Cline、Continue 或 Cursor，通过汇集的免费额度运行。对于 Claude Code，请设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，以便通过 Anthropic 桥接发现 /v1/models。参见 freellmpool code <agent>。（Claude Code 路径为实验性功能：支持文本和工具，不支持视觉。）

需要 API 密钥吗？ 只要有已启用的免密路由可用，就不需要：Pollinations、OVHcloud 和 Kilo Gateway 提供免密路由，LLM7 则可选用密钥。添加适用的免费额度或试用凭证，即可使用更多路由并获得更大容量；可用性和条款因提供商而异。

它免费且开源吗？ 是的，采用 MIT 许可。更多信息请参阅项目页面。

精选内容

• 社区视频（西班牙语，作者：lytohlg AI）："用一个命令免费使用 18 个 AI 模型" 和 "无需 API 密钥，30 秒内免费试用 18 个 AI"（基于较早的目录；freellmpool 目前收录了 23 个提供商）。
• 目录：MCP Market 上的 FreeLLM Pool。

贡献

新增提供商和修复过时的限制信息是最有价值的贡献，而且通常只需修改 providers.toml。请参阅 CONTRIBUTING.md。适合新手且可供维护者接手的任务列于 docs/GOOD_FIRST_ISSUES.md。测试可在无需网络访问的情况下运行：

python -m pip install -e ".[dev]" && ruff check . && pytest

本仓库的源代码优先验证使用 PYTHONPATH=src，因此无需先进行可编辑安装，pytest 就能针对当前检出代码运行；CI 使用相同配置。发布就绪检查使用 PYTHONPATH=src python3 scripts/check_release_ready.py。 安全扫描器、严重性门槛、限期豁免流程、本地复现、SBOM 和来源验证均记录在 SECURITY.md 中。

许可证

MIT