MateClaw：基于 Spring AI Alibaba 的开源多智能体 AI 操作系统（附架构详解）

一个聊天软件里。一个 JAR 包自部署，数据不出门。

---

写在前面

过去一年，AI 产品爆发式增长。但如果你认真看，大多数产品只做了一层：

• 给你一个聊天框，但记忆每天清零
• 给你一个工具执行器，但 AI 要删你的文件时你拦不住
• 给你一个知识库，只能检索碎片，说不清它到底"知道"什么
• 给你桌面端，但进不了团队在用的钉钉、飞书、Slack
• 或者以上全都给了------但跑在别人的云上，你的数据给别人交房租

MateClaw 换了一个打法：所有东西放在一个屋檐下，跑在你自己能摸到的硬件上。

本文从架构到实践，完整介绍这个基于 Spring AI Alibaba 构建的开源多智能体 AI 操作系统。

---

一、产品定位：不是聊天工具，是 AI 操作系统

MateClaw 的一句话定义：

自部署的多智能体 AI 操作系统。多个 Agent 协作拆解任务、调用工具、积累记忆。一个 JAR 包，数据不出门。

和同类产品的区别：

维度	Dify	LobeChat	MateClaw
定位	工作流编排器	聊天界面	多智能体 AI 操作系统
Agent 架构	DAG 工作流	单轮对话	StateGraph 多智能体协作
知识管理	向量检索	无	LLM Wiki 结构化知识引擎
记忆系统	对话上下文	对话上下文	四层记忆生命周期
工具扩展	内置 + API	插件	MCP 协议 + Tool Guard
渠道接入	Web	Web	Web + 桌面 + 8 IM 渠道
部署方式	Docker	Docker/Vercel	一个 JAR / Docker / 桌面端

---

二、核心架构：四层设计

MateClaw 的架构分四层，每一层都能独立站住：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

2.1 多智能体编排（Layer 1）------最核心的差异点

Agent 运行时基于 Spring AI Alibaba Graph （spring-ai-alibaba-graph）构建，不是传统的 BaseAgent → ReActAgent 类继承，而是一张 StateGraph 有向图：

两种推理模式：

• ReAct（Reasoning + Acting）：思考 → 行动 → 观察 → 继续。适合即时任务
• Plan-and-Execute：先生成计划 → 逐步执行 → 动态重规划。适合复杂任务

多智能体协作：

Agent 之间通过 DelegateAgentTool 互相委派任务。一个"产品经理 Agent"可以把技术调研委派给"技术 Agent"，把竞品分析委派给"分析 Agent"。每个 Agent 有自己的 system prompt、工具集、记忆和知识库。

实际操作：在控制台创建 Agent 时，选择推理模式、绑定工具和知识库即可：

关键代码路径：

agent/graph/StateGraphReActAgent.java        --- ReAct 循环图
agent/graph/plan/StateGraphPlanExecuteAgent.java --- Plan-Execute 图
agent/graph/node/                            --- 推理/行动/观察/终答节点
agent/graph/edge/                            --- 条件边（分发器）
agent/AgentGraphBuilder.java                 --- 按配置动态建图

2.2 知识引擎：LLM Wiki（Layer 2）

大多数 AI 知识系统只做一件事：切块 → 向量化 → 检索碎片。你拿到的是碎片，看不到全貌。

MateClaw 的 LLM Wiki 做的不一样：

1. 投喂：扔进 PDF、Markdown、整个文件夹
2. 消化：系统读一遍，消化一遍，写出结构化 Wiki 页面
3. 输出：每一页有摘要、双向链接、溯源指针（指向原文段落）
4. 使用：Agent 对话时自动注入相关页面摘要，需要细节时取整页

这是一座图书馆，不是一个搜索框。 你能翻、能读、能理解它到底"知道"什么。

mate_wiki_knowledge_base  --- 知识库
mate_wiki_raw_material    --- 原始材料
mate_wiki_page            --- 生成的结构化页面

2.3 四层记忆生命周期（Layer 2）

记忆不是聊天功能上贴的一张贴纸，是系统越用越懂你的底层机制。

• PROFILE.md：Agent 对你的认知画像------你是谁、你关心什么、和你合作的偏好
• MEMORY.md：长期事实记忆------项目背景、历史决策、上下文信息
• DREAMS.md：Dreaming 整合结果------跨对话的模式识别和趋势理解
• NUDGES.md：主动触发器------Agent 判断应该提醒你的事

别的 AI 每天从零开始。MateClaw 从昨天结束的地方继续。

2.4 MCP + Tool Guard（Layer 3）

14 个内置工具打底：Web 搜索、文件读写、Shell、时间、浏览器自动化、图像生成、视频创作、TTS、STT、音乐生成、delegate-agent 等。

MCP 协议（Model Context Protocol）是通往无限的逃生舱。配置方式：

# application.yml --- 接入 MCP 服务，零代码
mateclaw:
  mcp:
    servers:
      filesystem:
        command: npx
        args: ["-y", "@anthropic/mcp-filesystem", "/data"]
      tavily:
        command: npx
        args: ["-y", "tavily-mcp-server"]

从 Agent 的视角，一个内置 @Tool Spring bean 和一个 MCP 服务来的工具，没有任何区别。

Tool Guard 安全护栏------让你放心让 AI 施展能力：

# Tool Guard 规则示例
mateclaw:
  tool-guard:
    rules:
      - tool: "ShellTool"
        action: REQUIRE_APPROVAL    # 执行 Shell 必须人工审批
      - tool: "FileWriteTool"
        pattern: "*.env"
        action: BLOCK               # 禁止写入 .env 文件
      - tool: "*DeleteTool"
        action: REQUIRE_APPROVAL    # 所有删除操作需审批

2.5 全渠道统一接入（Layer 4

public interface ChannelAdapter {
    void onMessage(ChannelMessage message);
    void sendMessage(ChannelMessage message);
    ChannelType getChannelType();
}

每个渠道是一个 ChannelAdapter SPI 实现。目前支持：

渠道	模式	流式支持
Web 控制台	SSE	Yes
桌面端（Electron + JRE 21）	SSE	Yes
钉钉	Webhook	---
飞书	Webhook	---
企业微信	Webhook	---
微信	长连接	---
Telegram	Bot API	---
Discord	Bot API	---
QQ	Bot API	---
Slack	Events API	---

关键点 ：Slack 里回复你的 Agent 和飞书里的是同一个------同一份记忆、同一套技能、同一种性格。

---

三、技术栈一览

层	选型	说明
后端框架	Spring Boot 3.5	单体模块化，一个进程
AI 框架	Spring AI Alibaba 1.1	Agent Graph + 工具注册
Agent 运行时	StateGraph	有向图：节点 + 条件边
工具协议	MCP (Anthropic)	JSON-RPC，SSE/stdio 双传输
前端	Vue 3 + TypeScript	Pinia + Element Plus + TailwindCSS 4
ORM	MyBatis Plus	camelCase → underscore 自动映射
数据库	H2 / MySQL 8	开发/生产统一 schema.sql
桌面端	Electron + JRE 21	用户不需要装 Java
流式	SSE (Spring MVC)	WebFlux 被明确排除
模型	15+ 供应商	DashScope / OpenAI / Anthropic / Gemini / DeepSeek / Ollama ...
协议	Apache 2.0	不是 source-available，不是 open core

---

四、v1.0.418：企业级生产就绪

最新版 v1.0.418 重点解决三个问题：

4.1 工作空间隔离

多团队各管各的。Agent、知识库、记忆、规则、渠道------全部按工作空间划分。四级权限体系（Owner > Admin > Member > Viewer）。WorkspacePathGuard 沙盒防止 AI 越权访问文件。

4.2 Doctor 健康检查

7 大类自动巡检（基础设施 / 模型 / Agent / 记忆 / 渠道 / MCP / 定时任务），每 15 分钟一轮，三态报告（OK / Warning / Error）+ Fix 按钮。

# Doctor 配置
mateclaw:
  doctor:
    enabled: true
    schedule-minutes: 15
    cache-ttl-minutes: 10

4.3 完整国际化

从后端异常码到工具描述到 Guard 规则术语，结构化双语支持。不是机器翻译。

4.4 自然语言定时任务

对 Agent 说"每天早上 9 点检查服务器"，它自动创建 cron job：

用户：帮我每天早上 9 点检查一下生产服务器的状态
Agent：好的，我已经创建了一个定时任务：
       - 名称：生产服务器健康检查
       - 频率：每天 09:00
       - 执行内容：检查服务器 CPU/内存/磁盘状态并汇报

不需要学 cron 语法，不需要找菜单。对话就是操作界面。

4.5 安全加固

• JWT 密钥生产环境强制校验
• CORS 策略收紧
• H2 控制台生产环境自动关闭
• 登录频率限制，防暴力破解
• 技能安全扫描（prompt 注入 / 危险工具引用检测）

---

五、60 秒跑起来

方式一：桌面端（推荐新手）

1. 从 v1.0.418 桌面端下载 下载对应平台安装包
2. 双击打开，登录 admin / admin123
3. 设置 → 模型 → 粘贴 DashScope 或 OpenAI API Key
4. 回到聊天页面，开始对话

桌面端自带 JRE 21，不需要装 Java、不需要装 Node、不需要命令行。

方式二：Docker（推荐服务器部署）

git clone https://github.com/matevip/mateclaw.git
cd mateclaw
cp .env.example .env          # 填入 DASHSCOPE_API_KEY
docker compose up -d           # MySQL + 后端，18 行配置
# → http://localhost:18080     # 登录 admin / admin123

方式三：源码运行（推荐开发者）

# 后端
cd mateclaw-server
export DASHSCOPE_API_KEY=your-key
mvn spring-boot:run
# → http://localhost:18088

# 前端（可选，后端已内嵌 SPA）
cd mateclaw-ui
pnpm install && pnpm dev
# → http://localhost:5173 (自动代理 /api → :18088)

首次配置三步走

1. 登录 → admin / admin123
2. 设置 → 模型配置 → 选供应商 → 粘贴 API Key → 测试连接
3. 回到聊天 → 选一个 Agent → 开始对话

Ollama 用户：如果你本地跑了 Ollama，MateClaw 会自动发现并预配置 6 个常用模型，零配置即可使用。

---

六、适用场景

场景	怎么用
个人 AI 助手	本地部署，Ollama 本地模型，数据完全私有
团队知识协作	LLM Wiki 消化团队文档，Agent 自动注入知识回答问题
客服/运营自动化	8 渠道统一接入，同一个 Agent 回复钉钉 + 飞书 + Slack
开发者工具链	MCP 接入内部 API，Shell + 文件 + 浏览器自动化
企业私有化部署	工作空间隔离 + Tool Guard + 审计日志，满足合规

---

写在最后

MateClaw 不是又一个 ChatGPT 套壳。

它是一个完整的 AI 操作系统------多智能体协作、结构化知识引擎、四层记忆生命周期、MCP 无限工具扩展、8 渠道统一触达。跑在你自己的机器上，一个 JAR 包，数据不出门。

如果你是 Java 开发者，想在 Spring 生态里构建 AI 应用，MateClaw 是目前最完整的开源参考实现。

如果你需要一个可以私有化部署的多智能体 AI 平台，MateClaw 已经在生产环境跑起来了。

---

GitHub ：https://github.com/matevip/mateclaw
产品主页 ：https://claw.mate.vip
在线体验 ：https://claw-demo.mate.vip
文档中心 ：https://claw.mate.vip/docs/

Star 一下，然后 60 秒跑起来。