本文面向 Java 与 AI 开发工程师，系统介绍 MateClaw 的核心能力、技术特点、安装部署、配置流程与快速上手示例，帮助你在 Spring Boot 体系下快速落地企业级 AI 智能体。

一、MateClaw 是什么

MateClaw 是基于 Java 17 + Spring Boot 3.5 + Spring AI Alibaba 构建的开源 AI Agent 平台，对标 OpenClaw 并深度适配企业级场景，提供智能体编排、工具调用、长期记忆、多渠道接入与安全管控能力，补齐 Java 生态在 AI Agent 领域的工程化短板。

• 官网：https://claw.mate.vip
• GitHub：https://github.com/matevip/mateclaw
• 协议：Apache-2.0

二、核心功能

1. 双引擎智能体执行

• ReAct 引擎：快速推理 - 行动，适配日常对话与轻量工具调用
• Plan-and-Execute 引擎：复杂任务自动分步骤拆解、执行与状态校验

2. 多层记忆体系

• 短期上下文压缩：自动裁剪 Token 并保留核心语义
• 对话后异步提取：将用户偏好、习惯写入结构化文档
• 定时记忆整合：每日自动合并碎片化记忆，形成长期用户画像

3. MCP 协议与工具生态

• 原生支持 MCP（Model Context Protocol），无缝对接文件系统、GitHub、智能家居等
• ClawHub 技能市场：一键安装运维、办公、数据分析等预构建技能
• 内置工具：联网搜索、文件读写、日期时间、多媒体生成等

4. 企业级安全管控（ToolGuard）

• 绝对拦截：禁止 rm -rf /、管道执行等高危指令
• 高危审批：数据库删改、强制推送等需人工确认
• 路径保护与权限隔离，支持生产环境安全接入

5. 多渠道接入
   Web、桌面端、钉钉、飞书、企业微信、Telegram 等，一次部署多端可用。
6. LLM Wiki 知识库
   自动将文档、PDF、网页转为结构化 Wiki 页面，支持检索、摘要与反向链接，降低上下文消耗。

三、核心技术特点

• Java 原生：深度融合 Spring Boot/Spring Security/Spring AI，企业栈零改造接入
• 工程化稳健：多租户、JWT 认证、日志监控、容错重试，生产级可用
• 低侵入集成：支持渐进式接入，不重构现有系统
• 模型无关：兼容通义千问、OpenAI、Anthropic、Ollama 等云端 / 本地模型
• 可扩展架构：自定义智能体、工具、渠道、安全规则，二次开发友好

四、环境准备

• JDK 17+
• Maven 3.9+
• Node.js 18+ /pnpm（前端）
• Docker（可选，一键部署）
• LLM API Key（如通义千问、OpenAI）

五、安装部署

方式 1：本地开发（推荐）

# 1. 克隆代码
git clone https://github.com/matevip/mateclaw.git
cd mateclaw

# 2. 启动后端
cd mateclaw-server
# 配置模型密钥
export DASHSCOPE_API_KEY=your-key
mvn spring-boot:run
# 后端地址：http://localhost:18088
# Swagger：http://localhost:18088/swagger-ui.html

# 3. 启动前端
cd ../mateclaw-ui
pnpm install
pnpm dev
# 前端地址：http://localhost:5173
# 账号：admin / 密码：admin123

方式 2：Docker Compose（快速）

cp .env.example .env
# 编辑 .env 填入模型密钥
docker compose up -d
# 访问：http://localhost:18080

方式 3：桌面端（免环境）

从 GitHub Releases 下载对应系统安装包，内置 JRE，双击运行即可。

六、核心配置

1. 应用配置（application.yml）

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
server:
  port: 18088
mateclaw:
  memory:
    enable-consolidate: true # 开启记忆整合
    cron: 0 0 2 * * ? # 每日凌晨整合
  tool-guard:
    enable: true # 开启安全拦截
    need-approval: DROP_TABLE,git push --force

2. 安全规则（ToolGuard）

在 DefaultToolGuard.java 中自定义拦截 / 放行规则，支持正则匹配与白名单。

3. 渠道配置

在 Web 控制台「渠道管理」开启钉钉 / 飞书机器人，填入 Webhook 与密钥即可启用。

七、快速使用

1. 控制台对话

登录 Web 控制台，直接发送指令：

• 帮我整理近 7 天工作记录并生成周报
• 搜索 Java AI Agent 最新方案，输出 Markdown
• 帮我规划 3 天北京行程并估算预算

2. 工具调用（自动触发）

发送需求 → Agent 自主选择工具 → 执行 → 结果返回。
示例：

查询今天北京天气，并生成一张天气海报

MateClaw 自动调用搜索 + 图像生成，返回结果与图片。

3. 自定义智能体

1. 新建 Agent，设置角色（如：Java 开发专家、运维助手）
2. 绑定可用工具与模型
3. 配置上下文长度与记忆策略
4. 保存后直接对话使用

4. 技能安装

进入「技能市场」，一键安装「Excel 分析专家」「接口测试助手」「短视频脚本生成」等技能，开箱即用。

八、Java 代码集成（极简示例）

@RestController
@RequestMapping("/agent")
@RequiredArgsConstructor
public class MateClawController {
    private final AgentService agentService;

    @GetMapping("/chat")
    public String chat(@RequestParam String prompt) {
        // 构建请求
        ChatRequest request = ChatRequest.builder()
            .prompt(prompt)
            .enableMemory(true)
            .enableToolUse(true)
            .build();
        // 执行智能体
        ChatResponse response = agentService.execute(request);
        return response.getAnswer();
    }
}

九、适用场景

• 企业内部智能助手（工单、知识库、运维巡检）
• 业务流程自动化（审核、报表、数据同步）
• 研发效能提升（接口生成、文档生成、代码审查）
• 多渠道客服与私域运营
• 个人效率工具（笔记、日程、文件管理）

十、总结

MateClaw 以 Java 工程化能力为底座，将 AI Agent 从 “玩具” 变成生产级工具，具备安全、可扩展、易集成、低门槛的优势，是 Java 开发者进入 AI 原生时代的首选框架。