智能体工具
除了被动回复消息,智能体还会获得一套针对 当前会话 的专属工具。消息历史类工具无法读取其他会话或账号。仅限所有者使用的表情工具可管理已配置账号上的“我的表情”。
| 工具名称 | 功能描述 |
|---|---|
wechat_history | 获取当前会话更早的历史消息(最新在前) |
wechat_search | 在当前会话中搜索包含指定关键词的消息 |
wechat_message | 按 ID 获取单条消息详情 |
wechat_media | 下载某条消息的图片、文件、视频或语音,并为智能体提供本地文件路径。图片还会直接作为多模态输入呈现给大模型。 |
wechat_send_share | 发送分享卡片(标题、链接、可选摘要及缩略图) |
wechat_recall | 撤回你的账号在当前会话中发出的消息 |
wechat_stickers | 仅限所有者:列出“我的表情”、查看元数据、图片预览、下载原图、准备、添加、调整位置及移除 |
例如当用户提问“Sam 刚才发的地址是什么?”时,智能体可以调用 wechat_search 传入 {"query": "地址"},并对匹配到的照片调用 wechat_media 提取图像内容。
自定义表情
使用 wechat_stickers 准备执行工作区中的文件、检查实际的图片预览并管理“我的表情”。它支持八种操作:list、get、preview、download、prepare、add、move 和 remove。浏览官方表情包及管理成员关系可在桌面应用和 CLI 中完成。
语音通话
可选的 wechat_call 工具支持查询通话状态、向允许的联系人发起单聊语音呼叫、发起或加入配置好的语音会议、邀请允许的联系人,或挂断当前插件拥有的通话。使用该工具需要单独配置通话权限与授权的管理员所有者;单凭文字消息收发权限无法使用。
关于工具授权、凭据配置与对话模型设置,请参考配置语音通话。
语音通话与智能体工具访问属于不同的独立配置项。将 wechat_call 添加到所选智能体的 tools.alsoAllow 中,或在需要所有智能体都具备该工具时添加到全局 tools.alsoAllow 中。请保留现有已配置的条目:
{ "tools": { "alsoAllow": ["wechat_login", "wechat_call"] }}智能体级别的 alsoAllow 会完全覆盖继承的全局列表。在添加智能体级别覆盖时,请将该智能体需要保留的所有全局条目一并复制过来。
修改配置后请重启或重载 Gateway。经过所有者授权的通话协同咨询随后即可使用通话控制功能,无需像普通文字聊天请求那样通过额外的 outboundToolAllowFrom 检查。只读通话无法使用该工具。发送目标/群聊白名单、宿主工具限制与授权审批依然生效。在会议通话中,所有者兼邀请者的权限适用于整场通话;混音音频无法确切区分具体是哪位参与者发出了指令。挂断操作会使智能体退出会议,其他参会成员仍可继续通话。
指定消息发送目标
在使用 OpenClaw 内置的 message 工具时,请将 wx contacts find 姓名 或 wx chats find 群名 返回的联系人或会话 ID 作为 target。支持 wechat:ID 与 agent-wechat:ID 两种格式前缀。若 Daemon 本地已有该确切联系人或单聊会话记录,也支持不带 wxid_ 前缀的联系人 ID。微信昵称和可修改的微信号不能作为发送目标 ID。
引用某条消息
使用 OpenClaw 内置的 message 工具,并将 replyTo 设为历史消息或搜索返回的存储消息 id:
{ "action": "send", "channel": "agent-wechat", "target": "CHAT_ID", "message": "好的,就按这个办。", "replyTo": "STORED_MESSAGE_ID"}这会在单聊或群聊中发送一条带引用的文本回复。Hub 节点会自动装填被引用消息的内容,并校验其确实属于当前账号与当前会话。请使用本地存储的消息 ID,而非其 serverId 或发送任务 ID。若目标消息不存在、已被撤回或格式不支持,将返回错误。引用回复不支持同时附带附件或群 @ 提醒。
让智能体协助处理登录
当微信掉线时,可以通过另一个通道调用 wechat_login 工具引导重新上线(需智能体具备相应工具权限):
- 调用
{"action":"status"}检查配置的微信账号在线状态。 - 调用
{"action":"start"}获取并展示登录二维码。使用手机微信扫码并确认登录。 - 调用
{"action":"wait","timeoutMs":30000}等待登录完成。结果将包含任务 ID、状态和connected标记。
重复调用 start 将持续跟随当前登录流。若要强制重新扫码,传入 force: true 将使用新二维码而非沿用信任。disconnect 保持本地信任凭据断开网络;logout 彻底登出;forget 配合 confirm: true 抹除本地身份验证凭证但保留聊天历史。该工具需要令牌具备 login 权限范围。
仅限所有者查询的群组信息
wechat_group_info 用于查看指定群聊及其缓存的群成员单页列表,或使用 username 查阅特定成员。它严格要求 OpenClaw 具备受信任的 owner/admin 执行上下文,且 Daemon 令牌具备 read 权限。普通群主身份并不自动代表具备此权限。建议仅向私有管理智能体开放此工具;该工具不支持创建群或修改设置。
{ "groupId": "123456@chatroom", "limit": 50 }未在本地缓存中确认的成员将被标记为 unconfirmed。如需刷新最新数据,请参考 CLI 或 API。本插件未注册任何群修改变更工具。
跨会话全局检索工具
系统还提供了 5 个可选的全局工具,能够检索当前微信账号下的 所有 历史会话。默认情况下处于禁用状态,除非你显式授权给特定智能体:
| 全局工具名称 | 功能描述 |
|---|---|
wechat_archive_threads | 列出全部会话及其未读数 |
wechat_archive_search | 在全部会话或指定会话中搜索消息 |
wechat_archive_history | 读取任意会话的聊天记录 |
wechat_archive_message | 跨会话按 ID 读取任意消息 |
wechat_archive_media | 跨会话下载任意消息的多媒体附件 |
在 ~/.openclaw/openclaw.json 中按需授权:
{ "agents": { "ownership": "explicit", "entries": { "main": { "tools": { "alsoAllow": ["wechat_archive_*"] } }, "group-bot": { "tools": { "deny": ["wechat_archive_*"] } } } }}