项目背景
Java 生态在 AI Agent 运行时方面相对空白，OpenClaw Java 旨在填补这一缺口。这是一个基于 Spring Boot 3.3 构建的全栈实现，通过 WebSocket 自定义帧协议提供完整的 Agent 接口能力。
目前代码规模已达 594 个 Java 源文件 + 17 个测试文件，约 88,500 行代码。源码仓库位于 https://github.com/yuenkang/openclaw-java。
核心架构
系统采用模块化设计，主要包含以下部分：
┌────────────────────────────────────────────────────┐
│ openclaw-app │
│ Spring Boot 入口 + OpenAI 兼容 REST API │
├──────────┬──────────┬──────────┬──────────────────┤
│ gateway │ agent │ channel │ plugin │
│ WebSocket│ 大模型 │ 渠道适配 │ SPI │
│ 会话管理 │ 工具链 │ 消息归一化│ 插件加载 │
│ Cron 调度 │ Memory │ 出站投递 │ 注册中心 │
├──────────┴──────────┴──────────┴──────────────────┤
│ common │
│ Config · Models · Protocol · Auth · Media · CLI │
└────────────────────────────────────────────────────┘
- openclaw-common：配置管理、数据模型、协议定义及认证模块。
- openclaw-gateway：负责 WebSocket 服务、会话管理及方法路由。
- openclaw-agent：核心引擎，支持多模型提供者、内置工具链及 Hooks 系统。
- openclaw-channel：渠道适配器层，实现消息归一化与出站投递。
- openclaw-plugin：基于 SPI 的插件加载器与注册中心。
关键特性
1. Agent 执行引擎
支持多轮对话循环（用户 → 大模型 → 工具调用 → 回复），内置命令执行、文件读写、浏览器控制及图片分析等工具链。记忆系统支持索引与关键字搜索，配合优先级管理的 Hooks 机制，满足复杂业务逻辑。
2. 多渠道接入
采用插件化架构扩展渠道，目前已实现即时通讯 Bot（支持私聊/群聊、流式输出）及微信公众号（SHA-1 签名验证、客服消息）。未来计划覆盖飞书、钉钉等平台。
3. 通信协议
WebSocket 采用自定义帧协议，包含 req/res/event 三种类型，支持三步安全握手、Cron 定时任务及配置热重载。同时提供标准的 /v1/chat/completions 和 /v1/models 接口，兼容现有 OpenAI 客户端。
技术选型
- 框架：Spring Boot 3.3 (Web + WebSocket + Scheduling)
- 序列化：Jackson
- 网络：OkHttp
- 缓存：Caffeine
- 沙箱：docker-java
- 测试：JUnit 5 + Mockito
快速体验
环境要求 Java 17+ 及 Maven 3.8+。
# 克隆并构建
git clone https://github.com/yuenkang/openclaw-java.git
cd openclaw-java
mvn clean install
# 配置模型（二选一）
export OPENAI_API_KEY=sk-xxx
# export OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
# 启动服务
mvn spring-boot:run -pl openclaw-app
服务启动后监听 ws://127.0.0.1:3578/ws，连接 WebSocket 客户端即可开始对话。
持久化与演进
会话历史以 JSONL 格式存储，Bot 重启可自动恢复最近 50 条上下文。用量追踪功能支持多模型 token 统计与成本估算。项目历经 33 个迭代阶段，从基础框架搭建到集成测试、浏览器控制及图片处理，逐步完善基础设施。
后续规划包括向量数据库 Memory 后端、插件市场及 Web 管理面板，支持 Docker 一键部署。
License: MIT
