上个月我们在做内部AI能力中台的时候遇到一个特别现实的矛盾各个业务线都在接大模型接到最后接口五花八门、System Prompt各写各的、token消耗对不上账甚至连这个能力到底给谁用、用了多少次都说不清楚。后来我们换了个思路把OpenClaw作为Agent执行底座通过SpringCloud微服务把对话、技能、提示词配置全部统一封装成可调用的服务。这套方案落地之后AI能力真正变成了团队内部可以全局复用的基础设施新业务接入只需要调一个Feign接口。这篇就把我们的架构拆解、落地过程和踩坑记录完整写出来如果你也在头疼怎么把Agent能力平稳塞进现有微服务体系应该能帮你省不少时间。OpenClaw负责管理会话上下文、技能注册和模型调用SpringCloud负责把这份能力变成组织级的基础设施。两者结合之后模型和提示词可以被任意业务复用权限、限流、审计都有统一出口这也是我觉得这套集成最值钱的地方。1. 为什么非要把 AI Agent 接到微服务里1.1 各业务线各接各的到底有多痛先说我们当时面对的现状。公司内部有三条业务线几乎同时在搞AI功能电商团队要做客服助手数据团队要做SQL转自然语言运营团队要做内容总结。表面上各干各的实际上一聊才发现大家都在对接同一个模型服务商的API都在实现同一套会话管理都在维护各自的prompt版本。同一个模型被封装了三遍三个版本的System Prompt互相还不一样用户问同样的问题三个入口给出的语气和答案风格完全不同。这种各拉网线、不走主干网的方式带来几个非常实际的问题。第一是重复建设三个人各干一遍活排期还都排得满满的。第二是审计缺失用户问了什么、哪个模型回答的、花了多少token三个系统各自记各自的财务想分摊成本根本没依据。第三是升级困难模型版本从qwen2.5-3b换到7b的时候三个团队得分别发版、分别验证谁都不敢先升级因为不知道会不会影响自己的prompt效果。最讽刺的是团队里其实一直有SpringCloud这套现成的微服务基础设施只是没人想过把AI能力也当成一个服务放进去。我们后来就在想既然业务系统都能通过注册中心统一管理、统一调用为什么AI能力不行1.2 微服务封装后的核心收益直连模型API和把AI能力封装成微服务是两种完全不同的治理逻辑。我列个表格方便对比对比维度各业务直连模型APIOpenClaw SpringCloud 封装接入成本每条业务线独立开发对接业务方调一个Feign接口即可Prompt管理散落在各业务代码里配置中心统一管理、可动态刷新鉴权与审计各管各的API Key网关统一鉴权、全链路traceId限流与熔断各自为战容易雪崩Sentinel集中治理按技能维度限流模型升级逐业务发版验证适配层切换业务无感知成本归因混乱按调用记录精确分摊这个表格背后其实就一句话AI能力一旦被装进微服务框架就不再是某个小组的私有玩具而是整个组织可以一起用、一起管的基础设施。业务方不再需要知道背后是哪个模型、是本地部署还是云端调用他们只需要知道自己要的技能ID把参数传进去拿结果。底层的事情全部由适配层和OpenClaw搞定。1.3 OpenClaw 在架构里的位置有人可能会问为什么要单独引入OpenClaw一个Agent框架直接用Spring Boot调大模型API不就行了吗这个问题我们在方案评审时也被问过。我的理解是OpenClaw解决的是大模型怎么变成可编排能力的问题而不是单纯地调一次模型API。它是Agent运行时负责管理多轮会话的上下文、注册和调度各类Skill、处理模型调用的并发与异常。比如我们定义了一个知识库问答的Skill它可能需要先检索再生成这个编排逻辑写在OpenClaw的Skill里另一个SQL生成的Skill可能需要先看表结构再产出查询语句这也是OpenClaw侧的能力。如果我们把这些都塞进业务系统那业务系统会变得极其笨重而且每个系统都要理解Agent的运行逻辑。所以正确的姿势是OpenClaw负责思考和执行SpringCloud负责暴露和治理各干各的边界非常清晰。2. 环境准备OpenClaw 部署与 SpringCloud 底座搭建2.1 OpenClaw 本地部署与 Windows Companion 配置OpenClaw这个框架对部署环境不算挑剔官方支持Windows和Linux我们实际部署时建议优先用Linux环境或者Windows下的WSL2。原因很实际模型推理相关的依赖库在Linux下的生态更完整而且很多坑在社区里已经有解法Windows原生环境遇到问题能搜到的资料反而少。如果你是在Windows上搭建第一步是确认WSL2环境正常。直接在PowerShell里运行下面的命令检查wsl --status wsl -l -v确保默认版本是2并且Ubuntu发行版的状态是Running或Stopped不是错误状态。如果检查不通过先执行wsl --update把内核升级到最新版然后wsl --shutdown重启WSL服务。WSL里准备好之后接着装Node.js。OpenClaw基于Node.js运行建议装LTS版本版本太低会导致初始化的时候直接报错。在Ubuntu里执行curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs node --versionNode装好后安装OpenClaw并初始化项目npm install -g openclaw openclaw init my-agent cd my-agent openclaw start启动后OpenClaw默认会监听本机端口我们可以用一个单独的配置文件指定模型接入方式。另外很多人问OpenClaw Windows Companion怎么配置其实就是把OpenClaw注册成Windows下的后台服务方便开机自启和托盘管理。在WSL里跑着的场景下我更推荐直接用systemd或者screen管理进程简单直接不用额外装东西。2.2 大模型接入Ollama Qwen2.5-3B 本地化方案模型接入我们选了Ollama因为它对本地化部署非常友好一条命令就能拉起推理服务。我们用qwen2.5-3b作为主力模型原因很直接3B参数量在CPU上勉强能跑量化之后内存占用不高生成的响应还过得去。如果你机器配置好一点可以直接上7B。安装Ollamacurl -fsSL https://ollama.com/install.sh | sh拉取模型并启动服务ollama pull qwen2.5:3b ollama serve默认情况下Ollama监听11434端口。我们在OpenClaw的模型配置文件里做如下对接model: provider: ollama base_url: http://127.0.0.1:11434 model_name: qwen2.5:3b timeout: 120s这里有两个细节容易踩坑。第一个是Ollama首次加载模型会比较慢OpenClaw默认的超时时间如果太短会直接报连接超时建议把timeout调到120秒以上。第二个是如果你的OpenClaw跑在WSL里Ollama也跑在同一个WSL环境里别用localhost之外的地址直接127.0.0.1就行但如果OpenClaw的适配层在物理机、Ollama在WSL里那就要用WSL的虚拟IP这个很多人会忽略。2.3 SpringCloud 组件选型SpringCloud这块我们用的是最主流的那套组合Nacos做注册中心和配置中心Spring Cloud Gateway做统一入口OpenFeign做服务间调用Sentinel做限流熔断。选型理由只有一个这套组合在Java生态里最成熟踩坑案例最多后续团队招人也最容易接手。如果你团队已经有Consul或者Eureka在跑也不是不能换。但核心思路不变AI能力适配层必须作为一个独立服务注册到注册中心业务侧通过服务名调用而不是直接把IP写死在代码里。我们这边以Nacos为例后面所有配置都按照Nacos来讲。Nacos部署很简单下载解压后startup.cmd或者startup.sh启动就行默认控制台在8848端口服务注册接口也是8848。我们在统一环境里把Nacos放在一台独立的Linux服务器上配置了namespace区分开发和生产这个后面会详细说。2.4 落地部署形态整套架构在物理部署上是分层的客户端请求先打到Spring Cloud Gateway网关负责鉴权、路由、记录traceId。网关把请求转发到具体的业务微服务比如客服系统、报表系统。业务微服务通过OpenFeign调用OpenClaw Adapter也就是我们专门开发的适配层服务。Adapter再通过HTTP或WebSocket调用OpenClaw Runtime。OpenClaw Runtime根据skillId调度对应的Skill到底是查知识库还是执行SQL生成的编排逻辑都在这里完成。最后OpenClaw调用Ollama/Qwen2.5-3B完成生成。Adapter和OpenClaw Runtime可以部署在同一台机器也可以分开。如果业务量大建议把Adapter独立部署并且可以做多实例水平扩展因为它是整个链路里最可能成为瓶颈的一层。OpenClaw Runtime暂时没有做分布式但它的并发瓶颈主要是模型推理所以后面我们用了信号量隔离来控制并发这个在Sentinel小节里讲。3. 核心实现把 OpenClaw 封装成可复用的 AI 微服务3.1 能力封装层的统一接口设计整个集成方案里最核心的设计就是Adapter对外暴露的那几个接口。接口设计得不好后面所有业务方都会很难受。我坚持一个原则接口要简单到业务方不需要理解AI也能接入。我们对外只暴露了一个核心接口POST /ai/skill/execute Content-Type: application/json请求体{ traceId: 4a1f9c2e-8f6d-4b3a-9e95-d1f0a2b3c4d5, sessionId: user-001, skillId: sql-assistant, input: 帮我查一下最近30天订单量, params: { topN: 10 } }响应体{ code: 0, message: success, data: { output: 近30天订单量为68342单..., model: qwen2.5:3b, usage: { promptTokens: 120, completionTokens: 64 } } }这几个字段都是有讲究的。traceId必须由调用方传入这样全链路打日志的时候才能串起来出了问题一查一个准。sessionId用来标识多轮会话上下文OpenClaw侧要根据它维护会话状态。skillId是关键中的关键它决定了OpenClaw调度哪个Skill业务方不需要知道OpenClaw的内部逻辑只需要知道自己要的能力ID。params是技能级参数比如SQL生成的topN、知识库问答的检索数量都可以通过它透传。需要特别说明的是这里我们没有把模型名设计成必填字段。模型的选择权在配置中心不在调用方。这样做的目的是防止业务方为了追新模型绕过治理同时也是为了多模型回退时可以透明切换。3.2 Adapter 服务搭建与 Nacos 注册Adapter本身就是一个标准的Spring Boot服务。创建项目后引入必要的依赖然后配置Nacos注册。spring: application: name: openclaw-adapter cloud: nacos: discovery: server-addr: 192.168.1.10:8848 namespace: pro启动类上加上服务发现注解SpringBootApplication EnableDiscoveryClient public class OpenClawAdapterApplication { public static void main(String[] args) { SpringApplication.run(OpenClawAdapterApplication.class, args); } }启动之后去Nacos控制台的服务列表里确认openclaw-adapter这个服务出现在对应namespace下。很多人在这一步踩坑就是在本地启动Adapter配置的Nacos地址是生产环境的但namespace没对应上结果服务注册到了默认的public命名空间里业务侧怎么调都调不到。所以在Nacos里的namespace配置一定要认真核对。Adapter内部对OpenClaw的调用是用一个RestClient实现的。之所以自己写HTTP调用而不是引入OpenClaw的某种SDK是因为OpenClaw本身是Node.js生态的东西Java这边与其强行搞一个不成熟的封装不如直接通过明确稳定的HTTP接口对接两边解耦都更彻底。3.3 业务侧通过 OpenFeign 调用业务侧接入就简单多了。在业务服务里引入OpenFeign定义一个客户端接口FeignClient(name openclaw-adapter, fallback AiSkillFallback.class) public interface AiSkillClient { PostMapping(/ai/skill/execute) AiExecuteResponse execute(RequestBody AiExecuteRequest request); }这里fallback非常重要。模型推理是个慢操作Agent侧的编排又有不确定性如果OpenClaw或者模型挂了业务调用不能无限等下去。降级逻辑我建议不要返回空数据而是返回一段话术比如当前AI服务繁忙请稍后再试再配合日志记录原始请求方便后续重放排查。还要注意Feign的超时配置。默认的读超时是1秒对模型推理来说完全不够用。我们在业务侧把对openclaw-adapter的读超时调到了60秒feign: client: config: openclaw-adapter: connectTimeout: 3000 readTimeout: 600003.4 Skill 动态路由配置如果说统一接口Adapter的骨架那么Skill路由就是大脑。Adapter里不写死任何技能逻辑而是维护一张路由表这个表放在Nacos配置中心里ai: skills: sql-assistant: skillName: sql_generator version: v2 timeout: 30s customer-service: skillName: cs_chat version: v1 timeout: 60s doc-summary: skillName: doc_summary version: v3 timeout: 20s当Adapter收到请求时从配置中心读取路由表根据skillId找到对应的OpenClaw Skill名称和超时时间然后发起调用。这样带来的直接好处是新增一个AI能力只需要在OpenClaw侧新增一个Skill然后在Nacos配置里加一行映射Adapter和调用方的代码一行都不用改。我们甚至利用这个机制做了灰度。比如sql-assistant从v2升级到v3先把映射表里的version改成v3观察一段时间的效果和延迟如果不行马上改回v2配置一刷新就生效整个过程不需要发版重启。这就是AI能力全局复用该有的样子。4. AI 能力全局复用的关键细节鉴权、限流与配置管理4.1 统一鉴权API Key 内部收敛业务方直连模型API时最头疼的就是API Key的管理谁拿了Key、谁泄露了、谁在被外部刷量一概不知。我们做统一封装后把所有的模型API Key收敛到配置中心业务方彻底看不到真正的Key。外层的鉴权由Spring Cloud Gateway统一处理。我们在网关里加了一个全局过滤器校验请求头里的token或者签名Component public class AuthFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token exchange.getRequest().getHeaders().getFirst(X-Auth-Token); // 从配置中心读取apiKey校验不过则返回401 return chain.filter(exchange); } }Adapter内部也要做个保护防止绕过网关直接被内网其他服务调用。做法很简单Adapter检查一个内部专用的header值由配置中心下发只有网关和内部服务知道。这一步很多人会漏觉得内网就安全但实际业务系统之间有互相调用的情况很常见万一某个业务服务被攻击了没有内部校验的话AI能力就等于裸奔。4.2 Sentinel 限流与熔断保护 Agent 不被打爆模型推理的速度远慢于普通API。Qwen2.5-3B在纯CPU环境下生成一段话可能要好几秒这对并发量的容忍度非常低。所以限流必须放在Adapter这一层做而且要按Skill维度限流不能用统一QPS一刀切。我们在Adapter里集成了Sentinel在Nacos上配置了限流规则资源名阈值类型阈值效果/ai/skill/executeQPS20超过20 QPS直接拒绝sql-assistant并发线程数4SQL生成是重推理场景并发控制更严格doc-summaryQPS10文档总结响应时间可控QPS限流即可为什么不在网关统一限流因为网关限流是全局的如果某个Skill突然被刷量全公司的AI能力都会受影响。而在Adapter侧按Skill限流就可以把sql-assistant的故障限制在sql-assistant范围内customer-service不受影响这是隔离性的价值。同时我们开了Sentinel的熔断规则当某个Skill的慢调用比例超过50%、平均响应时间超过10秒时直接熔断一段时间让模型喘口气。熔断后业务方调用会快速失败走Feign的fallback逻辑而不是一直挂起。这样就算模型状态异常也不会拖垮整条链路。4.3 配置中心统一管理模型参数与提示词这一小节很关键它决定了这个方案的长期可维护性。我们把所有的模型参数、Prompt模板、温度、最大token数全部放到Nacos配置中心ai: model: temperature: 0.7 maxTokens: 2048 prompt: system: 你是一个企业内部知识库助手回答要简洁、准确、有依据。 fallback: enabled: true provider: cloud-api skills: sql-assistant: timeout: 30s version: v2Adapter里使用RefreshScope注解实现配置动态刷新RefreshScope Component public class AiConfig { Value(${ai.model.temperature}) private Double temperature; Value(${ai.prompt.system}) private String systemPrompt; }这套机制带来的效率提升非常明显。运营同事觉得回答语气太生硬我们直接在Nacos里改System Prompt不用动代码、不用发版配置刷新后立刻生效。以前改一个Prompt要走上线流程的荒唐事彻底不存在了。我还建议在配置中心里保留几份Prompt的历史版本比如v1稳定版、v2实验版通过路由参数选择用哪份。这样一旦新Prompt效果不佳改配置就能回滚数据也能对比验证。4.4 多模型回退与灰度切换本地模型部署不是永远都稳定Ollama进程可能挂、内存可能不够、推理可能慢到不可接受。所以我们做了一个多模型回退策略如果本地Qwen2.5-3B超时或不可用Adapter自动切换到云端模型API。实现逻辑很简单try { return callLocalModel(request); } catch (TimeoutException e) { log.warn(local model timeout, switch to cloud api); return callCloudModel(request); }但这里有个容易被忽略的细节切换链路必须完整记录日志包括切换原因、耗时、模型名和token用量。因为一旦走了云端API成本就和本地模型完全不是一个量级如果不是自己主动切的财务那边解释不清楚。我们把这部分日志单独拉到一张表里每天走一遍消耗对账确保所有费用都有出处。灰度切换本质上也是用配置中心的开关实现的。比如先让10%的流量走新模型观察效果稳定后再逐步加到100%。这比版本发布更轻量也是微服务化之后独有的优势。5. 常见问题与排查技巧实录5.1 OpenClaw 无法安全验证 WSL2 环境这是Windows部署场景下最常见的报错现象是执行OpenClaw命令时提示无法安全验证WSL2环境。根源通常是WSL内核版本过低、未开启虚拟化或者WSL状态异常。第一步先看状态wsl --status如果显示默认版本是1或者存在分发错误按顺序执行wsl --update wsl --shutdown wsl --status如果还是不行进BIOS确认Intel VT-x或者AMD SVM虚拟化已经开启。另外Windows老版本对WSL2的支持不完整建议把系统更新到最新后再装。这里我个人的建议是如果真的不想折腾WSL直接用一台Linux虚拟机或者云主机跑OpenClaw反而省心。5.2 Feign 调用一直超时症状是业务侧调用AI能力接口大概率超时但直接调Adapter接口又是通的。原因就是前面说的默认Feign读超时只有1秒根本容纳不了模型推理的时间。解决办法是把readTimeout调到60秒以上。另一个隐藏问题如果Adapter服务是单实例模型推理又是串行的一个长任务占住线程池后面所有请求全部排队超时。解决方式是用Sentinel的并发线程数控制把同一链路的e并发压到模型能承受的范围内宁可快速拒绝也不排队。定位这类问题我习惯看三层日志业务侧的Feign异常、Adapter的接口耗时、OpenClaw侧的模型响应时间。对比同一traceId基本一眼就能看出卡在哪一层。5.3 大模型响应体过大导致网关超时这个问题我们是后期才遇到的。Qwen2.5-3B虽然模型不大但生成一篇完整的文档总结时响应体可能到几百KB网关默认的缓冲和超时配置很容易被打爆。有两种解决方案。第一种是把Adapter的接口改成流式返回用SSE协议实时推送生成结果前端一边接收一边渲染体感上也不用等太久。第二种是限制生成长度把maxTokens压低同时做好输出裁剪只返回业务真正需要的部分。我们最后是两种方案结合业务方普通的问答请求走非流式但要生成长文档的场景走SSE流式。这个切换也只是在接口层面多一个参数对调用方完全透明。5.4 本地模型推理太慢怎么优化很多人第一次把Qwen2.5-3B跑在CPU上都会怀疑人生一个简单的问答要等几十秒。优化手段按性价比排序换量化版本用GGUF的IQ4或者Q5量化推理速度能快不少效果损失在可接受范围内。把模型放到GPU上哪怕是一个旧显卡速度也能提升数倍。限制并发宁可让单个请求快也不要让多个请求在CPU上互相抢资源导致所有请求都慢。从架构层优化把重推理任务做成异步。Adapter收到请求后先返回处理中然后回调结果。不过这会增加调用方的复杂度我们在内部用了但对外还是同步为主。还有一点经验是不是所有问题都要大模型来解决。很多固定话术、规则判断用模板引擎就够了。让AI只处理真正需要智能的场景整个系统会稳定得多。5.5 典型问题速查表问题可能原因快速处理OpenClaw启动报WSL2错误WSL内核版本旧、虚拟化未开wsl --update检查BIOS模型回答超时Ollama首次加载慢调大OpenClaw和Adapter的timeoutFeign调用超时默认读超时1秒配置readTimeout60000Nacos里找不到Adapter服务namespace不正确核对namespace与server-addr某个Skill拖垮整个系统缺少按Skill隔离限流用Sentinel按资源名限流云端模型费用暴增回退策略无日志给fallback链路补全日志和告警网关返回超时响应体过大改SSE流式返回或裁剪输出这套排查表基本上覆盖了我们上线初期遇到的所有问题。说句实话没有哪一行是真正高深的技术但每个问题不解决都会卡住进度提前了解能省下大量在线排查的时间。整套方案跑下来我最大的体会是AI能力一旦被装进微服务框架就不再是某个小组的玩具而是整个组织可以一起用、一起管的基础设施。把OpenClaw当底座、SpringCloud当骨架的好处在于后续无论换模型、加技能还是调整提示词业务方都感知不到所有变化都被限制在适配层和配置中心里。最后分享一个我一直保留的习惯给每个Skill维护一个版本号连同超时时间和模型名一起写进路由配置。这样线上调优的时候切一个配置就能灰度不用反复动代码。这个习惯听着简单但真正坚持下来会让整套AI能力平台的迭代效率和稳定性都提升一个台阶。