---
name: wechat-get-messages
description: 拉取微信消息列表，支持按联系人过滤、按时间增量拉取(since)。自动应答轮询流程的数据入口。
---

# wechat-get-messages

从后端拉取微信消息列表。支持三种常见用法：

1. **全量最新**：不带参数，返回最近 50 条
2. **按联系人**：传 `wxid=wxid_abc123` 只看某人的对话
3. **增量拉取**：传 `since=<ISO时间戳>` 只拿该时间之后的新消息（轮询场景）

## 触发场景

- 用户问："最近有谁给我发微信了？"
- 用户问："xxx 最近说了什么？"
- 自动应答的定时轮询（每 N 秒拉新消息后分发回复）

## 执行步骤（LLM 请按顺序执行）

**Step 1**：根据用户意图组装 query string。可选参数：

| 参数 | 说明 | 示例 |
|------|------|------|
| `limit` | 返回条数，默认 50，最大 200 | `limit=20` |
| `wxid` | 只看某联系人 | `wxid=wxid_abc123` |
| `direction` | `sent`=自己发的，`received`=别人发的 | `direction=received` |
| `since` | ISO 时间戳，增量拉取 | `since=2026-04-17T10:00:00.000Z` |

**Step 2**：用 `exec`/bash 工具执行（示例：拉最近 20 条别人发来的）：

```bash
API_BASE=$(node -e "console.log(JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(),'.openclaw','wechat-credentials.json'),'utf8')).wechatApiBase)")
curl -s --max-time 15 -G "$API_BASE/messages" \
  --data-urlencode "limit=20" \
  --data-urlencode "direction=received"
```

增量拉取示例：

```bash
curl -s -G "$API_BASE/messages" --data-urlencode "since=2026-04-17T10:00:00.000Z"
```

**Step 3**：解析响应。每条消息关键字段：

- `fromWxid` — 发送者 wxid（回复目标）
- `toWxid` — 接收者 wxid
- `nickName` — 发送者昵称
- `type` — `text`/`image`/`voice`/`link`/`emoji`/`system` 等
- `content` — 文字内容或媒体摘要
- `timestamp` — ISO 时间戳（用作下次 since）

**Step 4**：根据业务做下游处理：

- 自动应答场景 → 过滤 `type=text` 且 `direction=received` → 调 `wechat-send-text(fromWxid, 回复)`
- 纯查询场景 → 把消息条数和摘要报给用户

## 重要提示

- 群聊消息 `fromWxid` 形如 `xxx@chatroom`，个人形如 `wxid_xxx`
- 应忽略 `weixin`/`fmessage`/`gh_*`（系统和公众号）
- 轮询时务必保存上一次的 `timestamp`，下次作为 `since` 传入