核心用法
free-models 是一套面向 OpenClaw 及其他 AI Agent 工作流的模型发现工具集，核心功能围绕 OpenRouter 平台的免费与超低价大模型展开。用户可通过程序化接口或 CLI 完成三类操作：
1. 全局发现：discoverFreeModels() 自动抓取当前 $0.00 或极低费率（<$0.0001/1M tokens）的可用模型；
2. 精细筛选：filterModels() 支持多维过滤——上下文长度（minContext）、提示/补全单价（maxPromptPrice/maxCompletionPrice）、提供商（author/provider）、模型名称关键词（nameContains），便于针对 Tool Calling、长文本等场景定制；
3. 智能推荐：getBestFreeModel() 内置启发式策略，可依据是否需要推理（needReasoning/preferReasoning）、视觉能力（needVision）及价格上限（maxPrice）返回最优候选。
CLI 使用需先导出 OpenRouter API Key（OPENROUTER_API_KEY），工具将自动拉取实时模型列表。
显著优点
- 成本极优：聚焦 $0 或近零费率模型，显著降低多 Agent 长期运行成本；
- 场景适配：针对 Agent 高频需求（高上下文、Tool Calling、低延迟）设计筛选维度；
- 实时同步：直接对接 OpenRouter API，模型可用性与价格随官方更新；
- 零配置即用：提供开箱即用的 Node.js 脚本，无需复杂模型注册流程。
潜在缺点或局限性
- 可用性波动：免费模型受限于供应商配额，可能出现速率限制或临时下架；
- 质量参差：低价模型在复杂推理、指令遵循上可能弱于商业旗舰模型；
- 供应商锁定：依赖 OpenRouter 聚合层，若其 API 变更需同步更新；
- 无本地运行：所有推理仍需外部 API 调用，存在网络延迟与数据出境合规考量。
适合人群
- OpenClaw 用户需快速替换默认模型以降低成本；
- 多 Agent 系统开发者需动态切换高性价比后端；
- 原型验证阶段希望用最小预算测试不同模型表现的技术团队。
常规风险
- API Key 泄露：
OPENROUTER_API_KEY以环境变量管理，需避免误提交至版本控制； - 费率突变：免费模型可能随时调整定价，建议生产环境设置价格上限熔断机制；
- 数据隐私：请求需发送至 OpenRouter 及上游供应商，敏感数据需脱敏或本地化处理。