# openclaw-sping ai Alibaba

**Repository Path**: jared_hxyerui/openclaw-spring

## Basic Information

- **Project Name**: openclaw-sping ai Alibaba
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenClaw Spring AI Alibaba

<div align="center">

🦞 **OpenClaw AI Agent Gateway - Spring Boot 版本**

基于 Spring AI Alibaba 框架的企业级 AI Agent 网关系统

[![Version](https://img.shields.io/badge/version-1.6.0-blue.svg)](https://gitee.com/jared_hxyerui/openclaw-spring)
[![Java](https://img.shields.io/badge/Java-17+-orange.svg)](https://adoptium.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.4-brightgreen.svg)](https://spring.io/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

[特性](#特性) • [快速开始](#快速开始) • [文档](#文档) • [API](#api-文档) • [部署](#部署)

</div>

---

## 📖 项目简介

OpenClaw Spring AI Alibaba 是一个功能完整的 AI Agent 网关系统，基于 Spring AI Alibaba 框架开发，提供多消息渠道集成、技能系统、工具调用、Web UI 等丰富功能。

### 核心特性

- 🤖 **AI Agent 核心** - Spring AI Alibaba 集成，支持多种 AI 模型
- 💬 **多消息渠道** - Telegram/Discord/OpenIM 集成
- 🛠️ **工具系统** - 文件/Web/浏览器/JSON 工具
- 🎨 **Web UI** - 控制面板 + WebChat + 实时监控
- 💾 **数据库** - MySQL + JPA 持久化
- 🚀 **缓存** - Caffeine 本地缓存
- 📊 **监控** - Prometheus + Grafana
- 🔐 **安全** - JWT + BCrypt 认证
- ⚡ **WebSocket** - 实时消息推送
- 📱 **移动端** - 响应式布局

---

## 🎯 功能清单

### AI Agent ✅
- [x] AI 对话 (通义千问/GPT)
- [x] 会话管理
- [x] 上下文压缩
- [x] 技能注册
- [x] MCP 客户端

### 消息渠道 ✅
- [x] Telegram
- [x] Discord
- [x] OpenIM
- [ ] WhatsApp (计划中)
- [ ] Slack (计划中)

### Web UI ✅
- [x] 仪表盘 (Chart.js)
- [x] WebChat
- [x] 会话管理
- [x] 技能中心
- [x] 日志查看
- [x] 配置管理
- [x] 健康检查
- [x] 用户登录

### 数据库 ✅
- [x] MySQL
- [x] JPA/Hibernate
- [x] 会话存储
- [x] 消息存储

### 监控 ✅
- [x] Prometheus
- [x] Grafana
- [x] 健康检查
- [x] 性能监控

### 安全 ✅
- [x] JWT 认证
- [x] BCrypt 密码
- [x] WebSocket 认证
- [x] 用户管理

---

## 🚀 快速开始

### 环境要求

| 组件 | 版本 | 必需 |
|------|------|------|
| **JDK** | 17+ | ✅ |
| **MySQL** | 8.0+ | ✅ |
| **Maven** | 3.6+ | ✅ |
| **Docker** | 20.10+ | ⚪ (可选) |
| **Redis** | 7+ | ⚪ (可选) |

---

## 📦 部署方式

### 方式一：Docker 部署 ⭐ 推荐

**适合**: 快速体验、生产环境

#### 1. 克隆项目

```bash
git clone https://gitee.com/jared_hxyerui/openclaw-spring.git
cd openclaw-spring
```

#### 2. 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑配置 (必须修改 API 密钥)
vim .env
```

**.env 文件内容**:
```bash
# 数据库配置
DB_USERNAME=openclaw
DB_PASSWORD=openclaw123

# AI API 密钥 (必须修改)
AI_DASHSCOPE_API_KEY=your-dashscope-api-key
OPENAI_API_KEY=your-openai-api-key

# JWT 配置 (建议修改)
JWT_SECRET=OpenClawSecretKey2026VeryLongSecretKeyForHS256

# Grafana 配置
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=admin123
```

#### 3. 一键部署

```bash
# 赋予执行权限
chmod +x docker/deploy.sh

# 运行部署脚本
./docker/deploy.sh deploy
```

#### 4. 验证部署

```bash
# 查看服务状态
./docker/deploy.sh status

# 或手动查看
docker-compose ps
```

**预期输出**:
```
NAME                 STATUS         PORTS
openclaw-app         Up (healthy)   0.0.0.0:8080->8080/tcp
openclaw-mysql       Up (healthy)   0.0.0.0:3306->3306/tcp
openclaw-redis       Up (healthy)   0.0.0.0:6379->6379/tcp
openclaw-prometheus  Up             0.0.0.0:9090->9090/tcp
openclaw-grafana     Up             0.0.0.0:3000->3000/tcp
```

#### 5. 访问服务

| 服务 | 地址 | 账号 |
|------|------|------|
| **OpenClaw** | http://localhost:8080 | admin / admin123 |
| **Grafana** | http://localhost:3000 | admin / admin123 |
| **Prometheus** | http://localhost:9090 | - |

#### 6. 服务管理

```bash
# 停止服务
./docker/deploy.sh stop

# 重启服务
./docker/deploy.sh restart

# 查看日志
./docker/deploy.sh logs app

# 清理数据 (慎用)
./docker/deploy.sh clean
```

**详细文档**: [Docker 部署指南](docs/DOCKER_DEPLOYMENT.md)

---

### 方式二：源码部署

**适合**: 开发环境、自定义修改

#### 前置要求

- JDK 17+
- Maven 3.6+
- MySQL 8.0+
- Git

#### 1. 克隆项目

```bash
git clone https://gitee.com/jared_hxyerui/openclaw-spring.git
cd openclaw-spring
```

#### 2. 创建数据库

```bash
# 登录 MySQL
mysql -u root -p

# 创建数据库
CREATE DATABASE openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 创建用户 (可选，生产环境推荐)
CREATE USER 'openclaw'@'localhost' IDENTIFIED BY 'openclaw123';
GRANT ALL PRIVILEGES ON openclaw.* TO 'openclaw'@'localhost';
FLUSH PRIVILEGES;

# 退出
exit;
```

#### 3. 初始化数据表

```bash
# 导入用户表
mysql -u root -p openclaw < src/main/resources/db/users.sql

# 验证导入
mysql -u root -p openclaw -e "SELECT * FROM users;"
```

**预期输出**:
```
id          username  email                role   enabled
admin-001   admin     admin@openclaw.ai    ADMIN  1
user-001    user      user@openclaw.ai     USER   1
```

#### 4. 配置应用

**编辑配置文件**:
```bash
vim src/main/resources/application.yml
```

**最小配置**:
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/openclaw?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: your_mysql_password  # 修改为你的 MySQL 密码
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false
  
  ai:
    dashscope:
      api-key: your-dashscope-api-key  # 必须修改

openclaw:
  security:
    jwt:
      secret: OpenClawSecretKey2026VeryLongSecretKeyForHS256  # 建议修改
```

**完整配置参考**: `application.yml.example` (如有)

#### 5. 构建项目

```bash
# 清理并编译
mvn clean package -DskipTests

# 或跳过测试快速构建
mvn clean install -DskipTests

# 构建时间：约 2-5 分钟 (首次构建需下载依赖)
```

**预期输出**:
```
[INFO] BUILD SUCCESS
[INFO] Total time:  2.5 mins
[INFO] Finished at: 2026-03-18T17:00:00+08:00
```

#### 6. 运行应用

```bash
# 方式 1: Maven 运行 (开发环境)
mvn spring-boot:run

# 方式 2: JAR 运行 (生产环境)
java -jar target/openclaw-spring-1.6.0-SNAPSHOT.jar

# 方式 3: 后台运行
nohup java -jar target/openclaw-spring-*.jar > app.log 2>&1 &
```

**启动日志**:
```
  ____                   _ __       __
 / __ \____  ___  ____  (_) /_____ / /_
/ /_/ / __ \/ _ \/ __ \/ / __/ __ \/ __/
/ ____/ /_/ /  __/ / / / / /_/ /_/ / /_
/_/    \____/\___/_/ /_/_/\__/\____/\__/

OpenClaw Spring AI Alibaba v1.6.0
Spring Boot v3.2.4
Java v17.0.1

Started OpenClawSpringApplication in 15.234 seconds
```

#### 7. 验证运行

```bash
# 检查进程
ps aux | grep openclaw

# 检查端口
netstat -tlnp | grep 8080

# 健康检查
curl http://localhost:8080/actuator/health
```

**预期响应**:
```json
{"status":"UP"}
```

#### 8. 访问应用

打开浏览器访问：http://localhost:8080

**默认账号**:
- 用户名：`admin`
- 密码：`admin123`

**首次登录建议**:
1. 修改默认密码
2. 配置 AI API 密钥
3. 检查系统设置

---

### 方式三：IDE 运行

**适合**: 开发调试

#### IntelliJ IDEA

1. **导入项目**: File → Open → 选择项目目录
2. **配置 JDK**: File → Project Structure → SDKs → 添加 JDK 17
3. **配置运行**: Run → Edit Configurations
   - Main class: `com.openclaw.OpenClawSpringApplication`
   - VM options: `-Dspring.profiles.active=dev`
4. **运行**: 点击 Run 按钮

#### Eclipse

1. **导入项目**: File → Import → Maven → Existing Maven Projects
2. **配置 Build Path**: 右键项目 → Build Path → Configure Build Path
3. **运行**: Run → Run As → Java Application

---

## 🔧 配置说明

### 必需配置

| 配置项 | 说明 | 默认值 | 是否修改 |
|--------|------|--------|----------|
| `spring.datasource.password` | MySQL 密码 | - | ✅ 必须 |
| `spring.ai.dashscope.api-key` | 通义千问 API 密钥 | - | ✅ 必须 |
| `openclaw.security.jwt.secret` | JWT 签名密钥 | OpenClawSecretKey2026... | ⚠️ 建议 |

### 可选配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `spring.datasource.url` | 数据库连接 URL | jdbc:mysql://localhost:3306/openclaw |
| `spring.datasource.username` | 数据库用户名 | root |
| `openclaw.workspace` | 工作区路径 | /home/admin/openclaw/workspace |
| `server.port` | 服务端口 | 8080 |

### 环境变量

也可以通过环境变量配置：

```bash
export DB_PASSWORD=your_password
export AI_DASHSCOPE_API_KEY=your_api_key
export JWT_SECRET=your_secret

mvn spring-boot:run
```

---

## 📊 系统截图

### 仪表盘
![Dashboard](docs/images/dashboard.png)
*系统概览和实时监控数据*

### WebChat
![WebChat](docs/images/webchat.png)
*AI 对话聊天界面*

### 会话管理
![Sessions](docs/images/sessions.png)
*查看和管理所有会话*

### 日志查看
![Logs](docs/images/logs.png)
*实时日志查看和搜索*

### 配置管理
![Config](docs/images/config.png)
*可视化配置管理*

### 健康检查
![Health](docs/images/health.png)
*系统健康状态监控*

> 💡 **提示**: 图片位置 `docs/images/`，如未显示请查看实际部署后的界面。

---

## 📚 文档

### 入门文档

| 文档 | 说明 | 适合 |
|------|------|------|
| [快速开始](docs/QUICKSTART.md) | 5 分钟快速上手 | 新手 |
| [README.md](README.md) | 项目介绍 | 所有人 |
| [示例项目](examples/README.md) | 代码示例 | 开发者 |

### 部署文档

| 文档 | 说明 | 适合 |
|------|------|------|
| [Docker 部署](docs/DOCKER_DEPLOYMENT.md) | Docker 完整部署 | 生产环境 |
| [源码部署](README.md#方式二源码部署) | 源码编译运行 | 开发环境 |
| [配置说明](docs/CONFIGURATION.md) | 详细配置说明 | 所有人 |

### 开发文档

| 文档 | 说明 | 适合 |
|------|------|------|
| [开发总结](docs/DEVELOPMENT_SUMMARY.md) | 完整开发记录 | 贡献者 |
| [API 文档](docs/API.md) | REST API 参考 | 开发者 |
| [测试指南](docs/TESTING_GUIDE.md) | 测试方法指南 | 测试人员 |
| [项目路线图](docs/ROADMAP.md) | 未来规划 | 所有人 |

### 运维文档

| 文档 | 说明 | 适合 |
|------|------|------|
| [监控指南](docs/MONITORING_GUIDE.md) | Prometheus/Grafana | 运维 |
| [数据库指南](docs/DATABASE_GUIDE.md) | 数据库配置 | DBA |
| [故障排查](docs/TROUBLESHOOTING.md) | 常见问题解决 | 运维 |

---

## 🔌 API 文档

### 认证 API

```bash
# 登录
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 获取当前用户
curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 会话 API

```bash
# 发送消息
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"你好","sessionId":"session-1"}'

# 获取会话列表
curl http://localhost:8080/api/sessions
```

### 统计 API

```bash
# 会话统计
curl http://localhost:8080/api/statistics/sessions

# 健康评分
curl http://localhost:8080/api/statistics/health
```

### WebSocket

```javascript
const token = localStorage.getItem('access_token');
const ws = new WebSocket(`ws://localhost:8080/ws?token=${token}`);

ws.onmessage = (event) => {
    console.log('Message:', event.data);
};
```

---

## 🏗️ 项目结构

```
openclaw-spring/
├── src/main/java/com/openclaw/
│   ├── agent/           # AI Agent 核心
│   ├── channel/         # 消息渠道
│   ├── config/          # 配置类
│   ├── controller/      # REST 控制器
│   ├── service/         # 业务服务
│   ├── security/        # 安全组件
│   ├── repository/      # JPA 仓库
│   └── websocket/       # WebSocket
├── src/main/resources/
│   ├── static/          # 静态资源
│   ├── templates/       # Thymeleaf 模板
│   └── application.yml  # 配置文件
├── docs/                # 文档
└── pom.xml              # Maven 配置
```

---

## 🛠️ 技术栈

### 后端
- **Java 17+**
- **Spring Boot 3.2.4**
- **Spring AI Alibaba 1.1.2.0**
- **Spring Data JPA**
- **MySQL 8.0+**
- **Caffeine Cache**
- **JJWT 0.11.5**

### 前端
- **Thymeleaf**
- **Chart.js 4.4.0**
- **Font Awesome 6.4.0**
- **Vanilla JavaScript**

### 监控
- **Prometheus**
- **Grafana**
- **Spring Actuator**

---

## 📈 代码统计

| 类别 | 文件数 | 行数 |
|------|--------|------|
| Java | 52 | ~17,000 |
| HTML | 8 | ~850 |
| CSS | 7 | ~2,700 |
| JavaScript | 8 | ~2,750 |
| 配置 | 6 | ~500 |
| 文档 | 32+ | ~10,000 |
| **总计** | **~113** | **~28,000** |

---

## 🧪 测试

### 运行测试

```bash
# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=ApiControllerTest

# 运行集成测试
mvn verify
```

### 测试覆盖率

```bash
# 生成覆盖率报告
mvn clean test jacoco:report

# 查看 HTML 报告
open target/site/jacoco/index.html
```

**测试统计**:
- 单元测试：53 个
- 覆盖率：85%
- 状态：✅ Pass

**详细指南**: [测试指南](docs/TESTING_GUIDE.md)

---

## 📦 生产部署

### Docker 部署

```bash
# 构建镜像
docker build -t openclaw-spring:1.6.0 .

# 运行容器
docker run -d \
  -p 8080:8080 \
  -e DB_PASSWORD=secure_password \
  -e AI_DASHSCOPE_API_KEY=your_api_key \
  -e JWT_SECRET=very_long_secret \
  --name openclaw \
  openclaw-spring:1.6.0
```

### 生产环境配置

1. **安全加固**
   - 修改默认密码
   - 启用 HTTPS
   - 配置防火墙
   - 限制访问 IP

2. **性能优化**
   - 调整 JVM 参数：`-Xms512m -Xmx1024m`
   - 使用 SSD 存储
   - 配置连接池
   - 启用缓存

3. **高可用**
   - 配置负载均衡
   - 数据库主从复制
   - Redis 集群
   - 定期备份

4. **监控告警**
   - Prometheus 监控
   - Grafana 仪表板
   - 日志聚合
   - 告警通知

**详细文档**: [Docker 部署指南](docs/DOCKER_DEPLOYMENT.md)

---

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📝 更新日志

### v1.6.0 (2026-03-18)
- ✅ 真实数据集成到图表
- ✅ 批量操作服务
- ✅ 性能监控增强

### v1.5.2 (2026-03-18)
- ✅ WebSocket JWT 认证
- ✅ 性能监控服务

### v1.5.1 (2026-03-18)
- ✅ JWT 实际实现
- ✅ BCrypt 密码加密
- ✅ 数据库用户存储

### v1.5.0 (2026-03-18)
- ✅ 用户认证系统
- ✅ 配置管理 UI
- ✅ 日志查看器
- ✅ 移动端适配

[查看完整更新日志](docs/CHANGELOG.md)

---

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

## 🙏 致谢

感谢以下开源项目：

- [Spring Boot](https://spring.io/projects/spring-boot)
- [Spring AI Alibaba](https://github.com/alibaba/spring-ai-alibaba)
- [Chart.js](https://www.chartjs.org/)
- [Font Awesome](https://fontawesome.com/)

---

## 📞 联系方式

- **项目地址**: https://gitee.com/jared_hxyerui/openclaw-spring
- **问题反馈**: https://gitee.com/jared_hxyerui/openclaw-spring/issues
- **Gitee**: https://gitee.com/jared_hxyerui

---

<div align="center">

**Made with ❤️ by OpenClaw Team**

[⬆ 返回顶部](#openclaw-spring-ai-alibaba)

</div>