跳转到内容

智能体工具

除了被动回复消息,智能体还会获得一套针对 当前会话 的专属工具。消息历史类工具无法读取其他会话或账号。仅限所有者使用的表情工具可管理已配置账号上的“我的表情”。

工具名称功能描述
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 工具引导重新上线(需智能体具备相应工具权限):

  1. 调用 {"action":"status"} 检查配置的微信账号在线状态。
  2. 调用 {"action":"start"} 获取并展示登录二维码。使用手机微信扫码并确认登录。
  3. 调用 {"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_*"] } }
}
}
}