当前位置：首页 > news >正文

MateClaw 1.7.0 开源发布，企业级JAVA龙虾平台，支持员工、看板、WIKI知识库、技能和审计，Spring AI 最佳实践

news 2026/7/8 2:25:28

MateClaw 1.7.0 是一次生产化加固。

上一阶段，MateClaw 已经把数字员工、LLM Wiki、工作流、触发器、技能、MCP、ACP、多渠道入口、桌面端和 WebChat 放进同一套 Spring Boot Agent Harness 里。到了 1.7.0，重点变成真实团队协作里最容易出事故的地方：

审批不能挂死。
长任务不能黑盒。
Token 花销不能看不见。
本地模型不能被错误窗口预算卡死。
知识库和 Deep Research 不能只锁在管理端。
桌面端不能只能各跑各的本地服务。
运营和审计不能靠手工查库。

这就是 1.7.0 的一句话：从“能用”到“敢放进生产”。

一、MateClaw 是什么

MateClaw 是一个开源 Agent Harness 与 Loop Engine 底座。它用 Spring Boot + StateGraph 驱动 ReAct / Plan-and-Execute 循环，把 Prompt、工具、记忆、LLM Wiki、MCP / ACP、技能包、多渠道入口和权限审计收进一个可自部署的系统。

它不是只给一个人用的聊天框。它更像一个公司能部署的“数字员工运行时”：

多用户、多工作空间、RBAC。
数字员工有角色、目标、背景故事、技能、工具、知识库和记忆。
工具调用可审批、可审计、可限制文件路径。
Web 控制台、桌面端、WebChat、钉钉、飞书、企业微信、个人微信、Telegram、Discord、QQ、Slack 等入口接入同一个大脑。
支持 OpenAI、Anthropic、Gemini、DeepSeek、Kimi、DashScope、Ollama、LM Studio、MLX 等多模型生态。

二、快速体验

示例 1：源码开发模式启动

git clone https://github.com/mateaix/mateclaw.git cd mateclaw cd mateclaw-server mvn spring-boot:run # 新开终端 cd mateclaw-ui pnpm install pnpm dev

默认后端地址：

http://localhost:18088

默认前端开发地址：

http://localhost:5173

默认账号：

admin / admin123

示例 2：Docker 启动

cp .env.example .env docker compose up -d

访问：

http://localhost:18080

示例 3：桌面端

v1.7.0 起，mateclaw-desktop源码已开放。桌面端支持两种模式：

本地模式：内嵌 JRE 21 + Spring Boot JAR，双击即用。
远程模式：轻量客户端连接一台集中部署的 MateClaw Server。

适合企业团队统一部署一台 Server，多人用桌面端连接。

三、1.7.0 的 11 个核心变化

1. 审批三条链路彻底闭环

以前 MateClaw 已经有 ToolGuard 和审批机制，但真实生产协作里还有两类容易挂死的场景：工作流await_approval发不出渠道通知，WebChat/API-Key 访客无法处理挂起审批。

1.7.0 把三条链路补齐：

审批链路	1.7.0 结果
对话工具审批	Web / IM 可通知、可 resolve、可恢复
工作流`await_approval`	按`approverChannels`推送，resolve 后继续 workflow run
WebChat / API-Key	访客可 approve / deny，approve 后 replay 工具调用

示例 4：工作流审批 Step

下面是一个await_approvalstep 的典型结构。重点是approverChannels，例如推送到飞书群：

{ "id": "approval_contract", "name": "合同审批", "mode": "await_approval", "input": { "title": "是否允许发送合同审阅结果？", "summary": "{{ steps.review.output.summary }}", "approverChannels": ["feishu:oc_xxx"] } }

1.7.0 之前，approverChannels可能只是进入审批记录展示。现在它会被实际读回并推送通知；审批通过后，工作流会从暂停点恢复。

示例 5：WebChat 访客批准工具调用

WebChat 绑定的 Agent 如果命中 ToolGuard 审批规则，访客侧可以直接批准或拒绝。

curl -N -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/approve?visitorId=<visitorId>&sessionId=s1&pendingId=<pendingId>" \ -H "X-MC-Key: <API Key>" \ -H "X-MC-Visitor-Token: <visitorToken>"

拒绝：

curl -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/deny?visitorId=<visitorId>&sessionId=s1&pendingId=<pendingId>" \ -H "X-MC-Key: <API Key>" \ -H "X-MC-Visitor-Token: <visitorToken>"

visitorId/sessionId/pendingId是 query 参数，不是 JSON body；approve返回 SSE 流（重放工具调用），deny返回同步 JSON。

源码校对点：mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java的approveSession/denySession，另见文档docs/zh/webchat.md。

2. 长任务看得见：运行总览、Token 明细、子 Agent 成本

长任务最怕“它还在跑吗”“卡在哪一步”“到底花了多少”。1.7.0 在聊天页新增常驻「运行总览」侧栏：

Plan-and-Execute 步骤实时状态。
子 Agent 委派树。
生成文件一键下载。
窄屏自动降级为抽屉。
每轮 Token 拆成 input / output / reasoning / cache hit / cache miss / cache write。
子 Agent 用量逐层汇总到父任务。

示例 6：让 Plan-and-Execute 任务跑出可观察进度

你可以给一个 Plan-and-Execute 员工发：

调研最近一周国产数据库适配 AI Agent 平台的公开资料，分 4 步执行： 1. 搜索并列出资料来源 2. 对 KingbaseES、PostgreSQL、MySQL 的部署差异做对比 3. 输出风险清单 4. 生成一份 Markdown 简报

运行总览会把计划步骤和子 Agent 状态集中展示。若任务通过execute_code或execute_shell_command生成文件，文件会直接出现在侧栏里。

源码校对点：

mateclaw-ui/src/components/chat/RunOverviewPanel.vue
mateclaw-ui/src/types/tokenUsage.ts
mateclaw-server/src/main/java/vip/mate/agent/delegation/
提交：2e52db35、5cc5b7b9、3502c716、d0411a83

3. 装得下真实模型窗口：上下文与 Token 预算

很多本地模型或 OpenAI-compatible 服务并不真的等于“32K 上下文”。过去如果按固定假设注入身份 Prompt、Memory、Wiki 热点、工具 Schema，可能出现两种问题：

预检被严格服务端拒绝。
注入被静默截断，回答质量不稳定。

1.7.0 做了几件事：

Ollama / vLLM 真实上下文窗口探测。
超限报错后自动反解并回填窗口值。
Prefix 注入统一 Token 预算。
小上下文自动降级。
工具 Schema 超预算时，冷门工具降级到扩展目录，通过enable_tool再找回。
推理节点输出上限同时尊重模型配置与真实窗口。

示例 7：小窗口本地模型的使用建议

如果你在本地用 Ollama / vLLM 跑小窗口模型，建议：

在“设置 -> 模型”里配置本地 provider。
让 MateClaw 执行一次模型探测。
不要给员工塞过长身份 Prompt。
把低频工具放到扩展层，按需enable_tool。
对需要长上下文的员工绑定更大窗口模型链。

4. 开放出去：知识库 / Deep Research Open API

MateClaw 的 LLM Wiki 不再只能在管理端里用。1.7.0 新增了面向外部系统的 KB Open API：

独立 API Key，不依赖登录态。
Scope 与绑定 KB 控制。
限流。
返回显式 DTO，不直接暴露内部实体。
Deep Research 支持 start / stream / status / cancel。
研究会话严格绑定kbId和 API Key，避免跨 KB 越权。

示例 8：签发 KB Open API Key

管理员用 JWT 创建 API Key。明文只返回一次：

curl -X POST "http://localhost:18088/api/v1/open/keys" \ -H "Authorization: Bearer <管理员 JWT>" \ -H "Content-Type: application/json" \ -d '{ "name": "crm-kb-reader", "scopes": "kb:read,kb:search,kb:list,kb:meta", "kbIds": [1000000001], "expiresAt": "2026-12-31T23:59:59" }'

源码校对点：KbApiKeyAdminController的POST /api/v1/open/keys。

示例 9：外部系统检索知识库

curl -X POST "http://localhost:18088/api/v1/open/kb/1000000001/search" \ -H "Authorization: Bearer <KB_OPEN_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "query": "客户续费风险", "mode": "hybrid", "topK": 5 }'

源码校对点：KbOpenApiController的POST /api/v1/open/kb/{kbId}/search。

示例 10：查看页面详情

curl "http://localhost:18088/api/v1/open/kb/1000000001/pages/customer-renewal-risk?mode=summary" \ -H "Authorization: Bearer <KB_OPEN_API_KEY>"

示例 11：启动 Deep Research

curl -X POST "http://localhost:18088/api/v1/open/kb/1000000001/research" \ -H "Authorization: Bearer <KB_OPEN_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "topic": "分析过去 90 天客户续费风险的主要原因", "topKPerQuestion": 5 }'

返回包含：

{ "sessionId": "open-research-...", "kbId": 1000000001, "streamUrl": "/api/v1/open/kb/1000000001/research/open-research-.../stream" }

示例 12：订阅 Deep Research SSE

浏览器EventSource不能设置自定义 header，因此 SSE 支持?token=：

curl -N "http://localhost:18088/api/v1/open/kb/1000000001/research/<sessionId>/stream?token=<KB_OPEN_API_KEY>"

查询状态：

curl "http://localhost:18088/api/v1/open/kb/1000000001/research/<sessionId>/status" \ -H "Authorization: Bearer <KB_OPEN_API_KEY>"

取消：

curl -X POST "http://localhost:18088/api/v1/open/kb/1000000001/research/<sessionId>/cancel" \ -H "Authorization: Bearer <KB_OPEN_API_KEY>"

源码校对点：KbOpenResearchController。注意：本文以源码路径/api/v1/open/kb/{kbId}/research为准。

5. 插件化 Search Provider：搜索源可插拔

1.7.0 把搜索源从内置实现扩展为插件 SPI：

PluginType.SEARCH
PluginSearchProvider
PluginSearchQuery
PluginSearchResult
插件配置表单
Search provider catalog endpoint
设置页分组展示与选择

第三方搜索源可以打成 JAR 放进插件目录，不需要改mateclaw-server源码。

示例 13：搜索插件 manifest

仓库里的参考实现mateclaw-plugin-search-sample/src/main/resources/mateclaw-plugin.json：

{ "name": "mateclaw-plugin-search-demo", "version": "1.0.0", "type": "search", "displayName": "Demo Search Provider", "description": "Registers a custom web-search provider backed by a configurable JSON search endpoint.", "entrypoint": "vip.mate.plugin.sample.search.SimpleSearchPlugin", "minPlatformVersion": "1.1.0", "author": "MateClaw Team", "config": { "baseUrl": { "type": "string", "required": true, "secret": false, "description": "Search endpoint returning {\"results\":[{\"title\",\"url\",\"snippet\"}]}" }, "apiKey": { "type": "string", "required": false, "secret": true, "description": "Optional bearer token sent as Authorization header" } } }

示例 14：实现`PluginSearchProvider`

public class SimpleSearchPlugin implements MateClawPlugin { @Override public void onLoad(PluginContext context) { context.registerSearchProvider(new DemoSearchProvider(context)); } static class DemoSearchProvider implements PluginSearchProvider { private final PluginContext context; DemoSearchProvider(PluginContext context) { this.context = context; } @Override public String id() { return "demo-search"; } @Override public String label() { return "Demo Search"; } @Override public boolean isAvailable() { String baseUrl = context.getConfig("baseUrl", String.class); return baseUrl != null && !baseUrl.isBlank(); } @Override public List<PluginSearchResult> search(PluginSearchQuery query) { // 调用你的企业搜索、SearXNG、垂直知识源或内部搜索服务。 return List.of(); } } }

真实接口见：

mateclaw-plugin-api/src/main/java/vip/mate/plugin/api/search/PluginSearchProvider.java
mateclaw-plugin-search-sample/src/main/java/vip/mate/plugin/sample/search/SimpleSearchPlugin.java

6. MCP 身份透传：本地工具知道“谁在调用”

STDIO MCP server 是共享子进程，不能靠环境变量传每次调用的用户身份。1.7.0 增加了 per-server opt-in 的身份透传：

默认关闭。
按 server 名或 id 开启。
明文模式注入__mateclaw_user__。
签名模式注入__mateclaw_token__。
未知渠道 fail-closed。
签名密钥支持自愈。

示例 15：开启 MCP 身份透传

mateclaw: mcp: identity-forward: servers: - my-internal-api token: enabled: true issuer: mateclaw ttl-seconds: 60 key-id: mateclaw-mcp-1 private-key-pem: ${MCP_IDFWD_PRIVATE_KEY_PEM:} audiences: my-internal-api: my-internal-api

MCP Server 侧读取保留字段后，把身份传给内部 REST：

from mcp.server.fastmcp import FastMCP mcp = FastMCP("my-internal-api") @mcp.tool() def query_customer(customer_id: str, __mateclaw_token__: str = ""): if not __mateclaw_token__: raise ValueError("missing identity token") headers = {"Authorization": f"Bearer {__mateclaw_token__}"} # 调用内部系统，内部系统验签后知道代表的是哪个 MateClaw 用户 return {"customerId": customer_id} if __name__ == "__main__": mcp.run()

源码校对点：

McpIdentityForwardProperties
McpIdentityForwardService
docs/zh/mcp.md
的“透传用户身份给 MCP server”小节

7. 桌面端连远程 Server，源码开放

v1.7.0 之前，桌面端更偏单机使用。1.7.0 支持：

本地 / 远程双模式。
远程轻量构建，不带 JRE/JAR。
首次启动连接选择器。
最近服务器列表。
内网自签名证书按 host 显式信任。
mateclaw-desktop
源码开放。

示例 16：远程轻量构建

cd mateclaw-desktop npm install npm run package:mac:remote

package:mac:remote等价于npm run build && cross-env BUILD_MODE=remote electron-builder --mac——先构建渲染层再以远程模式打包，跳过内嵌 JRE / JAR。Windows 对应npm run package:win:remote。

构建配置源码入口：mateclaw-desktop/electron-builder.cjs。

8. 局域网部署模式：默认硬防护，显式放开内网访问

MateClaw 的出站访问守卫默认会封锁内网地址和云元数据地址，以降低 SSRF 风险。1.7.0 新增局域网部署模式：

默认关闭。
关闭时继续拦截内网 / metadata / redirect target。
显式开启后，放开受控内网服务访问。
自签名 TLS 放行也限定在局域网模式。
支持配置 SSRF allowlist。

这适合 MateClaw 和企业内部系统部署在同一局域网的场景，但不改变默认安全姿态。

9. 运营数据一键导出：Dashboard + CLI

1.7.0 新增运营数据导出：生成一个.xlsx，再打包为.zip。报告含 9 张表：

概览汇总
Token 用量
技能统计
用户统计
用户对话
安全与审计
渠道统计
模型配置
定时任务

示例 17：Dashboard 导出

进入仪表盘，点击“导出运营数据”：

快捷选择近 7 / 30 / 90 天。
自定义范围最长 90 天。
全局管理员可用。
下载 token 原子单次有效。
文件 24 小时或下载后清理。

源码入口：

mateclaw-ui/src/components/dashboard/OperationalExport.vue
mateclaw-server/src/main/java/vip/mate/operational/controller/OperationalDataController.java
mateclaw-server/src/main/java/vip/mate/operational/service/OperationalDataExportService.java

示例 18：命令行导出

java -jar app.jar --cli.command=export \ --cli.start=2026-01-01 \ --cli.end=2026-06-30 > report.zip

容器内：

docker exec <容器名> java -jar /app/app.jar --cli.command=export \ --cli.start=2026-01-01 \ --cli.end=2026-06-30 > report.zip

CLI 导出不走 HTTP，适合大范围离线导出。

10. Wiki 处理失败可视化

知识库处理失败不能只在日志里出现。1.7.0 增加：

错误码链路。
静默子步骤告警。
跨 KB 失败中心。
Agent 通过wiki_create_page写入页面后补齐 raw / chunks / embeddings / citations。
知识图谱支持按节点名定位。
廉价 ingest 步骤可路由到轻量模型。

11. 还有几处变透明、变可控

按员工模型链偏好
——每位数字员工可以配置自己的模型链（提供商 + 模型，允许同一提供商重复出现），覆盖全局默认模型，方便让某个员工固定用更强或更便宜的模型。
OpenAPI / Swagger 可直接调试
——新增全局 OpenAPI 元信息配置（标题 / 描述 / 服务器 +bearerAuth，同时覆盖 JWT 与mc_个人访问令牌）；Swagger UI 的 Authorize 按钮现在真的可用，受保护端点可以直接 Try it out，不用再拿 curl 单独试。
聊天「回到底部」浮动按钮
——上拉阅读历史消息时才出现，15 秒无操作自动收边，End键一键回到底部；上拉阅读时不再被自动滚动打断。

四、升级指南

从 v1.6.0 升级

配置兼容。你的数字员工、技能、Wiki、渠道、定时任务、工作流、触发器、目标会保留。

建议升级后检查：

工作流await_approval是否配置了正确的approverChannels。
小窗口本地模型是否需要重新探测上下文窗口。
是否需要签发 KB Open API Key。
是否需要给某个 STDIO MCP server 开启身份透传。
是否需要启用局域网部署模式。
生产环境是否收口 Swagger/OpenAPI 暴露。
是否把低频工具调整为扩展层，降低工具 Schema 压力。
是否有员工需要单独配置模型链，覆盖全局默认模型。

OpenAPI / Swagger

本地默认可访问：

http://localhost:18088/swagger-ui.html

下载 OpenAPI：

curl http://localhost:18088/v3/api-docs.yaml -o mateclaw-openapi.yaml

生产环境可通过：

mateclaw: openapi: expose-ui: false

把 Swagger UI / OpenAPI 文档路径收口到管理员权限。

五、适合哪些团队升级

如果你已经在跑工作流

升级优先级高。1.7.0 解决的是工作流审批通知、resolve 和恢复执行的闭环问题。

如果你有长任务和多 Agent 协作

升级优先级高。运行总览、Token 明细、子 Agent 成本汇总会显著降低黑盒感。

如果你使用本地模型

升级优先级高。真实上下文窗口探测、prefix 预算、小窗口降级和工具 Schema 预算门会直接影响稳定性。

如果你想把知识库接到外部系统

升级优先级高。KB Open API 与 Deep Research Open API 是 1.7.0 的核心开放能力。

如果你做企业私有化部署

升级优先级高。桌面远程模式、局域网部署模式、运营导出、OpenAPI 收口都面向企业部署现场。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～