OpenClaw 免费模型智能路由 — 本地代理，自动获取多渠道最佳免费模型，自动轮询，故障切换，兜底救援，配置零侵入。 （无需修改，原文已包含中文描述） 若需重新组织句子结构以提高中文可读性，可考虑如下翻译： OpenClaw 免费模型智能路由提供本地代理服务，能够自动获取多个渠道的最佳免费模型，并支持自动轮询、故障切换和兜底救援，且配置方式对现有系统零侵入。

免费模型智能路由 — 本地代理,自动配置,自动轮询,故障切换,配置零侵入 引导注册免费模型,永久在线,实现token自由。自动同步、自动检测、自动切换、自动救援。

核心架构 OpenClaw 配置只改一次 — 仅在 setup 时写入 free-model-router provider 指向本地 Router (127.0.0.1:5678) 所有模型切换在 Router 层透明完成 — 运行期间不再触碰 openclaw.json,避免 Gateway 宕机 Round-Robin 轮询 — 默认策略在各 provider 主模型间轮询 自动故障切换 — 主模型故障自动切换到备模型,所有 provider 不可用时自动降级 事件通知系统 — 模型切换、故障等事件写入 events.json,由 cron 任务推送

安装幂等性 本技能支持幂等安装 — 多次触发 setup 不会产生副作用。 详见 references/idempotency.md 核心要点: Router 已运行则跳过,OpenClaw 已配置则跳过 重复执行时仅同步 provider 列表,不会覆盖用户手动设置的主备模型 用户手动配置的 API Key 和主模型值始终保留

配置流程触发 安装/识别技能后,向用户展示: 选项 A:现在设置(推荐) — 回复 "现在设置"/"开始配置" 选项 B:延后设置 — 回复 "延后设置"/"稍后再说" 配置完成后,Router 注册两个定时任务(北京时间 UTC+8): 事件通知检查: 每天 10:00、15:00、20:00 检查一次(避免夜间打扰) 每日状态汇报: 每天 9:00 自动汇报各 provider 运行状态 注意: 如果已安装(Router 运行 + OpenClaw 已配置),setup 命令会输出当前状态摘要而非重新配置。

CLI 路径: 下文所有命令中的 指技能安装目录。 默认路径为 ~/.openclaw/skills/free-model-router，具体路径取决于当前 OpenClaw 变种的安装目录和技能名称（例如 ~/.kimi-openclaw/skills/free-model-router）。

命令执行约束 禁止复合命令: OpenClaw 的 exec 工具不支持 cd ... && node ... 或 bash -c "..." 等复合命令。 所有命令必须使用直接调用格式: node /scripts/free-model-cli.js 其中 的完整路径取决于当前 OpenClaw 变种的安装目录（例如 ~/.openclaw/skills/free-model-router 或 ~/.kimi-openclaw/skills/free-model-router）。 如需切换目录,应使用 OpenClaw 的 workingDirectory 参数指定,而不是在命令中使用 cd &&。

常用命令 查看完整命令列表: node /scripts/free-model-cli.js help 意图匹配 用户说 动作 /free-model-router setup、"开始配置"、"安装免费模型路由" Setup 流程 /free-model-router、/free-model-router status 运行 providers 查看状态 /free-model-router providers、"有哪些免费模型provider" 运行 providers /free-model-router models、"有哪些免费模型" 运行 models /free-model-router models xxx、"xxx 有哪些模型" 运行 models xxx /free-model-router providerApiKey xxx yyy 设置 provider API Key /free-model-router switchProviderPrimaryModel xxx yyy、"换成 yyy" 切换主模型 /free-model-router disableProvider xxx、"禁用 xxx" 禁用 provider /free-model-router enableProvider xxx、"启用 xxx" 启用 provider /free-model-router configureModelRole primary、"设为主模型"、"作为主模型" 设为 OpenClaw 主模型 /free-model-router configureModelRole fallback、"设为备用模型"、"作为备用模型" 设为 OpenClaw 备用模型 "openclaw 挂了"、"模型不可用" 检查 provider 状态 → 诊断 → 引导修复

意图识别规则

• 用户主动切换模型

用户说 "换成/切换到/换用 + 模型名" → 解析后在已配置 Provider 中查找并调用 switchProviderPrimaryModel 歧义处理: 用户提供了完整模型 ID(如 qwen/qwen3-coder:free) → 直接切换 用户只说了模型名(如 "qwen3-coder") → 在已配置 Provider 中查找匹配: 仅一个 Provider 有 → 自动使用该 Provider 的完整 ID 多个 Provider 都有 → 请用户确认使用哪个 Provider 找不到匹配 → 提示用户输入完整 ID 或先运行 models 查看 用户未指定 Provider → 先运行 models 列出各 Provider 的主模型,请用户确认

• 用户引导配置(首次)

触发 Setup 流程逐步引导,详见 references/setup-guide.md

• 兜底机制

openclaw 无法回复时: 1) 检查 Router 状态 → 2) 检查各 provider 状态 → 3) 如有故障切换,汇报结果

Setup 流程 核心原则: 多 Provider 优于单 Provider。 引导用户尽可能提供多个 Key。 完整 6 步流程详见 references/setup-guide.md 流程概览: 运行 setup 命令 — 启动 Router + 初始化 + OpenClaw 配置 注册定时任务 — 事件检查(北京时间 08:00~22:00 每30分钟) + 每日状态汇报(北京时间每天9:00) 展示 Provider 列表,引导设置 API Key [重要] 主动询问用户将free-model-router设为主模型还是备用模型，否则技能将不会生效 展示各 Provider 主备模型,可选择切换 完成配置

事件通知系统 Router 内置事件通知系统,自动推送模型切换、故障等事件。 详见 references/event-system.md 核心机制: 事件状态: pending(待推送) → notified(已推送) → read(已读) Cron 在北京时间 08:00~22:00 期间每 30 分钟读取 status=pending 且 shouldNotify=true 的事件 推送后调用 mark-notified 标记,避免重复推送 无事件时保持静默: 如果没有待推送事件,Cron 不会向用户发送任何消息 公告事件超链接: 公告事件可能包含 metadata.url 链接 推送时使用 Markdown 格式展示: 🔗 {action} 详见 event-system.md 公告格式

注意事项 API Key 安全: 仅存本地 router-config.json,不发送到外部 模型可用性: 免费模型随时可能下架/收费 配置安全: 所有修改自动备份,失败自动回滚 配置零侵入: OpenClaw 配置仅在 setup 和配置模型角色时修改,运行期间不再触碰

📚 参考文档 文档 内容 references/setup-guide.md Setup 完整 6 步流程 references/event-system.md 事件通知系统详解 references/idempotency.md 安装幂等性说明