龙虾PRO

登录

如今全网 AI Agent 相关文章九成是空泛架构科普，满屏流程图、理论概念，Java 开发看完依旧不知道如何把本地自托管 AI 网关接入现有业务系统。

绝大多数后端开发者卡在同一个落地难题：Java 业务工程如何低成本接入自主可控的 AI 智能代理，不绑定厂商 API、不侵入原有业务代码、支持随时切换大模型。

OpenClaw 自托管 AI 网关完美解决该痛点，它不属于闭源 SDK，无需对接厂商私有接口，本地一键部署即可标准化输出 OpenAI 兼容 REST 接口。

本文摒弃空洞理论，完整走完「网关部署→Spring Boot 工程分层封装→统一 AI 接口对外输出」全流程，所有代码可直接复制运行，适配生产环境分层规范，附带流式对话、熔断安全等企业级优化方案，真正实现能上线、可维护、易扩展的 Java AI Agent 落地。

一、OpenClaw 在 Java 业务架构中的核心定位

OpenClaw 本质是私有化部署 AI 中转网关，在整套系统中承担 AI 能力统一调度角色，核心特性：

  1. 完全自托管：部署在自有服务器 / 本地设备，模型密钥、会话数据自主管控，无第三方数据外泄风险；
  2. 标准 HTTP 对外接口：兼容 OpenAI 接口规范，Java 侧无需学习专属 SDK，仅通过 HTTP 请求调用；
  3. 多模型统一兼容：后端可接入 GPT、Gemini、Anthropic、OpenRouter 等主流大模型，切换模型仅改网关配置，业务代码零改动；
  4. 独立服务解耦：Spring Boot 工程仅作为调用方，把 OpenClaw 当成普通第三方微服务，架构分层清晰。

标准调用链路地址示例：

plaintext

http://网关IP:18789/v1/chat/completions

Java 侧无需引入任何 OpenClaw 专属依赖，仅依靠 Spring 原生 HTTP 工具即可完成交互。

二、前置操作：部署并初始化 OpenClaw 网关

编写 Java 代码前，必须完成网关部署、参数配置，保证接口可正常连通。

1. 一键安装启动（Linux / 云服务器通用）

bash

运行

# 执行官方安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash
# 初始化配置向导
openclaw setup

初始化流程按需填写配置：

  • 选择目标大模型服务商；
  • 填入对应服务商 API Key；
  • 确认网关监听端口（默认 18789，无需修改）。

2. 核心关键配置记录

全局配置文件路径：~/.openclaw/openclaw.json

两种认证方式任选其一：

  1. 配置文件内写入网关访问 Token；
  2. 环境变量注入 Token（推荐服务器部署，更安全）

bash

运行

export OPENCLAW_GATEWAY_TOKEN=自定义高强度密钥

开发 Spring Boot 仅需留存两个核心参数：

  • 网关基础地址：http://xxx:18789
  • 接口鉴权 Token：Bearer 认证凭证

三、从零搭建 Spring Boot 3.x 集成工程

1. 核心 Maven 依赖

仅需 Web 基础依赖，无需额外 AI 第三方包，轻量化无冗余：

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. 标准化分层工程目录（企业级规范）

plaintext

src/main/java/com/lobsterpro/ai
├── config          // RestClient全局配置、网关参数注入
│   └── OpenClawConfig.java
├── controller      // 对外统一AI接口，提供前端/第三方调用
│   └── AiChatController.java
├── service         // AI调用业务封装层，隔离底层HTTP逻辑
│   └── OpenClawAiService.java
└── dto             // 网关请求/响应实体，解耦业务与第三方结构
    ├── MessageDTO.java
    ├── OpenClawChatReq.java
    └── OpenClawChatResp.java

3. 统一 DTO 实体封装（解耦设计，适配接口迭代）

MessageDTO 对话消息实体

java

运行

package com.lobsterpro.ai.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class MessageDTO {
    // 角色：system/user/assistant
    private String role;
    // 对话内容
    private String content;
}

OpenClawChatReq 网关请求体

java

运行

package com.lobsterpro.ai.dto;
import lombok.Data;
import java.util.List;

@Data
public class OpenClawChatReq {
    // 指定模型名称
    private String model;
    // 完整对话上下文
    private List<MessageDTO> messages;
    // 流式输出开关，true返回分段流，false一次性返回完整结果
    private Boolean stream = false;
}

OpenClawChatResp 网关返回体

java

运行

package com.lobsterpro.ai.dto;
import lombok.Data;

@Data
public class OpenClawChatResp {
    private String id;
    private String model;
    private Choice[] choices;

    @Data
    public static class Choice {
        private MessageDTO message;
    }
}

设计优势：后续 OpenClaw 接口字段迭代、新增参数，仅修改 DTO 实体，上层 Controller、Service 业务代码完全不用改动。

4. RestClient 全局配置（SpringBoot3 原生推荐，替代 RestTemplate）

java

运行

package com.lobsterpro.ai.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.web.client.RestClient;

@Configuration
public class OpenClawConfig {

    @Value("${openclaw.gateway.base-url}")
    private String gatewayBaseUrl;

    @Value("${openclaw.gateway.token}")
    private String gatewayAuthToken;

    @Bean
    public RestClient openClawRestClient(RestClient.Builder builder) {
        return builder
                .baseUrl(gatewayBaseUrl)
                .defaultHeaders(header -> {
                    header.set(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE);
                    if (gatewayAuthToken != null && !gatewayAuthToken.isBlank()) {
                        header.set(HttpHeaders.AUTHORIZATION, "Bearer " + gatewayAuthToken);
                    }
                })
                .build();
    }
}

5. Service 业务封装层（隔离底层 HTTP，统一 AI 调用逻辑）

java

运行

package com.lobsterpro.ai.service;

import com.lobsterpro.ai.dto.MessageDTO;
import com.lobsterpro.ai.dto.OpenClawChatReq;
import com.lobsterpro.ai.dto.OpenClawChatResp;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;
import java.util.List;

@Service
public class OpenClawAiService {

    private final RestClient openClawRestClient;

    // 构造注入HTTP客户端
    public OpenClawAiService(RestClient openClawRestClient) {
        this.openClawRestClient = openClawRestClient;
    }

    /**
     * 普通一次性对话接口
     * @param userText 用户提问内容
     * @return AI完整回答
     */
    public String singleChat(String userText) {
        // 组装请求参数
        OpenClawChatReq req = new OpenClawChatReq();
        req.setModel("gpt-4o");
        req.setStream(false);
        req.setMessages(List.of(new MessageDTO("user", userText)));

        // 调用OpenClaw网关接口
        OpenClawChatResp resp = openClawRestClient.post()
                .uri("/v1/chat/completions")
                .body(req)
                .retrieve()
                .body(OpenClawChatResp.class);

        // 空值校验，避免空指针异常
        if (resp == null || resp.getChoices() == null || resp.getChoices().length == 0) {
            return "AI网关返回数据为空，请稍后重试";
        }
        return resp.getChoices()[0].getMessage().getContent();
    }
}

6. 对外统一 AI 控制层（前端 / 第三方系统调用入口）

java

运行

package com.lobsterpro.ai.controller;

import com.lobsterpro.ai.service.OpenClawAiService;
import lombok.Data;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/business/ai")
public class AiChatController {

    private final OpenClawAiService aiService;

    public AiChatController(OpenClawAiService aiService) {
        this.aiService = aiService;
    }

    /**
     * 同步对话统一接口
     */
    @PostMapping("/chat/sync")
    public ResponseEntity<String> syncChat(@RequestBody ChatParam param) {
        String answer = aiService.singleChat(param.getMessage());
        return ResponseEntity.ok(answer);
    }

    /**
     * 前端入参接收实体
     */
    @Data
    public static class ChatParam {
        private String message;
    }
}

调用测试地址：POST /business/ai/chat/sync，传入 JSON 参数即可完成完整链路：Spring Boot → OpenClaw 网关 → 大模型。

四、进阶扩展：流式 SSE 实时对话（ChatGPT 式打字输出效果）

前端聊天页面需要分段实时输出文字时，开启 stream 流式参数，搭配 SseEmitter 实现长连接推送，简易示例：

java

运行

@GetMapping("/chat/stream")
public SseEmitter streamChat(@RequestParam String message) {
    SseEmitter emitter = new SseEmitter(30000L);
    // 异步线程发起网关流式请求，分段推送token至前端
    new Thread(() -> {
        // WebClient订阅OpenClaw流式返回，逐段封装SSE消息推送
    }).start();
    return emitter;
}

五、生产环境落地核心最佳实践

1. 安全规范

  1. OpenClaw 网关禁止直接暴露公网，仅允许内网 Spring Boot 服务访问；
  2. 公网访问需前置 Nginx，增加 IP 白名单、接口限流；
  3. 网关鉴权 Token、模型 API Key 统一存入配置中心，禁止硬编码进代码；

2. 高可用稳定性优化

  1. 引入 Resilience4j 组件，对 AI 接口增加超时、重试、熔断降级策略，防止大模型响应缓慢拖垮业务；
  2. 统一捕获网关调用异常，自定义错误返回体，便于前端异常处理；
  3. 增加接口请求日志记录，留存对话上下文、响应耗时，方便问题排查。

3. 模型无感切换核心优势

整套架构最大价值：切换大模型完全不改动 Java 业务代码，仅两种修改方式：

  1. 修改 OpenClaw 网关配置，更换默认模型；
  2. 调用时动态修改请求体 model 字段，按需切换不同模型。

六、总结

市面上绝大多数 AI 相关教程只停留在概念和 Demo 层面，很难直接落地进企业 Java 业务系统。OpenClaw 作为私有化 AI 网关，完美解决 Java 后端接入 AI 的几大痛点：厂商绑定、代码耦合、数据不可控、模型切换成本高。

本文提供分层清晰、规范可上线的 Spring Boot 集成方案，把 AI 能力当成普通微服务调用，贴合传统后端开发思维，无需重构现有业务架构。真正有价值的 AI 落地，不是花哨的 PPT 架构图，而是稳定、可控、易维护、能直接投入生产运行的工程代码。

🦞 龙虾PRO | longxiapro.com — 企业级龙虾智能运维·OpenClaw全栈技术平台

专注龙虾智能化、OpenClaw部署、AI智能运维、企业级龙虾架构、自动化流程、智能排障、龙虾技术实战； 全网最全龙虾技术文档、教程、源码、问题解答、动态资讯、行业方案，尽在龙虾PRO。

遇到OpenClaw部署报错、龙虾运维难题、智能体搭建、企业级龙虾方案、技术咨询、最新龙虾动态， 请立即访问官网：longxiapro.com

深耕龙虾AI智能生态，赋能企业数字化运维，从入门到精通，从部署到生产，学龙虾·用龙虾·精通龙虾，认准龙虾PRO。

粤ICP备2024170283号-2