MateClaw桌面端完整教程：免装Java双击即用，内嵌JRE 21配置全解-平芜编程栈

人工智能
AI Agent
Agent 工作流
Agent 编排
RAG
工具调用
后端
前端

【免费下载链接】mateclaw

🤖 MateClaw — Your second brain with Multi-Agent Orchestration, MCP Protocol, Skills & Memory, Dream, and Multi-Channel Support. Built on Spring AI Alibaba.

项目地址：https://gitcode.com/gh_mirrors/mat/mateclaw

点击查看免费下载

MateClaw 是一款基于 Spring AI Alibaba 构建的开源多智能体（Multi-Agent）AI 助手，支持 MCP 协议、技能系统、长期记忆和多渠道接入。它的桌面端（MateClaw Desktop）最大的亮点就是免装 Java、双击即用——安装包内嵌了 Adoptium（Eclipse Temurin）JRE 21 运行时，无需手动配置 Java 环境，也无需任何环境变量，装完就能跑。本文从安装、启动流程、JRE 21 内嵌原理到自动升级，给你一份完整、易懂的桌面端使用教程。

一、MateClaw 桌面端是什么：为什么不用装 Java？

很多 Java 后端应用要求用户先安装 JDK 或 JRE、配置JAVA_HOME，对非技术用户非常不友好。MateClaw 桌面端用Electron 外壳 + 内嵌 JRE 21 + 打包好的后端 JAR的组合彻底解决了这个问题。

整体架构可以概括为四层（详见 mateclaw-desktop/README.md）：

Electron Shell ├── Splash Screen (Vue 3) ← 启动加载界面 ├── Bundled JRE 21 ← 自带 Java 运行时 ├── mateclaw-server.jar ← Spring Boot 后端 + Vue 前端 └── BrowserWindow → 本地后端

也就是说：

Electron 负责"外壳"：创建窗口、管理 Java 进程生命周期、处理自动升级；
Bundled JRE 21 负责"运行时"：打包在应用资源目录里，随安装包一起分发；
mateclaw-server.jar 负责"大脑"：Spring Boot 后端，内部还打包了 Vue 前端页面；
浏览器窗口负责"脸"：直接加载本地后端提供的 Web 界面。

💡 对普通用户来说，你只需要知道一件事：它像一个普通桌面软件，双击安装、双击启动，仅此而已。

二、下载安装步骤：三大平台开箱即用

2.1 下载安装包

从官方 Release 页面下载对应平台的安装包即可（不同版本文件名中的版本号会变化）：

平台	安装包类型	说明
macOS Apple Silicon	`.dmg`（arm64）	M1 ~ M5 芯片
macOS Intel	`.dmg`（x64）	Intel Mac
Windows 10/11	`.exe`（x64 / arm64）	通用安装包

参考 RELEASE_NOTES_v1.0.101.md 中的下载清单。

2.2 安装注意事项

macOS：未签名版本可能被 Gatekeeper 拦截，右键选择"打开"即可；
Windows：未签名的安装包会触发 SmartScreen 提示"Windows 已保护你的电脑"，点击"仍要运行"继续安装即可（详见 mateclaw-desktop/README.md 的 Windows 签名章节）；
不需要提前安装 Java、Maven、Node.js——这些只有开发构建时才需要；
不需要配置任何环境变量，LLM 供应商的 API Key 在首次启动后通过界面添加，会加密存储到本地数据库。

三、首次启动：从 Splash 到主界面的完整流程

双击启动后，桌面端会执行一套自动化的启动流程（实现见 electron/main/index.ts）：

Electron 启动，显示 Vue 3 构建的 Splash 加载页；
端口自选：应用自动探测一个空闲端口，避免与本机其他服务冲突；
用内嵌 JRE 21 拉起后端 JAR：等价于执行java -jar app.jar --server.port=<动态端口>；
健康检查轮询：每秒探测一次后端，最长等待 2 分钟，直到后端就绪；
加载主界面：窗口跳转到本地后端地址，进入 MateClaw 管理台。

首次启动时还有一个小环节——初始化引导：

选择界面语言：简体中文或英文，写入本地设置（实现见 src/App.vue）；
首次启动连接方式选择：桌面端支持两种工作模式（实现见 electron/main/config.ts）：
- 本地内嵌模式（local）：启动自带的 Java 后端，数据全部存在本机，适合个人使用；
- 远程服务器模式（remote）：连接公司统一部署的 MateClaw 服务，适合团队协作场景。

之后你就可以在界面里创建数字员工、配置模型供应商（如 OpenAI、DeepSeek、Ollama 等）、管理技能和知识库了。

四、内嵌 JRE 21 配置全解：打包与加载机制

4.1 JRE 从哪里来？

构建桌面端时，脚本 scripts/download-jre.sh 会通过 Adoptium API 自动下载Eclipse Temurin JRE 21（LTS 版本），并解压到resources/jre/<平台>目录，支持 arm64 与 x64 双架构。

4.2 启动时如何找到 java？

主进程会按平台依次尝试多组候选路径（见 getJavaExecutable 逻辑）：

平台	候选路径
macOS（打包版）	`Resources/jre/Contents/Home/bin/java`
macOS（开发版）	`jre/mac-arm64/...`、`jre/mac-x64/...`
Windows	`jre/bin/java.exe`、`jre/win32-x64/bin/java.exe`
Linux	`jre/bin/java`、`jre/linux-x64/bin/java`等

只要找到其中一个，就能启动后端；如果 JRE 或app.jar缺失，应用会弹出明确的错误提示（"找不到 Java 运行时环境，请重新安装 MateClaw"）并退出，方便定位问题。

4.3 数据存在哪里？

桌面端为后端设置了专门的本地数据库路径（H2 文件库，MODE=MySQL兼容模式），存放在系统用户数据目录下的data/mateclaw中。这意味着：

聊天记录、配置、模型 Key 全部本地化，不依赖外部数据库；
卸载前想备份数据，直接备份该目录即可；
切换"本地 / 远程"模式时，数据始终保留在用户目录，不会丢失。

4.4 local 与 remote 两种构建变体

桌面端还有两种发布形态（通过运行时检测app.jar是否存在自动识别）：

完整版（local）：内含 JRE + 后端 JAR，可独立离线运行；
轻量版（remote）：不含 JRE 和 JAR，安装包小约 530 MB，只能连接远程服务器。

如果你只需要连接公司统一部署的服务，选轻量版更划算。

五、进阶功能：自动升级与本地工具

5.1 免操作自动升级

桌面端内置electron-updater自动升级能力：启动 3 秒后自动检查更新 → Splash 底部出现更新通知 → 用户点击下载 → 下载完成后重启 →自动停止 Java 后端 → 安装新版本，全程不需要手动操作。平台差异如下：

平台	更新包格式	说明
Windows	NSIS`.exe`	未签名会触发 SmartScreen
macOS	`.zip`	需要签名 + 公证才能自动更新

5.2 本地文件/命令工具（Local Tools）

桌面端支持把本机的文件与命令能力"隧道"回后端，让 Agent 在受控范围内操作本地资源。核心安全设计见 localToolsConfig.ts：

目录白名单：只有加入白名单的目录才能被访问；
failClosed 默认策略：未配置白名单时默认拒绝所有本地访问（更安全的兜底）；
可通过菜单中的"本地工具设置…"随时启停、增删目录。

5.3 一键切换服务器

团队场景下如需更换后端，使用菜单中的Switch Server…（macOS 在应用菜单，Windows 在 File 菜单），即可重新进入连接选择页，最近连接过的 8 个服务器会自动记录，下次一键重连。

六、常见问题速查

问题	原因与解决办法
提示"找不到 Java 运行时环境"	安装包损坏或缺少资源文件，重新安装即可
提示"后端服务启动超时"	后端 2 分钟内未就绪，检查系统资源或重启应用；可配合 mateclaw-desktop/README.md 中"本地测试自动升级"章节的思路排查
更新后 macOS 无法启动	未签名版本无法自动更新，需手动下载新 DMG 安装
想体验完整源码构建	`git clone https://gitcode.com/gh_mirrors/mat/mateclaw`，然后进入 mateclaw-desktop/ 执行`npm install`→`npm run setup`（构建 JAR + 下载 JRE）→`npm run dev`

七、小结

MateClaw 桌面端把"装 Java、配端口、起服务"这些传统 Java 应用的繁琐步骤全部封装进安装包：内嵌 JRE 21 免环境配置、动态端口免冲突、H2 本地库免数据库、electron-updater 免手动升级。无论你是想快速体验多智能体 AI 助手，还是为团队部署一套本地优先的 AI 工作台，双击安装包就是最短路径。

📌 核心文件索引：

桌面端总览：mateclaw-desktop/README.md
JRE 下载脚本：scripts/download-jre.sh
主进程与 Java 生命周期：electron/main/index.ts
连接模式配置：electron/main/config.ts
本地工具安全配置：electron/main/localToolsConfig.ts
构建/打包脚本定义：package.json

人工智能
AI Agent
Agent 工作流
Agent 编排
RAG
工具调用
后端
前端

【免费下载链接】mateclaw

🤖 MateClaw — Your second brain with Multi-Agent Orchestration, MCP Protocol, Skills & Memory, Dream, and Multi-Channel Support. Built on Spring AI Alibaba.

项目地址：https://gitcode.com/gh_mirrors/mat/mateclaw

点击查看免费下载