企业官网建设流程全解析

做微服务的人迟早会遇到一个问题：业务系统多了，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 能力就变成了一种标准化接口，而不是散落在代码里的零散拼接。

表格式对比可能更直观：

注意“故障影响范围”这一项：直连模式下，大模型服务抖动，所有业务一起抖；而独立公共服务可以做降级、熔断、降级策略，把故障挡在业务链路之外。

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 扩展能力，比如新增一个数据库查询 Skill，Agent 就能主动调用数据库工具，这种能力是“裸调大模型”不容易实现的。

边界也要划清楚：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 可以换 Consul，Gateway 可以换云厂商网关，Qwen 可以换其他模型，但业务方看到的接口不变。这种“低耦合、高替换性”是微服务架构最值得坚持的原则。

2.3 接口设计与调用约定

AI 公共服务的接口设计直接影响后续的复用效果，这里给出一个我验证过比较合理的接口约定。

请求体的核心参数包括message（用户输入）、sessionId（会话标识，用于上下文隔离）、skillName（指定要使用的技能）、model（可选，指定模型）。响应体统一为{ "code": 0, "data": "...", "message": "ok" }，这样各业务方不用做繁琐的兼容处理。

3. 环境准备与 OpenClaw 部署实录

3.1 依赖准备：Node、Ollama、WSL2

OpenClaw 部署在 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 --update

wsl --status会告诉你当前内核版本和默认分发版。如果提示内核过期，执行wsl --update更新到最新内核。更新完成后重启终端，再检查一遍。多数情况下这一步做完，OpenClaw 就不再报这个错了。如果wsl --status本身就直接报错，那说明 Windows 的虚拟机平台功能没开，需要在“启用或关闭 Windows 功能”里打开“虚拟机平台”和“适用于 Linux 的 Windows 子系统”，重启后从头验证。

3.3 部署 OpenClaw：拉代码、初始化、启动

OpenClaw 的部署不需要复杂的编译过程，整体思路是拉取代码 → 安装依赖 → 初始化配置 → 启动服务。

流程上我建议这样走：

1. 从官方仓库拉取代码到 WSL2 环境内，建议放在/opt/openclaw这类统一目录下。
2. 进入项目目录执行依赖安装，需要耐心等 npm 把依赖拉完，网络不稳定时容易中断，中断了直接重跑即可。
3. 执行初始化命令生成配置目录，这里会创建默认的配置文件，内容包括模型接入方式、监听端口、Skill 目录等。
4. 编辑配置文件，指定大模型后端地址。
5. 启动服务，确认端口监听正常。

这里补充一个经验：不要把 OpenClaw 装在 Windows 原生文件系统里再通过 WSL2 访问，跨文件系统的 IO 性能很差，而且容易出现文件权限问题。直接放在 WSL2 内部的 Linux 文件系统里，后续调试会顺利很多。

3.4 接入本地大模型：Ollama + Qwen2.5

OpenClaw 支持通过 API 方式接入大模型算力，也支持指向本地模型服务。我这边为了内网可控性和成本考虑，选择用 Ollama 部署 Qwen2.5:3B。这个模型参数量不大，部署门槛低，作为功能联调已经足够。

Ollama 装完后执行：

ollama pull qwen2.5:3b ollama serve

ollama 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: ->