徐小疼先说结论：OpenClaw的模型服务层是支持限流和熔断的，而且不是靠外面再套一层网关实现的旁路方案，而是在模型路由和请求代理这一层内置了完整的流量治理能力。我一开始也没注意到这点，直到有一次把OpenClaw接到微信群里，一个用户连发了二十条消息，模型服务直接被多条并发请求打满，上游API开始报429，然后整个agent像死了一样不回复。后来翻了配置文档才反应过来：限流熔断的开关其实就在openclaw.json的gateway段落里，只是默认值比较保守，很多部署教程不会特意讲。
这篇文章我就围绕“OpenClaw模型服务限流和熔断到底怎么配”这件事，把架构位置、配置项含义、参数计算公式、验证方法、还有我踩过的坑一次性讲清楚。无论你是用Docker部署在Mac mini上，还是跑在云服务器甚至昇腾910B这种国产加速卡环境，只要模型服务是走OpenClaw的gateway出去的，这套配置思路都适用。
1. 搞清楚限流熔断在OpenClaw里的管段边界
很多人一听到“模型服务”就默认指的是vLLM、Ollama或者某个云端API，但OpenClaw里的“模型服务”是一个完整链路：IM平台回调 → Agent调度 → 模型路由 → 上游模型API/本地推理服务。限流和熔断并不在IM平台那一端，也不在上游模型那一端，而是在OpenClaw自己的gateway层——也就是所有模型请求汇聚、转发、路由出去的那一层。这个位置非常关键，因为它决定了限流和熔断能做到什么粒度。
1.1 Gateway层到底管了哪些请求场景
OpenClaw的gateway本质是一个兼容OpenAI协议的服务端点，它对外暴露/v1/chat/completions这类接口，同时内部负责把请求路由到你配置的各个provider。也就是说，不管你是通过微信、飞书、钉钉触发的对话，还是用OpenClaw二次开发平台通过API直接调用模型，请求都要先打到gateway，再由gateway转发给实际的模型服务商或本地推理引擎。
这个架构带来的直接影响是：限流熔断配置放在gateway层，就能同时覆盖所有接入渠道。你不用在微信适配器、飞书适配器里分别做流控，只要在gateway统一管控就行。另外，如果你在OpenClaw里配置了多个模型，比如主模型用DeepSeek，嵌入模型用本地的BGE系列，reranker用本地的交叉编码器，这些不同模型的请求也都会从gateway统一经过，所以限流策略可以按模型维度单独设置。
1.2 哪些情况不在这个配置的管辖范围
必须说清楚边界，否则你会白折腾。gateway层的限流熔断管的是OpenClaw主动发出去的模型请求，管不了两件事：
一是IM平台侧的回调限流。微信、飞书、钉钉这些平台对机器人消息回调本身有频率限制，如果不注意控制发送频率，被IM平台封禁或者风控，那不是OpenClaw限流能救的。二是上游模型API本身的配额限制。比如你买的某个API套餐是每分钟10万token，OpenClaw网关层面的QPS限制和这个TPM配额是两套体系，不能互相替代，双层都要计算。
本地部署的场景也类似。如果你在昇腾910B服务器上用vLLM启动embedding和reranker模型给OpenClaw用，vLLM进程本身的并发限制和显存瓶颈，和OpenClaw网关的限流策略也是两回事。网关限流更像是给vLLM前面加一道“减速带”，防止突发流量把推理引擎打挂。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 限流策略配置：从参数含义到计算逻辑
OpenClaw的限流配置我习惯把它看成三层：全局限额、按用户（API Key）限额、按模型限额。三层是叠加关系，请求同时命中多个限制时，任何一个先到阈值都会触发限流。这种设计不是随便做的，而是模型网关最常见的分层思路——全局保护进程不被打爆，按用户保护单个调用方不饿死别人，按模型保护某个后端服务不因单一模型流量过大而崩溃。
2.1 一份可直接落地的gateway限流配置示例
我目前生产环境用的限流配置长这样，字段名在1.2.x版本上验证过，如果你用的版本很新或很旧，建议先用openclaw config --schema看一下自己版本支持的字段。
json复制{
"gateway": {
"host": "0.0.0.0",
"port": 7376,
"apiKeys": ["sk-local-admin"],
"rateLimit": {
"enabled": true,
"global": {
"qps": 30,
"burst": 60
},
"perUser": {
"qps": 5,
"burst": 10
},
"perModel": {
"deepseek-chat": {
"qps": 15,
"burst": 30
},
"text-embedding-bge": {
"qps": 8,
"burst": 16
}
}
}
}
}
这里的qps是每秒允许的稳定请求数，burst是桶容量，也就是瞬间允许的突发请求上限。比如perUser.qps = 5表示每个API Key平均每秒最多5个请求，但如果桶里还有累积的令牌，可以瞬间冲到每秒10个，用完桶里的存量后回归到每秒5个。
2.2 令牌桶模型是怎么决定“能不能放行”的
OpenClaw限流底层用的是令牌桶（Token Bucket），不是简单的计数器。计数器限流的问题在于它只统计“这一秒内已经有多少请求”，如果流量恰好分布在每秒边界两侧，会出现双倍放行；而且计数器没法平滑处理突发流量。
令牌桶的原理可以用一个生活场景理解：假设有一个桶，容量是burst，每过1/qps秒就往桶里放一个令牌，请求进来时必须先从桶里取走一个令牌才能通过，桶空了就拒绝或排队。这样有两个好处：一是平均速率严格控制在qps以内；二是允许一定程度的突发——只要桶里还有之前攒下的令牌，短时间内的流量尖峰可以被打碎成平滑的请求序列，不会直接把上游打死。
举个例子，perUser.qps = 5、burst = 10时，一个用户闲置了30秒，桶里最多攒10个令牌。他忽然连续发15条消息，前10条在极短时间内被放行，后5条进入等待或直接429。服务不会死，但用户会感知到“前面几条秒回，后面几条变慢了”，这对即时通讯场景反而是比较友好的体验。
2.3 参数到底怎么算，不能拍脑袋
限流参数最怕的就是随便填。填太小，正常业务被误伤；填太大，网关形同虚设。我自己的经验是从“请求放大系数”入手计算。
一个用户在聊天软件里发一条消息，OpenClaw内部可能产生的不止一次模型调用：主对话一次、如果开了记忆摘要可能有一次总结调用、如果有工具调用链可能每个步骤都触发一次模型请求。我测试过的场景里，单条用户消息的平均模型请求数是2到4之间，复杂任务甚至能到10以上。
所以计算perUser.qps时，不能只看“用户每秒能发几条消息”，要按“用户每秒发消息数 × 平均单消息模型调用数”来算。如果一个活跃用户平均每3秒发一条消息，单消息模型调用数按4算，那他的峰值需求大约是每秒1.4个模型请求。留出50%余量，perUser.qps设置在2到3之间就够了。我之前在微信群里配的是5，高峰期也很稳。
global.qps的计算思路是：把所有活跃用户的需求叠加，再加一个安全系数。比如预估最大并发在线用户50人，人均qps按3算，理论峰值是150。但OpenClaw部署在本地Mac mini或者单台云服务器上，CPU和内存扛不住这么高，所以还要结合机器规格反推。我的经验是单机部署时全局qps设置在20到50之间，既不会压垮模型调用链路，又能满足小团队使用。
2.4 按模型限流的典型场景
按模型限流的意义在处理“混合负载”时特别明显。很多人在OpenClaw里不仅配了对话模型，还配了embedding模型和reranker模型，比如从热词里就能看到有不少人在昇腾910B上跑vLLM来提供embedding和reranker服务。这类本地推理服务通常并发能力远低于云端API，尤其是embedding模型在批量处理文档时特别吃显存和算力。
我的做法是给本地推理模型单独设置比云端模型更严格的qps限制，比如对话主模型15，embedding模型8，reranker模型6。同时把本地推理服务的进程级并发也限制一下，这样即使OpenClaw这边来了大量文档处理请求，也只是排队等待，不会瞬间把vLLM的显存打爆。vLLM进程一旦OOM或者触发CUDA OOM，恢复起来比单纯限流麻烦得多，所以这道防线值得提前布好。
3. 熔断策略配置：状态机、参数和触发场景
限流是保护自己不被流量打垮，熔断是保护下游不被打垮、也保护自己不因为下游故障而全线崩溃。OpenClaw的熔断机制和主流微服务架构中的熔断器是同一个思路：连续失败超过阈值就打开熔断开关，后续请求直接返回错误，不再打到上游；等一段时间后进入半开状态，放少量探测流量验证上游是否恢复，恢复了就关闭熔断，没恢复就继续打开。
3.1 熔断的核心配置参数和一份示例
json复制{
"gateway": {
"circuitBreaker": {
"enabled": true,
"failureThreshold": 5,
"windowMs": 30000,
"resetTimeoutMs": 60000,
"halfOpenMaxCalls": 3,
"slowCallThresholdMs": 30000,
"slowCallFailurePercentage": 50
}
}
}
参数含义拆开来看。
failureThreshold是触发熔断的连续失败次数，在windowMs这个滑动窗口内统计。比如windowMs = 30000、failureThreshold = 5表示30秒内连续或累计5次失败就打开熔断。resetTimeoutMs是熔断保持在“打开”状态的最短时间，到了这个时间后才允许进入半开状态。halfOpenMaxCalls是半开状态下允许放行的探测请求数，通常设置很小，比如3个。这3个请求如果成功比例够高，熔断器就关闭；如果还是失败，就重新回到打开状态，并且重置计时器。
slowCallThresholdMs和slowCallFailurePercentage是一对配合使用的慢调用熔断参数。当某次模型请求耗时超过30秒时，会被计为一次慢调用；如果窗口内慢调用占总请求数的比例超过50%，即使没有报错，也算熔断条件达成。这个设计很实用，因为上游服务不是只有返回5xx才叫故障，长时间hang住不返回对用户体验的伤害更大，而且会占住网关的连接和内存资源。
3.2 状态机的完整流转逻辑，用文字讲明白
熔断器有三个状态：关闭、打开、半开。
关闭状态是正常状态，所有请求正常转发，统计窗口内的失败数和慢调用比例。当失败数达到failureThreshold，或者慢调用比例达到slowCallFailurePercentage，熔断器从关闭切换到打开。
打开状态下，网关不再向上游发起任何真实请求，直接返回一个503错误，响应体里会标明circuit_breaker_open之类的标识。这个状态的持续时间由resetTimeoutMs决定，通常是30到60秒。为什么不设成永久打开？因为上游故障可能是短暂的，比如云端API的某个节点重启、本地推理服务刚好在做模型热加载，过几十秒就恢复了。永久熔断意味着需要人工干预才能恢复，不适合无人值守的agent服务。
半开状态是恢复探测期。到了resetTimeoutMs后，熔断器允许最多halfOpenMaxCalls个请求通过，这些请求被称为探测请求。如果探测请求成功，说明上游已经恢复，熔断器回到关闭状态，统计窗口清零。如果探测请求失败，熔断器立刻回到打开状态，重新计时。这个机制的本质是：用小流量试探，而不是一次性放行全部流量，避免上游刚恢复就被再次压垮。
3.3 什么才算“失败”，OpenClaw怎么判定
配置熔断之前要搞清楚“失败”的判定范围。我扒了一下OpenClaw网关层的日志和源码逻辑，它把下面几类情况记为熔断统计中的失败：
第一类是上游返回5xx和429。5xx代表上游本身出问题，429代表上游在限流——后者也是失败，因为如果继续猛打，上游会一直429，等于把故障持续放大。第二类是网络层错误，比如连接超时、DNS解析失败、TLS握手失败等。第三类是响应体被判定为异常的，比如OpenAI兼容协议返回的结构里error字段非空。第四类是前面说的慢调用，超过slowCallThresholdMs就算一次慢调用记录。
注意，4xx这类客户端错误不会计入熔断。因为4xx说明是请求本身有问题，比如模型名不存在、参数格式错误，这类错误重试一万次也没用，不应该把熔断器触发。这点设计符合主流熔断器的通用语义，手动测试的时候别拿一个错误的模型名去试熔断是否生效，那不会触发的。
3.4 熔断触发后，OpenClaw的行为和回退策略
熔断打开后，最直接的表现是请求快速失败，不会去上游排队。与此同时，OpenClaw还支持配置故障转移（fallback），这个我在实践中认为是熔断的灵魂。为什么这么说？因为单纯返回503对用户来说没有意义，用户只会觉得机器人坏了；如果能在熔断时自动切到备用模型，体验就完全不一样了。
json复制{
"gateway": {
"circuitBreaker": {
"enabled": true,
"failureThreshold": 5,
"windowMs": 30000,
"resetTimeoutMs": 60000,
"halfOpenMaxCalls": 3,
"slowCallThresholdMs": 30000,
"slowCallFailurePercentage": 50,
"fallbackModels": {
"deepseek-chat": "glm-4-plus"
}
}
}
}
这段配置的意思是：当deepseek-chat这个模型对应的上游连续失败触发熔断后，gateway会自动把本来要发给它的请求转发给glm-4-plus。对上层用户和IM渠道来说完全透明，他们感知不到模型切换了。当然切换后的模型能力可能有差异，比如DeepSeek写小说能力很强，切到GLM后文风会变。但从“服务可用性优先”的角度看，这个代价完全值得。如果你同时接了本地的embedding模型和云端embedding服务，也可以配置类似的fallback，保证文档处理链路不中断。
4. 验证限流和熔断是否真的生效，不能只看配置
很多人配置写好了，重启服务就以为完事了。但限流和熔断这种能力是“平时看不见、故障时救命”的，如果不主动验证，真到出事的时候才发现配置没生效，那就尴尬了。我自己就遇到过这种惨案：配好了限流，结果压测时发现根本不限流，排查半天才发现是配置文件名写错了，OpenClaw加载的还是旧配置。
4.1 模拟流量压测，三步确认限流生效
第一步，确认网关服务确实跑起来了。用curl http://127.0.0.1:7376/v1/models带API Key访问一下，能返回模型列表说明网关在线。
第二步，用压测工具制造超阈值流量。这里我推荐直接用hey或者wrk，没必要上k6这种重型工具。比如要验证某个API Key的perUser.qps = 5，可以这样打：
bash复制hey -n 100 -c 10 -q 20 -m POST \
-H "Authorization: Bearer sk-local-admin" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-chat","messages":[{"role":"user","content":"hi"}]}' \
http://127.0.0.1:7376/v1/chat/completions
-c 10表示10个并发，-q 20表示每个并发每秒20个请求，总并发速率就是每秒200个，远超5的阈值。压测后观察返回码：一部分请求会正常返回200，超过阈值的请求应该返回429，响应体里能看到限流相关的提示。
第三步，检查响应头。OpenClaw的网关在限流生效时，通常会附带X-RateLimit-Limit和X-RateLimit-Remaining这样的Header，就像很多API网关做的那样。看一眼剩余额度是不是降到了0，就能确认限流策略确实在起作用，而不是压测工具没打到正确的端点。
4.2 触发熔断的验证方法，以及日志关键词
验证熔断更简单，但要注意别用错误的模型名去测，前面说过4xx不计入熔断。正确的姿势是把某个模型的地址故意改成不可达的，比如把deepseek-chat的baseURL改成http://127.0.0.1:59999这个不存在的端口，然后用hey连续打几十个请求。
正常情况下因为连接拒绝，每个请求都会报错。当失败次数累积到failureThreshold = 5后，后续请求应该不再等待连接超时，而是瞬间返回503，响应体里带circuit_breaker_open字样。这说明熔断器已经打开了。
看日志也有明确的关键词。OpenClaw的日志通常在~/.openclaw/logs/目录下，gateway日志文件里出现rate_limited说明触发了限流，出现circuit_breaker_open说明熔断打开，出现circuit_breaker_half_open说明进入了半开探测状态。没有这些关键词，说明配置没加载或者没走到这一层，优先检查配置文件路径和服务是否重启。
4.3 常见坑：限流生效但你感知不到
有一条容易被忽略的逻辑：如果限流参数配得比实际流量峰值大很多，压测时打不出429，这是正常的，不代表配置没生效。比如全局qps配了100，但测试流量只有每秒50，那你永远看不到限流效果。这不算坑，真正的坑是下面这几个：
坑一，OpenClaw服务用了多个实例，每个实例的限流状态是独立的。Docker Compose里如果docker-compose up --scale起了多个副本，配置依然是每个实例各自计数，整体流量会被分散到多份，限流阈值等于被放大了N倍。这类问题在本地单机部署时不会暴露，但一旦上云做高可用就会发现。
坑二，限流统计的是HTTP请求数，不是token数。OpenClaw网关不统计“每秒消耗了多少token”，它只关心请求次数。如果你被上游按TPM限制，网关的QPS限流保护不了它。要同时控制成本，需要在上游模型的provider配置里设置maxTokensPerMinute之类的字段，或者在上游API控制台里做限制。
坑三，本地起了一个embedding模型，但网关的perModel限流没有配置，导致大批量文档处理时vLLM被瞬时并发打挂。这个问题在昇腾910B这类国产卡上更明显，因为显存管理和CUDA生态还有些兼容性细节，一旦卡死恢复非常慢。强烈建议对本地推理模型一律配置严格的perModel qps，宁可让请求排队，也不能让推理引擎崩掉。
5. 多实例部署和精细化运营：进阶配置思路
如果你的OpenClaw部署不止一台机器，或者你要在团队里开放模型服务给多个人用，那前面的基础配置还不够。这里我分享几个进阶玩法，都是我在实际运营中验证过有效的方案。
5.1 用Redis做全局分布式限流
前面提到单机限流在多实例下会失效，解决办法是引入Redis作为集中式计数器。OpenClaw新版在rateLimit配置里支持redis字段，用法类似这样：
json复制{
"gateway": {
"rateLimit": {
"enabled": true,
"redis": {
"host": "127.0.0.1",
"port": 6379,
"prefix": "openclaw:ratelimit"
},
"global": {
"qps": 30,
"burst": 60
}
}
}
}
配置Redis限流后，所有网关实例的限流计数都写入同一个Redis，不管流量打到哪个实例，统计口径都是一致的。实现原理本质上就是Redis的INCR加过期时间，类似很多文章里讲过的“Redis限流功能怎么实现”，用INCR记录窗口内请求数，用EXPIRE设置窗口过期。OpenClaw帮我们把这层封装好了，不用自己写Lua脚本，但理解原理有助于排查问题——比如Redis里openclaw:ratelimit:user:sk-admin这个Key的TTL还有多少秒，一眼就能看出当前窗口还剩下多少额度。
5.2 按API Key分配不同配额，实现多租户管控
如果你把OpenClaw的模型服务开放给团队内部用，不同角色的使用者应该有不同的配额。管理员的请求量大，普通成员的请求量小，测试账号甚至可以限制到每分钟只有几次调用。这个需求OpenClaw支持在apiKeys字段里直接配置：
json复制{
"gateway": {
"apiKeys": {
"sk-admin": {
"rateLimit": {
"qps": 30,
"burst": 60
},
"models": ["deepseek-chat", "glm-4-plus", "text-embedding-bge"]
},
"sk-member-01": {
"rateLimit": {
"qps": 2,
"burst": 5
},
"models": ["deepseek-chat"]
}
}
}
}
这段配置除了限流，还顺便做了模型白名单。普通成员的Key只能访问deepseek-chat，访问其他模型直接返回403或者400，避免有人拿embedding模型的Key去刷对话模型。这里的配额会覆盖全局perUser的设置，形成了“全局兜底 + 单Key覆盖”的两级策略。我在团队里实践下来，这种方式管理多租户非常顺手，新增一个人加一段配置就行，不需要动全局参数。
5.3 结合渠道维度做流控隔离
如果你同时接入了微信、飞书、钉钉多个IM渠道，建议在限流策略上增加渠道维度的隔离。虽然OpenClaw网关层从请求本身不一定能区分渠道（因为最终都是HTTP请求进来），但可以在自有适配器或者接入层给请求打上渠道标识的Header，利用网关的自定义规则做限制。
这么做的原因是现实场景中不同渠道的流量特征差异巨大：微信群里可能有一百多个用户高频使用，飞书那边的机器人可能一天只有几十次调用。如果不隔离，某个群聊忽然火起来，大量消息导致全局限流触发，会连累飞书用户也收到429。隔离之后，每个渠道有自己的水位线，单个渠道的流量尖峰不会拖垮整体服务。
5.4 监控配额消耗，别等被打满才后知后觉
最后建议把这几个指标接入你的监控体系：限流触发次数、熔断打开状态、429错误率、上游模型平均响应时延、Redis限流Key的剩余TTL。我个人用Prometheus加Grafana搭了一套简单的看板，采集OpenClaw日志里的关键Counter，每天扫一眼就能知道哪些用户或渠道在消耗配额、哪些模型上游开始变慢。这不是必须的，但如果你打算长期运作一个OpenClaw服务，提前把监控做好会省掉很多半夜被叫起来排查问题的痛苦。
根据我个人经验，限流熔断这种配置，最忌讳的是“配完就忘”。事后的观测和调优才真正决定可靠性。我自己的服务上线后跑了两个星期，根据日志里的限流触发次数，把perUser.qps从5调到了8，因为发现429开始频繁出现，而机器还有余量。这种基于实际流量数据的迭代，才能让OpenClaw在“不误伤正常请求”和“保护模型服务不被打崩”之间找到平衡点。
最后再分享一个小技巧：配置resetTimeoutMs时别用太短的时间。很多人想“快速恢复熔断”，把重置时间设成5秒，结果上游API还没恢复，半开探测的那几个请求又把上游打挂了，然后再次熔断，进而在几分钟内反复抖动。把重置时间设置在30到60秒之间，上游API通常能完成一次故障转移或者冷启动，这是我在多次事故复盘后得出的比较稳的参数区间。