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 把三条链路补齐：

示例 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

功能提交依据

关键源码入口

七、相关链接

• 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 推向生产现场的版本。