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示例 2Docker 启动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 runWebChat / API-Key访客可 approve / denyapprove 后 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可能只是进入审批记录展示。现在它会被实际读回并推送通知审批通过后工作流会从暂停点恢复。示例 5WebChat 访客批准工具调用WebChat 绑定的 Agent 如果命中 ToolGuard 审批规则访客侧可以直接批准或拒绝。curl -N -X POST https://mate.example.com/api/v1/channels/webchat/sessions/approve?visitorIdvisitorIdsessionIds1pendingIdpendingId \ -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?visitorIdvisitorIdsessionIds1pendingIdpendingId \ -H X-MC-Key: API Key \ -H X-MC-Visitor-Token: visitorTokenvisitorId/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、d0411a833. 装得下真实模型窗口上下文与 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 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 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?modesummary \ -H Authorization: Bearer KB_OPEN_API_KEY示例 11启动 Deep Researchcurl -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 支持?tokencurl -N http://localhost:18088/api/v1/open/kb/1000000001/research/sessionId/stream?tokenKB_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 把搜索源从内置实现扩展为插件 SPIPluginType.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 { 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 ListPluginSearchResult 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.java6. 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-apiMCP Server 侧读取保留字段后把身份传给内部 RESTfrom 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: 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-desktop npm install npm 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 mode9. 运营数据一键导出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 model11. 还有几处变透明、变可控按员工模型链偏好——每位数字员工可以配置自己的模型链提供商 模型允许同一提供商重复出现覆盖全局默认模型方便让某个员工固定用更强或更便宜的模型。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 收口都面向企业部署现场。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】