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_approval step 的典型结构。重点是 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.vuemateclaw-ui/src/types/tokenUsage.tsmateclaw-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。 - 对需要长上下文的员工绑定更大窗口模型链。
相关源码入口:
mateclaw-server/src/main/java/vip/mate/llm/probe/LocalContextProbe.javamateclaw-server/src/main/java/vip/mate/llm/probe/OllamaContextProbe.javamateclaw-server/src/main/java/vip/mate/agent/context/PrefixBudgetPlanner.javamateclaw-server/src/main/java/vip/mate/tool/disclosure/
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.SEARCHPluginSearchProviderPluginSearchQueryPluginSearchResult- 插件配置表单
- 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.javamateclaw-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()
源码校对点:
McpIdentityForwardPropertiesMcpIdentityForwardServicedocs/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 和企业内部系统部署在同一局域网的场景,但不改变默认安全姿态。
相关提交:
adab2087 feat(browser): 放开内网服务访问限制,新增局域网部署模式开关1ea7eb81 harden(browser): re-check SSRF on every requestce5ec8d4 fix(browser): actually block redirect targets in SSRF interceptor1ba592bf fix(browser): scope per-context TLS bypass to LAN mode
9. 运营数据一键导出:Dashboard + CLI
1.7.0 新增运营数据导出:生成一个 .xlsx,再打包为 .zip。报告含 9 张表:
- 概览汇总
- Token 用量
- 技能统计
- 用户统计
- 用户对话
- 安全与审计
- 渠道统计
- 模型配置
- 定时任务
示例 17:Dashboard 导出
进入仪表盘,点击“导出运营数据”:
- 快捷选择近 7 / 30 / 90 天。
- 自定义范围最长 90 天。
- 全局管理员可用。
- 下载 token 原子单次有效。
- 文件 24 小时或下载后清理。
源码入口:
mateclaw-ui/src/components/dashboard/OperationalExport.vuemateclaw-server/src/main/java/vip/mate/operational/controller/OperationalDataController.javamateclaw-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 步骤可路由到轻量模型。
相关提交:
d1460ce6 feat(wiki): KB processing-failure visibility552ccba4 fix(wiki): agent 通过 wiki_create_page 写入的页面缺少 raw/chunks/embeddings/citationsfed559fd feat(wiki): search box to locate a node by name in the knowledge graphc891544a feat(wiki): route cheap ingest steps to a configurable light model
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 收口都面向企业部署现场。
六、源码与提交校对依据
本文主要功能均已按源码与提交记录核对。
发布同步提交
3fb51291 release: v1.7.00a47ea8f release: v1.7.0
功能提交依据
| 功能 | 关键提交 |
|---|---|
| 工作流审批通知与恢复 | bcbe6c74 |
| 飞书 / 企微卡片 resolve 工作流审批 | c7ce8977 |
| WebChat API-Key 审批 resolve + replay | 78618f56 |
| 运行总览侧栏 | 2e52db35、5cc5b7b9 |
| Token 明细与子 Agent 成本 | 3502c716、d0411a83 |
| 上下文窗口探测与 prefix 预算 | 044c52b7、f232fafa、852538d7 |
| 工具 Schema 预算门 | cfd15f32 |
| 推理输出上限钳制 | d6fb0b2b |
| KB Open API 鉴权与 9 个端点 | e5f4266e、b7348eab |
| Deep Research Open API | ec0b1c05 |
| KB 会话绑定修复 | f137945d |
| 插件化搜索 Provider | bf0358e0、197b0c0c |
| MCP 身份透传 | cbb73b18、457e5578、46caf0a5 |
| 桌面远程与轻量构建 | 8072e777、75a96d43 |
| 桌面源码开放 | 76b6cb95 |
| 局域网部署与 SSRF 防护 | adab2087、1ea7eb81、ce5ec8d4、1ba592bf |
| 运营导出 | fac2c911、9959d037、7a7eac60 |
| Wiki 失败可视化 | d1460ce6、552ccba4、fed559fd |
关键源码入口
| 主题 | 源码入口 |
|---|---|
| 运行总览 | mateclaw-ui/src/components/chat/RunOverviewPanel.vue |
| Token 用量 | mateclaw-ui/src/types/tokenUsage.ts、mateclaw-ui/src/components/chat/MessageBubble.vue |
| WebChat 审批 | mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java |
| 工作流恢复 | mateclaw-server/src/main/java/vip/mate/workflow/、mateclaw-server/src/main/java/vip/mate/approval/ |
| KB Open API | mateclaw-server/src/main/java/vip/mate/kbopen/controller/KbOpenApiController.java |
| Deep Research Open API | mateclaw-server/src/main/java/vip/mate/kbopen/controller/KbOpenResearchController.java |
| API Key 管理 | mateclaw-server/src/main/java/vip/mate/kbopen/controller/KbApiKeyAdminController.java |
| 插件化搜索 | mateclaw-plugin-api/src/main/java/vip/mate/plugin/api/search/、mateclaw-server/src/main/java/vip/mate/plugin/bridge/PluginSearchBridge.java |
| MCP 身份透传 | mateclaw-server/src/main/java/vip/mate/tool/mcp/runtime/McpIdentityForwardProperties.java、McpIdentityForwardService.java |
| 上下文预算 | mateclaw-server/src/main/java/vip/mate/agent/context/PrefixBudgetPlanner.java |
| 模型窗口探测 | mateclaw-server/src/main/java/vip/mate/llm/probe/ |
| 桌面远程 | mateclaw-desktop/src/App.vue、mateclaw-desktop/electron-builder.cjs |
| 运营导出 | mateclaw-server/src/main/java/vip/mate/operational/、mateclaw-ui/src/components/dashboard/OperationalExport.vue |
七、相关链接
- GitHub:github.com/mateaix/mat…
- 官网:claw.mate.vip
- 在线文档:claw.mate.vip/docs
- 在线演示:claw-demo.mate.vip
- v1.7.0 Release Notes:
docs/zh/releases/1.7.0.md
八、结语
一个审批会静默挂死的系统,不适合进入业务流程。
一个长任务跑到哪、花了多少都看不见的员工,只能让人等待。
一个上下文预算不尊重真实模型窗口的助手,在本地模型上会变得不稳定。
一个能力只锁在管理端里的平台,很难真正接进企业系统。
MateClaw 1.7.0 把这些问题逐个补上:审批闭环、运行可见、成本可见、窗口感知、开放 API、插件化搜索、MCP 身份、桌面远程、局域网部署、运营导出。
这不是一次“堆功能”的版本。
这是一次把 MateClaw 推向生产现场的版本。