1. MateClaw：一个为团队而生的“第二大脑”AI平台

在AI工具层出不穷的今天，我们似乎陷入了一个怪圈：今天还在用的工具，明天可能就因为供应商的一次宕机、一次API调用失败，或者仅仅是你的浏览器标签页被关闭，而变得“失忆”或“瘫痪”。对于个人用户而言，这或许只是片刻的不便；但对于一个依赖AI进行日常协作、客户服务或内部流程自动化的团队来说，这种脆弱性是不可接受的。我们需要的是一个 稳定、可靠、且完全自主可控的“第二大脑” ，它不仅能思考，还能记住、能学习、能通过多种方式与我们交互，并且永远不会因为单一供应商的问题而罢工。

这就是MateClaw诞生的初衷。它不是一个简单的聊天机器人，也不是一个功能单一的AI助手。它是一个 完整的、一体化的AI Agent平台 ，集成了推理引擎、知识库、长期记忆、工具调用和多渠道接入能力。更重要的是，它基于Spring Boot构建，采用Apache 2.0开源协议，这意味着你可以将它部署在自己的服务器上，完全掌控你的数据、你的模型密钥和你的业务逻辑。零元成本，没有按Token计费，没有按席位收费，只有你对自己基础设施的完全控制权。

无论你是企业的技术负责人，希望为团队引入一个稳定、可管理的AI协作中枢；还是开发者，希望基于一个成熟框架快速构建具备复杂能力的智能体；亦或是AI爱好者，想要一个能整合所有主流模型、并能消化个人知识库的私人助手，MateClaw都提供了一个坚实且灵活的起点。接下来，我将带你深入拆解这个项目的核心设计、实操部署的每一个细节，并分享在真实场景中应用时可能遇到的“坑”与应对技巧。

2. 核心设计哲学：为何说MateClaw是“完整的部件”

在深入技术细节之前，理解MateClaw的设计哲学至关重要。市面上许多AI项目要么专注于模型调用层，要么专注于前端交互，要么专注于某个垂直领域的工具链。MateClaw的野心在于，它试图将 推理、知识、记忆、工具、渠道 这五个核心要素，作为一个有机整体来设计和构建，而非简单地将它们“螺栓式”地拼接在一起。

2.1 多供应商故障转移：让AI服务具备“韧性”

这是MateClaw最引人注目的特性之一。想象一下，你的生产环境AI客服正在与客户对话，突然，你主要依赖的OpenAI API因为配额用尽或网络波动返回了错误。在传统架构下，用户会立刻看到一个刺眼的错误提示，体验中断。MateClaw的解决方案是内置了一个 智能的供应商健康追踪与路由系统 。

其工作原理如下：

  1. 优先级队列 ：在管理后台（ 设置 -> 模型 ），你可以将支持的14+个模型供应商（如DashScope、OpenAI、Anthropic、Gemini、DeepSeek、Ollama等）拖拽排序，形成一个优先级列表。
  2. 健康检查与熔断 ：系统会实时监控每个供应商API的响应状态、延迟和错误率。当一个供应商连续失败或超时，它会被自动放入一个“冷却窗口”，在接下来的一段时间内，新的请求会绕过它，直接发给列表中的下一个健康供应商。
  3. 无缝切换 ：最巧妙的是，这个切换对用户是 无感知 的。如果在一个流式回复的中途主供应商宕机，MateClaw能够从故障点接续，使用备用供应商完成剩余的回复生成。用户看到的只是一条完整、连贯的消息，完全不知道背后已经发生了一次“心脏移植手术”。

实操心得 ：在配置模型优先级时，不要只考虑模型的“聪明程度”，更要考虑其 API的稳定性、延迟和成本 。可以将响应最快、最稳定的供应商设为最高优先级，而将能力最强但可能稍慢或较贵的模型作为备用。同时，合理设置“冷却窗口”时间（通常在管理界面可配置），避免因短暂网络抖动就将一个供应商打入冷宫过久。

2.2 知识链接：从“资料仓库”到“可验证图书馆”

很多AI知识库功能只是简单地将文档切片、向量化、然后检索。这就像一个杂乱无章的仓库，你知道东西在里面，但很难系统地找到并验证信息的来源和关联。MateClaw的 “LLM Wiki” 功能旨在解决这个问题。

它的工作流更具结构性：

  1. 消化与结构化 ：当你上传PDF、Markdown或网页内容时，系统并非简单存储。它会利用LLM去理解内容，将其消化并组织成结构化的Wiki页面。
  2. 自动建立链接 ：在生成页面的过程中，系统会自动识别相关概念，并创建 [[内部链接]] 。这模仿了人类知识体系的连接方式，使得知识不再是孤岛。
  3. 溯源与引用 ：每一个生成的句子或段落，都会关联到原始的文档片段（chunk）。当你在生成的Wiki页面上看到某个结论时，可以点击旁边的引用标记，直接定位到原文中的确切位置。这解决了AI“胡言乱语”或无法溯源的核心痛点，使得知识库变得 可审计、可验证 。

2.3 统一大脑，多元入口：真正的全渠道接入

一个强大的AI大脑，应该能从用户最习惯的入口进行交互。MateClaw设计了五种表面（Surface），共享同一套核心能力：

表面 定位与场景 技术实现要点
Web控制台 系统管理员和运营人员的主战场。用于配置Agent、管理模型、审核工具调用、查看知识库和审计日志。 基于Vue 3的完整SPA，打包在Spring Boot的JAR中，提供全面的RBAC（基于角色的访问控制）管理界面。
桌面应用 为普通用户或小团队提供的开箱即用客户端。无需安装Java环境。 基于Electron开发，并 捆绑了JRE 21 。用户下载后双击即可运行，实现了与本地应用无异的体验。
网页聊天插件 快速嵌入到任何现有网站中，提供客服或辅助对话功能。 通过Vite构建为独立的UMD/ES模块，只需在页面中引入一个 <script> 标签即可嵌入，高度可定制样式。
即时通讯通道 将AI能力接入日常工作流。支持钉钉、飞书、企业微信、Telegram、Discord、QQ等。 后端通过各自的Bot SDK建立连接，将IM消息路由到内部的Agent运行时进行处理和回复。
插件SDK 为开发者提供扩展能力。允许第三方开发自定义工具、技能包。 提供标准的Java模块接口（ mateclaw-plugin-api ），遵循清晰的契约，方便能力集成。

这种设计意味着，无论是内部员工通过飞书机器人提交一个数据查询请求，还是客户在官网通过Web Widget进行咨询，抑或是管理员在Web控制台进行系统配置，背后都是同一个MateClaw实例、同一套知识记忆、同一组工具技能在处理。这极大地简化了运维和一致性维护的复杂度。

3. 技术栈深度解析与环境准备

MateClaw选择了一条在AI领域略显独特但极其稳健的技术路径：以 Java生态 为核心。这对于已经拥有成熟Java技术栈的团队来说，意味着极低的接入和运维成本。

3.1 后端：Spring Boot构筑的坚实基石

后端基于Spring Boot 3.5，这是Java领域最成熟、应用最广泛的企业级框架。其优势在于：

  • 生产就绪 ：内嵌服务器、健康检查、指标监控、外部化配置等特性开箱即用。
  • 强大的生态 ：与Spring Security（用于RBAC和JWT认证）、MyBatis-Plus（数据访问）、Flyway（数据库版本迁移）等无缝集成。
  • 易于集成 ：对于企业已有的用户系统、数据库、消息队列等，通过Spring的集成模式可以相对轻松地对接。

核心依赖：Spring AI Alibaba 这是阿里云对Spring AI项目的实现。它抽象了与各大模型供应商交互的细节，提供了统一的 ChatClient 、 EmbeddingClient 等接口。MateClaw利用这一点，在其上构建了前文提到的多供应商路由层。这意味着，未来有新的模型供应商加入Spring AI生态，MateClaw也能较容易地支持。

3.2 前端与客户端：现代化的用户体验

  • 管理后台 (mateclaw-ui) ：采用Vue 3 + TypeScript + Vite + Element Plus的组合，这是目前中后台管理系统的主流技术选型，保证了开发效率和界面美观度。最终通过构建打包，将静态资源集成到Spring Boot的JAR文件中，实现单体部署。
  • 桌面客户端 ：使用Electron，使得用Web技术开发跨平台桌面应用成为可能。 捆绑JRE 21 是关键一步，它彻底消除了用户需要预先安装特定版本Java的麻烦，实现了真正的“双击即用”。
  • Webchat插件 ：同样基于Vite构建，但采用“库模式”，产出标准化的UMD和ES模块，方便其他Web项目以最轻量的方式引入。

3.3 数据库与部署灵活性

  • 开发环境 ：默认使用H2数据库，一个内存数据库，无需额外安装，非常适合快速启动和开发测试。
  • 生产环境 ：官方推荐并完美支持MySQL 8.0+。Flyway会负责在应用启动时自动执行SQL迁移脚本，确保数据库表结构始终与代码版本同步。
  • 部署方式 ：提供了极大的灵活性：
    1. 传统部署 ：直接运行 java -jar 启动打包好的Fat JAR。
    2. Docker部署 ：项目根目录提供了 docker-compose.yml 文件，可以一键拉起包含MySQL和MateClaw服务的完整环境，是最推荐的生产部署方式。
    3. 桌面端 ：直接下载发布的二进制安装包。

注意事项 ：如果你计划从H2开发环境迁移到MySQL生产环境，除了修改 application.yml 中的数据库连接配置外，还需要注意 数据迁移 。Flyway只管理表结构，不迁移数据。你需要手动将H2中的数据导出并导入到MySQL，或者在生产环境初始化时就直接使用MySQL。

4. 从零开始：完整部署与核心配置实战

让我们抛开理论，动手将一个MateClaw实例跑起来，并配置其核心功能。这里我们以最常用的 Docker Compose部署方式 为例，因为它隔离性好，复现容易。

4.1 第一步：获取代码与基础配置

# 1. 克隆代码仓库
git clone https://github.com/matevip/mateclaw.git
cd mateclaw

# 2. 复制环境变量模板文件，并根据你的环境进行修改
cp .env.example .env

接下来，编辑新创建的 .env 文件。这是整个Docker环境的配置中心。你需要关注以下几个关键配置：

# 数据库配置 (供MySQL容器使用)
MYSQL_ROOT_PASSWORD=your_strong_root_password_here
MYSQL_DATABASE=mateclaw
MYSQL_USER=mateclaw_user
MYSQL_PASSWORD=your_strong_user_password_here

# MateClaw应用配置
# 应用运行端口
SERVER_PORT=18080
# 数据库连接地址（指向上面定义的MySQL容器）
SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/mateclaw?useUnicode=true&characterEncoding=utf8&useSSL=false&allowPublicKeyRetrieval=true
SPRING_DATASOURCE_USERNAME=mateclaw_user
SPRING_DATASOURCE_PASSWORD=your_strong_user_password_here

# JWT令牌密钥，用于加密认证信息，务必修改为一个强随机字符串！
JWT_SECRET=your_very_strong_and_random_jwt_secret_key_here

重要提示 ： JWT_SECRET 和数据库密码 必须修改 ，切勿使用示例中的默认值或弱密码，这是生产环境安全的基本要求。

4.2 第二步：启动服务

配置好 .env 文件后，一行命令即可启动所有服务：

docker-compose up -d

执行后，Docker会完成以下工作：

  1. 拉取MySQL和MateClaw的镜像（如果本地没有）。
  2. 根据 docker-compose.yml 定义，创建网络和容器。
  3. 启动MySQL容器，并根据环境变量初始化数据库和用户。
  4. 启动MateClaw容器，应用启动时会：
    • 通过Flyway自动在MySQL中创建所有表结构。
    • 初始化默认的管理员账号（ admin / admin123 ）。
    • 启动内嵌的Web服务器。

等待几分钟（首次启动需要下载镜像和初始化数据库），访问 http://你的服务器IP:18080 ，应该能看到登录界面。

4.3 第三步：初始登录与安全加固

使用默认账号 admin / admin123 登录。 登录后第一件事，就是修改这个默认密码！

  1. 进入Web控制台。
  2. 通常在右上角或个人中心找到“修改密码”功能。
  3. 设置一个强密码并妥善保存。

4.4 第四步：核心配置——模型供应商与密钥

没有模型，AI大脑就无法思考。接下来配置MateClaw与外部AI模型的连接。

  1. 进入模型管理 ：在管理后台，找到 设置 -> 模型供应商 或类似菜单。
  2. 添加供应商 ：点击“新增”，你会看到一个支持供应商的列表（如OpenAI、Azure OpenAI、Anthropic Claude、DeepSeek等）。
  3. 配置API密钥 ：选择其中一个，例如“OpenAI”。你需要填写：
    • API Base URL : 通常保持默认（如 https://api.openai.com/v1 ），如果你使用代理或第三方网关，则需要修改。
    • API Key : 填入你在对应平台申请的密钥。
    • 模型列表 : 系统可能会预填一些常见模型（如 gpt-4o , gpt-4-turbo-preview ），你可以根据你的权限进行删减。
    • 优先级 ：设置一个数字，数字越小优先级越高。你可以配置多个供应商，并设置不同的优先级。
  4. 健康检查与熔断 ：在供应商配置中，通常还有“最大失败次数”、“冷却时间（秒）”等选项。例如，可以设置为“连续3次请求失败后，将该供应商冷却300秒（5分钟）”。
  5. 测试连接 ：保存后，使用界面提供的“测试”功能，验证密钥和连接是否有效。

配置多个供应商的实战策略： 假设你同时拥有OpenAI和DeepSeek的API密钥。你可以这样配置：

  • 供应商A：OpenAI，优先级1，模型 gpt-4o 。用于处理对回答质量要求最高的任务。
  • 供应商B：DeepSeek，优先级2，模型 deepseek-chat 。作为高性价比的备用选择，当OpenAI失效或达到速率限制时自动切换。

这样，在绝大多数情况下，系统会使用GPT-4o；一旦OpenAI服务出现问题，用户对话会自动由DeepSeek接棒，实现高可用。

4.5 第五步：创建你的第一个AI Agent

Agent是执行具体任务的工作单元。我们来创建一个简单的客服助手。

  1. 进入Agent管理 ：找到 AI智能体 -> Agent管理 ，点击“创建”。
  2. 基础信息 ：
    • 名称 ： 客服助手-初级
    • 描述 ：用于回答官网常见问题。
    • 系统指令 (System Prompt) ：这是Agent的“人格”和职责定义。例如： 
      你是一个友好、专业的客服助手。你的主要职责是回答用户关于我们产品（MateClaw）的常见问题。
如果用户的问题超出你的知识范围，或者涉及账号、订单等敏感信息，你应该礼貌地引导用户联系人工客服。
回答请简洁、清晰，使用中文。
  3. 能力配置 ：
    • 模型路由策略 ：选择“使用全局默认策略”或为此Agent单独指定一个模型供应商/优先级列表。
    • 启用工具 ：可以从已安装的工具列表中选择，例如“网页搜索”、“知识库查询”。（工具需要先在 工具管理 中配置或从市场安装）。
    • 启用记忆 ：勾选“工作空间记忆”，这样Agent能记住与同一用户的对话历史。
  4. 发布与测试 ：保存并发布Agent后，你可以在 Web控制台 的聊天界面中直接选择这个Agent进行测试，也可以将其分配给某个 渠道 （如Web Widget）供外部用户使用。

5. 高级功能实战：构建知识库与连接即时通讯

5.1 构建可验证的LLM Wiki知识库

假设你有一份产品手册PDF，希望将其转化为Agent可以查询的智能知识库。

  1. 创建知识库 ：进入 知识库 -> LLM Wiki ，点击“新建知识库”。
  2. 上传文档 ：将你的产品手册PDF拖入上传区域。MateClaw支持批量上传多种格式（PDF, MD, TXT, HTML等）。
  3. 配置处理参数 ：
    • 分块策略 ：选择文档切片的大小和重叠度。对于手册，中等大小的分块（如1000字符）可能比较合适。
    • 索引方式 ：除了传统的向量索引，确保开启 “生成结构化页面” 选项，这是LLM Wiki的核心。
  4. 启动处理 ：提交后，系统会在后台使用LLM处理文档。这个过程可能会花费一些时间，取决于文档大小和模型速度。处理完成后，你会看到文档被转换成了一个个有标题、有内容的Wiki页面。
  5. 验证与使用 ：
    • 浏览生成的Wiki页面，你会发现关键术语自动变成了 [[链接]] ，点击可以跳转。
    • 在页面上悬停或点击引用标记 [1] ，可以查看该段内容来源于原始PDF的哪一页哪一段。
    • 现在，你可以在创建或编辑Agent时，为其启用“知识库查询”工具，并关联到这个新建的知识库。当用户提问时，Agent会自动检索相关知识片段，并生成带有引用的回答。

5.2 接入钉钉机器人

将MateClaw接入日常办公IM，能极大提升效率。这里以钉钉为例。

在MateClaw端配置：

  1. 进入 渠道 -> 即时通讯 ，选择“钉钉”。
  2. 点击“创建机器人配置”。
  3. 这里需要填写从钉钉开放平台获取的信息，但首先我们需要去钉钉那边创建机器人。

在钉钉开放平台操作：

  1. 登录钉钉开发者后台（https://open.dingtalk.com）。
  2. 创建或进入一个企业内部应用（机器人）。
  3. 在应用详情中，找到：
    • AgentId : 应用详情里的 AgentId 。
    • AppKey 与 AppSecret : 用于API调用认证。
    • 消息接收地址 ：这是一个 回调URL ，需要填入MateClaw提供给钉钉的地址。格式通常为 http://你的MateClaw公网IP:端口/dingtalk/callback 。 确保此地址能被钉钉服务器公网访问到 （这通常意味着你需要为部署MateClaw的服务器配置公网IP和域名，或使用内网穿透工具）。
  4. 在钉钉后台配置“消息接收地址”时，需要验证Token。MateClaw在创建机器人配置时会生成一个Token，你需要将这个Token填回钉钉后台。

完成对接与测试：

  1. 将钉钉平台获取的 AgentId , AppKey , AppSecret 填回MateClaw的配置页面。
  2. 将MateClaw生成的 Token 和 加密密钥 （如果有）填到钉钉后台。
  3. 在MateClaw中，将该钉钉机器人配置绑定到之前创建的 客服助手-初级 Agent。
  4. 保存所有配置。在钉钉群里@你创建的机器人，发送一条消息测试。如果一切顺利，你应该能收到来自MateClaw Agent的回复。

避坑指南：IM通道配置的常见问题

  • 网络不通 ：这是最常见的问题。确保MateClaw服务器的回调地址（ /dingtalk/callback 等）能被公网访问。对于开发测试，可以使用 ngrok 或 localtunnel 等工具生成临时公网地址。
  • Token/Secret不匹配 ：两端配置的Token、加密密钥必须完全一致，包括大小写。
  • 权限不足 ：确保钉钉机器人已发布，并且拥有发送消息、接收消息等必要权限。
  • Agent未绑定或未启用 ：在MateClaw中，检查IM通道配置是否正确关联了已发布的Agent。

6. 生产环境运维、问题排查与性能调优

将MateClaw用于实际生产，除了功能配置，还需要关注稳定性、安全性和性能。

6.1 安全加固清单

  1. 修改所有默认凭证 ：包括管理员密码、数据库密码、JWT密钥。
  2. 启用HTTPS ：通过Nginx反向代理配置SSL证书，确保前端与管理后台、API接口的通信加密。
  3. 配置防火墙 ：只开放必要的端口（如80/443, 数据库端口3306应限制内网访问）。
  4. 细粒度RBAC ：不要所有人都用 admin 账号。根据团队成员职责，创建不同的角色（如“系统管理员”、“模型配置员”、“客服主管”、“客服人员”），并分配最小必要权限。
  5. 审计日志 ：定期检查MateClaw的审计日志，关注异常登录、敏感操作（如模型密钥修改、用户权限变更）。
  6. 模型API密钥管理 ：考虑使用Vault等密钥管理工具动态注入API密钥，而非硬编码在配置文件中。

6.2 常见问题排查速查表

问题现象 可能原因 排查步骤与解决方案
应用启动失败，数据库连接错误 1. 数据库服务未启动。
2. 连接参数（URL、用户名、密码）错误。
3. 数据库驱动版本不匹配。		 1. 检查MySQL容器/服务是否运行 ( docker ps 或 systemctl status mysql )。
2. 核对 .env 或 application.yml 中的连接字符串。
3. 确认MySQL版本为8.0+，尝试更新 pom.xml 中的MySQL驱动版本。
前端页面可以访问，但所有API请求返回401/403 1. 未登录或登录已过期。
2. JWT密钥在重启后变更，导致旧令牌失效。
3. 跨域问题（如果前端独立部署）。		 1. 清除浏览器缓存和Cookie，重新登录。
2. 检查JWT密钥配置，确保前后端一致且重启后未改变。
3. 检查浏览器开发者工具Network面板，查看请求头是否正确携带了 Authorization 。在后端配置正确的CORS策略。
AI对话无响应或一直“思考中” 1. 模型供应商API密钥无效或余额不足。
2. 网络问题导致无法访问外部API。
3. 所有配置的供应商均处于“冷却”状态。
4. Agent配置的上下文长度过长，导致生成缓慢。		 1. 在“模型供应商”管理页面，测试各个供应商的连接状态。
2. 在服务器上使用 curl 命令测试是否能访问 api.openai.com 等地址。
3. 检查供应商健康仪表盘，将处于冷却状态的供应商手动恢复或调整熔断策略。
4. 在Agent配置中减少“最大上下文长度”或启用“动态上下文修剪”功能。
知识库文档处理失败 1. 文档格式不支持或已损坏。
2. 处理文档的LLM供应商调用失败。
3. 服务器内存或磁盘空间不足。		 1. 尝试将文档转换为纯文本或Markdown格式再上传。
2. 检查处理知识库时指定的模型供应商是否工作正常。
3. 查看应用日志，定位具体错误信息。检查服务器资源使用情况。
钉钉/飞书等IM机器人不回复 1. 网络回调地址不通。
2. 机器人配置的Token/Secret不匹配。
3. Agent未正确绑定或未启用。
4. IM平台权限配置不全。		 1. 使用在线端口检测工具检查回调URL的公网可达性。
2. 逐字核对MateClaw和IM平台两边的Token、加密密钥。
3. 在MateClaw渠道配置中，确认绑定了已发布且启用的Agent。
4. 在IM平台后台，确保机器人已拥有“接收消息”、“发送消息”等权限。

6.3 性能监控与调优建议

  • 数据库 ：MySQL是主要性能瓶颈点之一。确保为 conversation , message , knowledge_chunk 等核心表建立合适的索引（如 conversation_id , created_at ）。定期清理过期的会话和消息数据。
  • JVM参数 ：如果部署在物理机或虚拟机上，根据服务器内存调整Spring Boot的JVM启动参数（如 -Xms 和 -Xmx ），避免频繁GC影响响应速度。
  • 模型调用超时 ：在 application.yml 中配置合理的超时时间，避免因某个慢速模型阻塞整个请求。 
    spring:
  ai:
    openai:
      chat:
        options:
          # 设置请求超时为30秒
          request-timeout: 30s
  • 对话上下文管理 ：对于长对话，启用Agent的“动态上下文修剪”功能。这可以让系统自动摘要或丢弃较早的、不重要的历史消息，在保证连贯性的同时控制输入Token数量，从而降低成本和提升速度。
  • 缓存策略 ：考虑对频繁查询的知识库向量索引结果、固定的系统提示词等进行缓存，减少对LLM和数据库的重复请求。

7. 扩展与定制：开发你的第一个MateClaw插件

MateClaw的插件系统（基于 mateclaw-plugin-api ）允许你扩展其能力。假设我们需要开发一个“天气查询”插件。

1. 创建Maven模块 使用 mateclaw-plugin-sample 作为模板，创建一个新的Maven模块，例如 mateclaw-plugin-weather 。

2. 实现工具接口 插件核心是实现 Tool 接口。创建一个 WeatherTool 类：

@Component
public class WeatherTool implements Tool {

    @Override
    public String getName() {
        return "get_weather";
    }

    @Override
    public String getDescription() {
        return "根据城市名称查询当前天气情况。";
    }

    @Override
    public Map<String, Object> getParameters() {
        // 定义工具需要的输入参数
        return Map.of(
            "city", Map.of("type", "string", "description", "城市名称，例如：北京")
        );
    }

    @Override
    public Object execute(Map<String, Object> parameters) {
        String city = (String) parameters.get("city");
        // 这里调用真实的外部天气API，例如和风天气、OpenWeatherMap等
        // 为了示例，我们返回模拟数据
        String weatherInfo = simulateWeatherApiCall(city);
        return Map.of("city", city, "weather", weatherInfo);
    }

    private String simulateWeatherApiCall(String city) {
        // 模拟API调用
        return String.format("%s的天气是晴，温度25°C，湿度60%%。", city);
    }
}

3. 定义技能描述文件 在 resources 目录下创建 SKILL.md 文件，用自然语言描述这个工具的功能、使用场景和示例，这有助于LLM更好地理解何时调用该工具。

4. 打包与安装 将模块打包成JAR文件，然后将其放入MateClaw服务器的插件目录（通常由 plugin.dir 配置项指定），重启MateClaw服务。系统会自动扫描并加载插件。

5. 在控制台启用工具 重启后，在管理后台的 工具管理 页面，你应该能看到新注册的 get_weather 工具。将其授权给相应的Agent角色，并绑定到具体的Agent上。

现在，当用户向绑定了此工具的Agent提问“北京天气怎么样？”时，Agent会自主决定调用 get_weather 工具，并将执行结果融入它的回复中。

通过这个流程，你可以将任何内部系统API、第三方服务或自定义逻辑封装成MateClaw的工具，极大地扩展了Agent的能力边界。从数据库查询到审批流触发，从硬件控制到数据分析，都可以通过插件体系无缝集成。

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

ClawBridge 网关日志审计：如何避免 Slack 事件重复处理与权限疲劳

avatar 龙虾开发者社区
cover

从零构建本地AI Agent网关：ClawBridge在沙箱与工具调用中的实战踩坑

avatar 龙虾开发者社区
cover

密钥管理实战：如何避免多模型路由场景下的 API Key 泄露风险

avatar 龙虾开发者社区