1. 项目概述BurnOver 智能配额代理如果你正在使用 OpenClaw 这类 AI 智能体框架并且订阅了像 Synthetic.new 这样提供固定请求次数套餐的服务商那你大概率遇到过这个令人头疼的场景你的智能体在某个关键时刻突然“卡死”或报出莫名其妙的“计费错误”而你明明刚续费不久。更让人恼火的是你事后查看用量报告发现很大一部分宝贵的请求配额竟然被那些你根本不在电脑前时发生的“心跳检测”请求给白白消耗掉了。这种资源浪费和体验割裂正是 BurnOver 这个项目要解决的核心痛点。BurnOver 是一个轻量级、零依赖的智能配额代理。它像一个聪明的交通警察坐在你的 AI 智能体如 OpenClaw和上游的 LLM 服务提供商如 Synthetic.new之间。它的核心工作有两项第一精准识别并拦截那些低价值的“心跳”请求将它们悄无声息地重定向到 Grok 这类按量付费的廉价模型上从而为你昂贵的固定套餐配额“节流”第二实时追踪你的套餐使用量在你即将触达服务商硬性限制之前主动返回一个清晰的429 Too Many Requests状态码从而优雅地触发你智能体中预设的模型降级策略而不是让整个流程因一个粗暴的错误而中断。简单来说它让你的固定配额套餐用得更久、更值同时让你的 AI 应用在面对配额限制时行为更可控、更优雅。无论你是个人开发者还是小团队只要你在用 OpenClaw 并管理着多个模型的配额BurnOver 都能帮你把成本控制和稳定性提升一个档次。2. 核心问题与解决方案拆解2.1 问题一隐蔽的配额杀手——后台心跳很多 AI 智能体框架包括 OpenClaw为了维持会话的活跃性和检查服务可用性会定期发送“心跳”请求。这些请求内容固定比如只是询问“一切正常吗”频率可能高达每30分钟一次。关键在于在 OpenClaw 的默认配置或某些版本中这些心跳请求会直接使用你为智能体配置的“主模型”也就是你套餐里最贵的那个。想象一下你订阅了一个每月135次请求的套餐。即便你一整天没有主动使用智能体后台的心跳也可能默默消耗掉20-40次请求。这相当于你什么都没做就白白损失了相当一部分付费资源。更糟糕的是OpenClaw 官方提供了一个heartbeat.model配置项本意是让你为心跳指定一个廉价模型但这个功能在多个版本中存在已知的 Bug导致配置失效心跳依然会“偷用”主模型配额。注意这个问题在开源社区 Issue 中已被多次报告但修复周期可能较长。与其等待框架更新不如在架构层面代理层一劳永逸地解决它。2.2 问题二生硬的配额墙与混乱的错误处理像 Synthetic.new 这类服务商通常会设置一个硬性的请求次数上限例如每5小时135次。当你触达这个上限时服务商 API 通常会返回一个错误。但这个错误信息可能是模糊的如“内部服务器错误”或“认证失败”而不是一个明确的“配额耗尽”提示。对于 OpenClaw 这样的智能体它无法从这种模糊错误中准确判断出是配额问题因此可能不会按照你预设的“降级链”去切换到备用模型如 Grok。结果就是智能体直接“挂起”或崩溃用户体验非常糟糕。我们需要的是一个清晰的、可编程的信号来告诉智能体“主路堵了请走备用路线。”2.3 BurnOver 的解决思路代理层智能管控BurnOver 的聪明之处在于它不尝试去修改 OpenClaw 的内部逻辑那会带来兼容性噩梦而是在网络请求的必经之路上设卡检查。所有从 OpenClaw 发往特定服务商如 Synthetic.new的请求都会先经过 BurnOver 代理服务器。对于心跳请求BurnOver 会扫描请求体中的消息内容与预设的心跳关键词模式如 “HEARTBEAT_OK”进行匹配。一旦命中它不会将请求转发给昂贵的 Synthetic.new而是立即、透明地将其重定向到配置好的廉价提供商如 Grok 的 API并将 Grok 的回复原样返回给 OpenClaw。OpenClaw 对此过程毫无感知它只是收到了一个“正常”的心跳回复但你的主套餐配额一次都没被消耗。对于普通请求BurnOver 会维护一个内部计数器或者通过服务商的配额查询接口如果支持来获取实时用量。当用量低于你设定的安全阈值例如套餐上限的90%时请求被正常放行至主服务商。当用量达到或超过阈值时BurnOver 会直接拦截请求并向 OpenClaw 返回一个标准的 HTTP 429 状态码Too Many Requests。OpenClaw 收到这个明确的状态码后就会按照你在其配置中定义的fallbacks列表自动切换到下一个可用的模型比如 Grok。整个过程平滑、自动用户无感。这种架构将配额管理和路由逻辑从应用业务代码中剥离出来使得系统更健壮也更容易维护和扩展。3. 部署与配置详解3.1 环境准备与快速启动BurnOver 基于 Node.js 开发因此你需要一个基本的 Node.js 运行环境建议版本 16。部署过程非常直接。# 1. 克隆项目代码 git clone https://github.com/mina-ai-io/burnover.git cd burnover # 2. 复制并编辑配置文件 cp config.example.json config.json # 使用你喜欢的编辑器如 nano 或 vim编辑 config.json nano config.json # 3. 设置必要的环境变量如 Grok 的 API Key export XAI_API_KEYyour-grok-api-key-here # 建议将环境变量写入 ~/.bashrc 或 ~/.profile 以便永久生效 # 4. 启动 BurnOver 服务 node index.js如果一切正常你将在终端看到服务启动日志默认监听在http://localhost:55001。接下来你只需要修改 OpenClaw 的配置将其指向 BurnOver 的地址而不是原先的 Synthetic.new 地址。3.2 核心配置文件解析config.json是 BurnOver 的大脑其结构清晰主要分为两大块providers主服务商配置和cheapRoute智能路由/廉价路由配置。下面我们逐项拆解。Providers 配置块这个数组定义了 BurnOver 需要代理和监控的“主”服务商。通常你至少需要配置一个。{ port: 55001, logLevel: info, providers: [ { name: synthetic, // 标识符用于日志和状态接口 upstream: https://api.synthetic.new, // 真实服务商API地址 maxRequests: 135, // 服务商规定的硬性限额每窗口期 windowSeconds: 18000, // 限额窗口时长单位秒5小时18000秒 thresholdPct: 90, // 安全阈值百分比。用量达到此值即触发拦截 quotaEndpoint: /v2/quotas, // 可选服务商提供的配额查询API路径 syncEvery: 10, // 可选每处理N个请求同步一次真实配额数据 urgencyPct: 90, // 可选紧急区域阈值。用量超过此值后每个请求都同步配额 paths: [/v1/, /anthropic/, /openai/] // 可选匹配的请求路径前缀 } ], cheapRoute: { ... } // 智能路由配置见下文 }关键参数深度解读maxRequestswindowSeconds: 这两个参数定义了配额窗口。例如(135, 18000)表示“每5小时最多135次请求”。BurnOver 主要依靠这两个参数进行内部计数。即使服务商不提供配额查询接口仅靠内部计数也能工作这是其健壮性的体现。thresholdPct: 这是核心控制阀。设置为90意味着当内部计数达到135 * 90% 121次时BurnOver 就会开始返回429状态码。建议永远不要设为100。留出10%的缓冲空间可以防止因网络延迟或计数微小误差导致请求被服务商直接拒绝从而保障降级流程的稳定触发。quotaEndpoint: 这是“增强模式”。如果服务商提供了查询剩余配额的免费API如 Synthetic.new 的/v2/quotas填写此项后BurnOver 会定期调用该接口用真实数据校准内部计数器实现更精准的控制。syncEveryurgencyPct: 这对参数用于优化配额同步频率。在用量安全时低于urgencyPct每10个请求同步一次避免对服务商API造成不必要的压力。当用量进入“紧急区域”超过90%则每个请求前都同步一次确保决策的实时性和准确性防止在最后关头超限。CheapRoute 配置块这个配置块定义了如何识别并重定向低价值请求主要是心跳。{ cheapRoute: { upstream: https://api.x.ai, // 廉价模型服务商地址 apiKey: ${XAI_API_KEY}, // 支持从环境变量读取 model: grok-4-fast, // 指定重定向后使用的模型 patterns: [ // 用于匹配消息内容的关键词列表 HEARTBEAT_OK, HEARTBEAT.md, Read HEARTBEAT.md, If nothing needs attention, 一切正常, // 你可以根据智能体语言添加自定义模式 status check ] } }patterns: 这是一个字符串数组。BurnOver 会检查每个请求中是否包含这些字符串。匹配逻辑是“包含”而非“全等”所以设置时要注意避免误伤正常对话。例如如果正常对话中也可能出现“一切正常”这个词就可能被误判为心跳。建议初期使用项目默认的、OpenClaw 心跳特有的模式稳定后再根据日志观察补充。实操心得配置完成后先不要连接生产环境。启动 BurnOver 和 OpenClaw 测试客户端发送几个测试请求同时观察 BurnOver 的日志输出。你会清晰地看到每个请求是被“转发”、“重定向”还是“拦截”这能帮你快速验证配置是否正确特别是patterns是否匹配成功。3.3 与 OpenClaw 的集成配置这是最后一步也是让整个系统运转起来的关键。你需要修改 OpenClaw 的配置文件通常是config.json或claude_desktop_config.json将主模型的baseUrl指向 BurnOver。// OpenClaw 配置片段 { models: { mode: merge, providers: { synthetic: { baseUrl: http://localhost:55001/openai, // 关键修改指向BurnOver apiKey: ${SYNTHETIC_API_KEY}, api: openai-completions, models: [ { id: hf:moonshotai/Kimi-K2.5, name: Kimi K2.5 } ] }, xai: { baseUrl: https://api.x.ai/v1, // Grok 作为降级模型直接连接 apiKey: ${XAI_API_KEY}, api: openai, models: [ { id: grok-4-fast, name: Grok 4 Fast } ] } } }, agents: { defaults: { model: { primary: synthetic/hf:moonshotai/Kimi-K2.5, // 主模型 fallbacks: [ xai/grok-4-fast ] // 降级模型链 } } } }请注意这里的细节baseUrl被设置为http://localhost:55001/openai。BurnOver 在接收到路径为/openai的请求时会根据配置中的paths字段进行匹配我们之前配置了/openai/匹配成功后它会将请求代理到upstream(即https://api.synthetic.new) 的对应路径上。同时你完全不需要也不应该在 OpenClaw 中再配置任何关于心跳模型覆写的参数因为心跳拦截已经在 BurnOver 层完成了。4. 高级部署与管理4.1 使用 systemd 托管服务对于 Linux 服务器使用 systemd 将 BurnOver 作为后台服务运行是最可靠的方式。这能保证服务在系统重启后自动运行并且方便查看日志和管理。# 1. 创建 systemd 服务单元文件 # 请将以下命令中的 /home/$USER/services/burnover 替换为你的 BurnOver 实际安装路径 # 将 $USER 替换为你的实际用户名 sudo tee /etc/systemd/system/burnover.service /dev/null EOF [Unit] DescriptionBurnOver Smart Quota Proxy Afternetwork.target StartLimitIntervalSec0 [Service] Typesimple Useryour_username # 改为你的用户名 WorkingDirectory/path/to/your/burnover # 改为 BurnOver 项目目录 ExecStart/usr/bin/node /path/to/your/burnover/index.js Restartalways # 任何原因退出都重启 RestartSec5 # 指定配置文件路径优先级高于项目目录下的 config.json EnvironmentBURNOVER_CONFIG/path/to/your/burnover/config.json # 加载包含 API KEY 等敏感信息的环境变量文件 EnvironmentFile/path/to/your/burnover/.env [Install] WantedBymulti-user.target EOF # 2. 创建 .env 文件如果使用 EnvironmentFile # 在 BurnOver 项目目录下创建 .env 文件内容如下 # XAI_API_KEYyour_grok_key_here # SYNTHETIC_API_KEYyour_synthetic_key_here # 3. 重新加载 systemd 配置 sudo systemctl daemon-reload # 4. 启用并启动服务 sudo systemctl enable --now burnover.service # 5. 检查服务状态和日志 sudo systemctl status burnover.service sudo journalctl -u burnover.service -f # 实时查看日志关键点说明Restartalways和RestartSec5确保了服务的高可用性即使意外崩溃也会在5秒后重启。EnvironmentFile是一种安全且方便的管理敏感信息如 API Key的方式避免将其硬编码在配置文件中。使用journalctl查看日志是排查问题的主要手段。4.2 使用 Docker 容器化部署如果你更熟悉 DockerBurnOver 也提供了完整的容器化支持能进一步简化环境依赖和部署流程。使用 Docker Compose推荐项目根目录下的docker-compose.yml文件已经配置好。# 1. 确保在项目根目录编辑 docker-compose.yml 或通过环境变量传参 # 通常需要检查 volumes 挂载和 environment 部分 # 2. 构建并启动容器 docker compose up -d # 3. 查看容器日志 docker compose logs -f burnover直接使用 Docker 命令# 1. 构建镜像 docker build -t burnover . # 2. 运行容器 docker run -d \ --name burnover-proxy \ -p 55001:55001 \ # 将宿主机的55001端口映射到容器 -e XAI_API_KEYyour_grok_key \ -e SYNTHETIC_API_KEYyour_synthetic_key \ -v $(pwd)/config.json:/app/config.json:ro \ # 挂载配置文件只读 burnoverDocker 部署的优势环境隔离无需在宿主机安装 Node.js避免环境冲突。一键部署配置文件和应用打包在一起迁移和复制极其方便。版本管理可以为不同版本的 BurnOver 打上不同的镜像标签轻松回滚。4.3 监控与状态查询BurnOver 提供了内置的 HTTP 端点方便你监控其运行状态和配额使用情况。主要监控端点GET /_burnover/status: 这是最重要的端点返回所有已配置 provider 的实时状态。curl http://localhost:55001/_burnover/status | jq . # 使用 jq 美化输出返回的 JSON 包含了用量 (used)、有效限制 (effectiveLimit)、剩余请求数 (remainingBeforeGate)、重置时间 (renewsAt)、以及智能路由的统计信息 (totalRerouted)。通过inUrgencyZone字段可以快速判断是否进入高警戒状态。GET /_burnover/health: 简易健康检查通常用于负载均衡器或监控系统探活。POST /_burnover/reset:谨慎使用。此端点会重置所有 provider 的内部计数器和缓存的配额数据。仅在测试或者你确认服务商配额已重置如新周期开始且 BurnOver 计数不同步时使用。集成到监控系统你可以编写一个简单的 cron 任务或使用 Prometheus、Datadog 等监控工具定期调用/_burnover/status接口将关键指标如used、remainingBeforeGate提取出来并设置告警。例如当remainingBeforeGate低于 10 时发送邮件或 Slack 通知提醒配额即将用尽。5. 测试策略与故障排查5.1 完整的测试流程在将 BurnOver 接入生产环境的 OpenClaw 之前必须进行完整的测试。以下是推荐的测试步骤阶段一独立测试 BurnOver# 1. 确保 config.json 中配置了正确的 API Key 和测试用的 patterns # 2. 启动 BurnOver node index.js # 3. 使用 curl 模拟不同类型的请求 # 模拟一个普通请求 curl -X POST http://localhost:55001/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer test-key \ -d {messages:[{role:user,content:Hello, world!}], model:gpt-3.5-turbo} # 模拟一个心跳请求内容包含配置的 pattern curl -X POST http://localhost:55001/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer test-key \ -d {messages:[{role:user,content:HEARTBEAT_OK}], model:gpt-3.5-turbo} # 4. 观察 BurnOver 服务端日志 # 你应该能看到类似这样的输出 # [INFO] Request to /v1/chat/completions forwarded to upstream. # [INFO] Heartbeat detected. Rerouting to cheap provider.这个阶段的目标是验证 BurnOver 本身的路由逻辑转发、重定向、拦截是否按预期工作。阶段二与 OpenClaw 集成测试修改 OpenClaw 配置指向本地的 BurnOver。在 OpenClaw 的 Web UI 或通过其 API 发起几次简单的对话。同时打开 BurnOver 的日志和 OpenClaw 的日志或界面观察请求流。重点测试配额拦截你可以临时将config.json中某个 provider 的maxRequests设为一个很小的值如 2thresholdPct设为 50。快速发送3个请求观察第3个请求是否被 BurnOver 拦截并返回429以及 OpenClaw 是否自动切换到了 fallback 模型。阶段三运行项目单元测试BurnOver 项目自带测试套件使用 mock 服务器模拟上游 API不会消耗真实配额。npm test # 或 node test.js确保所有测试用例通过这是代码质量的基本保障。5.2 常见问题与排查指南即使准备充分在实际运行中也可能遇到问题。下面是一个快速排查清单问题现象可能原因排查步骤OpenClaw 连接 BurnOver 超时或失败1. BurnOver 服务未启动。2. 防火墙/端口被阻止。3. OpenClaw 配置的baseUrl错误。1. 检查sudo systemctl status burnover或docker ps。2. 在服务器上运行curl http://localhost:55001/_burnover/health。3. 从 OpenClaw 所在机器运行telnet burnover-host-ip 55001。4. 仔细核对 OpenClaw 配置中的baseUrl主机名和端口。心跳请求未被重定向仍然消耗主配额1.cheapRoute.patterns配置错误未能匹配 OpenClaw 实际发送的心跳内容。2.cheapRoute配置块被注释或未生效。3. 请求路径未被providers.paths匹配。1.查看 BurnOver 日志这是最直接的证据。确认请求是否被识别为心跳。2. 检查 OpenClaw 发送的实际请求体内容可能需要开启 OpenClaw 的调试日志确保patterns中的字符串能匹配上。3. 确认config.json中cheapRoute部分格式正确且apiKey对应的环境变量已设置。达到阈值后未返回429请求仍发往主服务商并失败1.thresholdPct计算有误或设置过高如100。2. 内部计数器未正确递增。3. 配置了quotaEndpoint但同步失败导致计数器不准。1. 调用/_burnover/status查看used、effectiveLimit和remainingBeforeGate的值。2. 检查日志看请求是被forwarded还是blocked。3. 如果使用了quotaEndpoint检查网络连通性和 API 响应格式。可以临时注释掉它回退到纯内部计数模式测试。BurnOver 日志显示大量错误或崩溃1. 上游 API 不可用或返回异常。2. 配置文件语法错误如 JSON 格式不对。3. 环境变量未设置。1. 查看具体的错误堆栈信息。2. 使用jsonlint等工具验证config.json格式。3. 检查启动时环境变量是否成功加载查看日志开头部分。4. 尝试简化配置只保留最基本的一个 provider 进行测试。Docker 容器启动后立即退出1. 配置文件挂载失败或路径错误。2. 容器内应用启动出错如缺少模块。3. 端口已被占用。1. 运行docker logs burnover-proxy --tail 50查看退出前的日志。2. 检查docker run命令中的-v挂载路径是否正确。3. 检查宿主机 55001 端口是否已被其他进程占用sudo lsof -i :55001。一个关键的调试技巧在config.json中将logLevel设置为debug。这会输出每个请求的详细内容、匹配过程和决策逻辑对于排查路由问题至关重要。生产环境稳定后可改回info以减少日志量。6. 架构思考与进阶应用6.1 为什么是代理层解决方案在项目文档中作者已经清晰地对比了其他方案如 TokPinch、LiteLLM的局限性它们大多基于消费金额进行预算控制无法应对“固定次数套餐”这种场景。而直接修改 OpenClaw 的心跳逻辑则受限于其框架本身的 Bug 和版本碎片化。代理层方案的优势在于“关注点分离”和“非侵入性”。对上游透明Synthetic.new 等提供商接收到的请求其来源 IP、请求头等信息都经过了 BurnOver 的转发但内容本身除了被重定向的心跳是原样的符合服务商的使用规范。对下游透明OpenClaw 认为自己一直在和 Synthetic.new 对话完全不知道中间有个“智能调度员”。这最大程度地保证了与现有智能体生态的兼容性无需修改业务代码。职责单一BurnOver 只负责配额管理和路由决策逻辑清晰易于维护和扩展。6.2 扩展可能性多级路由与自定义规则BurnOver 目前的智能路由基于简单的关键词匹配这已经能解决大部分心跳问题。但我们可以设想更复杂的场景基于请求内容的深度路由不仅仅是心跳对于一些简单的、归纳性的任务例如“总结以下文章大意”是否也可以路由到中等成本的模型如 Claude Haiku而将复杂的推理、创作任务留给顶级模型这需要更复杂的 NLP 规则或轻量级分类模型。基于响应时间的降级如果主模型响应缓慢可以自动将后续相似请求降级到更快可能精度稍低的模型保障整体响应速度。多 Provider 负载均衡与灾备如果你订阅了多个提供商的套餐BurnOver 可以扩展为一个负载均衡器根据各 provider 的剩余配额、当前延迟、成本等因素智能分配请求。这些都可以在现有的代理架构上通过增加新的配置模块和路由逻辑来实现。项目的 Roadmap 中也提到了自定义正则规则、按消息长度阈值路由等方向社区可以在此基础上共同构建。6.3 在生产环境中的稳定性考量将 BurnOver 用于生产环境还需要考虑以下几点高可用如果 BurnOver 本身宕机会导致所有依赖它的智能体服务不可用。可以考虑的方案是1) 将 BurnOver 部署在 Kubernetes 中配置多副本和健康检查2) 在 OpenClaw 配置中将 BurnOver 的地址设为一个负载均衡器如 Nginx的地址由负载均衡器在后端多个 BurnOver 实例间分发请求并提供故障转移。状态持久化目前 BurnOver 的计数器存储在内存中重启后清零。这对于按固定时间窗口如5小时重置的配额来说重启可能导致短期内的计数不准。Roadmap 中提到的“持久化计数器存储”功能将解决这个问题可以将计数存入 Redis 或 SQLite 数据库。性能作为代理BurnOver 会增加微小的网络延迟通常 1ms。对于绝大多数 AI 应用来说这个开销可以忽略不计。但在超高并发场景下需要监控其资源使用情况CPU/内存。从我个人的部署经验来看对于中小规模的 AI 应用将 BurnOver 部署在一台独立的、低配的云服务器上并以 systemd 或 Docker 方式守护运行已经能提供非常可靠的服务。它的价值在于以极低的复杂度和运维成本解决了固定配额管理和无效消耗这两个实实在在的痛点让开发者能更专注于智能体本身的业务逻辑。