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

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

写在前面

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

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

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

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

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

MateClaw 的一句话定义：

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

和同类产品的区别：

二、核心架构：四层设计

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 做的不一样：

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

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 实现。目前支持：

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

三、技术栈一览

四、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 秒跑起来

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

桌面端自带 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 个常用模型，零配置即可使用。

六、适用场景

写在最后

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 秒跑起来。