OpenClaw 配置 Sapiens 新模型与 OpenRouter 免费模型实战

日期：2026-07-27
主题：在 OpenClaw 中接入 Sapiens 2.5 系列模型，并补充 OpenRouter 免费模型池
标签：openclaw 模型配置 sapiens openrouter 运维

一、背景与目标

今天的配置目标有两个：

1. 把 Sapiens 新发布的 agnes-2.5-flash 和 agnes-2.5-pro-alpha 接入 OpenClaw，在不改动 primary model 的前提下扩大可选模型范围。
2. 把 OpenRouter 上可用的免费模型批量接入，形成一个可随时切换的“零成本尝鲜”模型池，用于日常测试、fallback 和低优先级任务。

执行过程中没有修改 Cherry Studio；所有变更都只在 ~/.openclaw/openclaw.json 内完成。

二、Sapiens 新模型配置

2.1 新增模型定义

在 models.providers.sapiens.models 下新增两个模型：

• agnes-2.5-flash
• agnes-2.5-pro-alpha

关键参数如下。

agnes-2.5-flash

• contextWindow: 524288
• maxOutputTokens: 未单独设置，使用默认值
• reasoning: true
• input: ["text", "image"]

agnes-2.5-pro-alpha

• contextWindow: 1048576
• maxOutputTokens: 65536
• reasoning: true
• input: ["text", "image"]

两个模型都支持图文输入，且 reasoning 开启。

2.2 Alias 映射

为避免上层调用时写死 provider 内部名称，在 agents.defaults.models 里补充 alias：

• sapiens/agnes-2.5-flash → agnes-2.5-flash
• sapiens/agnes-2.5-pro-alpha → agnes-2.5-pro-alpha

这样后续切换模型只需改 session/agent 配置，不需要改 provider 内部名。

2.3 Primary model 保持不变

当前 primary model 仍保持为 sapiens/agnes-2.0-flash，不因为新模型上线而直接替换主路。

三、OpenRouter 免费模型配置

3.1 Provider 配置

新增 models.providers.openrouter，基础信息：

• baseUrl: https://openrouter.ai/v1
• api: openai-completions
• apiKey: 来自环境变量 OPENROUTER_API_KEY

3.2 免费模型筛选原则

以 OpenRouter API /api/v1/models 返回结果为准，筛选条件：

• pricing.prompt == 0
• pricing.completion == 0

即完全免费，不依赖 slug 是否带 :free 后缀。后续更新时也应回到 API 重新核对，不要凭印象维护名单。

3.3 首批 6 个免费模型

第一批先上线 6 个明确可用的免费模型：

1. inclusionai/ling-3.0-flash:free
2. poolside/laguna-s-2.1:free
3. poolside/laguna-xs-2.1:free
4. cohere/north-mini-code:free
5. google/gemma-4-31b-it:free
6. openrouter/free

并为它们一一配置 alias，方便上层统一引用。

3.4 扩展至 18 个免费模型

第二批再补入 12 个免费模型，把免费池扩大到 18 个，覆盖更多模型族和用途：

NVIDIA Nemotron 系列

• nvidia/nemotron-3.5-content-safety:free
• nvidia/nemotron-3-ultra-550b-a55b:free
• nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free
• nvidia/nemotron-3-super-120b-a12b:free
• nvidia/nemotron-3-nano-30b-a3b:free
• nvidia/nemotron-nano-12b-v2-vl:free
• nvidia/nemotron-nano-9b-v2:free

其他补充模型

• poolside/laguna-m.1:free
• google/gemma-4-26b-a4b-it:free
• openai/gpt-oss-20b:free
• google/lyria-3-pro-preview
• google/lyria-3-clip-preview

其中 lyria-3 系列属于音频/多媒体模型，不适合作为主力文本模型，但按需求一并接入，供特定场景调用。

四、模型验证与限额说明

4.1 验证方式

新增模型不是只看名称，而是通过 OpenRouter API 返回的 JSON 字段逐一核对：

• id
• name
• contextWindow
• maxTokens（若有）
• reasoning
• input 能力
• pricing.prompt
• pricing.completion

只有上述字段齐全且价格字段符合 0，才写入配置。

4.2 免费模型限额

根据 OpenRouter 官方 FAQ：

• 未充值账户：免费模型每日最多 50 次请求（RPD）
• 充值 ≥ 10 美元后：免费模型每日限额提升到 1000 次请求（RPD）

这不是 10 倍提升，而是 20 倍提升（从 50 到 1000）。如果后续长期高频使用免费模型，充值 10 美元是一个很划算的杠杆点。

五、最终配置状态

• Sapiens provider 已包含 2 个新模型
• OpenRouter provider 已包含 18 个免费模型
• 配置已通过 openclaw config validate
• 配置修改前已备份到 ~/.openclaw/openclaw.json.backup.bak

当前 primary model 仍是 sapiens/agnes-2.0-flash，新增模型作为扩展能力存在，不冲击主路稳定性。

六、后续可优化项

1. 定期刷新免费模型列表：OpenRouter 的免费模型集会变化，后续可定期用 API 重新拉取并更新。
2. 是否需要更多免费模型：当前 18 个只是 OpenRouter 342 个模型中的一部分，如需继续扩充可按同样方式筛选。
3. 是否将 2.5-pro-alpha 提升为主模型：目前仍保持 2.0-flash 为主，后续可根据实际表现评估。

七、参考来源

• Sapiens 官方文档：
  • Agnes 2.5 Flash
  • Agnes 2.5 Pro Alpha
• OpenRouter 官方文档：https://openrouter.ai/docs
• OpenRouter 免费模型 FAQ：https://openrouter.ai/docs/limits

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。