Skip to content
agent-wechat

Agent tools

Besides replying, the agent gets tools for the current chat. They can’t see other chats or accounts.

ToolWhat it does
wechat_historyEarlier messages in this chat, newest first
wechat_searchMessages in this chat containing some text
wechat_messageOne message by ID
wechat_mediaDownloads a message’s image, file, video or voice and gives the agent the file. Images are also shown to the model.
wechat_send_shareSends a link card (title, URL, optional description and thumbnail)
wechat_recallRecalls a message your account sent in this chat

For example, asked “what was that address Sam sent?”, the agent can call wechat_search with {"query": "address"}, then wechat_media on a matching photo.

Calling

The optional wechat_call tool checks status, places an allowed direct voice call, or ends the call this plugin owns. It requires separate calling permissions and an authorized owner; messaging permission alone does not grant it. See Set up calling for the tool grant, credentials and model setup.

Choose a message destination

For OpenClaw’s built-in message tool, use the contact or chat ID returned by wx contacts find NAME or wx chats find NAME as target. Both wechat:ID and agent-wechat:ID are accepted. Contact IDs without a wxid_ prefix are supported when the daemon has that exact contact or direct conversation. Nicknames and changeable WeChat aliases are not destination IDs.

Quote a message

Use OpenClaw’s built-in message tool with replyTo set to the stored message’s id from history, search or message lookup:

{
  "action": "send",
  "channel": "agent-wechat",
  "target": "CHAT_ID",
  "message": "Agreed, let's do that.",
  "replyTo": "STORED_MESSAGE_ID"
}

This sends a quoted text reply in a direct chat or group. The hub supplies the original content and checks that it belongs to the same account and chat. Use a stored message ID, rather than its serverId or a send/job ID. Unavailable, recalled or unsupported targets return an error. Attachments and mentions cannot be combined with a quoted reply.

Log in through your agent

wechat_login works from another channel while WeChat is offline, if your agent’s tool policy allows it:

  1. Call {"action":"status"} to check the configured account.
  2. Call {"action":"start"} and show the returned QR image. Scan it and approve on your phone.
  3. Call {"action":"wait","timeoutMs":30000} to check completion. The result includes the operation ID, state and connected status.

Repeating start follows the current login. For a new login, force: true uses a QR instead of saved trust. disconnect keeps saved trust; logout logs out; forget with confirm: true removes local authentication but keeps history. The tool needs the login token scope.

Group information for the owner

wechat_group_info reads a group and one page of cached members, or one exact member with username. It requires OpenClaw’s trusted owner/admin invocation context and the daemon’s read scope. Group ownership does not grant this permission. Allow the tool for your owner-facing agent; it cannot create groups or change settings.

{ "groupId": "123456@chatroom", "limit": 50 }

A missing cached member is unconfirmed. Use the CLI or API to refresh server data. No group mutation tools are registered.

Reading all chats

Five optional tools work across every chat on the account. They’re off unless you grant them to an agent:

ToolWhat it does
wechat_archive_threadsLists chats, with unread counts
wechat_archive_searchSearches all chats, or one
wechat_archive_historyReads any chat
wechat_archive_messageOne message from any chat
wechat_archive_mediaDownloads media from any chat

Grant them in ~/.openclaw/openclaw.json:

{
  "agents": {
    "ownership": "explicit",
    "entries": {
      "main": { "tools": { "alsoAllow": ["wechat_archive_*"] } },
      "group-bot": { "tools": { "deny": ["wechat_archive_*"] } }
    }
  }
}