MateClaw 1.7.0一次生产化加固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.gitcd mateclawcd mateclaw-servermvn spring-boot:run# 新开终端cd mateclaw-uipnpm installpnpm dev默认后端地址http://localhost:18088默认前端开发地址http://localhost:5173默认账号admin / admin123示例 2Docker 启动cp .env.example .envdocker 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 补齐了三条链路对话工具审批Web / IM 可通知、可 resolve、可恢复工作流 await_approval按 approverChannels 推送resolve 后继续 workflow runWebChat / API-Key访客可 approve / denyapprove 后 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 可能只是进入审批记录展示。现在它会被实际读回并推送通知审批通过后工作流会从暂停点恢复。示例 5WebChat 访客批准工具调用WebChat 绑定的 Agent 如果命中 ToolGuard 审批规则访客侧可以直接批准或拒绝。curl -N -X POST https://mate.example.com/api/v1/channels/webchat/sessions/approve?visitorIdsessionIds1pendingId-H X-MC-Key: -H X-MC-Visitor-Token: 拒绝curl -X POST https://mate.example.com/api/v1/channels/webchat/sessions/deny?visitorIdsessionIds1pendingId-H X-MC-Key: -H X-MC-Visitor-Token: visitorId / sessionId / pendingId 是 query 参数不是 JSON bodyapprove 返回 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 跑小窗口模型建议1. 在设置 - 模型里配置本地 provider2. 让 MateClaw 执行一次模型探测3. 不要给员工塞过长身份 Prompt4. 把低频工具放到扩展层按需 enable_tool5. 对需要长上下文的员工绑定更大窗口模型链。相关源码入口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 APIMateClaw 的 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 -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?modesummary-H Authorization: Bearer 示例 11启动 Deep Researchcurl -X POST http://localhost:18088/api/v1/open/kb/1000000001/research-H Authorization: Bearer -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 支持 ?tokencurl -N http://localhost:18088/api/v1/open/kb/1000000001/research//stream?token查询状态curl http://localhost:18088/api/v1/open/kb/1000000001/research//status-H Authorization: Bearer 取消curl -X POST http://localhost:18088/api/v1/open/kb/1000000001/research//cancel-H Authorization: Bearer 源码校对点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实现PluginSearchProviderpublic class SimpleSearchPlugin implements MateClawPlugin {Overridepublic void onLoad(PluginContext context) {context.registerSearchProvider(new DemoSearchProvider(context));}static class DemoSearchProvider implements PluginSearchProvider {private final PluginContext context;DemoSearchProvider(PluginContext context) {this.context context;}Overridepublic String id() {return demo-search;}Overridepublic String label() {return Demo Search;}Overridepublic boolean isAvailable() {String baseUrl context.getConfig(baseUrl, String.class);return baseUrl ! null !baseUrl.isBlank();}Overridepublic List 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-apitoken:enabled: trueissuer: mateclawttl-seconds: 60key-id: mateclaw-mcp-1private-key-pem: ${MCP_IDFWD_PRIVATE_KEY_PEM:}audiences:my-internal-api: my-internal-apiMCP Server 侧读取保留字段后把身份传给内部 RESTfrom mcp.server.fastmcp import FastMCPmcp 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: fBearer {__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-desktopnpm installnpm run package:mac:remotepackage:mac:remote 等价于 npm run build cross-env BUILD_MODEremote 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 CLI1.7.0 新增运营数据导出生成一个 .xlsx再打包为 .zip。报告含 9 张表概览汇总Token 用量技能统计用户统计用户对话安全与审计渠道统计模型配置定时任务。示例 17Dashboard 导出进入仪表盘点击导出运营数据快捷选择近 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.commandexport--cli.start2026-01-01--cli.end2026-06-30 report.zip容器内docker exec 容器名 java -jar /app/app.jar --cli.commandexport--cli.start2026-01-01--cli.end2026-06-30 report.zipCLI 导出不走 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下载 OpenAPIcurl 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 工作流审批 | c7ce8977WebChat API-Key 审批 resolve replay | 78618f56运行总览侧栏 | 2e52db35、5cc5b7b9Token 明细与子 Agent 成本 | 3502c716、d0411a83上下文窗口探测与 prefix 预算 | 044c52b7、f232fafa、852538d7工具 Schema 预算门 | cfd15f32推理输出上限钳制 | d6fb0b2bKB Open API 鉴权与 9 个端点 | e5f4266e、b7348eabDeep Research Open API | ec0b1c05KB 会话绑定修复 | f137945d插件化搜索 Provider | bf0358e0、197b0c0cMCP 身份透传 | cbb73b18、457e5578、46caf0a5桌面远程与轻量构建 | 8072e777、75a96d43桌面源码开放 | 76b6cb95局域网部署与 SSRF 防护 | adab2087、1ea7eb81、ce5ec8d4、1ba592bf运营导出 | fac2c911、9959d037、7a7eac60Wiki 失败可视化 | d1460ce6、552ccba4、fed559fd关键源码入口主题|源码入口---|---运行总览 | mateclaw-ui/src/components/chat/RunOverviewPanel.vueToken 用量 | mateclaw-ui/src/types/tokenUsage.ts、mateclaw-ui/src/components/chat/MessageBubble.vueWebChat 审批 | 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.javaDeep Research Open API | mateclaw-server/src/main/java/vip/mate/kbopen/controller/KbOpenResearchController.javaAPI 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.javaMCP 身份透传 | 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七、相关链接GitHubhttps://github.com/mateaix/mateclaw官网https://claw.mate.vip/在线文档https://claw.mate.vip/docs在线演示https://claw-demo.mate.vip/v1.7.0 Release Notesdocs/zh/releases/1.7.0.md八、结语一个审批会静默挂死的系统不适合进入业务流程。一个长任务跑到哪、花了多少都看不见的员工只能让人等待。一个上下文预算不尊重真实模型窗口的助手在本地模型上会变得不稳定。一个能力只锁在管理端里的平台很难真正接进企业系统。MateClaw 1.7.0 把这些问题逐个补上审批闭环、运行可见、成本可见、窗口感知、开放 API、插件化搜索、MCP 身份、桌面远程、局域网部署、运营导出。这不是一次堆功能的版本。这是一次把 MateClaw 推向生产现场的版本。