人工智能AI AgentAgent 工作流Agent 编排RAG工具调用后端前端【免费下载链接】mateclaw MateClaw — Your second brain with Multi-Agent Orchestration, MCP Protocol, Skills Memory, Dream, and Multi-Channel Support. Built on Spring AI Alibaba.项目地址https://gitcode.com/gh_mirrors/mat/mateclaw点击查看免费下载MateClaw 是一款基于 Spring AI Alibaba 构建的多智能体平台内置多模型供应商配置与**故障转移Failover**机制当你配置的主模型 API Key 失效、限流或宕机时系统会按优先级自动切换到下一个健康供应商重试当前请求让 AI 始终在线。本文以新手视角手把手带你完成供应商接入、切换链配置与健康状态查看。1. 为什么需要多模型故障转移大多数 AI 工具的命运取决于一个供应商Key 过期返回 401、额度耗尽返回 429、网络抖动返回 5xx用户端看到的就是一张红色报错卡片。MateClaw 的思路不同——把模型供应当作可用池来治理故障转移链主模型失败后按配置顺序依次尝试下一个健康供应商而不是直接报错健康跟踪器连续失败的供应商自动进入冷却期避免每轮对话都浪费几秒去撞坏掉的 API可用池硬性错误鉴权失效、余额不足的供应商会被移出池子TTL 到期后自动重新纳入——充完费、换完 Key 不用重启服务。 你不需要写任何重试脚本把供应商拖到优先级顺序里看着健康面板上的状态点实时变化即可。2. 启用模型供应商从 API Key 到自动体检所有配置都在设置 → Models页面完成界面即卡片式供应商列表。2.1 三步接入一个供应商启用供应商点击「启用/恢复提供商」从内置目录中选择DashScope、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、OpenRouter、智谱、火山引擎、Ollama、LM Studio、MLX 等或「自定义提供商」接入任意 OpenAI 兼容协议服务填写凭证在卡片内直接粘贴 API Key 并保存本地服务如 Ollamahttp://localhost:11434可关闭需要 API Key开关发现模型填写 Key 后点击「发现模型」自动拉取该供应商全部可用模型并标记默认模型。各供应商的默认 Base URL 已在界面中内置提示见 zh-CN.ts通常无需修改。2.2 启动时自动体检MateClaw 启动后会对每个已配置供应商发起探测ProviderInitProbe调用其模型列表等轻量接口验证凭据有效性。体检通过的供应商进入可用池才有资格参与故障转移失败的会显示启动体检失败可点击卡片上的「重新检测」按钮手动复测前端逻辑见 useProviderPool.ts。3. 配置故障转移链池内尝试顺序这是多模型供应商配置的核心告诉 MateClaw主模型挂了之后先试谁、再试谁。3.1 设置 fallbackPriority池内尝试顺序在供应商卡片 →「配置」中填写池内尝试顺序字段见 ProviderConfigModal.vue取值含义0不参与故障转移默认1第一顺位主模型失败后第一个被尝试2第二顺位依此类推相同数字多个供应商同值时按 ID 字典序尝试配置完成后供应商卡片上会出现「偏好 #1」徽标ProviderCard.vue。3.2 转移链是这样走起来的运行时由 AgentGraphBuilder.buildFallbackChain 构建转移链规则如下显式优先级 0 的供应商排前面数字升序未设优先级的排后面链的来源是可用池构建时不在池中的供应商直接跳过但运行时每次请求都会复查池成员身份恢复后自动生效每个供应商取其默认或第一个启用的对话模型无需为每个供应商手动指定回退模型主模型先在自己的重试预算内重试预算耗尽才移交给转移链——所以回退不是秒切而是确认主模型确实不可用之后才切保证成本可控。3.3 按员工定制转移偏好除了全局顺序还可为单个数字员工单独设置供应商偏好AgentProviderPreference列出该员工专属的供应商模型序列排在链首其余供应商按全局优先级跟随。比如写代码员工偏好本地 Ollama 的量化模型客服员工偏好云端的 DeepSeek——互不干扰。4. 健康跟踪MateClaw 如何判断该切了故障转移的聪明之处在于对错误做了分级处理实现见 AvailableProviderPool.java 与 ProviderHealthTracker.java错误类型级别处理方式限流 429 / 服务端 5xx / 空响应SOFT软故障留在池内连续失败 3 次进入 5 分钟冷却冷却后自动恢复API Key 失效AUTH_ERRORHARD硬故障移出可用池30 分钟后自动重新纳入余额/计费问题BILLINGHARD移出可用池1 小时后自动重新纳入模型不存在MODEL_NOT_FOUND模型级只跳过该模型不影响同供应商的其他模型几个值得新手知道的设计细节限流时长智能同步如果供应商在 429 响应中返回Retry-After头冷却期会直接采用供应商声明的恢复时间上限 2 小时而不是傻等 5 分钟一次成功即满血复活冷却期内的供应商一旦某次调用成功计数器清零、冷却立即解除自动重纳入是自愈的TTL 到期后被重新纳入的供应商如果仍然坏掉第一次真实调用就会再次把它踢出去——无需人工干预也无需重启。以上阈值均可通过配置文件调整定义见 ProviderHealthProperties.javamateclaw: llm: failover: health: enabled: true failure-threshold: 3 # 连续失败几次进入冷却 cooldown-ms: 300000 # 冷却窗口毫秒 billing-readmit-ms: 3600000 # 计费故障自动重纳入 TTL auth-readmit-ms: 1800000 # 鉴权故障自动重纳入 TTL5. 在控制台查看供应商健康状态设置 → Models的每张供应商卡片上有一个状态胶囊直接回答这个供应商现在能不能用状态含义 可用已通过体检正在参与故障转移 冷却中近期连续失败显示倒计时到期自动恢复 未连接已从可用池移除悬停可见原因如API Key 失效⚪ 检测中启动后正在探测稍候自动更新需要配置尚未填写 API Key后端状态由 ProviderPoolController 聚合可用池成员 移出原因 冷却剩余时间 连续失败次数一次接口调用即可看全。6. 新手常见疑问Q只配了一个供应商需要手动开启故障转移吗A不需要。只要配置了多个供应商并设置了池内尝试顺序转移链自动生效只有一个供应商时行为与从前完全一致。QAPI Key 过期了要手动处理吗A过期后该供应商会立即移出可用池不浪费调用30 分钟后系统自动重新探测你更新 Key 后也可以直接点「重新检测」秒级生效。Q本地模型Ollama宕机了会拖慢切换吗A不会。本地服务不可达属于失败计数连续 3 次即冷却 5 分钟期间转移链直接跳过它请求直奔云端供应商。Q如何验证转移真的生效A把主供应商的 API Key 改错一个字符发起一次对话——观察消息流仍正常返回同时该卡片变为未连接API Key 失效即可确认故障转移链路畅通。7. 延伸阅读供应商卡片与状态展示mateclaw-ui/src/views/Settings/Models/故障转移核心源码目录mateclaw-server/src/main/java/vip/mate/llm/failover/转移链构建逻辑AgentGraphBuilder.java项目总览README.md一句话总结在 MateClaw 里模型宕机不再是事故而是一次静默的供应商切换——配好优先级、看住健康面板你的 AI 数字员工就拥有了自己的双路供电。赞分享人工智能AI AgentAgent 工作流Agent 编排RAG工具调用后端前端【免费下载链接】mateclaw MateClaw — Your second brain with Multi-Agent Orchestration, MCP Protocol, Skills Memory, Dream, and Multi-Channel Support. Built on Spring AI Alibaba.项目地址https://gitcode.com/gh_mirrors/mat/mateclaw点击查看免费下载相关推荐如何配置永不宕机的 LLM 模型池Experiential 认证池与故障转移规则实战如何配置永不宕机的 LLM 模型池Experiential 认证池与故障转移规则实战 Experiential 是一款开源、零附加费的 LLM 模型网关支持Cursor AI Pro破解技术深度解析智能绕过试用限制的完整解决方案Cursor AI Pro破解技术深度解析智能绕过试用限制的完整解决方案 还在为Cursor AI的Youve reached your trial re开发工具CLIAgent-Native API设计构建RESTful和GraphQL接口的最佳实践指南Agent Native API设计构建RESTful和GraphQL接口的最佳实践指南 Agent Native是一个用于构建agent native应用程人工智能AI AgentAgent 框架后端前端工具调用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考