MateClaw 1.7.0 开源发布,企业级龙虾平台,支持员工、看板、WIKI知识库、技能和审计

0 阅读16分钟

在这里插入图片描述

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_approvalapproverChannels 推送,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.javaapproveSession / 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_codeexecute_shell_command 生成文件,文件会直接出现在侧栏里。

源码校对点:

  • mateclaw-ui/src/components/chat/RunOverviewPanel.vue
  • mateclaw-ui/src/types/tokenUsage.ts
  • mateclaw-server/src/main/java/vip/mate/agent/delegation/
  • 提交:2e52db355cc5b7b93502c716d0411a83

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

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

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

1.7.0 做了几件事:

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

在这里插入图片描述

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

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

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

相关源码入口:

  • mateclaw-server/src/main/java/vip/mate/llm/probe/LocalContextProbe.java
  • mateclaw-server/src/main/java/vip/mate/llm/probe/OllamaContextProbe.java
  • mateclaw-server/src/main/java/vip/mate/agent/context/PrefixBudgetPlanner.java
  • mateclaw-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"
  }'

源码校对点:KbApiKeyAdminControllerPOST /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
  }'

源码校对点:KbOpenApiControllerPOST /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 和企业内部系统部署在同一局域网的场景,但不改变默认安全姿态。

相关提交:

  • adab2087 feat(browser): 放开内网服务访问限制,新增局域网部署模式开关
  • 1ea7eb81 harden(browser): re-check SSRF on every request
  • ce5ec8d4 fix(browser): actually block redirect targets in SSRF interceptor
  • 1ba592bf fix(browser): scope per-context TLS bypass to LAN mode

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

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

  1. 概览汇总
  2. Token 用量
  3. 技能统计
  4. 用户统计
  5. 用户对话
  6. 安全与审计
  7. 渠道统计
  8. 模型配置
  9. 定时任务

在这里插入图片描述

示例 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 步骤可路由到轻量模型。

相关提交:

  • d1460ce6 feat(wiki): KB processing-failure visibility
  • 552ccba4 fix(wiki): agent 通过 wiki_create_page 写入的页面缺少 raw/chunks/embeddings/citations
  • fed559fd feat(wiki): search box to locate a node by name in the knowledge graph
  • c891544a 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、渠道、定时任务、工作流、触发器、目标会保留。

建议升级后检查:

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

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.0
  • 0a47ea8f release: v1.7.0

功能提交依据

功能关键提交
工作流审批通知与恢复bcbe6c74
飞书 / 企微卡片 resolve 工作流审批c7ce8977
WebChat API-Key 审批 resolve + replay78618f56
运行总览侧栏2e52db355cc5b7b9
Token 明细与子 Agent 成本3502c716d0411a83
上下文窗口探测与 prefix 预算044c52b7f232fafa852538d7
工具 Schema 预算门cfd15f32
推理输出上限钳制d6fb0b2b
KB Open API 鉴权与 9 个端点e5f4266eb7348eab
Deep Research Open APIec0b1c05
KB 会话绑定修复f137945d
插件化搜索 Providerbf0358e0197b0c0c
MCP 身份透传cbb73b18457e557846caf0a5
桌面远程与轻量构建8072e77775a96d43
桌面源码开放76b6cb95
局域网部署与 SSRF 防护adab20871ea7eb81ce5ec8d41ba592bf
运营导出fac2c9119959d0377a7eac60
Wiki 失败可视化d1460ce6552ccba4fed559fd

关键源码入口

主题源码入口
运行总览mateclaw-ui/src/components/chat/RunOverviewPanel.vue
Token 用量mateclaw-ui/src/types/tokenUsage.tsmateclaw-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 APImateclaw-server/src/main/java/vip/mate/kbopen/controller/KbOpenApiController.java
Deep Research Open APImateclaw-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.javaMcpIdentityForwardService.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.vuemateclaw-desktop/electron-builder.cjs
运营导出mateclaw-server/src/main/java/vip/mate/operational/mateclaw-ui/src/components/dashboard/OperationalExport.vue

七、相关链接


八、结语

一个审批会静默挂死的系统,不适合进入业务流程。

一个长任务跑到哪、花了多少都看不见的员工,只能让人等待。

一个上下文预算不尊重真实模型窗口的助手,在本地模型上会变得不稳定。

一个能力只锁在管理端里的平台,很难真正接进企业系统。

MateClaw 1.7.0 把这些问题逐个补上:审批闭环、运行可见、成本可见、窗口感知、开放 API、插件化搜索、MCP 身份、桌面远程、局域网部署、运营导出。

这不是一次“堆功能”的版本。

这是一次把 MateClaw 推向生产现场的版本。