1. 项目概述告别手动切换让免费AI模型池为你自动工作如果你正在使用像OpenClaw或Claude Code这样的AI编程助手并且依赖OpenRouter上的免费模型那你一定经历过这种场景正写到关键处突然弹出一个“rate limit exceeded”或者“model not found”的错误然后就得手忙脚乱地去配置文件里把出错的模型ID换成另一个祈祷它能正常工作。这种“保姆式”的模型管理工作不仅打断思路还让人心力交瘁。infinity-router这个工具就是为了彻底解决这个问题而生的。简单来说infinity-router是一个智能的LLM路由管理器。它把OpenRouter上30多个免费模型当作一个庞大的资源池自动帮你做三件事发现当前可用的、支持工具调用的聊天模型评估它们的性能、上下文长度和稳定性并打分排序最后配置到你的OpenClaw或Claude Code中并建立好后备链。当主模型因为限速、故障或下线而罢工时它会自动切换到下一个最优的模型整个过程无需你手动干预。它的设计理念非常务实就是为AI编程助手Agent实际运行的“混乱”环境而生——无论是Windows笔记本、Ubuntu VPS还是配置了多个API密钥的场景它都能让免费模型的使用变得可靠和省心。2. 核心设计思路从“单点故障”到“弹性资源池”传统的AI助手配置往往是选定一个模型ID写死在配置里。这种模式存在明显的单点故障风险。infinity-router的核心思路是将思维从“使用一个模型”转变为“管理一个模型池”。这个转变背后是对免费服务不稳定性的深刻理解和对自动化运维的实践。2.1 为什么需要路由和后备OpenRouter的免费模型虽然丰富但每个都有独立的每日或每分钟调用限制。此外模型本身可能临时下线、更新或者对工具调用的支持在声明和实际表现上有差异。手动应对这些变化是低效且不可靠的。infinity-router引入的“主模型后备链”设计本质上是为你的AI助手构建了一个高可用的服务层。主模型负责日常请求而后备模型列表则作为降级方案。当网关如OpenClaw Gateway遇到错误时它可以自动按顺序尝试后备模型直到有一个能成功响应。infinity-router的智能之处在于它不仅仅提供一个静态列表而是动态地、根据实时情况去构建和排序这个后备链。2.2 模型评估体系的构建逻辑工具不是简单地把所有免费模型罗列出来而是建立了一套评分体系0.0-1.0来量化模型的“可用性”。这个权重分配体现了对编程助手场景的深度理解工具调用支持35%这是最高权重项。对于Claude Code、OpenClaw这类需要执行代码、调用API的Agent来说模型能否正确理解和执行工具调用Function Calling是核心能力。infinity-router会通过API元数据筛选并特别处理了像Gemma这类“声称支持但实际运行时失败”的模型将其排除在工具支持评分之外避免了配置陷阱。上下文长度30%大上下文窗口意味着模型能处理更复杂的代码库、更长的对话历史这对编程任务至关重要。128K的模型显然比8K的模型更有价值。模型新旧程度20%一般来说更新的模型权重文件Checkpoint往往在代码、推理等任务上表现更好。这个权重鼓励系统优先选择更现代的架构。供应商信誉10%来自Meta、Mistral AI、DeepSeek、Google等知名机构的模型通常在服务稳定性和长期维护上更有保障。其他能力5%如视觉理解、结构化输出等作为锦上添花的加分项。这套体系确保了被选中的模型不仅是“免费的”更是“适合编程Agent工作的”。它还会主动过滤掉非聊天模型如音频、图像生成、嵌入模型确保资源池的纯净性。2.3 多API密钥的负载均衡策略单个免费API密钥的调用限额很容易触达。infinity-router鼓励并支持配置多个API密钥这不仅是简单的备用更实现了探针负载均衡。在执行--validate验证命令时工具会轮询使用不同的密钥去测试候选模型。这样验证12个模型所消耗的额度会平摊到3个密钥上每个密钥只消耗4次极大地延缓了触发单个密钥速率限制的时间提升了整体探测成功率和可持续性。这是一种非常工程化的、对抗资源限制的思路。3. 安装与初始配置详解infinity-router的安装力求简洁提供了适应不同环境的方案。我个人强烈推荐使用项目自带的安装脚本它能优雅地处理不同Linux发行版的包管理冲突。3.1 跨平台安装方案选择对于大多数Linux/macOS用户直接使用install.sh脚本是最稳妥的方式。这个脚本的精妙之处在于它规避了Debian/Ubuntu等系统上常见的“externally-managed-environment”限制即系统禁止直接使用pip安装包。它的工作原理是在本地创建一个Python虚拟环境venv将infinity-router安装到这个隔离环境中然后将可执行命令软链接到/usr/local/bin目录下。这样你获得了全局可用的命令同时又没有污染系统Python环境。# 1. 克隆项目或下载安装脚本 git clone https://github.com/genoshide/infinity-router.git cd infinity-router # 2. 赋予脚本执行权限并运行 chmod x install.sh sudo ./install.sh # 可能需要sudo权限来创建软链接运行后infinity-router和infinity-router-daemon两个命令就可以在终端中直接调用了。卸载同样简单执行./uninstall.sh即可。对于Windows用户过程也很直接。在PowerShell中进入项目目录创建虚拟环境并安装即可# 在项目目录下打开PowerShell py -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -e .安装后你可以在当前激活的虚拟环境中使用infinity-router命令。如果想全局使用可以考虑使用pipx进行安装它能为你管理独立的、隔离的CLI应用环境。3.2 API密钥配置单密钥与多密钥策略配置API密钥是使用前的关键一步。infinity-router会从环境变量OPENROUTER_API_KEY中读取密钥。单密钥配置基础版# 临时生效当前终端会话 export OPENROUTER_API_KEYsk-or-v1-你的密钥 # 持久化配置如果你使用OpenClaw openclaw config set env.OPENROUTER_API_KEY sk-or-v1-你的密钥这种方式简单但容易遇到每日限额问题。多密钥配置推荐的生产级做法 将多个密钥用英文逗号分隔放在同一个环境变量里。这是给infinity-router的探测命令使用的。openclaw config set env.OPENROUTER_API_KEY sk-or-v1-密钥1,sk-or-v1-密钥2,sk-or-v1-密钥3然而对于实际的模型调用通过OpenClaw网关你需要将这些密钥注册为独立的认证配置。这是为了避免网关在调用时始终使用同一个密钥。你需要编辑OpenClaw的认证配置文件~/.openclaw/agents/main/agent/auth-profiles.json{ version: 1, profiles: { openrouter:default: { type: api_key, provider: openrouter, key: sk-or-v1-密钥1 }, openrouter:backup1: { type: api_key, provider: openrouter, key: sk-or-v1-密钥2 }, openrouter:backup2: { type: api_key, provider: openrouter, key: sk-or-v1-密钥3 } } }一个重要提示infinity-router非常智能它在需要读取密钥时例如写入配置会优先尝试从上述auth-profiles.json文件中解析openrouter类型的密钥。这意味着只要你在这里配置好了即使不在openclaw.json的环境变量中重复设置OPENROUTER_API_KEYinfinity-router也能正常工作。这避免了配置的冗余和不同步。4. 核心工作流程与命令实战安装配置好后就可以开始体验自动化模型管理的威力了。infinity-router提供了多个子命令覆盖了从探索、配置到监控的全流程。4.1 探索与评估scan和bench命令在盲目配置之前先看看池子里有什么。infinity-router scan命令会从OpenRouter获取免费模型列表并根据前述评分规则进行排序展示。# 显示排名前20的模型 infinity-router scan # 显示前30名并强制刷新缓存获取最新数据 infinity-router scan --limit 30 --refresh输出是一个清晰的表格包含排名、模型ID、上下文长度、综合得分和状态提示。状态栏会显示当前配置中的主模型● primary和后备模型· fallback让你一目了然。如果你更关心模型的响应速度可以使用infinity-router bench命令对排名靠前的模型进行延迟测试。它会向每个模型发送一个轻量的测试请求并记录响应时间。这对于追求交互流畅度的场景很有参考价值。# 对排名前5的模型进行基准测试 infinity-router bench # 测试前10名 infinity-router bench --count 10测试结果会清晰标出成功✓和失败✗如触发限速并最终按延迟排序。这能帮你从“可用”的模型中筛选出“又快又稳”的那一个。4.2 一键智能配置pick命令这是最常用的命令也是工具的核心价值体现。infinity-router pick会自动完成“评分-选择-写入配置”的全过程。# 基础用法快速选择最佳模型并配置5个后备模型 infinity-router pick执行后它会读取模型缓存选择分数最高的作为主模型再依次选择后续的4个高分模型作为后备链然后将这个配置写入你的OpenClaw或Claude Code配置文件。之后你需要重启网关使配置生效openclaw gateway restart。为了更保险尤其是在首次使用或感觉模型不稳定时强烈建议加上--validate参数# 安全用法验证每个候选模型后再写入 infinity-router pick --validate这个命令会变慢因为它会实际调用API去验证每个候选模型是否真的能正常工作特别是工具调用。但它能有效避免将那些“声称支持工具但实际会崩溃”的模型如某些Gemma版本加入配置。工具会使用多密钥轮询策略来最小化验证带来的额度消耗。其他有用的pick参数--fallbacks-only保持当前主模型不变只重新构建后备链。适用于你觉得主模型还行但后备失效的情况。--count 10构建包含10个模型的后备链默认是5个。后备链越长容错能力越强但列表末尾的模型质量可能下降。--auth在写入模型配置的同时尝试在OpenClaw的auth-profiles.json中添加一个对应的API密钥配置如果尚未存在。4.3 手动指定与状态查看有时你可能想强制使用某个特定模型比如社区热议的某个新模型。infinity-router use命令支持通过模型名称的部分匹配来快速指定。# 使用包含“deepseek”的模型作为主模型 infinity-router use deepseek # 使用包含“llama-3.3-70b”的模型并仅重建后备链 infinity-router use llama-3.3-70b --fallbacks-only想了解当前工具和系统的状态infinity-router status命令会给你一份完整的报告包括检测到的API密钥脱敏显示、当前生效的配置目标、主模型和后备模型列表、缓存状态等信息。这是排查问题时第一个应该运行的命令。4.4 高级监控与自动故障转移watch命令如果说pick是静态优化那么watch就是动态守护。这个命令会实时监控OpenClaw网关的日志文件自动检测模型调用失败。# 开始监控使用默认阈值120秒窗口内3次失败触发切换 infinity-router watch # 详细模式打印出每一行匹配到的错误日志 infinity-router watch --verbose # 自定义策略60秒内出现5次失败则触发切换两次切换间至少等待10分钟 infinity-router watch --window 60 --thresh 5 --cooldown 600它的工作原理是持续读取日志文件默认在/tmp/openclaw/或 Windows 的%TEMP%\openclaw\匹配特定的错误模式如FailoverError、model_not_found、No endpoints found以及各种速率限制错误。当失败次数在设定的时间窗口内超过阈值它就会自动执行以下操作将当前主模型标记为“速率受限”记录到本地状态避免短时间内再次选用。从可用模型中选取下一个最优模型作为新的主模型。重新构建后备链。自动执行openclaw gateway restart以应用新配置。这意味着当你的AI助手因为模型限速而开始报错时infinity-router watch能在几十秒到几分钟内自动完成故障切换无需你从睡梦中醒来或中断工作去手动处理。对于在VPS上长期运行的服务建议将其配置为后台服务。使用nohup是最简单的方式nohup infinity-router watch ~/.infinity-router/watch.log 更优雅的方式是创建systemd用户服务单元实现开机自启和日志管理。4.5 守护进程模式infinity-router-daemonwatch命令是一个常驻的日志监控进程。而infinity-router-daemon则提供了另一种更轻量的、基于轮询的检查方式。# 单次检查如果需要则执行切换 infinity-router-daemon # 以循环模式运行每5分钟检查一次默认间隔 infinity-router-daemon --loop # 强制切换到下一个最佳模型 infinity-router-daemon --rotate # 查看守护进程的旋转历史和各模型的冷却状态 infinity-router-daemon --statusdaemon更适合与cron定时任务结合或者在你觉得日志监控 (watch) 占用资源时使用。你可以设置一个cron作业例如每30分钟运行一次infinity-router-daemon来实现定期的健康检查和自动恢复。5. 配置目标与文件结构解析infinity-router支持将配置写入不同的目标主要是为了适配不同的AI助手平台。5.1 OpenClaw 目标配置这是默认且功能最全的目标。它会修改~/.openclaw/openclaw.json文件。写入的内容主要是模型配置部分具体是在agents.main.chatModel或相关配置块下设置model为主模型ID并构建一个fallbacks数组。工具非常谨慎只会修改与模型ID相关的配置项你文件中的其他自定义设置如温度、最大令牌数等都会得到保留。这种“非侵入式”的写入策略避免了配置冲突。5.2 Claude Code 目标配置对于Claude Code它修改的是~/.claude/settings.json文件。需要注意的是Claude Code的配置结构可能不支持原生的后备链fallback配置。因此infinity-router在--target claude-code模式下通常只写入单一的model字段。这意味着自动故障转移的功能在Claude Code上可能受限但自动选择最佳模型的功能依然有效。使用此目标的前提是你的Claude Code环境已经预先配置好能够识别并使用OpenRouter格式的模型ID。5.3 本地状态文件管理工具的所有运行时状态都保存在~/.infinity-router/目录下理解这些文件有助于高级调试model-cache.json: 缓存了从OpenRouter获取并评分后的模型列表。默认6小时TTL过期避免频繁请求API。当你发现模型列表陈旧或想强制刷新时可以手动删除此文件。rate-limits.json: 记录了每个模型被标记为“速率受限”的时间戳。当一个模型在watch或daemon过程中因失败被切换它会被记录在这里并在接下来的30分钟默认冷却时间内不会被选为主模型。你可以通过infinity-router reset --clear-rl来清除这些记录。daemon-state.json: 守护进程的运行状态如旋转次数、最后一次检查时间等。定期清理缓存是一个好习惯可以作为一个简单的每日维护脚本#!/bin/bash # 每日清理并刷新配置 rm -f ~/.infinity-router/model-cache.json infinity-router pick --validate openclaw gateway restart echo [$(date)] 模型配置已刷新。6. 实战经验与避坑指南在实际部署和使用infinity-router的过程中我积累了一些关键经验能帮你少走弯路。6.1 多API密钥配置的常见陷阱陷阱一环境变量与认证文件混淆。最容易出错的地方就是API密钥的配置位置。记住用于探测验证的密钥来自环境变量OPENROUTER_API_KEY多个用逗号隔开。用于实际API调用的密钥配置在OpenClaw的auth-profiles.json中。infinity-router在写入配置时会尝试从auth-profiles.json里找一个可用的openrouter密钥来填充配置。如果这里没配或者配置的密钥无效即使探测时成功了实际调用也会失败。陷阱二密钥额度耗尽连锁反应。如果你只配置了一个密钥并且频繁使用--validate或bench很容易快速耗尽该密钥的免费额度导致后续真正的模型调用失败。务必配置至少2-3个密钥并利用工具的多密钥轮询特性。6.2watch模式下的日志与权限问题问题watch命令报错“Log file not found”。这通常是因为OpenClaw网关的日志路径不标准。infinity-router默认在/tmp/openclaw/或 Windows 的临时目录查找openclaw-YYYY-MM-DD.log。如果你的OpenClaw将日志输出到了其他地方需要通过环境变量OPENCLAW_LOG_DIR来指定目录。export OPENCLAW_LOG_DIR/path/to/your/openclaw/logs infinity-router watch问题watch检测到失败但重启网关失败。watch在触发切换后会尝试执行openclaw gateway restart。如果这个命令需要sudo权限或者不在当前用户的PATH中就会失败。确保运行watch的用户有权限执行openclaw命令。在systemd服务中配置时要注意用户环境变量。6.3 模型评分与选择的个性化调整工具的评分权重是作者基于通用编程Agent场景设定的但你的需求可能不同。例如如果你处理的代码库非常庞大可能希望给“上下文长度”更高的权重如果你主要做代码生成而非工具调用或许可以降低“工具支持”的权重。目前infinity-router没有提供修改权重参数的CLI选项这需要你直接修改源代码中的models.py文件。对于高级用户来说这是一个值得考虑的定制点。6.4 冷启动与缓存策略第一次运行infinity-router scan或pick时需要从OpenRouter API获取模型列表可能会稍有延迟。获取后的列表会缓存6小时。如果你刚刚在OpenRouter账户中添加了新的API密钥或者得知上线了新模型可以使用--refresh参数强制刷新缓存。同理如果你发现工具一直推荐一个已经明显变慢或常出错的模型可以手动删除~/.infinity-router/model-cache.json文件然后重新运行pick --validate来建立新的、更准确的模型排名。6.5 与现有OpenClaw配置的兼容性infinity-router的设计原则是“只写模型配置不动其他设置”。但在极少数情况下如果你的openclaw.json结构非常特殊例如使用了自定义的模型配置块名称工具的自动写入可能会失败或写入到错误的位置。在执行pick命令前强烈建议备份你的配置文件。执行后用infinity-router status检查写入的模型ID是否正确并快速浏览一下配置文件确认没有意外改动。7. 故障排查与典型问题解决即使有了自动化工具遇到问题时知道如何排查也至关重要。下面是一个快速排查清单。7.1 模型调用持续失败症状配置成功后OpenClaw网关依然返回模型错误或认证错误。排查步骤检查状态运行infinity-router status确认主模型和后备模型列表是预期的并且显示了检测到的API密钥数量是否正确。验证模型运行infinity-router pick --validate。这个命令会实际测试模型如果这里就失败说明问题出在模型选择或API密钥上。观察输出看是“rate_limit”错误还是“tool call failed”错误。检查认证文件打开~/.openclaw/agents/main/agent/auth-profiles.json确认里面配置的openrouter类型密钥是有效的且没有过期。手动测试API用curl或Postman使用auth-profiles.json里的一个密钥直接向OpenRouter API发送一个简单请求验证密钥本身是否有效。curl https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer sk-or-v1-你的密钥 \ -H Content-Type: application/json \ -d {model: meta-llama/llama-3.3-70b-instruct:free, messages: [{role: user, content: Hello}]}7.2watch或daemon不触发自动切换症状网关日志中已经出现大量错误但infinity-router没有执行切换。排查步骤检查阈值确认失败次数是否达到了你设置的--thresh默认3次在--window默认120秒时间内。日志中的错误必须能被工具识别如包含FailoverError,rate limit等关键词。启用详细模式使用infinity-router watch --verbose。这会打印出工具匹配到的每一行错误日志。看看它是否识别出了错误。检查冷却时间运行infinity-router-daemon --status或查看rate-limits.json文件。可能当前主模型刚被切换过还处于冷却期默认30分钟工具不会立即再次切换它。检查日志路径确认OPENCLAW_LOG_DIR环境变量设置正确或者日志文件确实在默认路径并且运行watch的用户有读取权限。7.3 工具安装或命令找不到症状执行infinity-router提示“command not found”。解决Linux/macOS脚本安装确保执行了sudo ./install.sh并且/usr/local/bin在你的系统PATH中。虚拟环境安装确认你已经使用source .venv/bin/activate(Linux/macOS) 或.\venv\Scripts\Activate.ps1(Windows) 激活了虚拟环境。Pipx安装尝试使用pipx run infinity-router来运行。7.4 性能与资源考虑infinity-router本身非常轻量主要开销在于网络请求。--validate参数会发起真实的API调用消耗OpenRouter额度请酌情使用。watch命令是文件I/O密集型持续监控日志文件。在资源极其有限的VPS上如果磁盘I/O敏感可以考虑使用infinity-router-daemon --loop的轮询模式替代并将检查间隔设得长一些例如300秒这比持续读取日志文件更节省资源。经过一段时间的深度使用我的体会是infinity-router真正将免费LLM的使用从一种“碰运气”的体验变成了接近“稳定服务”的体验。它背后的设计思想——将不稳定的资源池化、自动化故障转移、利用多密钥分摊风险——不仅适用于OpenRouter其实也为管理任何外部API服务提供了很好的范式。最大的价值不在于省下那点API费用而在于让你能专注于提示工程和业务逻辑而不是整天和“Model is overloaded”这样的错误信息作斗争。最后一个小技巧是可以将infinity-router-daemon --loop和系统的定时任务如cron结合设定在每天你的工作开始前自动运行一次pick --validate确保你每天开工时AI助手都已经用上了当天最稳定、最快的免费模型。