ZeroAPI：基于订阅与任务感知的AI模型智能路由插件设计与实践

1. 项目概述ZeroAPI一个为AI订阅服务而生的智能路由插件如果你和我一样手头订阅了不止一个AI服务——比如OpenAI的ChatGPT Plus、月之暗面的Kimi、智谱AI的GLM可能还有MiniMax或者通义千问——那你一定遇到过这个烦恼每次和AI对话都得手动切换模型或者干脆让某个默认模型“一肩挑”所有任务。写代码时GPT-5.4表现惊艳但处理一个简单的JSON格式化请求用GLM-5-Turbo可能更快、更经济。这种“一刀切”的用法不仅浪费了订阅资源也没能发挥出每个模型的专长。ZeroAPI就是为了解决这个问题而生的。它不是一个独立的AI服务而是一个运行在OpenClaw平台上的插件。你可以把它理解为一个智能的“交通调度员”安装在OpenClaw这个“网关”上。每当你的AI助手Agent准备处理一条消息时ZeroAPI会先于OpenClaw的默认决策机制介入根据消息内容、你的订阅情况以及各模型在权威基准测试中的表现动态地选择最合适的模型来处理这条消息。它的核心价值在于“平衡”与“数据驱动”。它不会盲目追求基准测试分数最高的模型而是综合考虑你的订阅套餐等级、账户使用优先级以及当前任务类型在“性能”和“成本/配额”之间找到一个可持续的优化点。最妙的是这一切决策都是基于本地的关键词分类和配置文件处理延迟极低宣称在1毫秒以内不会引入额外的LLM调用开销。2. 核心设计理念与架构拆解2.1 设计哲学从“模型中心”到“任务与订阅中心”传统的多模型使用方式要么是手动切换要么是基于简单规则如“所有代码任务都用GPT”。ZeroAPI的设计哲学则更进了一步它建立了一个三层决策框架任务识别层首先判断用户消息属于哪种任务类型如代码、研究、数学、快速任务等。这是通过一个轻量级的关键词和正则表达式分类器完成的避免了复杂的意图识别模型保证了速度。能力与订阅过滤层根据任务类型过滤掉不具备相应能力的模型例如没有视觉能力的模型无法处理图片问题再根据用户配置的订阅清单过滤掉用户未订阅或当前不可用的模型。策略选择层在剩余的候选模型中基于“基准测试前沿”算法进行选择。简单来说它会优先选择基准分数最高的模型但如果某个模型分数与最高分相差在某个可接受的“前沿”范围内且用户的订阅配置如更高等级的套餐、指定的使用意图更倾向于使用它那么这个模型就可能胜出。这种设计确保了路由决策既尊重客观性能数据又贴合用户个人的资源分配策略实现了全局优化而非局部最优。2.2 架构总览插件如何嵌入OpenClaw工作流ZeroAPI作为一个OpenClaw插件其核心是挂载在before_model_resolve这个钩子hook上。这意味着它的执行时机非常关键在OpenClaw即将为当前消息决定使用哪个模型之前ZeroAPI有机会介入并给出自己的建议。整个决策流程可以概括为以下步骤用户消息 - OpenClaw接收 - ZeroAPI插件触发 (before_model_resolve) - 任务分类 - 过滤能力订阅- 策略选择 - 返回模型覆盖建议 - OpenClaw使用建议的模型处理消息这个流程有几个关键特性非侵入性它只建议模型不改变会话历史、工作区文件等OpenClaw的核心运行时状态。OpenClaw仍然是最高权威。按需覆盖只有当当前运行时模型在ZeroAPI配置的模型池中且当前Agent没有被明确排除时插件才会尝试覆盖。这保护了那些被专门指定了某个模型的专业Agent。零运行时成本决策逻辑完全基于本地配置和缓存的基准数据不进行任何网络API调用因此延迟极低。2.3 关键概念解析订阅清单、策略模式与任务感知要理解ZeroAPI的配置需要厘清几个核心概念订阅清单 (subscription_inventory)这是ZeroAPI配置的核心。它允许你声明同一个提供商下的多个账户。例如你有一个用于工作的OpenAI Pro账户和一个用于个人的OpenAI Plus账户。通过订阅清单你可以为每个账户设置usagePriority使用优先级和intendedUse预期用途ZeroAPI在路由时会优先考虑匹配intendedUse且优先级更高的账户。这实现了精细化的资源管理和成本控制。策略模式 (routing_mode)目前主要是balanced平衡模式。这是默认且推荐的模式。它不会让基准分数略低但订阅配额更充裕的模型完全“插队”只会在其分数与领先者足够接近时才让订阅配置发挥影响力。这防止了为了节省成本而过度牺牲质量。任务感知修饰符 (routing_modifier)这是一个可选的全局设置用于微调特定任务类型的路由策略。例如coding-aware修饰符会在处理代码任务时收紧“基准测试前沿”的容忍度更坚决地保护代码能力最强的模型而speed-aware修饰符则可能放宽对快速任务的前沿要求让响应速度更快的模型有更多机会被选中。3. 从零开始安装、配置与深度调优实战3.1 环境准备与两种安装路径ZeroAPI的安装分为两个层面主机安装和频道引导。推荐绝大多数用户通过OpenClaw的聊天频道进行引导式安装这是最直观的方式。路径一通过ClawHub插件市场安装推荐给大多数用户这是最简洁的方式适合已经运行OpenClaw并可以通过Slack、Telegram等频道交互的用户。在OpenClaw的任意聊天频道中输入命令/zeroapi。如果频道只暴露通用技能命令则输入/skill zeroapi。系统会启动一个交互式的设置向导通过几个简短的问题收集你的订阅信息。回答完毕后向导会自动生成配置文件 (~/.openclaw/zeroapi-config.json) 并安装插件。安装完成后通常需要重启OpenClaw网关服务。管理化安装Managed Install会自动安排一个延迟重启让你可以先确认安装成功。路径二通过仓库源码进行管理化安装推荐给高级用户或自托管场景如果你更喜欢在服务器上直接操作或者需要更精细的控制可以使用此方法。# 克隆仓库 git clone https://github.com/dorukardahan/ZeroAPI.git cd ZeroAPI # 执行管理化安装脚本指定你的OpenClaw配置目录 npm run managed:install -- --openclaw-dir ~/.openclaw这个managed:install脚本做了几件重要的事将当前ZeroAPI仓库的快照复制到~/.openclaw/zeroapi-managed/repo。同步技能目录确保插件和技能代码一致。从管理化的仓库路径安装或更新插件。如果系统支持启用一个用户级的systemd定时器用于未来自动应用小版本更新并包含回滚机制。写入管理化状态这样即使网关需要重启聊天驱动的安装流程也能先报告成功。注意如果你的主机不支持systemctl --user例如某些Docker环境或旧的系统定时器会被跳过。你仍然可以手动运行npm run managed:update来更新。路径三终端回退安装 (first_run.ts)当插件或技能还无法通过聊天频道访问时例如全新搭建的环境可以使用仓库内的终端向导。npm run first-run这个脚本会以命令行问答的形式引导你完成提供商选择、套餐等级设置甚至配置多账户清单最后生成配置文件。它也可以作为从源码安装到管理化安装的桥梁。3.2 核心配置文件详解与个性化定制安装成功后核心配置文件位于~/.openclaw/zeroapi-config.json。理解这个文件的每个部分是进行高级调优的基础。下面是一个结合了多账户和任务感知修饰符的配置示例{ version: 1.0.0, routing_mode: balanced, routing_modifier: coding-aware, subscription_profile: { openai-codex: plus, zai: max, moonshot: vivace }, subscription_inventory: { version: 1.0.0, accounts: { openai-work: { provider: openai-codex, tierId: pro, authProfile: openai:company, usagePriority: 3, intendedUse: [research, orchestration] }, openai-personal: { provider: openai-codex, tierId: plus, authProfile: openai:personal, usagePriority: 1, intendedUse: [code, fast, default] }, zai-main: { provider: zai, tierId: max, authProfile: zai:primary, usagePriority: 2, intendedUse: [default, fast, math] } } }, external_model_policy: stay, models: { openai-codex: [gpt-5.4, gpt-5.3-codex, gpt-5.4-mini], zai: [glm-5.1, glm-5, glm-5-turbo], moonshot: [kimi-k2.6, kimi-k2.5] } }关键配置项解析routing_mode和routing_modifier定义了路由的底层策略。balancedcoding-aware是一个经典组合确保代码任务的质量优先。subscription_profile这是一个传统的全局订阅声明定义了每个提供商你拥有的套餐等级。在多账户清单存在时它的部分作用会被覆盖但作为回退参考仍有价值。subscription_inventory这是实现精细控制的灵魂。你可以为同一提供商配置多个账户并指定每个账户的用途和优先级。usagePriority是一个整数越高越优先intendedUse是一个数组当任务类别匹配时该账户会获得加分。external_model_policy默认为stay。这意味着如果当前对话正在使用一个不在你models配置池中的模型例如来自其他插件或手动指定的冷门模型ZeroAPI会保持现状不会强行将其拉回自己的管理池。设置为allow则允许覆盖。models明确声明你允许ZeroAPI为每个提供商路由到哪些具体模型。这应与你的订阅实际支持的模型列表保持一致。3.3 实战调优利用数据驱动策略迭代ZeroAPI区别于“设置即遗忘”型插件的一大特点是其内置的评估和调优循环。它记录了每一次路由决策到~/.openclaw/logs/zeroapi-routing.log。步骤一生成评估报告定期运行评估脚本分析路由日志# 分析最近500条路由决策 npm run eval -- --last 500报告会显示任务类别分布你的对话中代码、研究、快速任务等各占多少比例这有助于你了解自己的使用模式。风险覆盖率有多少比例的消息被ZeroAPI覆盖了模型过高可能意味着过度干预过低则可能意味着配置太保守。提供商多样性流量在各个模型间的分布是否健康是否过度集中在某一个模型上关键词命中率哪些关键词最常触发分类这可以用来优化或扩展keyword_classifier配置。具体调优建议脚本可能会建议你调整某个类别的“基准测试前沿”阈值或者修改某个提供商的优先级。步骤二模拟测试在对生产配置进行任何修改前强烈建议使用模拟器进行测试# 测试单个提示词的路由决策 npm run simulate -- --prompt 帮我优化一下这个Python函数的性能 # 或者使用提示词文件进行批量测试 npm run simulate -- --prompts-file my_test_prompts.txt模拟器会输出详细的决策过程任务分类、过滤后的候选模型、策略评分、以及最终选择或保持的理由。这是理解插件“思维过程”最直接的方式。步骤三应用与验证根据评估报告或模拟结果修改zeroapi-config.json中的相关参数如关键词、风险等级、TTFT阈值等。重启OpenClaw网关以使配置生效管理化安装通常提供了scripts/reload_gateway.mjs脚本用于安全重启。等待新的对话流量产生。再次运行npm run eval对比调优前后的报告验证改动是否产生了预期的积极效果。这个“测量-实验-推广”的循环灵感来源于karpathy的autoresearch项目只不过应用的对象从模型训练变成了路由策略。它让你从一个被动的配置使用者转变为主动的策略优化者。4. 高级特性与场景化应用指南4.1 多账户池化同一提供商下的智能负载分配当你为同一服务如OpenAI拥有多个订阅账户时subscription_inventory的强大之处才真正显现。它不仅仅是一个列表更是一个智能的账户池。工作原理按需匹配当一条消息被分类后ZeroAPI会先看哪些账户的intendedUse包含了当前任务类别。这些账户进入“匹配池”。层级优先在匹配池内套餐等级tierId如proplus是首要排序因素。高等级账户天然具有优势。优先级微调在同一等级内usagePriority数值更高的账户会获得轻微的优势加成用于打破平局或体现你的偏好。弹性回退如果没有任何账户的intendedUse匹配当前任务ZeroAPI会回退到该提供商下的所有账户进行选择确保不会因为用途配置过窄而导致无账户可用。会话亲和当获胜的账户指定了authProfile时ZeroAPI会尝试通过OpenClaw的会话存储机制让后续对话“粘性”地使用这个身份。这为同一提供商下的多账户切换提供了基础支持。配置心得工作与生活分离如上例所示将高优先级的pro账户用于“研究”和“编排”这类重型工作而plus账户用于日常的“代码”和“快速”任务。避免过度细分不要为每个任务类别都创建一个专属账户这会导致池子碎片化。通常2-3个账户搭配2-3个intendedUse类别就能实现很好的负载平衡。优先级设置usagePriority的差值不宜过大。通常用1、2、3这样的梯度即可过大的差值可能会让优先级信号压倒基准分数信号影响路由质量。4.2 代理级精细控制为特定AI助手定制策略你可能有一些专用的AI助手。比如一个名为“CodeReviewer”的助手你希望它永远使用最强的代码模型另一个“QuickHelper”助手你希望它只用最快的模型。ZeroAPI通过workspace_hints支持这种代理级别的覆盖。在zeroapi-config.json中你可以这样配置{ workspace_hints: { CodeReviewer: [code], QuickHelper: [fast], ResearchBot: null } }[code]这个数组意味着当CodeReviewer助手处理消息时ZeroAPI只会在“代码”这个任务类别下尝试路由。即使消息内容是“解释这个概念”因为不匹配code类别ZeroAPI会跳过路由保持助手原有的模型。[fast]同理QuickHelper只处理“快速”任务的路由。null这是一个特殊值。设置为null意味着完全禁用ZeroAPI对该助手的路由。这对于那些已经被手动指定了固定模型、不希望被任何策略干扰的专家型助手非常有用。重要提示如果某个助手已经在OpenClaw运行时被指定了非默认模型例如通过/model命令并且该助手没有在workspace_hints中列出ZeroAPI默认会跳过对其的路由以示尊重。你必须显式地在workspace_hints中列出它并赋予类别ZeroAPI才会对其生效。4.3 基准数据维护与策略家族ZeroAPI的路由决策严重依赖benchmarks.json中的数据。这个文件包含了来自Artificial Analysis等来源的、对上百个模型的基准测试分数。公共用户如何更新作为公共用户你不需要也不应该直接调用AA的API。ZeroAPI仓库的维护者通过一个私有的GitHub Actions密钥每周自动更新benchmarks.json的快照。你只需要定期拉取最新的仓库代码或者如果你使用管理化安装可以通过npm run managed:update来获取更新。什么是策略家族 (policy-families.json)benchmarks.json包含了所有可能的模型但其中一些可能是实验性的、昂贵的或难以稳定获取的。policy-families.json是一个更保守、更实用的子集它定义了ZeroAPI当前推荐并支持用于日常路由的模型家族。你的models配置应该主要从这个家族中选取。这确保了路由的稳定性和可预测性。实操建议除非你非常清楚自己在做什么否则不要随意修改benchmarks.json或policy-families.json。错误的基准分数会导致路由决策偏离最优解。信任上游维护的更新并关注更新日志了解有哪些新模型被纳入了策略家族。5. 故障排查、常见问题与避坑指南即使设计再精良的系统在实际部署中也会遇到各种问题。以下是我在长期使用和测试ZeroAPI过程中积累的一些常见问题与解决方案。5.1 路由不生效或行为不符合预期这是最常见的一类问题。请按照以下清单进行排查检查插件是否已加载在OpenClaw的日志中通常是~/.openclaw/logs/openclaw.log搜索ZeroAPI或zeroapi确认插件初始化成功并且before_model_resolve钩子已注册。检查配置文件路径与权限确认~/.openclaw/zeroapi-config.json文件存在并且OpenClaw进程有读取权限。JSON格式必须正确可以使用jq . zeroapi-config.json命令验证。查看路由决策日志这是最直接的诊断工具。tail -f ~/.openclaw/logs/zeroapi-routing.log。观察每条消息的category、risk、finalAction和reason字段。如果finalAction是stay或skip根据reason判断原因例如“model not in pool”、“agent hint mismatch”。使用模拟器验证用你遇到问题的实际提示词运行npm run simulate。对比模拟器的输出和日志中的实际决策看是否一致。不一致可能意味着配置缓存问题尝试重启网关。确认模型标识符确保配置文件中models字段里使用的模型ID与OpenClaw内部使用的ID完全一致。一个常见的错误是使用了通俗名称如“GPT-5.4”而非官方ID如“gpt-5.4”。参考policy-families.json或OpenClaw的提供商文档。5.2 性能与延迟问题ZeroAPI宣称分类延迟低于1毫秒。如果你感知到明显的延迟排除配置加载首次启动或配置变更后的第一次请求可能会读取和解析配置文件这可能有几十毫秒的延迟。后续请求应该都在内存缓存中完成。检查日志输出确保zeroapi-routing.log的日志级别不是DEBUG或TRACE。过于详细的日志写入磁盘会成为瓶颈。生产环境建议使用INFO或WARN级别。基准数据量benchmarks.json文件可能较大。虽然它被缓存但在内存受限的环境中频繁的垃圾回收可能产生影响。如果怀疑这一点可以尝试使用一个精简版的policy-families.json作为基准源进行测试这需要修改插件代码不推荐新手操作。5.3 多账户切换与会话粘性失效这是目前一个比较复杂的领域因为OpenClaw对authProfile的原生支持仍在演进。理解现状截至当前稳定版OpenClaw的before_model_resolve钩子可能只接受providerOverride和modelOverride而不接受authProfileOverride。因此ZeroAPI通过一个“会话存储回退”机制来同步身份偏好。检查会话存储ZeroAPI会在决策后尝试将获胜账户的authProfile写入当前会话的元数据中。你可以检查OpenClaw的会话存储位置取决于配置看对应的会话对象里是否有preferredAuthProfile之类的字段被更新。OpenClaw版本确保你使用的OpenClaw版本足够新以支持会话存储的相关功能。查阅ZeroAPI的references/目录下的兼容性说明。回退机制即使会话粘性暂时失效subscription_inventory的权重计算仍然有效。这意味着在同一个提供商内部路由仍然会倾向于你配置的优先级和用途只是具体使用哪个账户如果多个账户对应同一套餐等级可能由OpenClaw的默认auth.order决定变得不确定。5.4 配置更新后未生效重启网关修改zeroapi-config.json后必须重启OpenClaw网关进程才能加载新配置。管理化安装提供了scripts/reload_gateway.mjs脚本它比完全重启更温和。缓存问题插件内部对配置和基准数据有缓存。重启是清除缓存最彻底的方式。语法错误配置文件中的任何JSON语法错误都会导致整个文件加载失败插件会回退到上一次的有效配置或默认行为。务必使用jq或在线工具验证JSON格式。5.5 如何处理新提供商或新账户当你新增了一个AI订阅或在已有提供商下新增了一个账户运行时提示ZeroAPI的“运行时顾问”功能会检测到OpenClaw中新增的、但未在ZeroAPI配置中声明的支持提供商或身份。它会在~/.openclaw/zeroapi-advisories.json中记录并在下一次对话开始时在回复前添加一个简短的提示。重新运行设置此时你只需要在聊天频道中再次运行/zeroapi命令。设置向导会检测到配置“漂移”并直接从第一个相关问题开始让你快速将新资源纳入管理而不是重走整个冗长的流程。手动更新配置你也可以直接编辑zeroapi-config.json在subscription_profile和subscription_inventory中添加相应的条目然后重启网关。一个重要的避坑点不要盲目追求“全栈”配置。即不要仅仅因为ZeroAPI支持某个提供商就去订阅它。仔细评估每个提供商在你主要任务类型代码、研究等上的基准表现、成本以及API稳定性。通常2-3个优势互补的提供商组合其效果和性价比远高于5个提供商的简单堆砌。ZeroAPI的价值在于帮你用好已有的资源而不是鼓励资源浪费。