工具系统

工具（Tool）是 Agent 与外部世界交互的桥梁。Agent 在推理过程中可以调用工具来获取信息、执行操作或处理数据。

工具概念

在 MateClaw 中，工具是一个可被 Agent 调用的函数，具有明确的输入参数和输出结果。Agent 通过 LLM 的函数调用（Function Calling）能力自动选择和使用合适的工具。

工具的生命周期：

Agent 推理 → 选择工具 → [ToolGuard 审批] → 执行工具 → 返回结果 → Agent 继续推理

内置工具

MateClaw 提供 12 个开箱即用的内置工具：

工具名称	说明	典型用途
`DateTimeTool`	获取当前日期和时间	时间相关查询
`WebSearchTool`	搜索互联网信息	信息检索、事实核查
`ShellExecuteTool`	执行系统 Shell 命令	系统操作、脚本执行
`ReadFileTool`	读取本地文件内容	文件分析、代码审查
`WriteFileTool`	创建或覆写文件	生成代码、写入配置
`EditFileTool`	编辑文件的指定部分	代码修改、配置更新
`SkillFileTool`	读取 SKILL.md 技能文件	加载技能定义
`SkillScriptTool`	执行技能脚本	运行技能逻辑
`FileTypeDetectorTool`	检测文件 MIME 类型	文件类型判断
`DocumentExtractTool`	提取文档内容（PDF、Word 等）	文档解析
`WorkspaceMemoryTool`	读写工作区记忆	跨会话信息保持
`BrowserUseTool`	控制浏览器执行操作	网页自动化
`DelegateAgentTool`	委派任务给其他 Agent	多 Agent 协作
`MateClawDocTool`	读取项目内置文档	文档查阅

DateTimeTool

获取当前日期、时间和时区信息。

用户：现在几点了？
Agent：[调用 DateTimeTool] 当前时间是 2024-12-15 14:30:25（Asia/Shanghai）

WebSearchTool

搜索互联网信息，支持 Serper 和 Tavily 两种搜索引擎，可在系统设置中动态切换。

用户：Spring Boot 3.5 有什么新特性？
Agent：[调用 WebSearchTool("Spring Boot 3.5 new features")]
       搜索返回 5 条结果...

搜索工具的配置已迁移至 系统设置 → 搜索服务 页面，支持：

选择主搜索提供商（Serper / Tavily）
配置 API Key 和接口地址
开启失败回退（主提供商不可用时自动切换）
修改后即时生效，无需重启

详见配置参考 → 搜索工具配置。

ShellExecuteTool

在服务器上执行命令，支持 跨平台：Linux/macOS 使用 /bin/sh -c，Windows 使用 cmd.exe /D /S /C。每次执行都需要用户通过 ToolGuard 审批确认。

安全设计：

超时控制：默认 60 秒，硬上限 300 秒，超时后强制终止进程
输出限制：stdout/stderr 各最多 10,000 字节，防止大输出撑爆内存
输出重定向到临时文件（非管道），确保 timeout 在大输出场景下仍然生效
返回结构化结果（exitCode、stdout、stderr、timedOut）

yaml

mateclaw:
  tool:
    shell:
      allowed-commands:
        - ls
        - cat
        - grep
        - find
        - wc
        - df
        - free
      timeout: 30000

ReadFileTool / WriteFileTool / EditFileTool

文件操作三件套，支持读取、创建和编辑文件：

用户：读取 /tmp/config.json 的内容
Agent：[调用 ReadFileTool("/tmp/config.json")]
       文件内容：{"key": "value", ...}

用户：把 port 改成 8080
Agent：[调用 EditFileTool("/tmp/config.json", ...)]
       已将 port 修改为 8080

DocumentExtractTool

从 PDF、Word、Excel 等文档中提取文本内容：

用户：帮我读取这份 PDF 报告的内容
Agent：[调用 DocumentExtractTool("/path/to/report.pdf")]
       提取到 15 页内容...

BrowserUseTool

控制无头浏览器执行自动化操作：

用户：打开百度搜索 MateClaw
Agent：[调用 BrowserUseTool]
       打开浏览器 → 导航到百度 → 输入搜索词 → 获取结果

DelegateAgentTool

委派任务给其他 Agent 执行，实现多 Agent 协作。提供两个方法：

delegateToAgent(agentName, task) — 按名称调用目标 Agent，在独立会话中运行，结果作为工具观察返回
listAvailableAgents() — 列出所有可用 Agent 的名称、类型和描述

用户：帮我搜索 Spring AI 的最新动态，然后让写手整理成一篇简报
Agent A：[调用 WebSearchTool 搜索]
         [调用 delegateToAgent(agentName="写手", task="整理以下内容为简报：...")]
         [收到写手的回复结果]
         整合后回复用户

安全机制：

递归保护 — 最多 3 层委派深度，防止 Agent 互相调用死循环
独立会话 — 被委派的 Agent 使用独立会话，不污染调用方的对话历史
结果截断 — 返回结果限制 4000 字符，防止上下文爆炸

@Tool 注解

MateClaw 使用 Spring AI 的 @Tool 注解注册工具。每个工具是一个 Spring Bean 中的方法：

java

@Component
public class MyCustomTool {

    @Tool(description = "计算两个数的和")
    public String add(
        @ToolParam(description = "第一个数") int a,
        @ToolParam(description = "第二个数") int b
    ) {
        return String.valueOf(a + b);
    }
}

关键点：

@Tool 的 description 告诉 LLM 这个工具的用途
@ToolParam 的 description 描述每个参数的含义
返回值必须是 String 类型
方法所在的类必须是 Spring Bean（@Component）

工具注册

工具注册在 mate_tool 数据库表中：

字段	说明
`name`	工具名称（唯一标识）
`description`	工具描述
`type`	工具类型：`builtin` / `custom` / `mcp`
`enabled`	是否启用
`config`	工具配置（JSON）
`guard_required`	是否需要 ToolGuard 审批

ToolGuard 审批机制

ToolGuard 是 MateClaw 的工具安全机制。对于高风险工具（如 ShellExecuteTool、WriteFileTool），可以要求执行前需人工审批。

工作流程

Agent 决定调用工具
       ↓
   需要审批？ ──否──→ 直接执行
       │
      是
       ↓
   暂停，通知用户
       ↓
   用户审批（同意/拒绝）
       ↓
   同意 → 执行工具
   拒绝 → Agent 调整策略

配置

yaml

mateclaw:
  tool:
    guard:
      enabled: true
      auto-approve:            # 自动审批的工具（低风险）
        - DateTimeTool
        - WebSearchTool
        - DocumentExtractTool
        - FileTypeDetectorTool

未在 auto-approve 列表中的工具将触发审批流程。

启用和禁用工具

通过 UI

进入「工具管理」页面
找到目标工具
切换启用/禁用开关

通过 API

bash

# 查询所有工具
curl http://localhost:18088/api/v1/tools \
  -H "Authorization: Bearer <token>"

# 启用工具
curl -X PUT http://localhost:18088/api/v1/tools/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"enabled": true}'

# 禁用工具
curl -X PUT http://localhost:18088/api/v1/tools/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"enabled": false}'

为 Agent 分配工具

每个 Agent 可以独立配置可用的工具集合。在创建或编辑 Agent 时，通过 tools 字段指定：

bash

curl -X PUT http://localhost:18088/api/v1/agents/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "tools": ["DateTimeTool", "WebSearchTool", "ReadFileTool"]
  }'

也可以在 Agent 工作台的 UI 中勾选需要的工具。

MCP 工具

通过 MCP（Model Context Protocol）协议，MateClaw 可以接入外部工具服务器提供的工具。MCP 工具在工具列表中显示为 mcp 类型。

详细的 MCP 配置请参考 MCP 协议指南。

自定义工具开发

步骤一：创建工具类

java

@Component
public class WeatherTool {

    @Tool(description = "查询指定城市的天气信息")
    public String getWeather(
        @ToolParam(description = "城市名称，如：北京") String city
    ) {
        // 调用天气 API
        String result = callWeatherApi(city);
        return result;
    }

    private String callWeatherApi(String city) {
        // 实现天气查询逻辑
        return "晴，气温 15-26°C";
    }
}

步骤二：注册到数据库

工具在应用启动时自动扫描并注册到 mate_tool 表。你也可以通过 db/data.sql 预先插入记录：

sql

INSERT INTO mate_tool (name, description, type, enabled, guard_required)
VALUES ('WeatherTool', '查询城市天气信息', 'custom', 1, 0);

步骤三：分配给 Agent

在 Agent 配置中添加新工具的名称即可。

下一步

技能系统 — 更高层次的能力封装
MCP 协议 — 接入外部工具服务器
Agent 引擎 — 工具如何被 Agent 使用

工具系统 ​

工具概念 ​

内置工具 ​

DateTimeTool ​

WebSearchTool ​

ShellExecuteTool ​

ReadFileTool / WriteFileTool / EditFileTool ​

DocumentExtractTool ​

BrowserUseTool ​

DelegateAgentTool ​

@Tool 注解 ​

工具注册 ​

ToolGuard 审批机制 ​

工作流程 ​

配置 ​

启用和禁用工具 ​

通过 UI ​

通过 API ​

为 Agent 分配工具 ​

MCP 工具 ​

自定义工具开发 ​

步骤一：创建工具类 ​

步骤二：注册到数据库 ​

步骤三：分配给 Agent ​

下一步 ​