【免费下载链接】ClawRouterThe agent-native LLM router for autonomous agents. Every frontier model behind one wallet, 1ms local routing, USDC payments on Base Solana via x402.项目地址https://gitcode.com/gh_mirrors/cl/ClawRouter点击查看免费下载导读本文基于 ClawRouter 仓库中的 exclude-models 实现计划系统讲解模型排除这一用户级路由控制能力的完整设计与落地如何通过 Telegram 的/exclude命令将指定模型从智能路由的候选回退链中剔除、如何持久化到磁盘并实现热加载以及代理层在构建回退链时如何安全地应用排除过滤。读完本文你将掌握该功能的存储格式、过滤语义、命令交互与源码级实现路径并可以直接照搬到自己的 Agent 路由系统中。功能概述为什么需要排除模型ClawRouter 是一个面向自主 Agent 的 LLM 路由器会根据请求复杂度为每次调用挑选最合适的模型并维护一条多级回退链fallback chain以保证请求总能被服务。但自动路由并不总能满足所有用户的偏好——某些模型可能价格不透明、质量不稳定、不兼容特定工具调用或者用户就是不想用某个特定供应商。排除模型功能正是为此设计的用户级控制面用户在运行时通过/exclude命令把指定模型加入黑名单路由器在构建回退链时将其过滤掉并持久化到磁盘重启后依然生效。从 实现计划 的架构说明可以看到其核心设计由四部分组成持久化模块exclude-models.json文件存放于~/.openclaw/blockrun/目录过滤函数filterByExcludeList()过滤回退链与既有过滤器同一套安全模式命令入口/exclude命令通过 add / remove / clear 子命令管理列表代理接入代理在启动时加载列表并在每次请求时重新读取热加载。持久化模块exclude-models.json 的存储与读写文件位置与格式排除列表以 JSON 数组形式存储在用户主目录下~/.openclaw/blockrun/exclude-models.json默认路径由 exclude-models.ts 中的DEFAULT_FILE_PATH常量定义const DEFAULT_FILE_PATH join(homedir(), .openclaw, blockrun, exclude-models.json);写入时模型 ID 会排序后以缩进 JSON 格式落盘保证文件内容稳定、可 diff、可人工编辑。例如[ anthropic/claude-sonnet-4.6, openai/gpt-4o ]exclude-models.test.ts 中的测试验证了这一点写入两个模型后文件内容必须是排序后的数组[anthropic/claude-sonnet-4.6, openai/gpt-4o]。核心 APIload / add / remove / clear模块导出四个函数见 exclude-models.ts每个函数都接受可选的filePath参数以便测试注入临时路径函数签名行为loadExcludeList(filePath?) Setstring读取文件并返回Set文件不存在或解析失败时返回空SetaddExclusion(model, filePath?) string解析别名后加入列表并持久化返回解析后的模型 IDremoveExclusion(model, filePath?) boolean解析别名后从列表删除存在并删除返回true否则falseclearExclusions(filePath?) void清空整个列表并落盘写入空数组关键实现细节容错读取loadExcludeList使用 try/catch文件缺失、JSON 损坏都静默返回空Set不会让排除功能导致整个代理崩溃exclude-models.ts类型过滤解析数组时仅保留字符串元素typeof x string防止脏数据污染模型 ID 集合目录自动创建saveExcludeList在写入前用mkdirSync(dirname(filePath), { recursive: true })递归创建父目录对应测试 验证了深层嵌套路径也能直接写入去重底层使用Set重复添加同一模型只会保留一条记录见 测试。热加载与 mtime 缓存优化计划文档要求代理在启动时加载每次请求重新读取热加载。实际实现还额外做了一层优化由于loadExcludeList运行在代理的热请求路径上exclude-models.ts 引入了一个基于 mtime 的缓存/** mtime-validated cache — loadExcludeList runs on the proxys hot request * path, so skip the readparse when the file hasnt changed. */ const loadCache new Mapstring, { mtimeMs: number; set: Setstring }();每次加载先statSync取文件的mtimeMs与缓存比对文件未变则直接返回缓存的拷贝拷贝是为了防止调用方修改污染缓存文件变了才重新 read parse。而saveExcludeList写入后主动删除缓存条目避免同毫秒写入读取时 mtime 相同导致读到旧数据见 exclude-models.ts 注释。这样既实现了改文件即时生效的热加载语义又把磁盘 I/O 开销降到接近零——这正是计划文档所说的文件很小成本可忽略。别名解析写前统一归一到真实模型 IDaddExclusion和removeExclusion在操作列表前都会调用resolveModelAlias()将用户输入的别名解析为真实模型 ID。该函数定义在 models.ts规则包括小写化 去空白后查MODEL_ALIASES表例如claude→anthropic/claude-sonnet-4.6在计划文档的测试中是free→nvidia/gpt-oss-120b实际仓库中的别名目标随目录更新演进自动剥离blockrun/、openai/、openai-codex/等前缀OpenClaw 以openai-completionsAPI 类型发送虚拟模型时会带openai/前缀已知虚拟路由配置eco / auto / premium 等剥离前缀后保留裸 ID。别名归一化带来的实际好处用户用free、claude、nvidia这类友好名称排除与用完整模型 ID 排除的效果完全一致且文件里只存规范 ID杜绝同一模型被多个别名重复记录的隐患。测试 exclude-models.test.ts 验证了别名写入、别名删除nvidia加入、lightning删除同一模型等场景。过滤函数filterByExcludeList 与安全网语义过滤语义过滤函数的作用是把排除列表应用到候选模型数组上。按计划文档的设计并在集成测试中固化核心逻辑为export function filterByExcludeList(models: string[], excludeList: Setstring): string[] { if (excludeList.size 0) return models; const filtered models.filter((m) !excludeList.has(m)); return filtered.length 0 ? filtered : models; }三个行为要点对应 exclude-models.test.ts 单元测试场景空排除列表原样返回模型列表零开销部分排除剔除命中的模型其余模型保持原顺序顺序对回退链的优先级至关重要全部被排除时回退原列表安全网如果某条链上的模型全被用户排除filterByExcludeList会返回原始完整链而不是空数组——这与filterByToolCalling、filterByVision等既有过滤器一致确保任何情况下回退链都不会为空请求永远不会因为无模型可用而失败。在仓库中该函数实际由blockrun/router-core包提供通过 router/index.ts 这个兼容导出层转发给blockrun/clawrouter的 SDK 消费者proxy.ts 直接从该包导入filterByToolCalling、filterByVision、filterByExcludeList三个过滤器。集成测试覆盖真实路由层级exclude-models.integration.test.ts 将过滤函数与真实的回退链生成器getFallbackChain组合验证从 eco SIMPLE 链中排除nvidia/gpt-oss-120b后该模型不再出现且过滤后仍有可用模型跨 SIMPLE / MEDIUM / COMPLEX / REASONING 四个 eco 层级同时排除多个模型每个层级都正确生效排除整条链的全部模型时filtered等于原始链安全网验证在 auto 层级DEFAULT_ROUTING_CONFIG.tiers上同样生效。这套测试证明了排除逻辑不是纸上过滤而是与 ClawRouter 的 tier 分层路由简单/中等/复杂/推理真实结合在任何层级上都保持安全网语义。代理接入把排除过滤织入回退链构建流程ProxyOptions 新增配置项代理层在ProxyOptions中新增了excludeModels选项proxy.ts/** * Set of model IDs to exclude from routing. * Excluded models are filtered out of fallback chains. * Loaded from ~/.openclaw/blockrun/exclude-models.json */ excludeModels?: Setstring;请求级热加载在每次请求构建回退链时proxy.ts代理读取排除列表const excludeList options.excludeModels ?? loadExcludeList();即显式传入的excludeModels优先主要用于测试注入否则从磁盘实时加载——这就是计划文档要求的每次请求重新读取热加载。回退链过滤流水线回退链的构建在 proxy.ts 附近排除过滤被精确插入在上下文容量过滤之后、工具调用过滤之前组装完整链路由决策的selectedModel置顶其后跟随按能力排序的候选routingDecision.candidates或按 tier 生成的getFallbackChain同时把会话粘性模型sticky explicit model前置上下文容量过滤filterCandidatesByCapacity根据估算 token输入按 4 字符/token maxOutput剔除放不下上下文的模型排除过滤filterByExcludeList// Filter out user-excluded models const excludeFiltered filterByExcludeList(contextFiltered, excludeList); const excludeExcluded contextFiltered.filter((m) !excludeFiltered.includes(m)); if (excludeExcluded.length 0) { console.log( [ClawRouter] Exclude filter: excluded ${excludeExcluded.join(, )} (user preference), ); }工具调用过滤filterByToolCalling(excludeFiltered, hasTools, supportsToolCalling)——注意这里输入的是排除过滤后的excludeFiltered即过滤管线是链式串联的后续过滤器只会看到用户允许的模型proxy.ts视觉能力过滤filterByVision(toolFiltered, hasVision, supportsVision)。每一级过滤都会计算被剔除的模型并打印[ClawRouter] ...日志运维时可以直接从日志看到某个模型是因为用户偏好被排除的而不是被误认为容量或能力问题。免费模型回退也尊重排除列表回退链之外代理还维护一条免费模型兜底路径。钱包余额不足、跳过路由等场景会直接走免费模型此时排除列表同样生效pickFreeModel(excludeList)会在FREE_MODELS列表中跳过被排除的模型proxy.ts若第一遍按网关可用性过滤后全部被排除还会做第二遍未过滤走查兜底防止目录数据陈旧把免费层整个关掉——只有所有免费模型都被用户排除时才返回undefined余额不足短路场景中const freeFallback pickFreeModel(excludeList) ?? FREE_MODEL;proxy.ts保证兜底模型也不会踩中用户的排除偏好。计划文档第 3 步要求的免费模型是最后兜底除非用户明确排除它在实现中升级为对整个 FREE_MODELS 列表的逐个跳过语义更完整。/exclude 命令Telegram 侧的交互与输出命令结构与注册计划文档最初把命令内联在src/index.ts实际仓库将实现抽取为独立模块commands/exclude.tsindex.ts只负责导入并注册见 index.ts 与 index.ts 的api.registerCommand(createExcludeCommand())。命令定义为标准的 OpenClaw 插件命令export function createExcludeCommand(): OpenClawPluginCommandDefinition { return { name: exclude, description: Manage excluded models — /exclude add|remove|clear model, acceptsArgs: true, requireAuth: true, // handler: ... }; }requireAuth: true意味着该命令需要鉴权不能随意被未授权用户操控。子命令与响应文案命令解析ctx.args按空格拆分出子命令与模型参数模型名可能含空格因此用parts.slice(1).join( )还原。完整交互矩阵如下输入行为输出示例/exclude无参数展示当前排除列表列表为空时顺带给出用法提示Excluded models (2):\n • anthropic/claude-sonnet-4.6\n • openai/gpt-4o/exclude add model解析别名后加入并持久化回显解析后的 ID 与当前完整列表Excluded: openai/gpt-4o\n\nActive exclusions (1):\n • openai/gpt-4o/exclude remove model解析别名后删除不在列表中时给出提示Unblocked: openai/gpt-4o或Model xxx was not in the exclude list./exclude clear清空全部排除All model exclusions cleared.未知子命令 / 缺参数返回isError: true并打印用法Usage:\n /exclude — show list\n /exclude add model\n /exclude remove model\n /exclude clear所有列表展示都会.sort()排序并逐行•列出保证在 Telegram 多行消息中清晰可读。启动时日志回显代理启动成功后index.ts会加载一次排除列表并记录const startupExclusions loadExcludeList(); if (startupExclusions.size 0) { api.logger.info( Model exclusions active (${startupExclusions.size}): ${[...startupExclusions].join(, )}, ); }这样每次重启运维人员都能在日志中确认当前生效的排除策略避免改了文件但忘了生效的认知偏差。测试体系从 TDD 到集成验证该功能遵循严格的 TDD 流程计划文档每个 Task 都是先写失败测试 → 最小实现 → 验证通过 → 提交沉淀出三层测试单元测试exclude-models.test.ts覆盖空文件读取、增删清、去重、别名解析含跨别名删除、排序落盘、目录自动创建等 12 个场景全部使用mkdtempSync临时目录隔离不污染真实用户目录过滤函数测试验证安全网语义全部排除时返回原链与顺序保持集成测试exclude-models.integration.test.ts用真实的getFallbackChainDEFAULT_ROUTING_CONFIG覆盖 eco 四层级与 auto 层级证明排除过滤与 ClawRouter 路由层级真实协同。此外index.lifecycle.test.ts 也涉及排除相关生命周期验证确保启动加载、命令注册与代理生命周期集成无回归。手动验证与运维要点验证排除效果添加排除向 Telegram 机器人发送/exclude add nvidia/gpt-oss-120b确认回显Excluded: nvidia/gpt-oss-120b检查落盘cat ~/.openclaw/blockrun/exclude-models.json应看到排序后的 JSON 数组观察路由日志发起请求后代理日志会出现[ClawRouter] Exclude filter: excluded nvidia/gpt-oss-120b (user preference)确认过滤实际生效热加载验证直接编辑 JSON 文件添加/删除模型保持合法 JSON下一次请求即生效无需重启——因为请求路径每次都重新loadExcludeList()且 mtime 缓存只在文件未变化时命中。限制与前提排除列表是用户级配置作用于整个代理的所有请求它不改变模型目录只是从回退链候选里剔除若显式指定模型发起请求不走路由决策排除过滤不会拦截——它只作用于 fallback chain 构建proxy.ts 注释明确explicit model requests 没有回退全部模型被排除时安全网会放行原始链这是设计使然宁可尊重路由决策也不让请求无模型可用。总结排除模型功能是 ClawRouter智能路由 用户控制哲学的一个缩影~/.openclaw/blockrun/exclude-models.json负责持久化resolveModelAlias负责别名归一filterByExcludeList以全部排除即回退原链的安全网语义织入回退链过滤流水线上下文 → 排除 → 工具调用 → 视觉/exclude命令提供 add/remove/clear 三态管理免费模型兜底同样尊重排除偏好。整套实现以 TDD 驱动、三层测试护航既保证用户的我不想用某个模型诉求得到即时响应又保证任何极端情况下请求链都不会为空——这是生产级 LLM 路由器中用户偏好控制的一个可复用的参考实现。赞分享【免费下载链接】ClawRouterThe agent-native LLM router for autonomous agents. Every frontier model behind one wallet, 1ms local routing, USDC payments on Base Solana via x402.项目地址https://gitcode.com/gh_mirrors/cl/ClawRouter点击查看免费下载相关推荐OpenTofu 的 -exclude 排除资源定向Exclude Flag设计与实现解析OpenTofu 的 exclude 排除资源定向Exclude Flag设计与实现解析 exclude 是 OpenTofu 提供的一种“反向资源定向”云原生DevOps基础设施彻底掌握Type Challenges中的Exclude类型从入门到实战的联合类型排除指南彻底掌握Type Challenges中的Exclude类型从入门到实战的联合类型排除指南 你是否在使用TypeScript时遇到过需要从复杂联合类型中筛选特示例工程masscan 排除列表exclude listFAQ 深度解析为什么不能申请加入以及如何正确使用 --exclude / --excludefilemasscan 排除列表exclude listFAQ 深度解析为什么不能申请加入以及如何正确使用 exclude / excludefile 导读 本网络安全渗透测试CLI上一篇在 Kimi Code CLI 中使用 Wren AI用 /wren 技能完成语义层安装、脚手架与首次查询下一篇Data Formulator 完全入门指南微软开源的 AI 数据分析与可视化系统安装、架构与实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考