项目简介
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 社区相对缺乏成熟的运行时方案。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 架构设计，都欢迎参考源码。
License: MIT
