构建AI模型智能路由池:告别手动切换,实现高可用编程助手
1. 项目概述:告别模型保姆,构建智能路由池
如果你正在用 OpenClaw 或者 Claude Code 这类 AI 编程助手,并且依赖 OpenRouter 上的免费模型,那你一定经历过这种场景:正写到关键处,突然弹出一个rate_limit错误,或者模型莫名其妙地“罢工”了。于是你不得不停下手中的活,手动去 OpenRouter 的模型列表里翻找,看看哪个免费模型今天还没被用光额度,然后打开配置文件,小心翼翼地修改model字段,保存,重启网关……整个过程就像在照顾一个需要时刻关注状态的“婴儿”。
infinity-router就是为了终结这种“保姆式”运维而生的。它的核心思想很简单:把 OpenRouter 上那 30 多个免费的聊天模型看作一个“资源池”,而不是一个个孤立的选项。这个工具会自动帮你做三件事:发现当前可用的模型,评估它们的质量(重点是工具调用能力和上下文长度),然后配置一个包含主选模型和备用链的稳健方案。当主模型因为限流、故障或“假死”而失效时,它能自动切换到下一个最优的备用模型,整个过程无需你手动干预。
这不仅仅是简单的故障转移。它内置了一套评分机制,会优先选择那些真正支持工具调用(这对编程 Agent 至关重要)、拥有更长上下文窗口、并且来自可靠提供商的模型。它会自动避开那些声称支持工具但实际会崩溃的“坑货”(比如某些 Gemma 模型),也会过滤掉图像、音频生成等非聊天模型。最终,它生成的是一个可以直接被 OpenClaw 或 Claude Code 使用的配置文件,让你能在一个看似不稳定的免费模型池上,获得接近付费服务的可靠性。
2. 核心设计思路:从脆弱单点走向弹性集群
为什么手动切换模型这么痛苦?因为传统的用法是把所有希望寄托在一个模型 ID 上。这是一个典型的单点故障。infinity-router的设计哲学,就是引入“路由”和“池化”的概念,将单点架构转变为弹性集群。
2.1 模型池的动态发现与评分
OpenRouter 的免费模型列表是动态变化的,新模型会上线,旧模型可能调整配额或下线。infinity-router的第一步是构建一个动态的模型池。它通过调用 OpenRouter 的公开 API 获取所有模型信息,然后执行严格的过滤:
- 类型过滤:首先剔除所有非聊天模型。这包括像
lyria(音频)、imagen/dall-e(图像)、stable-video(视频)以及各类embedding模型。我们的目标是寻找能进行代码对话和工具调用的模型。 - 能力过滤:这是关键一步。API 返回的模型信息中有一个
capabilities字段。infinity-router会检查其中是否包含function_calling(函数调用)。但这里有个陷阱:有些模型(如部分 Gemma 变体)在 API 中声明支持此功能,但在实际调用工具时会崩溃。因此,工具会结合社区反馈和内部规则,将这些“假支持”的模型从高优先级列表中降权或排除。 - 多维评分:通过筛选的模型会进入评分环节。评分权重分配体现了对编程 Agent 场景的深度理解:
- 工具调用能力 (35%):最高权重。没有可靠的函数调用,AI 就无法执行代码、搜索文件或调用外部 API,编程助手就失去了灵魂。
- 上下文长度 (30%):次高权重。处理大型代码库、保持长对话记忆,都依赖足够的上下文窗口。128K 的模型显然比 8K 的更有优势。
- 模型新旧 (20%):一般来说,更新的模型权重和架构往往在代码和推理任务上表现更好。
- 提供商信誉 (10%):Meta (Llama)、Mistral AI、DeepSeek、Google 等知名机构的模型,通常在稳定性和持续维护上更有保障。
- 其他能力 (5%):如视觉理解、结构化输出等,作为锦上添花的加分项。
这个评分结果会缓存起来(默认 6 小时),避免频繁请求 API 造成不必要的开销。
2.2 智能回退链的构建
选出一个最高分的模型作为“主节点”只是开始。infinity-router更强大的地方在于它会构建一个“回退链”。当你执行infinity-router pick时,它会做以下事情:
- 设置主模型:选择评分最高的模型作为默认使用模型。
- 插入智能路由:总是将
openrouter/free这个特殊的模型 ID 作为第一备用。这不是一个具体的模型,而是 OpenRouter 提供的智能路由终点,它会在每次请求时为你选择当时可用的最佳免费模型。这相当于在你自己构建的静态路由之上,又加了一层动态负载均衡。 - 填充备用列表:接着,它会按评分降序,选取接下来的 N 个模型(默认 5 个)作为后续备用,形成一条链:
主模型 -> openrouter/free -> 备用模型1 -> 备用模型2 -> ...。 - 写入目标配置:根据
--target参数,将这个链式结构写入对应的配置文件。对于 OpenClaw,它会修改~/.openclaw/openclaw.json中的模型配置,利用 OpenClaw 网关原生的故障转移机制。对于 Claude Code,则写入~/.claude/settings.json的model字段(Claude Code 本身不支持链式回退,因此只写入主模型)。
这样,当主模型失败时,请求会先流向openrouter/free这个“动态选择器”,如果它还不行,再依次尝试你预设的其他优质备用模型。多重保险,极大提升了可用性。
2.3 基于故障感知的自动旋转
动态发现和备用链解决了“有准备”的问题,而watch和daemon命令则解决了“自动响应”的问题。它们会实时监控 OpenClaw 网关的日志文件(如/tmp/openclaw/openclaw-*.log),寻找特定的错误模式:
FailoverError/Unknown model:模型不存在或不可用。model_not_found:明确的模型未找到错误。No endpoints found:通常意味着模型不支持当前请求的工具。free-models-per-day/free-models-per-min:明确的速率限制错误。
监控器采用滑动窗口算法。例如,默认设置在 120 秒窗口内,如果同一模型的错误次数超过 3 次,则判定该模型“失效”。一旦触发,infinity-router会:
- 将该模型标记为“速率受限”,并记录时间戳(30分钟内不再选用)。
- 从当前可用模型池中,选择下一个评分最高的模型作为新的主模型。
- 重新构建以新主模型为首的备用链。
- 自动执行
openclaw gateway restart以应用新配置。
这个过程完全自动化,将故障恢复时间从“分钟级”的人工响应缩短到“秒级”的系统自愈。
3. 实战部署与配置详解
理解了原理,我们来一步步把它用起来。部署infinity-router非常灵活,你可以根据运行环境选择最适合的方式。
3.1 安装:选择你的最佳路径
推荐方案(Linux/macOS):使用安装脚本项目提供的install.sh脚本是最省心的方式,尤其能完美解决 Debian/Ubuntu 等系统因强制使用外部包管理器而导致的externally-managed-environment错误。
# 1. 克隆或下载项目 git clone https://github.com/genoshide/infinity-router.git cd infinity-router # 2. 运行安装脚本 chmod +x install.sh ./install.sh这个脚本会创建一个 Python 虚拟环境(venv),将infinity-router安装到其中,然后将两个可执行文件(infinity-router和infinity-router-daemon)符号链接到/usr/local/bin。这样,你就可以在系统的任何地方直接调用它们了。卸载同样简单:./uninstall.sh。
手动方案(通用):使用虚拟环境如果你喜欢更手动的控制,或者脚本在你的系统上不工作,可以手动创建虚拟环境。
# 创建并激活虚拟环境 python3 -m venv .venv source .venv/bin/activate # Linux/macOS # 对于 Windows: .venv\Scripts\activate # 安装包 pip install -e . # 验证安装 infinity-router --versionWindows 特别说明在 Windows PowerShell 中,过程类似,但激活脚本的路径不同。使用pipx是另一种优雅的隔离安装方式,适合经常安装命令行工具的用户。
# 方法一:虚拟环境 py -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -e . # 方法二:使用 pipx (需先安装 pipx) pipx install .注意:无论哪种方式,请确保你的 Python 版本在 3.10 及以上。
infinity-router的依赖极简,只有requests一个库,这减少了环境冲突的可能性。
3.2 核心配置:API 密钥的管理艺术
配置的核心是 OpenRouter API 密钥。免费获取方式是在 OpenRouter 官网 注册账户。
单密钥基础配置最简单的方式是设置环境变量。这只在当前终端会话有效。
export OPENROUTER_API_KEY="sk-or-v1-你的密钥"为了持久化,特别是配合 OpenClaw,更好的方法是通过 OpenClaw 的配置系统设置:
openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-你的密钥"这会将密钥保存在 OpenClaw 的配置中,对其管理的所有进程(包括网关)生效。
多密钥轮询配置(强烈推荐)免费模型的每日调用次数是有限的。使用多个密钥是突破此限制、提升可用性的关键。infinity-router支持简单的多密钥轮询。
# 在环境变量中用逗号分隔多个密钥 openclaw config set env.OPENROUTER_API_KEY "sk-or-v1-KEY1,sk-or-v1-KEY2,sk-or-v1-KEY3"当你使用infinity-router pick --validate命令时,工具会轮流使用这些密钥去探测模型可用性。假设每个密钥每天有 100 次免费调用,3 个密钥就能让你在验证阶段拥有 300 次的探测额度,大大降低了单个密钥被快速耗尽的风险。
OpenClaw 网关的认证配置环境变量中的密钥主要用于infinity-router自身的探测和发现。要让 OpenClaw 网关在真正转发请求时也能使用多密钥,需要在 OpenClaw 的认证配置文件中声明它们。
打开或创建~/.openclaw/agents/main/agent/auth-profiles.json,添加如下内容:
{ "version": 1, "profiles": { "openrouter:default": { "type": "api_key", "provider": "openrouter", "key": "sk-or-v1-KEY1" }, "openrouter:backup1": { "type": "api_key", "provider": "openrouter", "key": "sk-or-v1-KEY2" }, "openrouter:backup2": { "type": "api_key", "provider": "openrouter", "key": "sk-or-v1-KEY3" } } }infinity-router足够智能,在需要读取密钥时,会同时检查环境变量和这个auth-profiles.json文件,所以你无需重复配置。
实操心得:多密钥策略是保障稳定性的基石。你可以用不同的邮箱注册多个 OpenRouter 账户来获取多个免费密钥。将这些密钥同时配置在环境变量(用于探测)和 OpenClaw 认证文件(用于推理)中,能让你的免费模型池的总体可用调用量成倍增加。
3.3 初体验:快速启动与验证
配置好密钥后,就可以进行第一次模型选取了。
快速选取(信任缓存)
infinity-router pick openclaw gateway restart这个命令会直接使用本地缓存的模型评分列表,快速选出最佳模型并配置备用链,然后你需要重启 OpenClaw 网关使配置生效。速度最快,但如果缓存过期或模型状态已变化,可能选到不可用的模型。
安全选取(推荐首次使用)
infinity-router pick --validate openclaw gateway restart加上--validate参数后,infinity-router在写入配置前,会向候选模型发送一个轻量的测试请求(例如一个简单的对话),以确认其当前确实可用且能正常响应。这会多花一些时间(大约10-20秒),但能确保你得到的配置是立即可用的。它会自动在多个密钥间轮询以分散探测请求,避免触发限流。
执行后,你可以通过infinity-router status命令查看当前的配置状态,确认主模型和备用链是否已按预期设置。
4. 核心工作流与命令全解
infinity-router提供了丰富的子命令来应对不同场景。理解每个命令的用途和组合,能让你像交响乐指挥一样掌控整个模型池。
4.1 探索与评估:scan与bench
在你完全信任自动化之前,或者想了解当前模型池的状况时,scan和bench是你的侦察兵。
infinity-router scan这个命令会获取并展示经过评分和排名的模型列表。
# 显示前20个模型 infinity-router scan # 显示前30个,并强制刷新缓存(从OpenRouter API重新拉取) infinity-router scan --limit 30 --refresh # 针对 Claude Code 环境进行扫描 infinity-router scan --target claude-code输出是一个清晰的表格,包含排名、模型ID、上下文长度、综合评分和状态(是否被选为主模型或备用)。通过这个列表,你可以直观地看到哪些模型在工具支持、上下文等方面更有优势。
infinity-router bench评分高不一定代表响应快。bench命令会对排名靠前的模型进行实时延迟测试。
# 测试前5个模型 infinity-router bench # 测试前10个模型 infinity-router bench --count 10它会向每个模型发送一个相同的、简单的提示词,并测量响应时间。输出会显示每个模型是否成功响应(✓/✗)以及耗时。这对于追求低延迟交互的用户非常重要。你可能发现一个评分稍低但响应极快的模型,更适合你的实时编码场景。
注意事项:基准测试会消耗模型的免费调用次数。虽然每次请求很小,但不宜过于频繁地运行。建议在初次设置或感觉模型变慢时使用。
4.2 核心配置:pick与use
这是最常用的两个命令,负责模型的选定和配置。
infinity-router pick这是主力命令,负责全自动的最佳模型选择与配置。
# 标准自动选取 infinity-router pick # 安全选取(验证可用性) infinity-router pick --validate # 仅重建备用链,保留当前主模型 infinity-router pick --fallbacks-only # 构建包含10个备用模型的更长的回退链 infinity-router pick --count 10 # 选取并自动在OpenClaw认证配置中添加对应的API密钥配置(如果缺失) infinity-router pick --auth--validate是最常用的参数之一,它能有效避免配置到一个“僵尸”模型。--fallbacks-only在你对当前主模型满意,但觉得备用模型需要更新时非常有用。
infinity-router use有时候自动化选出的模型不一定符合你的特定偏好。比如你可能特别想尝试新发布的deepseek-r1,或者钟爱llama-3.3-70b的风格。use命令允许你手动指定模型。
# 通过部分名称匹配(非常方便) infinity-router use deepseek infinity-router use llama-3.3-70b # 手动指定模型,并重新验证和构建备用链 infinity-router use qwen/qwen-2.5-coder-32b-instruct:free --validate # 仅更换备用链,保留我手动指定的主模型 infinity-router use deepseek-r1 --fallbacks-only这个命令在你想进行 A/B 测试,或者针对特定类型的任务(如代码调试、文档生成)固定使用某个特长模型时,提供了灵活性。
4.3 状态监控与自动愈合:watch与daemon
这是infinity-router的“自动驾驶”模式,让系统具备自我修复能力。
infinity-router watch这个命令会实时尾随(tail)OpenClaw 网关的日志文件,并监控其中的错误信息。
# 开始监控,使用默认阈值(120秒内3次错误触发旋转) infinity-router watch # 更敏感的监控:60秒内5次错误就触发 infinity-router watch --thresh 5 --window 60 # 触发旋转后,至少等待10分钟才允许再次旋转(防止频繁抖动) infinity-router watch --cooldown 600 # 详细模式,打印出每一条匹配到的错误日志行 infinity-router watch --verbose # 旋转发生时,向一个Webhook地址发送通知(可用于集成告警) infinity-router watch --notify https://your-server.com/webhook当检测到的错误频率超过阈值,它会自动执行旋转操作:标记故障模型、选取新主模型、重建备用链、重启网关。这一切都在后台静默完成,你可能只会注意到 AI 助手的响应短暂中断了几秒,然后就恢复了。
infinity-router-daemon这是watch命令的一个更简洁的、适合作为系统服务运行的版本。
# 单次检查,如果需要就旋转 infinity-router-daemon # 持续监控(直到按 Ctrl-C) infinity-router-daemon --loop # 强制立即旋转到下一个最佳模型 infinity-router-daemon --rotate # 查看旋转历史和各模型的冷却状态 infinity-router-daemon --statusdaemon更适合部署在服务器上。你可以用nohup或systemd将其作为后台服务运行,实现 7x24 小时无人值守的模型池管理。
避坑技巧:在 VPS 上部署
watch或daemon时,建议通过systemd用户服务来管理,这比简单的nohup更可靠,能处理进程崩溃重启和日志收集。创建一个~/.config/systemd/user/infinity-router-watch.service文件,配置Restart=on-failure等参数。
4.4 信息查询与清理:status与reset
infinity-router status这是一个综合仪表板,一眼看清当前系统的所有状态。
infinity-router status它会显示:
- 发现的 API 密钥数量(脱敏显示)。
- 检测到的目标配置(OpenClaw/Claude Code)及其状态。
- 当前配置的主模型和备用链。
- 模型缓存的新旧程度和速率限制冷却信息。 在遇到问题时,首先运行
status命令,能快速定位是密钥问题、配置问题还是模型本身的问题。
infinity-router reset当你想一切从头开始时,或者配置出现混乱时,使用这个命令。
# 从配置文件中移除 infinity-router 写入的模型配置 infinity-router reset # 移除配置,并清除所有模型的速率限制记录(让所有模型重新变为可用) infinity-router reset --clear-rl注意,reset不会删除你的 API 密钥或 OpenClaw 的其他配置,它只清理由本工具管理的模型设置部分。
5. 高级策略与故障排查
掌握了基本命令后,一些高级策略和问题排查技巧能让你用得更顺手。
5.1 多目标配置:同时服务 OpenClaw 和 Claude Code
你可能在同一个开发机上同时使用 OpenClaw 和 Claude Code。infinity-router可以分别管理它们的配置。
# 为 OpenClaw 配置模型 infinity-router pick --target openclaw # 为 Claude Code 配置模型 (可能是一个不同的、更适合对话的模型) infinity-router use meta-llama/llama-3.2-3b-instruct:free --target claude-code通过--target参数指定写入哪个应用的配置文件。两个配置相互独立,互不干扰。这对于根据工具特性选用不同模型(例如,为代码生成选 DeepSeek Coder,为文档对话选 Llama)的场景非常有用。
5.2 模型评分的微调与理解
工具内置的评分权重(工具35%,上下文30%等)是针对通用编程 Agent 场景优化的。如果你有特殊需求,可以间接影响评分结果。
- 偏好新模型:
infinity-router的“新旧”评分基于模型 ID 的发布信息。通常名称中带更新版本号(如llama-3.2vsllama-3.1)或更新日期标识的模型得分更高。 - 偏好特定提供商:虽然不能直接改权重,但你可以通过
infinity-router use手动指定你信任的提供商模型(如mistralai/或deepseek/),然后使用--fallbacks-only让工具围绕它构建备用链。 - 排除问题模型:如果你发现某个评分高的模型在实际使用中频繁出错,最直接的方法是使用
infinity-router use切换到另一个模型,让有问题的模型在备用链中靠后,或者通过多次失败触发watch将其标记为受限。
5.3 常见问题与解决方案实录
即使有自动化工具,在实际运行中也可能遇到一些问题。下面是一些典型场景及应对方法。
问题1:执行infinity-router pick后,OpenClaw 网关启动失败或报“模型未找到”。
排查步骤:
- 检查密钥:运行
infinity-router status,确认它是否成功读取到了你的OPENROUTER_API_KEY。如果显示未找到,请检查环境变量设置或auth-profiles.json文件格式。 - 检查模型ID:运行
infinity-router scan,确认你配置的模型(在status中显示)是否在列表中,且状态正常。免费模型列表可能变动,缓存可能过期。尝试infinity-router pick --refresh --validate强制刷新并验证。 - 检查 OpenClaw 配置:手动查看
~/.openclaw/openclaw.json,看model字段是否被正确修改为一个有效的 OpenRouter 模型 ID(如openrouter/meta-llama/llama-3.3-70b-instruct:free)。确保格式正确,特别是openrouter/前缀。 - 检查网关日志:运行
openclaw gateway log或查看/tmp/openclaw/openclaw-*.log文件,寻找具体的错误信息。
- 检查密钥:运行
解决方案:
- 如果密钥问题,重新正确设置环境变量或修复
auth-profiles.json。 - 如果模型不存在,运行
infinity-router pick --refresh更新缓存,或手动infinity-router use一个已知存在的模型。 - 如果配置格式错误,可以运行
infinity-router reset清除配置,再重新pick。
- 如果密钥问题,重新正确设置环境变量或修复
问题2:infinity-router watch监控不触发自动旋转。
排查步骤:
- 确认日志路径:
watch命令默认从/tmp/openclaw/或%TEMP%\openclaw\读取日志。如果你的 OpenClaw 日志写在别处,需要通过环境变量OPENCLAW_LOG_DIR指定。 - 检查错误模式:在
watch命令后加--verbose参数,它会打印出匹配到的每一行日志。确认你看到的错误信息是否包含FailoverError、rate_limit等关键字。有些错误信息可能格式不同。 - 调整触发阈值:默认是120秒内3次错误。如果你的错误是偶发的,可以降低阈值(
--thresh 2)或缩短时间窗口(--window 30)使其更敏感。 - 检查进程权限:确保运行
watch的用户有权限读取 OpenClaw 的日志文件和执行openclaw gateway restart命令。
- 确认日志路径:
解决方案:
- 设置正确的
OPENCLAW_LOG_DIR。 - 根据
--verbose输出调整监控逻辑(如果需要,可以反馈给开发者以支持更多错误模式)。 - 调整
--thresh和--window参数以适应你的环境。 - 使用
sudo或以正确用户身份运行。
- 设置正确的
问题3:所有免费模型都很快返回速率限制错误。
- 原因分析:这是免费 tier 的固有限制。每个模型、每个 API 密钥都有独立的每日调用次数和每分钟调用频率限制。
- 解决方案:
- 配置多API密钥:这是最有效的方案。按照前文所述,配置多个密钥,让
infinity-router在探测和 OpenClaw 在实际调用时都能轮询使用。 - 降低使用频率:如果只是个人轻度使用,可以尝试减少与 AI 助手的交互频率。
- 混合使用付费模型:考虑将最重要的任务分配给一个低成本的付费模型(如
gpt-3.5-turbo),将免费模型池作为备用。这需要在 OpenClaw 的配置中设置更复杂的路由规则,超出了infinity-router当前的范围,但是一个可行的架构方向。
- 配置多API密钥:这是最有效的方案。按照前文所述,配置多个密钥,让
问题4:infinity-router-daemon --loop在终端关闭后就停止了。
- 解决方案:这是正常的,因为进程与终端会话绑定。你需要将其作为后台服务运行。
- 使用
nohup:nohup infinity-router-daemon --loop > ~/.infinity-router/daemon.log 2>&1 & - 使用
systemd(推荐):创建用户级 systemd 服务文件,启用并启动它。这样可以实现开机自启、自动重启和集中的日志管理(通过journalctl)。
- 使用
5.4 维护与最佳实践
为了让infinity-router长期稳定运行,建议建立简单的维护习惯。
定期清理缓存:模型列表和评分缓存默认6小时过期。如果你发现工具总是选取一个已经失效的模型,可以手动删除缓存文件强制刷新。
rm -f ~/.infinity-router/model-cache.json infinity-router pick --validate可以将此命令加入每周的 crontab 任务中。
善用
--validate参数:在每次计划性重启或感觉模型不稳定后,执行infinity-router pick --validate是一个好习惯。虽然慢一点,但能确保你得到的配置是健康的。监控与通知集成:利用
infinity-router watch --notify功能,将模型旋转事件发送到你的监控平台(如 Slack、Discord 或自定义的运维面板)。这能让你了解模型池的稳定性情况,并在频繁旋转时意识到可能存在问题(比如所有密钥额度都快用完了)。理解“最终保障”:
openrouter/free这个备用节点是最后的智能保障。即使你配置的所有具体模型都失败了,它仍会尝试让 OpenRouter 的路由器为你选一个能用的。这意味着,只要 OpenRouter 服务本身和你的 API 密钥有效,你的 AI 助手就总有一条路可以走通。
infinity-router的本质,是将管理分布式、易失效资源的复杂性封装了起来,为你提供了一个稳定的抽象层。它让你可以更专注于使用 AI 助手完成工作,而不是陷于基础设施的泥潭。通过合理的配置和多密钥策略,你完全可以在免费额度内,构建一个足以应对日常开发和学习需求的、高可用的 AI 编程助手环境。
