agent-whatsapp

Agent WhatsApp

一款由 Baileys 驱动、供 AI Agent 使用的 WhatsApp 命令行工具。通过 QR 码或配对码以伴侣设备的方式关联，因此手机会保持连接。每条命令都会按需建立连接，并在完成后断开。

使用以下任一入口：

• 全局安装：agent-whatsapp ...
• 一次性执行：bunx --package agent-messenger agent-whatsapp ...

核心概念

开始之前，先了解一些 WhatsApp 架构相关知识：

• JID（Jabber ID）= WhatsApp 的地址格式。个人：[email protected]。群组：[email protected]。你可以直接传入电话号码，命令行工具会自动将其解析为 JID。
• QR 码身份验证 = 扫描终端或浏览器中显示的 QR 码，将命令行工具关联为伴侣设备。打开 WhatsApp > 已关联的设备 > 关联设备，然后扫描 QR 码。
• 配对码身份验证 = 使用终端中显示的数字代码，将命令行工具关联为伴侣设备。在手机 WhatsApp 的“已关联的设备”下输入该代码。
• 按需连接 = 命令行工具会为每条命令打开 WebSocket 连接，并在完成后断开。不会有持久运行的后台进程。
• 多账号 = 可关联多个 WhatsApp 账号。使用 auth list 和 auth use 切换账号。

快速开始

# Link as companion device via QR code (scan with your phone)
agent-whatsapp auth login --qr

# Or link via pairing code (enter the code on your phone)
agent-whatsapp auth login --phone +1234567890

# List chats
agent-whatsapp chat list

# Send a message
agent-whatsapp message send +1234567890 "Hello from agent-whatsapp"

身份验证流程

WhatsApp 支持两种身份验证方式。两种方式都会将命令行工具注册为伴侣（已关联）设备，因此不会影响手机会话。

• QR 码（--qr）：终端中会显示 QR 码，并在浏览器中打开。用手机上的 WhatsApp 扫描。无需提供电话号码。
• 配对码（--phone）：会显示数字代码。在手机 WhatsApp 的“已关联的设备”>“通过手机号关联”下输入该代码。

Agent 行为（强制）

如果命令因未配置账号而失败，Agent 必须自行完成身份验证流程。切勿让用户运行命令，一切操作都由 Agent 执行。

步骤 1：检查是否存在已有账号

agent-whatsapp auth list

如果存在账号，使用 agent-whatsapp auth use <account-id>，然后重试原始命令。

步骤 2：如果没有账号，开始 QR 码登录（首选）

agent-whatsapp auth login --qr
# -> QR code displayed in terminal + opened in browser
# -> {"next_action":"scan_qr","qr_url":"...","message":"Scan with WhatsApp on your phone"}

告知用户使用 WhatsApp 扫描 QR 码：设置 > 已关联的设备 > 关联设备 > 扫描 QR 码。

替代方案：使用配对码登录

如果无法扫描 QR 码（例如，在无头环境中），请询问用户的电话号码并使用配对码：

agent-whatsapp auth login --phone +1234567890
# -> {"pairing_code":"A1B2-C3D4","message":"Enter this code in WhatsApp > Linked Devices > Link with phone number"}

告知用户配对码，并请其在手机上输入。

步骤 3：等待确认

命令行工具会等待用户在手机上确认。确认后：

# -> {"authenticated":true,...}

步骤 4：重试原始命令

身份验证成功后，立即执行用户最初要求的操作。

常用身份验证命令

agent-whatsapp auth status              # Check current auth state
agent-whatsapp auth status --account <id>  # Check specific account
agent-whatsapp auth list                # List all linked accounts
agent-whatsapp auth use <id>            # Switch active account
agent-whatsapp auth logout              # Unlink current account
agent-whatsapp auth logout --account <id>  # Unlink specific account

记忆

Agent 会将 ~/.config/agent-messenger/MEMORY.md 文件用作跨会话的持久记忆。该文件由 Agent 管理。命令行工具不会读取或写入此文件。使用 Read 和 Write 工具管理记忆文件。

读取记忆

每项任务开始时，使用 Read 工具读取 ~/.config/agent-messenger/MEMORY.md，加载之前发现的聊天 ID、联系人姓名和偏好。

• 如果文件尚不存在，也没关系。继续操作，并在首次获得有用信息时创建该文件。
• 如果无法读取文件（权限问题、目录不存在），则不使用记忆继续操作。

写入记忆

发现有用信息后，使用 Write 工具更新 ~/.config/agent-messenger/MEMORY.md。以下情况应触发写入：

• 发现聊天 JID 和联系人姓名后（通过 chat list）
• 发现群组名称和参与者后
• 用户提供别名或偏好后（“把这个叫作家庭群组”“我的工作聊天是 X”）

写入时，包含完整文件内容。Write 工具会覆盖整个文件。

存储内容

• 包含联系人／群组名称的聊天 JID
• 你自己的电话号码和 JID
• 用户提供的别名（“家庭群组”“工作聊天”）
• 常用聊天 JID
• 互动过程中表达的任何用户偏好

不应存储的内容

绝不要存储身份验证凭据、会话密钥或任何敏感数据。绝不要存储完整消息内容（仅存储 ID 和聊天上下文）。

处理过期数据

如果记忆中的 JID 返回错误，请将其从 MEMORY.md 中移除。不要盲目信任记忆中的数据。对于可能已过期的记忆 JID，应优先重新列出聊天，而不是直接使用。

格式／示例

# Agent Messenger Memory

## WhatsApp Account

- Phone: +1234567890
- JID: [email protected]

## Chats

- `[email protected]` - Alice (1:1)
- `[email protected]` - Bob (1:1)
- `[email protected]` - Project Team (group, 8 members)
- `[email protected]` - Family (group, 5 members)

## Aliases

- "alice" -> `[email protected]`
- "project" -> `[email protected]` (Project Team)
- "family" -> `[email protected]` (Family group)

## Notes

- User prefers --pretty output
- Project Team is the most frequently used chat

使用记忆可以跳过重复的 chat list 调用。如果你已在先前的会话中知道某个 JID，请直接使用。

命令

身份验证命令

# Link as companion device via QR code (no phone number needed)
agent-whatsapp auth login --qr

# Link as companion device via pairing code
agent-whatsapp auth login --phone +1234567890

# Check auth status
agent-whatsapp auth status
agent-whatsapp auth status --account <id>

# List linked accounts
agent-whatsapp auth list

# Switch active account
agent-whatsapp auth use <id>

# Unlink account
agent-whatsapp auth logout
agent-whatsapp auth logout --account <id>

Whoami 命令

# Show current authenticated user
agent-whatsapp whoami
agent-whatsapp whoami --pretty
agent-whatsapp whoami --account <account-id>

输出包含已验证用户的身份信息。

聊天命令

# List chats (sorted by most recent activity)
agent-whatsapp chat list
agent-whatsapp chat list --limit 50
agent-whatsapp chat list --account <id>

# Search chats by name
agent-whatsapp chat search "project"
agent-whatsapp chat search "project" --limit 10
agent-whatsapp chat search "project" --account <id>

输出包含：

• jid - 聊天 JID（个人或群组）
• name - 联系人或群组名称
• unread_count - 未读消息数
• last_message - 最近一条消息的预览

消息命令

# List messages in a chat
agent-whatsapp message list <chat> --limit 20
agent-whatsapp message list +1234567890 --limit 50
agent-whatsapp message list [email protected] --limit 10
agent-whatsapp message list +1234567890 --limit 20 --account <id>

# Send a text message
agent-whatsapp message send <chat> <text>
agent-whatsapp message send +1234567890 "Hello!"
agent-whatsapp message send [email protected] "Hello team!"
agent-whatsapp message send +1234567890 "Hello!" --account <id>

# Edit one of your own messages (within ~15 minutes)
agent-whatsapp message edit <chat> <message-id> <text>
agent-whatsapp message edit +1234567890 ABC123DEF456 "Updated text"

# React to a message
agent-whatsapp message react <chat> <message-id> <emoji>
agent-whatsapp message react +1234567890 ABC123DEF456 "👍"
agent-whatsapp message react +1234567890 ABC123DEF456 "👍" --from-me
agent-whatsapp message react +1234567890 ABC123DEF456 "👍" --account <id>

<chat> 参数接受：

• 电话号码：+1234567890（自动解析为 JID）
• 个人 JID：[email protected]
• 群组 JID：[email protected]

message react 上的 --from-me 标志表示目标消息由你发送（发出的消息）。如果不使用该标志，回应的目标就是收到的消息。

输出格式

JSON（默认）

所有命令默认输出 JSON，供 AI 使用：

{
  "jid": "[email protected]",
  "name": "Alice",
  "unread_count": 3,
  "last_message": {
    "id": "ABC123DEF456",
    "text": "See you tomorrow!",
    "from": "[email protected]",
    "timestamp": 1705312200
  }
}

Pretty（便于阅读）

使用 --pretty 标志输出格式化内容：

agent-whatsapp chat list --pretty

全局选项

选项	说明
--pretty	输出便于阅读的内容，而非 JSON
--account <id>	为此命令使用指定账户

常见用法

查看未读消息

# List chats to see unread counts
agent-whatsapp chat list --limit 20

# Read messages from a specific chat
agent-whatsapp message list +1234567890 --limit 10

向联系人发送消息

# By phone number (simplest)
agent-whatsapp message send +1234567890 "Hey, are we still on for tomorrow?"

# By JID
agent-whatsapp message send [email protected] "Hey, are we still on for tomorrow?"

向群组发送消息

# Find the group first
agent-whatsapp chat search "Project Team"

# Send to the group JID
agent-whatsapp message send [email protected] "Status update: deployment complete."

对最新消息作出回应

# Get the latest message ID
agent-whatsapp message list +1234567890 --limit 1

# React to it
agent-whatsapp message react +1234567890 <message-id> "👍"

编辑你自己发送的消息

# Get the message ID of a message you sent
agent-whatsapp message list +1234567890 --limit 5

# Edit it (only your own messages, within ~15 minutes)
agent-whatsapp message edit +1234567890 <message-id> "Updated text"

SDK 通过 WhatsAppClient.editMessage 提供相同功能：

import { WhatsAppClient } from 'agent-messenger/whatsapp'

const client = await new WhatsAppClient().login()
const sent = await client.sendMessage('+1234567890', 'Deploying…')
await client.editMessage('+1234567890', sent.id, 'Deployed ✅')

错误处理

所有命令均返回一致的错误格式：

{
  "error": "No WhatsApp account linked. Run: agent-whatsapp auth login --qr"
}

常见错误：

• No WhatsApp account linked - 尚未通过身份验证。运行 auth login --qr 或 auth login --phone <number>。
• Connection timeout - 与 WhatsApp 的 WebSocket 连接失败。请重试该命令。
• Invalid JID - 电话号码或 JID 格式错误。请使用带 + 前缀的国际格式。
• Not a group participant - 无法向你不是成员的群组发送消息。

注意事项

• JID 格式：个人聊天使用 [email protected]，群组使用 [email protected]。可以直接传入电话号码，系统会自动解析。
• 按需连接：每条命令都会打开 WebSocket 连接，并在完成后关闭。没有持久运行的守护进程或后台进程。
• 封禁风险：WhatsApp 会监测自动化行为。避免高频发送消息、连续快速发送或批量操作。发送多条消息时，请拉开发送间隔。
• 多账户：可以同时关联多个 WhatsApp 号码。使用 auth list 查看所有账户，并使用 auth use <id> 切换账户。
• 电话号码：始终使用包含国家代码的国际格式（例如 +1234567890、+821012345678）。
• agent-whatsapp 默认返回 JSON，使用 --pretty 可输出缩进格式。

故障排除

agent-whatsapp: command not found

agent-whatsapp 不是 npm 包名。 npm 包名是 agent-messenger。

如果已全局安装此包，请直接使用 agent-whatsapp：

agent-whatsapp chat list --pretty

如果尚未安装此包，请使用 --package 安装并运行：

npx -y --package agent-messenger agent-whatsapp chat list --pretty
bunx --package agent-messenger agent-whatsapp chat list --pretty
pnpm dlx --package agent-messenger agent-whatsapp chat list --pretty

切勿在未指定 --package agent-messenger 的情况下运行 npx agent-whatsapp、bunx agent-whatsapp 或 pnpm dlx agent-whatsapp。 由于 agent-whatsapp 不是 npm 包名，这些命令会失败或安装错误的包。

无法扫描二维码

1. 确保手机上的 WhatsApp 已打开
2. 前往 Settings > Linked Devices > Link a Device
3. 将手机摄像头对准终端或浏览器中的二维码
4. 如果二维码过期，请再次运行 auth login --qr 获取新二维码
5. 如果无法扫描二维码，请尝试配对码：auth login --phone <number>

配对码无法使用

1. 确保手机上的 WhatsApp 已打开
2. 前往 Settings > Linked Devices > Link a Device
3. 如果看到二维码，请选择“Link with phone number instead”
4. 输入终端中显示的配对码
5. 如果配对码过期，请再次运行 auth login --phone <number> 获取新配对码

关联新设备后聊天列表为空

WhatsApp 配套设备会从主手机接收聊天列表——没有可直接获取该列表的服务器 API。对于刚关联的设备，chat list 可能只返回群聊（也可能为空），不会显示个人聊天或私聊。

• 保持手机联网并打开 WhatsApp，在关联期间和关联完成后都要如此。手机会将聊天记录推送到新设备；如果手机关机或 WhatsApp 被关闭，就不会收到任何内容。
• 等待几分钟，然后再次运行 chat list。聊天记录会逐渐同步并保存在本地，因此后续运行时会显示更多聊天。
• 群聊始终可以立即使用——它们从服务器获取，而不是通过聊天记录同步。
• 向已知电话号码发送消息，即使该聊天未包含在初次同步中，也会使其显示出来。

这是 WhatsApp 协议的限制，并非错误。

连接中断

如果关联设备长时间处于非活动状态，WhatsApp 可能会断开其连接。如果命令开始失败：

# Check if still linked
agent-whatsapp auth status

# Re-link if needed
agent-whatsapp auth login --qr