WorkBuddy应对API限流需五步：一、启用令牌桶限流；二、配置多层级滑动窗口策略；三、部署Nginx缓存代理；四、启用动态错误码感知降频；五、实施API密钥轮转与分片调用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用WorkBuddy调用外部API时遭遇响应异常、请求被中断或返回429错误，则很可能是触发了平台级或目标服务端的频率限制机制。以下是针对WorkBuddy场景下实施API调用频率限制、防范恶意刷量与QPS限流的具体操作路径：
一、启用WorkBuddy内置令牌桶限流器
WorkBuddy支持在HTTP连接器层面嵌入轻量级令牌桶算法，通过控制单位时间内可发出的请求数，从源头抑制突发流量。该机制适用于私有化部署及公有云高权限实例，需配合Redis中间件实现跨Worker一致性。
1、进入【集成中心】→【连接器管理】，选中待限流的HTTP连接器，点击【编辑】。
2、在高级配置区域勾选【启用QPS限流】，输入目标阈值（例如：15次/秒）及桶容量（例如：30）。
3、确认已配置Redis连接地址与认证信息，系统将自动创建以连接器ID为前缀的原子计数键。
4、保存后，所有经该连接器发起的API调用均受此速率约束，超限请求将被立即拒绝并返回HTTP 429 Too Many Requests及X-RateLimit-Remaining: 0头信息。
二、配置多层级滑动窗口限流策略
单一QPS限制易被短时高频请求绕过，建议叠加自然日总量与IP维度并发数双重防护，形成时间+空间双控结构，有效识别并拦截脚本类恶意刷量行为。
1、在【系统设置】→【安全策略】→【API流量控制】中，新增限流规则组。
2、添加第一条规则：选择“按API Key”维度，窗口类型设为“24小时滚动”，上限设为86400次/日（即1次/秒均值），触发动作设为“静默丢弃”。
3、添加第二条规则：选择“按客户端IP”维度，窗口类型设为“1分钟”，上限设为60次/分钟，触发动作设为“返回429并记录审计日志”。
4、启用规则组，系统将实时比对每条出站请求的Key哈希与源IP，任一维度超限即执行对应处置逻辑。
三、部署前置缓存代理层拦截重复请求
对于读接口（如客户查询、知识库检索），大量语义等价但参数格式微异的请求极易造成无效QPS消耗。通过引入本地缓存代理，可将相同逻辑请求归一化并复用响应，显著降低后端调用频次。
1、在WorkBuddy服务器本地部署Nginx反向代理，启用proxy_cache模块。
WorkBuddy 桌宠工厂 —— 给一张角色图、一个 codex.pet 链接、一条 codex-pets.net 下载 URL、或一份现成的精灵表，就能自动创建一只可联动 WorkBuddy 状态的桌面宠物。当用户说"创建桌宠"、"做一只桌宠"、"用这张图做桌宠"、"从 codex.pet 安装桌宠"、"导入 codex 桌宠 XX"、"装一下 codex-pets.net 上的 XX&quo
2、为指定API域名配置缓存键生成规则，例如：proxy_cache_key "$scheme$request_method$host$uri?$(echo $args | sort | tr '&' '\n' | sort | tr '\n' '&' | sed 's/&$//')";
3、设置proxy_cache_valid 200 302 10m; proxy_cache_use_stale error timeout updating;
4、将原连接器URL替换为Nginx代理地址，所有GET类请求将自动命中缓存，仅首次请求穿透至后端，后续相同语义请求响应延迟降至毫秒级且不占用QPS配额。
四、启用动态错误码感知降频机制
当目标API主动返回限流信号（如429、自定义错误码10008）时，WorkBuddy可自动暂停该连接器调用，并按指数退避策略逐步恢复，避免持续冲击导致临时封禁。
1、在连接器【响应映射】配置中，新增错误码识别规则：状态码匹配429，或响应体JSON路径$.code == 10008。
2、在【高级重试策略】中启用【智能退避】，初始等待2秒，最大重试3次，每次间隔翻倍（2s→4s→8s）。
3、勾选【触发全局降频】，一旦单连接器连续2次触发限流，系统将自动下调其QPS阈值至原值的50%，持续5分钟。
4、观察【监控中心】→【API调用健康度】面板，确认“限流触发率”指标稳定低于0.5%，且“平均响应延迟”未出现阶梯式上升。
五、实施API密钥轮转与分片调用
针对支持多密钥的第三方服务（如飞书、企微开放平台），可通过密钥分片将流量分散至不同配额池，规避单密钥瓶颈，同时提升整体容错能力。
1、在【API凭证管理】中为同一服务商注册至少3个独立API Key，分别标注为“key-a”“key-b”“key-c”。
2、编辑连接器，在认证方式中选择【密钥轮转模式】，设置轮转周期为100次调用切换一次。
3、配置负载均衡策略：按连接器调用次数哈希取模，自动分配至对应密钥实例，确保各密钥QPS分布标准差＜15%。
4、启用【密钥健康检查】，当某密钥连续返回5次401或403时，自动将其标记为失效并从轮转队列剔除，切换过程对上层工作流完全无感。
