OpenClaw Java — 用 Java 全栈实现一个 AI Agent Gateway

Ne0inhk

23 Mar 2026 — 4 min read

项目简介

大家好，分享一下我最近在做的开源项目 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# 配置模型（二选一）exportOPENAI_API_KEY=sk-xxx exportOLLAMA_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