OpenClaw-Java 技术栈深度解析

项目地址：https://github.com/yuenkang/openclaw-java 作者：yuenkang 星数：⭐ 35 | Fork：🔱 11

项目概述

OpenClaw-Java 是 OpenClaw 的 Java 全栈实现，基于 Spring Boot 的 AI Agent Gateway。采用微服务架构，包含 14 个独立模块，提供完整的 AI 智能体平台解决方案。

技术栈总览

Java 17 LTS
├── Spring Boot 3.3.7 (核心框架)
│   ├── Spring Framework 6.x
│   ├── Spring WebFlux (响应式 Web）
│   ├── Spring Security (安全框架)
│   └── Spring Data (数据访问)
├── Jackson 2.17.3 (JSON 序列化)
├── Caffeine 3.1.8 (高性能缓存)
├── OkHttp 4.12.0 (HTTP 客户端 + SSE)
├── Docker Java 3.4.1 (容器管理)
├── Playwright 1.58.0 (浏览器自动化)
├── Flexmark 0.64.8 (Markdown 处理)
├── Lombok 1.18.34 (代码生成)
└── MapStruct 1.6.3 (Bean 映射)

项目结构

14 个微服务模块

openclaw-java/
├── openclaw-common (通用模块)
├── openclaw-node (节点管理)
├── openclaw-gateway (API 网关)
├── openclaw-media (媒体处理)
├── openclaw-sandbox (沙箱环境)
├── openclaw-memory (记忆系统)
├── openclaw-providers (AI 提供商)
├── openclaw-hooks (钩子系统)
├── openclaw-browser (浏览器自动化)
├── openclaw-agent (智能体核心)
├── openclaw-autoreply (自动回复)
├── openclaw-channel (消息通道)
├── openclaw-plugin (插件系统)
└── openclaw-app (应用主模块)

核心依赖详解

1. Spring Boot 3.3.7

特性：

✅ Java 17+ 支持
✅ 响应式 WebFlux（非阻塞 I/O）
✅ 原生镜像支持（GraalVM）
✅ 虚拟线程支持
✅ 可观测性增强（Micrometer）

应用场景：

openclaw-gateway - API 网关（响应式路由）
openclaw-channel - 消息通道（SSE 推送）
所有模块的启动和配置

2. Jackson 2.17.3

特性：

高性能 JSON 序列化/反序列化
支持 JSON Schema 验证
支持 YAML、XML、CBOR 等多种格式
与 Spring Boot 深度集成

应用场景：

API 请求/响应序列化
配置文件解析
消息格式转换

3. Caffeine 3.1.8

特性：

高性能本地缓存
基于 W-TinyLFU 算法
支持过期策略（TTL、基于大小）
支持异步加载
Spring Boot 自动配置支持

应用场景：

API 路由缓存（openclaw-gateway）
AI 模型响应缓存
用户会话缓存
配置项缓存

4. OkHttp 4.12.0

特性：

高效 HTTP/2 和 HTTP/3 支持
连接池和连接复用
自动 GZIP 压缩
响应缓存
支持 WebSocket
SSE（Server-Sent Events）支持

应用场景：

AI 模型 API 调用
飞书/钉钉等平台对接
外部服务集成

5. Docker Java 3.4.1

特性：

Docker 容器管理
镜像构建和拉取
容器网络和存储管理
支持沙箱环境隔离

应用场景：

openclaw-sandbox - 代码执行沙箱
容器化部署
资源隔离

6. Playwright 1.58.0

特性：

跨浏览器支持（Chrome、Firefox、WebKit）
支持 JavaScript 渲染
自动等待和重试
网络拦截和 Mock
截图和 PDF 生成
Headless 模式支持

应用场景：

openclaw-browser - 浏览器自动化
网页内容抓取
表单自动填写
截图和 PDF 生成

7. Flexmark 0.64.8

特性：

CommonMark 规范实现
扩展语法支持（表格、任务列表、脚注等）
HTML 渲染
AST 转换和解析

应用场景：

Markdown 文档渲染
AI 输出格式转换
用户输入解析

8. 开发工具

Lombok 1.18.34：

自动生成 Getter/Setter
自动生成 Builder 模式
日志注解（@Slf4j）
数据类注解（@Data, @Value）

MapStruct 1.6.3：

类型安全的 Bean 映射
编译时代码生成
支持自定义映射策略
与 Lombok 集成

模块架构设计

1. 分层架构

API 层 (openclaw-gateway)
    ↓
业务逻辑层 (openclaw-agent, openclaw-autoreply)
    ↓
数据层 (openclaw-memory, openclaw-media)
    ↓
基础设施层 (openclaw-sandbox, openclaw-browser, openclaw-providers)

2. 事件驱动架构

openclaw-hooks 提供事件发布/订阅
模块间解耦
异步处理支持
横切关注点（日志、监控、安全）

3. 微服务架构

14 个独立模块
每个模块职责单一
通过 Maven 模块化组织
支持独立部署和水平扩展

核心功能模块

1. openclaw-agent（智能体核心）

职责：

AI 模型调用（OpenAI、Anthropic、本地模型）
Prompt 模板管理
Tool 调用
ReAct 推理

依赖：

OkHttp（HTTP 客户端）
Jackson（序列化）
openclaw-memory（历史记录）

2. openclaw-memory（记忆系统）

职责：

长期记忆存储
短期记忆缓存
记忆检索（RAG）
记忆清理和过期

依赖：

Caffeine（本地缓存）
可能的向量数据库集成

3. openclaw-sandbox（沙箱环境）

职责：

代码执行隔离
Docker 容器管理
安全限制
资源配额

依赖：

Docker Java（容器管理）
Playwright（浏览器沙箱）

4. openclaw-browser（浏览器自动化）

职责：

网页内容抓取
表单自动填写
截图和 PDF
交互操作

依赖：

Playwright 1.58.0
OkHttp（网络请求）

5. openclaw-providers（AI 提供商）

职责：

OpenAI 接入
Anthropic 接入
本地模型接入（Ollama）
模型切换和路由

依赖：

OkHttp（HTTP 客户端）
Jackson（序列化）

6. openclaw-channel（消息通道）

职责：

多平台消息接入
消息格式转换
消息队列管理
Webhook 处理

依赖：

Spring WebFlux（响应式处理）
SSE（Server-Sent Events）
可能的 WebSocket 支持

7. openclaw-plugin（插件系统）

职责：

插件加载和卸载
插件依赖管理
插件间通信
插件市场支持

依赖：

Java SPI（Service Provider Interface）
可能的类加载器隔离

8. openclaw-gateway（API 网关）

职责：

API 路由和转发
认证和授权
限流和熔断
请求/响应日志

依赖：

Spring WebFlux（响应式 Web）
Spring Security Gateway
Caffeine（路由缓存）

性能优化策略

1. 响应式编程

java

// Spring WebFlux 示例
@RestController
public class ChatController {

    @GetMapping("/chat")
    public Flux<String> chat(@RequestParam String message) {
        return Flux.fromStream(model.stream(message));
    }
}

优势：

非阻塞 I/O
背压支持
高并发处理能力

2. 缓存策略

java

// Caffeine 缓存配置
Cache<String, Response> cache = Caffeine.newBuilder()
    .maximumSize(10_000)
    .expireAfterWrite(10, TimeUnit.MINUTES)
    .build();

策略：

多级缓存（本地 + 分布式）
LRU 淘汰
TTL 过期
基于大小的淘汰

3. 连接池

java

// OkHttp 连接池配置
OkHttpClient client = new OkHttpClient.Builder()
    .connectionPool(new ConnectionPool(5, 5, TimeUnit.MINUTES))
    .build();

优化：

HTTP 连接池
数据库连接池
Docker 连接复用

安全设计

1. Spring Security

java

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .anyRequest().authenticated())
            .oauth2ResourceServer(oauth2 -> oauth2.jwt(jwt -> jwt.decoder(jwtDecoder())));
        return http.build();
    }
}

特性：

JWT Token 认证
OAuth2 支持
CORS 配置
防护：CSRF、XSS

2. 沙箱隔离

java

// Docker 容器隔离
DockerClient docker = DockerClientBuilder.getInstance().build();
CreateContainerResponse container = docker.createContainerCmd("sandbox-image")
    .withCpuCount(1L)
    .withMemory(512 * 1024 * 1024L)
    .exec();

安全措施：

CPU/内存限制
网络隔离
文件系统隔离
特权限制

扩展性设计

1. 插件系统

java

// SPI 插件定义
@SPI
public interface Plugin {
    String getName();
    void execute(Context context);
}

扩展点：

Java SPI 机制
插件生命周期管理
插件间通信
热加载/卸载

2. Provider 抽象

java

// AI 提供商接口
public interface AIProvider {
    String getName();
    ChatResponse chat(List<Message> messages);
}

扩展点：

多 AI 提供商支持
统一接口设计
易于扩展新模型

3. Hook 机制

java

// Hook 注解
@Hook(event = "before_chat")
public void logBeforeChat(ChatEvent event) {
    log.info("Before chat: {}", event.getMessage());
}

扩展点：

预定义扩展点
事件监听
拦截器链

部署架构

单体部署

yaml

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw-java:latest
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=production

微服务部署

yaml

# docker-compose.yml
services:
  gateway:
    image: openclaw/gateway:latest
    ports:
      - "8080:8080"

  agent:
    image: openclaw/agent:latest
    depends_on:
      - gateway

  memory:
    image: openclaw/memory:latest
    depends_on:
      - agent

与其他 Java AI 项目对比

特性	OpenClaw-Java	Spring AI	LangChain4j
架构	微服务（14 模块）	单体/微服务	库/工具
浏览器自动化	✅ Playwright	❌ 无	❌ 无
沙箱隔离	✅ Docker	❌ 无	❌ 无
插件系统	✅ 有	❌ 无	✅ 有
响应式编程	✅ WebFlux	✅ 有	❌ 无
记忆系统	✅ 独立模块	✅ 有	✅ 有
多提供商	✅ 独立模块	✅ 支持	✅ 支持

最佳实践

1. 模块间通信

java

// 使用事件驱动
@EventListener
public void handleChatEvent(ChatEvent event) {
    // 处理聊天事件
}

2. 错误处理

java

// 统一异常处理
@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(AIException.class)
    public ResponseEntity<ErrorResponse> handleAIException(AIException e) {
        return ResponseEntity.status(500)
            .body(new ErrorResponse(e.getMessage()));
    }
}

3. 监控和追踪

java

// Micrometer 监控
@Timed("ai.model.call")
public String callModel(String prompt) {
    return model.generate(prompt);
}

总结

OpenClaw-Java 是一个设计精良的微服务架构 AI Agent 平台，具有以下特点：

优势：

✅ 14 个模块化设计，职责清晰
✅ 基于 Spring Boot 3.x，技术栈现代
✅ 响应式编程，高并发支持
✅ 集成 Playwright，支持浏览器自动化
✅ Docker 沙箱隔离，执行安全
✅ 插件系统，易于扩展
✅ 多 AI 提供商支持

特色功能：

🎯 完整的记忆系统（长期 + 短期）
🎯 浏览器自动化能力
🎯 沙箱环境隔离
🎯 插件生态系统
🎯 消息通道抽象

适用场景：

企业级 AI 智能体平台
多租户 AI 服务
需要浏览器自动化的场景
需要安全代码执行的场景

学习价值：

微服务架构设计
Spring Boot 3.x 最佳实践
响应式编程模式
插件系统设计
沙箱安全隔离

更新时间: 2026-03-14 分类: Java AI 平台 | OpenClaw | 架构分析

OpenClaw-Java 技术栈深度解析 ​

项目概述 ​

技术栈总览 ​

项目结构 ​

14 个微服务模块 ​

核心依赖详解 ​

1. Spring Boot 3.3.7 ​

2. Jackson 2.17.3 ​

3. Caffeine 3.1.8 ​

4. OkHttp 4.12.0 ​

5. Docker Java 3.4.1 ​

6. Playwright 1.58.0 ​

7. Flexmark 0.64.8 ​

8. 开发工具 ​

模块架构设计 ​

1. 分层架构 ​

2. 事件驱动架构 ​

3. 微服务架构 ​

核心功能模块 ​

1. openclaw-agent（智能体核心） ​

2. openclaw-memory（记忆系统） ​

3. openclaw-sandbox（沙箱环境） ​

4. openclaw-browser（浏览器自动化） ​

5. openclaw-providers（AI 提供商） ​

6. openclaw-channel（消息通道） ​

7. openclaw-plugin（插件系统） ​

8. openclaw-gateway（API 网关） ​

性能优化策略 ​

1. 响应式编程 ​

2. 缓存策略 ​

3. 连接池 ​

安全设计 ​

1. Spring Security ​

2. 沙箱隔离 ​

扩展性设计 ​

1. 插件系统 ​

2. Provider 抽象 ​

3. Hook 机制 ​

部署架构 ​

单体部署 ​

微服务部署 ​

与其他 Java AI 项目对比 ​

最佳实践 ​

1. 模块间通信 ​

2. 错误处理 ​

3. 监控和追踪 ​

总结 ​

OpenClaw-Java 技术栈深度解析

项目概述

技术栈总览

项目结构

14 个微服务模块

核心依赖详解

1. Spring Boot 3.3.7

2. Jackson 2.17.3

3. Caffeine 3.1.8

4. OkHttp 4.12.0

5. Docker Java 3.4.1

6. Playwright 1.58.0

7. Flexmark 0.64.8

8. 开发工具

模块架构设计

1. 分层架构

2. 事件驱动架构

3. 微服务架构

核心功能模块

1. openclaw-agent（智能体核心）

2. openclaw-memory（记忆系统）

3. openclaw-sandbox（沙箱环境）

4. openclaw-browser（浏览器自动化）

5. openclaw-providers（AI 提供商）

6. openclaw-channel（消息通道）

7. openclaw-plugin（插件系统）

8. openclaw-gateway（API 网关）

性能优化策略

1. 响应式编程

2. 缓存策略

3. 连接池

安全设计

1. Spring Security

2. 沙箱隔离

扩展性设计

1. 插件系统

2. Provider 抽象

3. Hook 机制

部署架构

单体部署

微服务部署

与其他 Java AI 项目对比

最佳实践

1. 模块间通信

2. 错误处理

3. 监控和追踪

总结