项目简介

大家好，分享一下我最近在做的开源项目 OpenClaw Java —— 基于 Spring Boot 3.3 的 AI Agent Gateway 全栈实现，通过 WebSocket 自定义帧协议提供全功能 Agent 接口。

项目地址：https://github.com/yuenkang/openclaw-java

当前规模: 594 个 Java 源文件 + 17 个测试文件，约 88,500 行代码

为什么做这个项目？

目前 AI Agent 框架大多集中在 Python 和 TypeScript 生态，Java 社区相对缺少成熟的 Agent 运行时方案。OpenClaw Java 希望为 Java 开发者提供一个工程化的 AI Agent 运行时，支持多模型接入、多渠道对话、工具调用和会话管理等完整能力。

核心亮点

🤖 Agent 执行引擎

• 多轮对话循环：用户 → 大模型 → 工具调用 → 大模型 → 回复
• 多模型提供者：支持 Claude、GPT 系列、Ollama 本地模型、vLLM 等 OpenAI 兼容接口
• 内置工具链：命令执行 (Exec)、文件读写 (File)、浏览器控制 (Browser)、图片分析 (Image)
• 指令处理：快速回复、队列验证、Follow-up
• Hooks 系统：内置 Hook + Workspace Hook + 优先级管理
• Memory 系统：记忆索引、关键字搜索

📱 多渠道接入

支持通过即时通讯渠道与 AI Agent 对话，已实现的渠道适配器：

• 即时通讯 Bot — 私聊/群聊、图片收发、流式输出、会话管理、白名单
• 微信公众号 — SHA-1 签名验证、access_token 缓存、客服消息 API

渠道适配器采用插件化架构，方便扩展更多平台。

🌐 WebSocket 自定义协议

采用 req/res/event 三种帧类型的自定义协议：

// 请求帧
{"type":"req", "id":"1", "method":"agent.message", "params":{"message":"你好"}}
// 响应帧
{"type":"res", "id":"1", "ok":true, "payload":{...}}
// 事件帧
{"type":"event", "event":"agent.streaming", "payload":{...}}

支持三步安全握手、会话管理、Cron 定时任务、配置热重载等。

🔌 OpenAI 兼容 HTTP API

提供标准的 /v1/chat/completions 和 /v1/models 接口，可作为现有 OpenAI 客户端的后端使用。

架构设计

┌────────────────────────────────────────────────────┐
│                     openclaw-app                    │
│    Spring Boot 入口 + OpenAI 兼容 REST API          │
├──────────┬──────────┬──────────┬──────────────────┤
│ gateway  │  agent   │ channel  │     plugin       │
│ WebSocket│  大模型   │ 渠道适配  │      SPI         │
│ 会话管理  │  工具链   │ 消息归一化│    插件加载       │
│ Cron调度  │  Memory  │ 出站投递  │    注册中心       │
├──────────┴──────────┴──────────┴──────────────────┤
│                      common                        │
│  Config · Models · Protocol · Auth · Media · CLI   │
└────────────────────────────────────────────────────┘

模块说明：

• openclaw-common — 配置管理 (90+ 嵌套类型)、数据模型、协议、认证
• openclaw-gateway — WebSocket 服务、会话管理、方法路由、Cron 调度
• openclaw-agent — Agent 引擎、多模型提供者、内置工具、Hooks、Memory
• openclaw-channel — 渠道适配器、消息归一化、出站投递
• openclaw-plugin — SPI 插件加载器、注册中心
• openclaw-app — Spring Boot 入口、模块桥接

技术栈

• Spring Boot 3.3 — Web + WebSocket + Scheduling
• Jackson — JSON 序列化
• OkHttp — HTTP 客户端
• Caffeine — 本地缓存
• Lombok — 代码简化
• 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 客户端即可与 Agent 对话。

持久化设计

• 会话历史 — JSONL 格式对话记录，Bot 重启自动恢复最近 50 条上下文
• 用量追踪 — 多模型 token 用量统计和成本估算
• 会话元数据 — JSON 原子写入，保证数据一致性

开发历程

项目经历了 33 个迭代 Phase：

• Phase 1–6 — 基础框架 + Gateway + Agent + 渠道 + 测试
• Phase 7–18 — Agent 高级功能 + Gateway 深度扩展
• Phase 19–23 — 工具链 + 认证 + CLI + 渠道类型定义
• Phase 24–28 — 编译修复 + 基础设施补齐
• Phase 29–31 — 渠道 Bot 完整层 + 微信公众号
• Phase 32–33 — 集成测试 + 浏览器控制 + 图片处理 + 持久化

未来计划

• 更多渠道适配（飞书、钉钉等）
• 向量数据库 Memory 后端
• 插件市场
• Web 管理面板
• Docker 一键部署

总结

OpenClaw Java 致力于成为 Java 生态中功能完整的 AI Agent Gateway。无论你是想在生产环境部署 AI Agent，还是想学习 Agent 架构设计，都欢迎来看看源码。

欢迎 Star、提 Issue 和 PR！

---

License: MIT