Requirements
- Target platform
- OpenClaw
- Install method
- Manual import
- Extraction
- Extract archive
- Prerequisites
- OpenClaw
- Primary doc
- SKILL.md
Tencent SkillHub · AI
Semantic Router
让 AI 代理根据对话内容自动选择最合适的模型。四层识别（系统过滤→关键词→指示词→语义相似度），三池架构（高速/智能/人文），五分支路由，全自动 Fallback 回路。
skill openclawclawhub Free
让 AI 代理根据对话内容自动选择最合适的模型。四层识别（系统过滤→关键词→指示词→语义相似度），三池架构（高速/智能/人文），五分支路由，全自动 Fallback 回路。
⬇ 0 downloads ★ 0 stars Unverified but indexed
Install for OpenClaw
Known item issue.
This item's current download entry is known to bounce back to a listing or homepage instead of returning a package file.
Quick setup
- Open the source page and confirm the package flow manually.
- Review SKILL.md if you can obtain the files.
- Treat this source as manual setup until the download is verified.
Package facts
- Download mode
- Manual review
- Package format
- ZIP package
- Source platform
- Tencent SkillHub
- What's included
- README.md, README_CN.md, README_Humanities_CN.md, README_v7.6.3_完整版.md, README_v7.9.2_设计哲学与演进史.md, SKILL.md
Validation
- Open the source listing and confirm there is a real package or setup artifact available.
- Review SKILL.md before asking your agent to continue.
- Treat this source as manual setup until the upstream download flow is fixed.
Install with your agent
Agent handoff
Use the source page and any available docs to guide the install because the item currently does not return a direct package file.
- Open the source page via Open source listing.
- If you can obtain the package, extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the source page and extracted files.
New install
I tried to install a skill package from Yavira, but the item currently does not return a direct package file. Inspect the source page and any extracted docs, then tell me what you can confirm and any manual steps still required. Then review README.md for any prerequisites, environment setup, or post-install checks.
Upgrade existing
I tried to upgrade a skill package from Yavira, but the item currently does not return a direct package file. Compare the source page and any extracted docs with my current installation, then summarize what changed and what manual follow-up I still need. Then review README.md for any prerequisites, environment setup, or post-install checks.
Trust & source
Release facts
- Source
- Tencent SkillHub
- Verification
- Indexed source record
- Version
- 7.9.6
Provenance
- Publisher
- halfmoon82
- Source page
- View original listing
- Canonical URL
- Open canonical page
Documentation
⚠️ Security & Permissions Declaration
This skill performs the following privileged operations — all are intentional and explicitly user-initiated: OperationPurposeScopeRead/patch ~/.openclaw/openclaw.jsonConfigure model routing poolsLocal config onlyRead/write ~/.openclaw/workspace/.lib/pools.jsonStore model pool configurationWorkspace onlyRead/write ~/.openclaw/workspace/.lib/tasks.jsonStore task type definitionsWorkspace onlyRun semantic_check.py locallyClassify user messages for routingNo network requiredPatch session model via sessions.patchSwitch active model poolCurrent session onlyRestart OpenClaw Gateway (openclaw gateway restart)Apply routing config changesLocal service onlyInject prependContext into agent turnsOutput routing declaration in first lineRead-only context injectionUpdate Cron Job sessionTarget to "isolated"Prevent background tasks from polluting user sessionsAffects only background Cron jobs What this skill does NOT do: Does NOT exfiltrate conversation content or model credentials to external servers Does NOT access API keys or secrets directly Does NOT modify files outside ~/.openclaw/ and the skill's own workspace Does NOT run with elevated (sudo/root) privileges Does NOT auto-install additional packages Requires: Python 3.8+, OpenClaw Gateway running, configured model providers
🔷 Semantic Router v7.9.3 — 生产级会话路由系统 🔷
ClawHub: https://clawhub.ai/halfmoon82/semantic-router 版本: 7.6.3 (生产环境) 作者: halfmoon82 状态: ✅ ROM 级固化，完全测试通过
核心问题（v7.2 新解决）
你是否遇到过： Cron Job 导致会话频繁重置 — 后台定时任务打断用户交互 Discord/Telegram 渠道会话突然清空 — 长任务无法延续 AGENTS.md 被截断注入 — 大文件超过 20KB 限制 模型自动切换被全局配置覆盖 — 切换不生效
解决方案
会话隔离架构： 用户直连渠道（稳定） ├─ 主代理会话 → semantic-router（精准路由） └─ Cron Job 隔离会话（独立环境） ├─ cloudflared-watchdog ├─ Fallback 回切检查 └─ 自定义后台任务 完整配置引导： 零冲突的智能合并配置 预检脚本防止覆盖现有设置 自动回滚失败的配置修改
为什么需要这些权限？
权限用途安全措施读取 openclaw.json检测现有模型配置只读，不修改修改 openclaw.json添加模型池配置自动备份 + 一键回滚执行本地脚本运行配置向导和验证开源脚本，可审计重启 Gateway应用新配置失败自动回滚
配置保护机制
前置备份：任何修改前自动创建带时间戳的备份 语法验证：JSON 修改后自动验证语法 健康检查：Gateway 重启后验证服务可用性 自动回滚：任何步骤失败立即恢复原配置 # 手动回滚命令 python3 ~/.openclaw/workspace/.lib/config-rollback-guard.py rollback
代码审计
所有脚本开源，位于 scripts/ 目录 核心逻辑 semantic_check.py 62KB，完全可审计 无网络请求，无数据上报，纯本地运行
第一步：安装技能
# 从 ClawHub 安装 clawhub install https://clawhub.ai/halfmoon82/semantic-router # 或手动复制到本地 cp -r ~/.openclaw/workspace/skills/semantic-router ~/my-projects/
第二步：运行配置引导
# 启动交互式配置向导 python3 ~/.openclaw/workspace/skills/semantic-router/scripts/setup_wizard.py # 向导将： # 1. 检测你的已有配置 # 2. 扫描可用模型 # 3. 推荐三池配置 # 4. 生成 pools.json 和 tasks.json
第三步：启动 Webhook 服务（重要！）
# 复制核心文件到 .lib 目录 cp ~/.openclaw/workspace/skills/semantic-router/scripts/semantic_check.py \ ~/.openclaw/workspace/.lib/ cp ~/.openclaw/workspace/skills/semantic-router/scripts/semantic-webhook-server.py \ ~/.openclaw/workspace/.lib/ # 启动 Webhook 服务（端口 9811） python3 ~/.openclaw/workspace/.lib/semantic-webhook-server.py --port 9811 & # 验证服务是否运行 curl http://127.0.0.1:9811/health # 预期输出: {"status": "ok", "version": "7.9.x"}
第四步：隔离现有 Cron Job（重要！）
# 列出你的所有 Cron Job cron list | jq '.jobs[] | {id, name, sessionKey}' # 对每个使用了渠道会话（telegram/discord/whatsapp）的 Job，执行隔离 cron update {job_id} \ --patch '{"sessionKey": null, "sessionTarget": "isolated"}' # 示例（cloudflared-watchdog） cron update ba28e228-473a-4963-8413-c228762bf2d1 \ --patch '{"sessionKey": null, "sessionTarget": "isolated"}'
第五步：验证安装
# 测试 Webhook 路由接口 curl -X POST http://127.0.0.1:9811/route \ -H "Content-Type: application/json" \ -d '{"message": "帮我写个Python爬虫", "current_pool": "Highspeed"}' # 预期输出 # { # "branch": "C", # "task": "development", # "target_pool": "Intelligence", # "primary_model": "claude-opus-4.6", # "declaration": "【语义检查 by DeepEye@halfmoon82】P1-任务切换..." # }
四池模型架构
池名用途模型示例特点Highspeed查询、检索、信息搜索gemini-2.5-flash快速、成本低Intelligence开发、编程、复杂任务claude-sonnet-4.6精准、能力强Humanities内容生成、翻译、写作gemini-2.5-pro平衡、流畅Agentic长上下文代理、Computer Use、专业知识工作gpt-5.41M上下文、工具调用、多步骤
两步判断法
Step 1: 关键词 + 指示词检测 "帮我写个爬虫" → 关键词 "写" + "爬虫" → 开发任务 → Intelligence "继续刚才的" → 指示词 "继续" → 延续当前池 → B 分支 "查一下天气" → 关键词 "查" + "天气" → 查询任务 → Highspeed "帮我整理这些材料做成PPT" → trigger_groups_all 规则命中 → 代理任务 → Agentic trigger_groups_all 非连续词组命中（v7.7 新增） 支持在 tasks.json 中定义分组规则，每条规则内所有分组取 AND，分组内词取 OR，多条规则取 OR： "trigger_groups_all": [ [["帮我","自动","用AI"], ["操作","填写","截图"]], [["处理","生成","制作"], ["报告","表格","文档","PPT"]] ] 说"帮我自动操作浏览器"→ 规则①命中 → Agentic 池。无需精确关键词，口语自然表达即可触发。 Step 2: 上下文关联度评分（当 Step 1 无结果时） 相似度 ≥ 0.15 → 延续当前会话（B 分支） 相似度 0.08~0.15 → 延续但警告（B+ 分支） 相似度 < 0.08 → 新话题，重置会话（C-auto 分支）
五分支路由决策
分支触发条件动作会话行为A关键词完全匹配直接切到目标池切换模型，不重置B指示词（延续）保持当前无动作B+中等关联度（0.08~0.15）保持 + 警告输出漂移警告C新任务关键词切到目标池切换模型，不重置C-auto低关联度（<0.08）重置 + 切池/new + 切换模型
问题：为什么配置容易冲突？
你的 OpenClaw 配置可能已经存在： 已配置的模型提供商（OpenAI、Claude、本地 LLM 等） 已配置的模型池（可能与语义路由的池名冲突） 已定义的任务类型（可能与 tasks.json 冲突） 直接覆盖会导致：❌ 原有配置丢失 ❌ 某些模型无法使用 ❌ Cron Job 执行失败
解决方案：智能合并流程
Step 1: 环境检测 # 检查现有配置 cat ~/.openclaw/openclaw.json | jq '.models | keys' # 输出: ["anthropic", "openai", "google-ai", "minimax-cn"] cat ~/.openclaw/openclaw.json | jq '.agents[0].model' # 输出: "custom-llmapi-lovbrowser-com/anthropic/claude-haiku-4.5" Step 2: 冲突预检 # 备份当前配置 cp ~/.openclaw/openclaw.json \ ~/.openclaw/backup/openclaw.json.backup-$(date +%s) # 运行预检脚本 python3 ~/.openclaw/workspace/.lib/config-rollback-guard.py check # 查看冲突报告 cat ~/.openclaw/logs/config-modification.log Step 3: 智能合并（推荐） # 选项 A: 使用自动合并脚本 python3 ~/.openclaw/workspace/.lib/merge-config.py \ --existing ~/.openclaw/openclaw.json \ --new ~/.openclaw/workspace/skills/semantic-router/config/pools.json \ --output ~/.openclaw/openclaw.json.merged \ --mode append # 仅追加，不覆盖 # 选项 B: 手动合并（更安全） # 编辑 ~/.openclaw/openclaw.json，按以下步骤： # 1. 检查 .models 字段，仅追加缺失的提供商 # 2. 检查 .agents[].model，如果已有则不修改 # 3. 检查 .env，仅追加缺失的环境变量（如 LOVBROWSER_API_KEY） Step 4: 验证 & 激活 # 验证 JSON 语法 python3 -c "import json; json.load(open('~/.openclaw/openclaw.json'))" && echo "✅ JSON 有效" # 备份原配置 cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak # 应用新配置 cp ~/.openclaw/openclaw.json.merged ~/.openclaw/openclaw.json # 重启 Gateway（失败时自动回滚） openclaw gateway restart # 如果启动失败，自动回滚 python3 ~/.openclaw/workspace/.lib/config-rollback-guard.py rollback
❌ 错误做法（会导致会话重置）
cron add \ --name "my-background-task" \ --sessionKey "agent:main:telegram:direct:123456" \ --sessionTarget "main" \ --payload '{"kind": "agentTurn", "message": "执行任务..."}' 为什么错？ sessionKey 使用了 Telegram 渠道的直连会话 任务消息可能无法匹配 tasks.json 中的关键词 semantic-router 触发 C-auto 分支 → 会话被强制重置 用户的长任务被打断 ❌
✅ 正确做法 A：隔离会话（推荐）
cron add \ --name "my-background-task" \ --sessionTarget "isolated" \ --payload '{ "kind": "agentTurn", "message": "运维任务：执行后台清理。检查磁盘空间...", "timeoutSeconds": 60 }' # 关键字段： # - sessionKey: null （让 Gateway 自动分配隔离会话） # - sessionTarget: "isolated" （完全隔离，语义路由只在这个会话内生效） 优点： ✅ 后台任务不影响用户会话 ✅ 完全隔离，无须担心关键词匹配 ✅ 自动过期清理（24h）
✅ 正确做法 B：包含显式关键词（如果需要直连会话）
cron add \ --name "my-background-task" \ --sessionKey "agent:main:cron:manual" \ --payload '{ "kind": "agentTurn", "message": "【运维检查】执行磁盘空间检查。关键词: 检查、运维、系统。" }' # 消息中必须包含 tasks.json 中的关键词 # （检查、运维、系统）→ 可以匹配到 "query" 或 "operations" 任务类型
检查隔离状态
# 验证 Cron Job 已隔离 cron list | jq '.jobs[] | select(.name == "cloudflared-watchdog") | {id, name, sessionKey, sessionTarget}' # 期望输出 # { # "id": "ba28e228-473a-4963-8413-c228762bf2d1", # "name": "cloudflared-watchdog", # "sessionKey": null, ✅ 已隔离 # "sessionTarget": "isolated" ✅ 隔离会话 # }
查看语义路由日志
# 实时监控路由决策 tail -f ~/.openclaw/logs/gateway.log | grep "semantic-router" # 查看特定消息的路由结果 cat ~/.openclaw/workspace/.lib/semantic_check.log | jq '.[] | select(.input | contains("爬虫"))'
故障排除表
症状根因解决方案"Cron Job 执行失败，超时 30s"消息文本不在 tasks.json 中，semantic-router 无法识别方案 A: 改用隔离会话 / 方案 B: 添加关键词"Discord 会话仍在被重置"sessionKey 未清空，仍使用渠道会话cron update {id} --patch '{"sessionKey": null}'"模型没有切换到目标池"全局 default_model 覆盖了切换结果改用隔离会话避免全局影响"配置修改后 Gateway 启动失败"JSON 语法错误 或 模型不可用运行 config-rollback-guard.py rollback 回滚
📋 语义检查声明格式
semantic-router 自动生成的声明格式规范：
声明示例
【语义检查 by DeepEye@halfmoon82】P2-延续｜模型池:【智能池】｜实际模型:claude-opus-4.6 【语义检查 by DeepEye@halfmoon82】P1-执行开发任务｜新会话→智能池｜实际模型:claude-opus-4.6
字段说明
字段说明PXP1=开发/自动化, P2=信息检索, P3=内容生成模型池:【XXX池】当前所属模型池中文名实际模型:当前调用的模型 ID新会话→C分支专用，表示触发 session reset 完整规范见：references/declaration-format.md
M1 机制更新（FIX-0 第一轮）
原实现：prependContext 包含声明字符串（declarationPrepend），用于让 LLM 在回复首行输出声明。 问题根因：声明字符串含 ctx_score（每消息均不同的浮点相似度）等易变字段，导致： 每条用户消息前缀不同 → LLM provider 前缀缓存（prefix cache）每轮全部 miss 20 轮对话的历史 input tokens 每轮都重新计费 新实现： declarationPrepend 从 prependContext 数组中移除（声明改由 semantic_check.log 记录） extractDeclKey → extractSkillKey：缓存键只关心 skill/retry/degrade 激活状态 普通消息（无技能激活）prependContext = undefined → 用户消息完全干净 → 对话历史 100% cache 命中 技能激活时：prependContext = skillPrepend（技能指令相对稳定）→ 高缓存命中率 节省估算：单活跃会话每日约节省 6-10M tokens（对话历史从 input 变为 cache_read，约 1/10 价格）
Option C 路由标签（FIX-0 第二轮，2026-03-06 续）
背景：用户需要在 Discord/Telegram 回复中看到语义路由声明（当前使用的模型池+模型）。 由于 OpenClaw 主网关的 message_sending hook 从未被触发（架构限制：deliver-DCtqEVTU.js 的 globalHookRunner 在主网关上下文中从不初始化），无法在发送前修改消息内容。 选择 Option C：通过 prependContext 注入路由标签指令，由 LLM 自行在首行输出。 新增函数：extractStableRoutingParts(declarationText, fallbackModel) 从 declarationText 提取：pool、model、sessionType sessionType: "延续" | "新对话" — 通过解析 P\d+-XXX 分支标签判断：延续 → 延续，其他 → 新对话 路由标签格式： 【语义检查·路由】高速池｜gemini-2.5-flash｜延续 【语义检查·路由】智能池｜claude-sonnet-4.6｜新对话 注入逻辑（before_agent_start）： const isChannelSession = isMainAgentSession && !sessionKey.includes(":cron:") && !sessionKey.includes(":subagent:"); // subagent 不注入 const routingInstruction = routingTag ? `请在你回复的第一行，原样输出以下路由标签（不要修改）：${routingTag}` : undefined; // M1 stability: combinedKey = skillKey + routingTagKey // routingTagKey = "rt:{pool}:{model}:{sessionType}" // 相同池+模型+会话类型 → 相同 prependContext → LLM prefix cache 命中 缓存稳定性分析： 场景routingTagKey结果连续对话（同池同模型）rt:高速池:gemini-2.5-flash:延续 不变M1 命中，cache hit ✅首条新话题消息rt:xxx:yyy:新对话cache miss（pool 切换本来就 miss）✅Gateway 重启后首条任意 keycache miss（M1 state 清空），第二条起命中 ✅ subagent 排除：isChannelSession 新增 !sessionKey.includes(":subagent:") 条件。 原因：subagent session 如 agent:main:subagent:xxx 满足 startsWith("agent:main:")，若不排除会注入两份 routingInstruction，导致 Discord 回复中路由标签重复出现。
FIX-4（lockModel 毒化修复）
modelOverride/providerOverride 已从 before_agent_start 返回值中移除。路由仅通过 sessions.patch 实现。原 lockModel 时返回 override 会毒化所有 fallback（kimi-coding/zai/minimax 等非 lovbrowser 渠道），导致 All models failed。
📚 完整文档
文档内容位置SKILL.md技能说明（本文件）/skills/semantic-router/README_v3_PRODUCTION.md完整部署指南（英文）/skills/semantic-router/README_v7.2_生产部署指南_中文.docx完整部署指南（中文 DOCX）/skills/semantic-router/declaration-format.md声明格式规范（已内置）/skills/semantic-router/references/完整架构指南五分支、评分算法、Fallback 回路docs/INTELLIGENT_ROUTING_SYSTEM.md部署清单7 步完整部署流程docs/ROUTING_DEPLOYMENT_CHECKLIST.md
💡 常见问题
Q: 我应该选择哪种隔离方案？ A: 99% 的情况下，选择方案 A（隔离会话）。只有在特殊需求下（需要在用户可见的会话中执行）才选方案 B。 Q: 隔离会话会占用额外资源吗？ A: 不会。隔离会话是临时的，自动过期（24h），不会额外占用内存。 Q: 如何自定义三池模型？ A: 编辑 ~/.openclaw/workspace/.lib/pools.json，或运行 setup_wizard.py 交互式配置。 Q: 我的原有配置会被覆盖吗？ A: 不会。使用智能合并流程（Step 3），仅追加缺失配置，保留原有设置。
🎓 学习路径
快速体验（5 分钟） 运行 setup_wizard.py 隔离现有 Cron Job 测试语义检查 深入理解（30 分钟） 阅读本文档 自定义 tasks.json 关键词 配置三池模型 生产部署（1 小时） 完整配置指南 智能合并配置 故障排除与监控
📊 版本对比
特性v7.0v7.1v7.2关键词匹配✅✅✅上下文评分✅✅✅三池架构✅✅✅会话隔离规则❌❌✅ 新增无冲突配置❌❌✅ 新增完整故障排除❌❌✅ 新增
📝 许可与支持
许可证: MIT ClawHub: https://clawhub.ai/halfmoon82/semantic-router 反馈: 在 ClawHub 提交 issue 或改进建议 最后更新: 2026-03-06 GMT+8 维护者: halfmoon82 稳定性: ⭐⭐⭐⭐⭐ (生产级)
⚖️ 知识产权与归属声明 (Intellectual Property & Attribution)
Powered by halfmoon82 🔷 本技能（Semantic Router）由 halfmoon82 开发并维护。 版权所有: © 2026 halfmoon82. All rights reserved. 官方发布: ClawHub 许可证: 本技能采用 MIT 许可证。您可以自由使用、修改和分发，但必须保留原始作者信息及此版权声明。 贡献与支持: 欢迎通过 ClawHub 提交 Issue 或参与讨论。
Category context
Agent frameworks, memory systems, reasoning layers, and model-native orchestration.
Source: Tencent SkillHub
Largest current source with strong distribution and engagement signals.
Package contents
Included in package
6 Docs
- SKILL.md
- README_CN.md
- README_Humanities_CN.md
- README_v7.6.3_完整版.md
- README_v7.9.2_设计哲学与演进史.md
- README.md