---
name: claw-friend-message-capture
description: 自动抓取虾友发送的 IM 消息，包括文字、截图和文件附件。场景：抓取虾友消息、查看虾友消息、获取好友消息、拉取未读消息、下载虾友附件。
---

# 抓取虾友消息

通过 Sophnet IM API 拉取虾友（好友）发送的消息，支持文字、图片截图和文件附件。脚本 `{baseDir}/scripts/capture_messages.py` 提供四个子命令。

## 子命令速查

| 子命令 | 用途 | 示例场景 |
|--------|------|---------|
| `friends` | 查看所有虾友及 DM 频道 | "列出我的虾友" |
| `list` | 拉取指定好友的消息历史 | "查看小明的最近消息" |
| `unread` | 拉取所有未读/最近消息 | "抓取虾友消息" / "查看未读消息" |
| `download` | 下载消息附件（图片/文件） | "下载虾友发的截图" |

## 用法

### 1. 列出虾友 + DM 频道

```bash
uv run {baseDir}/scripts/capture_messages.py friends --json
```

输出每项含 `friendId`、`nickname`、`dmChannelId`（rid）。

### 2. 拉取指定好友消息

```bash
# 通过 friendId 自动查找 DM 频道
uv run {baseDir}/scripts/capture_messages.py list --friend-id 123 --count 30

# 直接用 rid（DM 频道 ID）
uv run {baseDir}/scripts/capture_messages.py list --rid "<rid>" --count 30

# 指定时间范围（latest 为毫秒时间戳，拉取此时间之前的消息）
uv run {baseDir}/scripts/capture_messages.py list --rid "<rid>" --latest 1700000000000 --count 20
```

### 3. 抓取所有未读/最近消息

```bash
# 拉取所有 DM 频道最新消息
uv run {baseDir}/scripts/capture_messages.py unread

# 仅拉取有未读的频道，每个频道 20 条
uv run {baseDir}/scripts/capture_messages.py unread --count 20 --min-unread 1
```

### 4. 下载消息附件

```bash
# 下载指定消息中的图片和文件
uv run {baseDir}/scripts/capture_messages.py download \
  --rid "<rid>" \
  --msg-id "<消息ID>" \
  --out-dir ./downloads
```

附件保存到 `{out-dir}/images/`（截图）和 `{out-dir}/files/`（文件）。

## 执行建议

- 用户说「抓取虾友消息」→ 先执行 `friends --json`，然后对每个 DM 频道执行 `list` 或批量执行 `unread`
- 用户说「下载虾友发的图片」→ 从消息 JSON 中找到 `imageAttachments`，对目标消息执行 `download`
- 用户提供昵称 → 从 `friends` 输出中匹配 `nickname`，拿到 `dmChannelId` 再拉消息

## 首次设置（获取 refresh token）

首次使用前需配置 refresh token，之后 JWT 过期会自动续期。

### 获取 refresh token

1. 浏览器打开 Sophnet 并登录
2. 按 F12 → **应用**（Application）→ **本地存储**（Local Storage）→ `user-info`
3. 复制其中 `refreshToken` 字段的值

也可以打开浏览器控制台（Console），执行以下命令直接复制：

```js
copy(JSON.parse(localStorage['user-info']).refreshToken)
```

### 配置 refresh token（三选一）

**方式 A — setup 子命令（推荐）**：

```bash
uv run {baseDir}/scripts/capture_messages.py setup --refresh-token "<你的refreshToken>"
```

**方式 B — 环境变量**（重启后失效）：

```bash
export SOPHCLAW_REFRESH_TOKEN="<你的refreshToken>"
```

**方式 C — 文件持久化**：

```bash
echo "<你的refreshToken>" > ~/.openclaw/refresh_token
```

配置完成后即可正常使用，JWT 过期时自动续期。

## 注意事项

- 从 `/home/node/.openclaw/jwt.json` 的 `web_jwt` 字段读取 JWT，通过 `sophclaw_auth` 模块自动检测过期并续期（refresh token 有效期最长 30 天）
- refresh token 读取优先级：jwt.json → 环境变量 `SOPHCLAW_REFRESH_TOKEN` → 文件 `~/.openclaw/refresh_token`
- 默认 API 地址：`https://yagent.sophnet.com/api`，可通过 `--api-base-url` 或环境变量 `SOPHCLAW_API_BASE_URL` 覆盖
- 附件 URL 默认按 `https://www.sophnet.com` 拼接 Origin，可通过 `--origin` 或 `SOPHCLAW_ORIGIN` 覆盖
- 凭证文件和 JWT 切勿提交 Git
- 本 skill 仅提供单次拉取，如需定时自动抓取，请在 Agent 侧配置 Cron Job