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_KEYsk-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这个命令会实时尾随tailOpenClaw 网关的日志文件并监控其中的错误信息。# 开始监控使用默认阈值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文件配置Restarton-failure等参数。4.4 信息查询与清理status与resetinfinity-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。问题2infinity-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当前的范围但是一个可行的架构方向。问题4infinity-router-daemon --loop在终端关闭后就停止了。解决方案这是正常的因为进程与终端会话绑定。你需要将其作为后台服务运行。使用nohupnohup infinity-router-daemon --loop ~/.infinity-router/daemon.log 21 使用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 编程助手环境。