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.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 跑小窗口模型，建议：

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"
  }'

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

相关提交：

• 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 + 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：https://github.com/mateaix/mateclaw

• 官网：https://claw.mate.vip

• 在线文档：https://claw.mate.vip/docs

• 在线演示：https://claw-demo.mate.vip

• v1.7.0 Release Notes：docs/zh/releases/1.7.0.md

---

八、结语

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

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

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

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

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

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

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