\r \r

free-model-router\r

\r

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

安全与隐私声明\r

\r 本技能涉及以下敏感操作，所有行为均透明可控：\r \r | 行为 | 说明 | 用户控制 |\r |------|------|----------|\r | 外部通信 | 向 freemodel.eu.org 等服务器注册匿名 API Key、拉取 provider 列表和模型元数据 | 仅同步 provider 配置，不含任何用户对话内容 |\r | 数据上报 | 可选的匿名健康状态上报（模型延迟、可用性） | 默认关闭，可随时通过 reporting off 命令或管理面板开启/关闭 |\r | 设备指纹 | SHA256(hostname + homedir + platform + arch) 不可逆哈希 | 仅用于区分设备，无法反推原始信息 |\r | 配置修改 | 仅在 setup 时向 openclaw.json 添加 free-model-router provider | 自动备份（最多3份）+ 失败自动回滚，幂等设计 |\r | 本地代理 | 127.0.0.1:5678 仅监听本地回环 | 不暴露公网，仅接收 OpenClaw 内部请求 |\r | 推荐码 | 完全自愿的推荐试用系统 | 不参与不影响任何免费功能 |\r \r

隐私承诺：本技能不收集、不传输、不存储任何用户对话内容、提示词或模型响应数据。所有外部请求仅涉及模型配置元数据。\r \r

核心架构\r

\r

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

安装幂等性\r

\r 本技能支持幂等安装 — 多次触发 setup 不会产生副作用。\r \r 详见 references/idempotency.md\r \r 核心要点:\r

• Router 已运行则跳过,OpenClaw 已配置则跳过\r
• 重复执行时仅同步 provider 列表,不会覆盖用户手动设置的主备模型\r
• 用户手动配置的 API Key 和主模型值始终保留\r \r

配置流程触发\r

\r 安装/识别技能后,向用户展示:\r \r 选项 A:现在设置(推荐) — 回复 "现在设置"/"开始配置"\r 选项 B:延后设置 — 回复 "延后设置"/"稍后再说"\r \r 配置完成后,Router 注册两个定时任务(北京时间 UTC+8):\r

• 事件通知检查: 每天 10:00、15:00、20:00 检查一次(避免夜间打扰)\r
• 每日状态汇报: 每天 9:00 自动汇报各 provider 运行状态\r \r

注意: 如果已安装(Router 运行 + OpenClaw 已配置),setup 命令会输出当前状态摘要而非重新配置。\r \r CLI 路径: 下文所有命令中的 \x3Cskill_dir> 指技能安装目录。默认路径为 ~/.openclaw/skills/free-model-router，具体路径取决于当前 OpenClaw 变种的安装目录和技能名称（例如 ~/.kimi-openclaw/skills/free-model-router）。\r \r

命令执行约束\r

\r 禁止复合命令: OpenClaw 的 exec 工具不支持 cd ... && node ... 或 bash -c "..." 等复合命令。所有命令必须使用直接调用格式:\r \r

node \x3Cskill_dir>/scripts/free-model-cli.js \x3Ccommand>\r
```\r
\r
其中 `\x3Cskill_dir>` 的完整路径取决于当前 OpenClaw 变种的安装目录（例如 `~/.openclaw/skills/free-model-router` 或 `~/.kimi-openclaw/skills/free-model-router`）。如需切换目录,应使用 OpenClaw 的 `workingDirectory` 参数指定,而不是在命令中使用 `cd &&`。\r
\r
## 常用命令\r
\r
查看完整命令列表:\r
```bash\r
node \x3Cskill_dir>/scripts/free-model-cli.js help\r
```\r
\r
## 意图匹配\r
\r
| 用户说 | 动作 |\r
|--------|------|\r
| `/free-model-router setup`、"开始配置"、"安装免费模型路由" | Setup 流程 |\r
| `/free-model-router`、`/free-model-router status` | 运行 providers 查看状态 |\r
| `/free-model-router providers`、"有哪些免费模型provider" | 运行 providers |\r
| `/free-model-router models`、"有哪些免费模型" | 运行 models |\r
| `/free-model-router models xxx`、"xxx 有哪些模型" | 运行 models xxx |\r
| `/free-model-router providerApiKey xxx yyy` | 设置 provider API Key |\r
| `/free-model-router switchProviderPrimaryModel xxx yyy`、"换成 yyy" | 切换主模型 |\r
| `/free-model-router disableProvider xxx`、"禁用 xxx" | 禁用 provider |\r
| `/free-model-router enableProvider xxx`、"启用 xxx" | 启用 provider |\r
| `/free-model-router configureModelRole primary`、"设为主模型"、"作为主模型" | 设为 OpenClaw 主模型 |\r
| `/free-model-router configureModelRole fallback`、"设为备用模型"、"作为备用模型" | 设为 OpenClaw 备用模型 |\r
| "openclaw 挂了"、"模型不可用" | 检查 provider 状态 → 诊断 → 引导修复 |\r
\r
## 意图识别规则\r
\r
### 1. 用户主动切换模型\r
\r
用户说 "换成/切换到/换用 + 模型名" → 解析后在已配置 Provider 中查找并调用 switchProviderPrimaryModel\r
\r
**歧义处理:**\r
- 用户提供了完整模型 ID(如 `qwen/qwen3-coder:free`) → 直接切换\r
- 用户只说了模型名(如 "qwen3-coder") → 在已配置 Provider 中查找匹配:\r
  - 仅一个 Provider 有 → 自动使用该 Provider 的完整 ID\r
  - 多个 Provider 都有 → 请用户确认使用哪个 Provider\r
  - 找不到匹配 → 提示用户输入完整 ID 或先运行 models 查看\r
- 用户未指定 Provider → 先运行 models 列出各 Provider 的主模型,请用户确认\r
\r
### 2. 用户引导配置(首次)\r
\r
触发 Setup 流程逐步引导,详见 [references/setup-guide.md](references/setup-guide.md)\r
\r
### 3. 兜底机制\r
\r
openclaw 无法回复时:1) 检查 Router 状态 → 2) 检查各 provider 状态 → 3) 如有故障切换,汇报结果\r
\r
## Setup 流程\r
\r
> **核心原则:** 多 Provider 优于单 Provider。引导用户尽可能提供多个 Key。\r
\r
完整 6 步流程详见 [references/setup-guide.md](references/setup-guide.md)\r
\r
**流程概览:**\r
1. 运行 `setup` 命令 — 启动 Router + 初始化 + OpenClaw 配置\r
2. 注册定时任务 — 事件检查(北京时间 08:00~22:00 每30分钟) + 每日状态汇报(北京时间每天9:00)\r
3. 展示 Provider 列表,引导设置 API Key\r
4. [重要]主动询问用户将free-model-router设为主模型还是备用模型，否则技能将不会生效\r
5. 展示各 Provider 主备模型,可选择切换\r
6. 完成配置\r
\r
## 事件通知系统\r
\r
Router 内置事件通知系统,自动推送模型切换、故障等事件。\r
\r
详见 [references/event-system.md](references/event-system.md)\r
\r
**核心机制:**\r
- 事件状态: `pending`(待推送) → `notified`(已推送) → `read`(已读)\r
- Cron 在北京时间 08:00~22:00 期间每 30 分钟读取 `status=pending` 且 `shouldNotify=true` 的事件\r
- 推送后调用 `mark-notified` 标记,避免重复推送\r
- **无事件时保持静默**: 如果没有待推送事件,Cron 不会向用户发送任何消息\r
\r
**公告事件超链接:**\r
- 公告事件可能包含 `metadata.url` 链接\r
- 推送时使用 Markdown 格式展示: `[🔗 {action}]({url})`\r
- 详见 [event-system.md 公告格式](references/event-system.md#公告事件格式)\r
\r
## 注意事项\r
\r
1. **API Key 安全:** 仅存本地 router-config.json,不发送到外部\r
2. **模型可用性:** 免费模型随时可能下架/收费\r
3. **配置安全:** 所有修改自动备份,失败自动回滚\r
4. **配置零侵入:** OpenClaw 配置仅在 setup 和配置模型角色时修改,运行期间不再触碰\r
\r
## 📚 参考文档\r
\r
| 文档 | 内容 |\r
|------|------|\r
| [references/setup-guide.md](references/setup-guide.md) | Setup 完整 6 步流程 |\r
| [references/event-system.md](references/event-system.md) | 事件通知系统详解 |\r
| [references/idempotency.md](references/idempotency.md) | 安装幂等性说明 |\r