做微服务的人迟早会遇到一个问题业务系统多了AI 能力该怎么给出去。一个后台管理服务要做智能问答一个经营分析服务要做自然语言查询一个客服服务要做语义分类如果每个服务都自己去对接大模型、各自维护一套 Prompt 和上下文用不了多久整个技术团队就会被一堆重复代码和混乱配置拖垮。我的方案是把 AI 能力整体往上抽一层做成独立公共服务通过 SpringCloud 统一暴露给所有业务服务。OpenClaw 恰好是一个适合承担“通用 Agent 能力”的组件配合 SpringCloud 的注册发现、网关路由和负载均衡可以让 AI 能力像普通 RPC 服务一样被调用和复用。这篇文章就围绕“OpenClaw SpringCloud 微服务集成”这条主线讲清楚架构怎么搭、调用链怎么走、部署会踩到哪些坑以及如何把 Skill 变成多个业务系统都能直接用的公共能力。适合正在做微服务改造、又想用一套 Agent 能力覆盖多个业务场景的团队参考。1. 先想清楚为什么把 OpenClaw 放进微服务1.1 独立 AI 公共服务而不是每个业务各接一遍大模型很多团队刚开始接 AI 能力时习惯是“哪个业务要用哪个业务自己调”。于是订单服务里写了一套调用大模型的代码库存服务里又写了一套客户服务里还维护着另一份 Prompt 模板。短期看没什么问题等业务上去后就会很痛苦Prompt 逻辑改动一次要通知所有业务方同步改大模型接口升级所有服务跟着返工每个服务各自计费、各自管理上下文成本散落一地。把 AI 能力集中到一个独立服务里是微服务架构里很自然的演进方向。这个服务只做一件事——“让任何业务服务都能通过 HTTP 拿到 AI 能力”。业务服务不需要关心模型是哪个、Prompt 怎么写、上下文怎么维护只需要按约定传参数、收结果。这样 AI 能力就变成了一种标准化接口而不是散落在代码里的零散拼接。表格式对比可能更直观做法重复成本Prompt 管理上下文隔离故障影响范围各业务直连大模型高分散难全局独立 AI 公共服务低集中容易局部注意“故障影响范围”这一项直连模式下大模型服务抖动所有业务一起抖而独立公共服务可以做降级、熔断、降级策略把故障挡在业务链路之外。1.2 SpringCloud 在这里到底承担什么职责SpringCloud 不负责让 AI 变聪明它负责的是“治理”。在 OpenClaw SpringCloud 的组合里SpringCloud 主要做四件事服务注册与发现、网关路由、负载均衡、配置管理。服务注册与发现解决的是“AI 服务在哪儿”。OpenClaw 部署后的地址变化、实例扩展业务方不需要知道只要知道服务名叫ai-agent-service就行。网关路由解决的是“外部请求怎么进来”。统一入口内部结构对外不可见后面多部署几个 OpenClaw 实例也不用动客户端。负载均衡解决的是“多个实例怎么分配流量”SpringCloud LoadBalancer 在 Feign 调用层自动完成。配置管理解决的是“不同环境怎么切换模型”开发环境接qwen2.5:3b生产环境切更强模型改配置中心即可不用重新发版。所以这套方案的本质是把 AI Agent 当成微服务体系里的一个普通节点由 SpringCloud 帮它解决分布式环境下的通用问题OpenClaw 只需要专注在 Agent 能力本身上。1.3 OpenClaw 的角色与边界OpenClaw 在架构里是“Agent 层”不是大模型本身。它负责理解用户请求、编排调用步骤、管理上下文、加载 Skill 工具。你可以把它想成“一个自带工具箱的调度员”而真正干“思考”这件事的是背后的大模型比如 Ollama 部署的 Qwen 系列。为什么用 OpenClaw 而不是直接调大模型因为业务系统里的大多数需求不是“问一句答一句”那么简单。比如“帮我把上个月的订单按地区汇总并解释一下异常订单集中的原因”这句话需要拆解成“查询数据 分析数据 组织结果”三个动作OpenClaw 负责把这三个动作编排出来。而且它允许通过 Skill 扩展能力比如新增一个数据库查询 SkillAgent 就能主动调用数据库工具这种能力是“裸调大模型”不容易实现的。边界也要划清楚OpenClaw 不适合直接暴露给外部用户调用因为它需要有统一鉴权、流量控制、上下文治理这些应该由 SpringCloud 网关和 AI 公共服务层来处理。OpenClaw 应该被包在微服务体系内部像一个“能力底座”一样存在。2. 整体架构与关键选型2.1 拓扑结构调用链路怎么走整个链路由三层构成外部客户端 / 前端只访问 SpringCloud Gateway比如POST /api/agent/chat用户只感知到一个标准 HTTP 接口。AI 公共服务层负责接收内部各业务系统的 Feign 调用把请求信息孵化成 OpenClaw 能理解的格式统一做鉴权、上下文管理、日志追踪。OpenClaw 实例层真正执行对话编排和 Skill 调用背后接大模型比如 Ollama 提供的本地模型服务。用文字描述大概是这样业务服务 → Nacos 发现 ai-agent-service → Feign 调用 → OpenClaw HTTP 接口 → Ollama/Qwen。外部客户端则是网关 → ai-agent-service → OpenClaw。这样设计的最大好处是“内部可替换”。今天 OpenClaw 是这个版本明天换另一个 Agent 框架只要 AI 公共服务对外接口不变所有业务方无感知。2.2 服务拆分与选型细节我实际搭建时采用了以下组件这个组合是当前社区验证比较多、坑相对少的一套Nacos 2.x 作为注册中心和配置中心当前微服务标配和 SpringCloud 集成成熟度高。Spring Cloud Gateway 做统一入口注意它基于 WebFlux不能和spring-boot-starter-web同时使用这是新手最容易踩的坑。OpenFeign 做服务调用业务方像调本地接口一样调 AI 服务。Ollama Qwen2.5 作为本地大模型规避外部 API 的延迟和成本问题。OpenClaw 作为 Agent 引擎负责对话编排与 Skill 调度。这套选型有一个核心考量所有组件都是“可以独立替换”的。Nacos 可以换 ConsulGateway 可以换云厂商网关Qwen 可以换其他模型但业务方看到的接口不变。这种“低耦合、高替换性”是微服务架构最值得坚持的原则。2.3 接口设计与调用约定AI 公共服务的接口设计直接影响后续的复用效果这里给出一个我验证过比较合理的接口约定。接口方法说明/agent/chatPOST通用对话接口返回完整对话结果适合聊天类场景/agent/askPOST普通查询接口只返回最终答案适合内部服务调用/agent/taskPOST异步任务接口处理耗时较长的分析任务返回任务 ID/agent/skillsGET查看当前可用的 Skill 列表便于业务方感知能力请求体的核心参数包括message用户输入、sessionId会话标识用于上下文隔离、skillName指定要使用的技能、model可选指定模型。响应体统一为{ code: 0, data: ..., message: ok }这样各业务方不用做繁琐的兼容处理。3. 环境准备与 OpenClaw 部署实录3.1 依赖准备Node、Ollama、WSL2OpenClaw 部署在 Windows 和 Linux 上流程略有不同。我这边实际用的是 Windows WSL2 的组合依赖项有这些Node.js 18 及以上版本建议 LTS、WSL2 内 Ubuntu 22.04、Ollama 最新版以及足够的内存运行 3B 参数量模型建议 8G 以上。安装顺序有讲究。先把 WSL2 环境理顺再装 Node.js最后装 OpenClaw。因为 OpenClaw 的安装和运行过程会依赖 npm 和系统环境变量如果 WSL2 本身状态不正常后面每一步都会跟着报错排查起来很费时间。3.2 最容易遇到的 WSL2 状态异常搜索 OpenClaw 部署的问题时最常看到的一个就是“openclaw 无法安全验证 sl2 环境请在 powershell 中运行 wsl -- status”。这个问题在 Windows 上部署 OpenClaw 时非常典型。它的本质是 OpenClaw 启动前会检查 WSL2 内核和发行版状态而很多人的 WSL2 其实处于“半可用”状态。处理方式很简单在 PowerShell 里依次执行wsl --status wsl --updatewsl --status会告诉你当前内核版本和默认分发版。如果提示内核过期执行wsl --update更新到最新内核。更新完成后重启终端再检查一遍。多数情况下这一步做完OpenClaw 就不再报这个错了。如果wsl --status本身就直接报错那说明 Windows 的虚拟机平台功能没开需要在“启用或关闭 Windows 功能”里打开“虚拟机平台”和“适用于 Linux 的 Windows 子系统”重启后从头验证。3.3 部署 OpenClaw拉代码、初始化、启动OpenClaw 的部署不需要复杂的编译过程整体思路是拉取代码 → 安装依赖 → 初始化配置 → 启动服务。流程上我建议这样走从官方仓库拉取代码到 WSL2 环境内建议放在/opt/openclaw这类统一目录下。进入项目目录执行依赖安装需要耐心等 npm 把依赖拉完网络不稳定时容易中断中断了直接重跑即可。执行初始化命令生成配置目录这里会创建默认的配置文件内容包括模型接入方式、监听端口、Skill 目录等。编辑配置文件指定大模型后端地址。启动服务确认端口监听正常。这里补充一个经验不要把 OpenClaw 装在 Windows 原生文件系统里再通过 WSL2 访问跨文件系统的 IO 性能很差而且容易出现文件权限问题。直接放在 WSL2 内部的 Linux 文件系统里后续调试会顺利很多。3.4 接入本地大模型Ollama Qwen2.5OpenClaw 支持通过 API 方式接入大模型算力也支持指向本地模型服务。我这边为了内网可控性和成本考虑选择用 Ollama 部署 Qwen2.5:3B。这个模型参数量不大部署门槛低作为功能联调已经足够。Ollama 装完后执行ollama pull qwen2.5:3b ollama serveollama serve默认监听11434端口并且提供了 OpenAI 兼容的 API。OpenClaw 的配置文件里模型地址填http://localhost:11434/v1就行API Key 可以随便填一个占位字符串因为本地服务不校验。模型名称填qwen2.5:3b。验证方式很简单在终端执行curl http://localhost:11434/api/tags能列出模型列表就说明本地模型服务已经就绪。这一步一定要做因为很多人配置完 OpenClaw 后一直报错查到最后发现是 Ollama 根本没起来或者端口被占用。4. SpringCloud 接入与全局复用实现4.1 注册中心让业务方发现 AI 服务先创建一个ai-agent-service的 Spring Boot 工程引入 Nacos 注册发现相关依赖。在application.yml里配置服务名和注册中心地址spring: application: name: ai-agent-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848启动后到 Nacos 控制台确认服务列表里出现ai-agent-service。这一步的意义在于业务方后续通过 Feign 调用 AI 服务时不关心它部署在哪台机器、哪个端口只凭服务名就能找到。如果 Nacos 和服务不在同一环境注意把server-addr改成可访问的地址。我遇到过团队内网防火墙挡住8848端口的情况调了半天才发现是网络策略问题所以环境联调前先检查端口连通性。4.2 网关路由对外统一暴露外部请求走 Spring Cloud Gateway配置一段路由规则spring: cloud: gateway: routes: - id: ai-agent uri: lb://ai-agent-service predicates: - Path/api/agent/**这里的关键是uri用了lb://前缀。它表示网关会从注册中心拉取ai-agent-service的服务实例列表并自动做负载均衡。如果配成固定http://localhost:8080那后续 AI 服务扩多实例时流量只会打到一台机器上就失去了微服务的意义。需要提醒的是网关默认的转发超时时间很短而 AI 请求的推理耗时常达到几十秒甚至更久。因此需要调大网关的响应超时配置否则前端请求会先在网关层被切断业务方根本等不到 AI 的返回结果。4.3 将 OpenClaw 封装成标准的 HTTP 服务ai-agent-service的核心逻辑是把业务方的请求转成 OpenClaw 能识别的格式再转发出去。这里用 Spring Boot Controller 做一个封装层RestController RequestMapping(/agent) public class AgentController { private final AgentService agentService; public AgentController(AgentService agentService) { this.agentService agentService; } PostMapping(/ask) public Result ask(RequestBody AgentRequest request) { String answer agentService.ask(request); return Result.ok(answer); } }封装层内部做的事情值得展开说第一把业务方的message、sessionId、skillName组装成 OpenClaw 的请求体第二给请求带上traceId方便后续排查问题第三处理 OpenClaw 的异常响应转换成统一错误码。内部调用 OpenClaw 时用RestTemplate或WebClient都行关键是设置合理的超时时间一般建议connect-timeout3 秒read-timeout60 秒起步。为什么要单独写这一层封装而不是让业务方直接调 OpenClaw因为 OpenClaw 的接口格式、协议细节可能会随着版本变化而业务方只依赖你封装后的稳定接口。这层封装就是“防腐层”把变化的、不稳定的细节隔离在内部。4.4 业务服务通过 Feign 调用业务方的接入成本很低Feign 接口定义如下FeignClient(name ai-agent-service, path /agent) public interface AgentClient { PostMapping(/ask) Result ask(RequestBody AgentRequest request); }调用时和调用普通本地方法一样。业务服务只需要引入spring-cloud-starter-openfeign并在启动类上加EnableFeignClients。这里有一个容易忽略的点Feign 的默认超时时间也很短必须在业务方配置文件里显式调大。AI 请求不是数据库查询不能按毫秒级别的预期来设置超时。另外Feign 调用方还应该做一层兜底。比如 AI 服务暂时不可用业务方要有降级方案——返回缓存结果、抛出可控异常或者走规则引擎的兜底逻辑。AI 服务毕竟是复杂链路不能因为模型推理超时把整个业务接口拖死。5. Skill 复用、配置与团队协作5.1 Skill 的本质与运行机制OpenClaw 的 Skill 是它最值钱的扩展能力。一个 Skill 可以理解为一个“具备特定工具能力的子模块”比如“查询天气”“查数据库”“分析日志”“总结文档”。Skill 由 OpenClaw 在对话编排过程中自动调用或者由调用方显式指定。在实际微服务集成中Skill 需要被当作“公共能力资源”来管理而不是堆在 OpenClaw 项目里不管。我建议的做法是把 Skill 的启停做成配置项放到 Nacos 配置中心这样运营人员可以随时调整不用登录服务器改文件。5.2 把 Skill 变成可复用的公共能力在ai-agent-service里维护一份 Skill 清单配置用比如这样的结构agent: skills: enabled: ->