Back to Details

agent-whatsapp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent WhatsApp

Agent WhatsApp

A Baileys-backed WhatsApp CLI for AI agents. Links as a companion device via QR code or pairing code, so your phone stays connected. Each command connects on demand and disconnects when done.
Use one of these entrypoints:
  • Global install: 
    agent-whatsapp ...
  • One-off execution: 
    bunx --package agent-messenger agent-whatsapp ...
一款基于Baileys的AI Agent专用WhatsApp CLI工具。可通过二维码或配对码作为关联设备连接，无需断开手机端的WhatsApp连接。每个命令按需建立连接，执行完成后自动断开。
使用以下任意一种方式启动：
  • 全局安装后使用：
    agent-whatsapp ...
  • 一次性执行：
    bunx --package agent-messenger agent-whatsapp ...

Key Concepts

核心概念

Before diving in, a few things about WhatsApp's architecture:
  • JID (Jabber ID) = WhatsApp's address format. Individual: 
    1234567890@s.whatsapp.net
    . Group: 
    123456789-123345@g.us
    . You can pass plain phone numbers and the CLI resolves them to JIDs automatically.
  • QR code auth = links the CLI as a companion device by scanning a QR code displayed in the terminal or browser. Open WhatsApp > Linked Devices > Link a Device and scan the code.
  • Pairing code auth = links the CLI as a companion device using a numeric code displayed in your terminal. Enter it in WhatsApp on your phone under Linked Devices.
  • Connect-on-demand = the CLI opens a WebSocket connection for each command and disconnects afterward. There's no persistent background process.
  • Multi-account = multiple WhatsApp accounts can be linked. Use 
    auth list
    and 
    auth use
    to switch between them.
开始使用前，先了解WhatsApp的架构特点：
  • JID（Jabber ID）：WhatsApp的地址格式。个人账号格式：
    1234567890@s.whatsapp.net
    ，群组格式：
    123456789-123345@g.us
    。你可以直接输入普通电话号码，CLI会自动将其解析为JID。
  • 二维码验证：通过扫描终端或浏览器中显示的二维码，将CLI关联为辅助设备。操作步骤：打开WhatsApp > 关联设备 > 关联新设备，然后扫描二维码。
  • 配对码验证：通过终端显示的数字代码，将CLI关联为辅助设备。在手机端WhatsApp的「关联设备」中输入该代码即可。
  • 按需连接：每个命令执行时会建立WebSocket连接，执行完成后立即断开，无持久后台进程。
  • 多账号支持：可同时关联多个WhatsApp账号，使用
    auth list
    和
    auth use
    命令切换账号。

Quick Start

快速开始

bash
undefined
bash
undefined

Link as companion device via QR code (scan with your phone)

通过二维码关联辅助设备（用手机扫描）

agent-whatsapp auth login --qr
agent-whatsapp auth login --qr

Or link via pairing code (enter the code on your phone)

或通过配对码关联（在手机上输入代码）

agent-whatsapp auth login --phone +1234567890
agent-whatsapp auth login --phone +1234567890

List chats

列出聊天列表

agent-whatsapp chat list
agent-whatsapp chat list

Send a message

发送消息

agent-whatsapp message send +1234567890 "Hello from agent-whatsapp"
undefined
agent-whatsapp message send +1234567890 "Hello from agent-whatsapp"
undefined

Authentication Flow

验证流程

WhatsApp supports two authentication methods. Both register the CLI as a companion (linked) device, so your phone session is never affected.
  • QR code (
    --qr
    ): A QR code is displayed in the terminal and opened in the browser. Scan it with WhatsApp on your phone. No phone number needed.
  • Pairing code (
    --phone
    ): A numeric code is displayed. Enter it in WhatsApp on your phone under Linked Devices > Link with phone number.
WhatsApp支持两种验证方式，均会将CLI注册为关联设备，不会影响手机端的会话。
  • 二维码验证（
    --qr
    ）：终端会显示二维码并在浏览器中打开，用手机端WhatsApp扫描即可，无需输入电话号码。
  • 配对码验证（
    --phone
    ）：终端会显示数字代码，在手机端WhatsApp的「关联设备 > 使用电话号码关联」中输入该代码。

Agent Behavior (MANDATORY)

Agent行为规范（强制要求）

When a command fails because no account is configured, the agent MUST drive the auth flow itself. Never tell the user to run commands. The agent runs everything.
Step 1: Check for existing accounts
bash
agent-whatsapp auth list
If accounts exist, use 
agent-whatsapp auth use <account-id>
and retry the original command.
Step 2: If no accounts, start QR login (preferred)
bash
agent-whatsapp auth login --qr
当命令因未配置账号而失败时，Agent必须自动引导验证流程，绝不能让用户自行运行命令，所有操作由Agent执行。
步骤1：检查已有账号
bash
agent-whatsapp auth list
若存在账号，使用
agent-whatsapp auth use <account-id>
切换后重试原命令。
步骤2：若无账号，启动二维码登录（推荐方式）
bash
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"}

-> {"next_action":"scan_qr","qr_url":"...","message":"Scan with WhatsApp on your phone"}


Tell the user to scan the QR code with WhatsApp: Settings > Linked Devices > Link a Device > scan the QR code.

**Alternative: Pairing code login**

If QR scanning is not possible (e.g. headless environment), ask for the phone number and use pairing code:

```bash
agent-whatsapp auth login --phone +1234567890

告知用户用手机端WhatsApp扫描二维码：设置 > 关联设备 > 关联新设备 > 扫描二维码。

**备选方案：配对码登录**

若无法扫描二维码（如无头环境），请求用户提供电话号码并使用配对码：

```bash
agent-whatsapp auth login --phone +1234567890

-> {"pairing_code":"A1B2-C3D4","message":"Enter this code in WhatsApp > Linked Devices > Link with phone number"}

-> {"pairing_code":"A1B2-C3D4","message":"Enter this code in WhatsApp > Linked Devices > Link with phone number"}


Tell the user the pairing code and ask them to enter it on their phone.

**Step 3: Wait for confirmation**

The CLI waits until the user confirms on their phone. Once confirmed:

```bash

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

**步骤3：等待确认**

CLI会等待用户在手机上确认，确认成功后：

```bash

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

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


**Step 4: Retry the original command**

After successful auth, immediately execute whatever the user originally asked for.

**步骤4：重试原命令**

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

Common Auth Commands

常用验证命令

bash
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
bash
agent-whatsapp auth status              # 检查当前验证状态
agent-whatsapp auth status --account <id>  # 检查指定账号的验证状态
agent-whatsapp auth list                # 列出所有关联账号
agent-whatsapp auth use <id>            # 切换活跃账号
agent-whatsapp auth logout              # 解除当前账号关联
agent-whatsapp auth logout --account <id>  # 解除指定账号关联

Memory

内存管理

The agent maintains a 
~/.config/agent-messenger/MEMORY.md
file as persistent memory across sessions. This is agent-managed. The CLI does not read or write this file. Use the 
Read
and 
Write
tools to manage your memory file.
Agent会维护一个
~/.config/agent-messenger/MEMORY.md
文件，作为跨会话的持久化存储。该文件由Agent管理，CLI不会读写此文件，需使用
Read
和
Write
工具进行管理。

Reading Memory

读取内存

At the start of every task, read 
~/.config/agent-messenger/MEMORY.md
using the 
Read
tool to load any previously discovered chat IDs, contact names, and preferences.
  • If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
  • If the file can't be read (permissions, missing directory), proceed without memory.
在每个任务开始时，使用
Read
工具读取
~/.config/agent-messenger/MEMORY.md
，加载之前保存的聊天ID、联系人名称和用户偏好。
  • 若文件不存在，无需处理，后续有有用信息时再创建。
  • 若无法读取文件（权限问题、目录缺失），跳过内存直接执行操作。

Writing Memory

写入内存

After discovering useful information, update 
~/.config/agent-messenger/MEMORY.md
using the 
Write
tool. Write triggers include:
  • After discovering chat JIDs and contact names (from 
    chat list
    )
  • After discovering group names and participants
  • After the user gives you an alias or preference ("call this the family group", "my work chat is X")
When writing, include the complete file content. The 
Write
tool overwrites the entire file.
发现有用信息后，使用
Write
工具更新
~/.config/agent-messenger/MEMORY.md
，触发写入的场景包括：
  • 发现聊天JID和联系人名称后（来自
    chat list
    命令）
  • 发现群组名称和成员后
  • 用户设置别名或偏好后（如「将这个群组称为家庭群」、「我的工作群是X」）
写入时需包含完整文件内容，
Write
工具会覆盖整个文件。

What to Store

存储内容

  • Chat JIDs with contact/group names
  • Your own phone number and JID
  • User-given aliases ("family group", "work chat")
  • Commonly referenced chat JIDs
  • Any user preference expressed during interaction
  • 带联系人/群组名称的聊天JID
  • 自身的电话号码和JID
  • 用户设置的别名（如「家庭群」、「工作群」）
  • 常用的聊天JID
  • 交互过程中用户表达的偏好

What NOT to Store

禁止存储内容

Never store auth credentials, session keys, or any sensitive data. Never store full message content (just IDs and chat context).
绝不要存储验证凭证、会话密钥或任何敏感数据，不要存储完整消息内容（仅存储ID和聊天上下文）。

Handling Stale Data

处理过期数据

If a memorized JID returns an error, remove it from 
MEMORY.md
. Don't blindly trust memorized data. Prefer re-listing over using a memorized JID that might be stale.
若保存的JID返回错误，将其从
MEMORY.md
中删除。不要盲目信任保存的数据，优先重新获取列表而非使用可能过期的JID。

Format / Example

格式示例

markdown
undefined
markdown
undefined

Agent Messenger Memory

Agent Messenger Memory

WhatsApp Account

WhatsApp Account

  • Phone: +1234567890
  • JID: 1234567890@s.whatsapp.net
  • Phone: +1234567890
  • JID: 1234567890@s.whatsapp.net

Chats

Chats

  • 1234567890@s.whatsapp.net
    - Alice (1:1)
  • 5678901234@s.whatsapp.net
    - Bob (1:1)
  • 123456789-123345@g.us
    - Project Team (group, 8 members)
  • 987654321-654321@g.us
    - Family (group, 5 members)
  • 1234567890@s.whatsapp.net
    - Alice (1:1)
  • 5678901234@s.whatsapp.net
    - Bob (1:1)
  • 123456789-123345@g.us
    - Project Team (group, 8 members)
  • 987654321-654321@g.us
    - Family (group, 5 members)

Aliases

Aliases

  • "alice" -> 
    1234567890@s.whatsapp.net
  • "project" -> 
    123456789-123345@g.us
    (Project Team)
  • "family" -> 
    987654321-654321@g.us
    (Family group)
  • "alice" -> 
    1234567890@s.whatsapp.net
  • "project" -> 
    123456789-123345@g.us
    (Project Team)
  • "family" -> 
    987654321-654321@g.us
    (Family group)

Notes

Notes

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

> Memory lets you skip repeated `chat list` calls. When you already know a JID from a previous session, use it directly.
  • User prefers --pretty output
  • Project Team is the most frequently used chat

> 内存管理可避免重复调用`chat list`命令，若已从之前的会话中获取JID，可直接使用。

Commands

命令列表

Auth Commands

验证命令

bash
undefined
bash
undefined

Link as companion device via QR code (no phone number needed)

通过二维码关联辅助设备（无需电话号码）

agent-whatsapp auth login --qr
agent-whatsapp auth login --qr

Link as companion device via pairing code

通过配对码关联辅助设备

agent-whatsapp auth login --phone +1234567890
agent-whatsapp auth login --phone +1234567890

Check auth status

检查验证状态

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

List linked accounts

列出关联账号

agent-whatsapp auth list
agent-whatsapp auth list

Switch active account

切换活跃账号

agent-whatsapp auth use <id>
agent-whatsapp auth use <id>

Unlink account

解除账号关联

agent-whatsapp auth logout agent-whatsapp auth logout --account <id>
undefined
agent-whatsapp auth logout agent-whatsapp auth logout --account <id>
undefined

Whoami Command

Whoami命令

bash
undefined
bash
undefined

Show current authenticated user

显示当前已验证用户信息

agent-whatsapp whoami agent-whatsapp whoami --pretty agent-whatsapp whoami --account <account-id>

Output includes the authenticated user's identity information.
agent-whatsapp whoami agent-whatsapp whoami --pretty agent-whatsapp whoami --account <account-id>

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

Chat Commands

聊天命令

bash
undefined
bash
undefined

List chats (sorted by most recent activity)

列出聊天列表（按最近活动排序）

agent-whatsapp chat list agent-whatsapp chat list --limit 50 agent-whatsapp chat list --account <id>
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>

Output includes:
- `jid` - chat JID (individual or group)
- `name` - contact or group name
- `unread_count` - unread message count
- `last_message` - most recent message preview
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` - 最新消息预览

Message Commands

消息命令

bash
undefined
bash
undefined

List messages in a chat

列出指定聊天的消息

agent-whatsapp message list <chat> --limit 20 agent-whatsapp message list +1234567890 --limit 50 agent-whatsapp message list 123456789-123345@g.us --limit 10 agent-whatsapp message list +1234567890 --limit 20 --account <id>
agent-whatsapp message list <chat> --limit 20 agent-whatsapp message list +1234567890 --limit 50 agent-whatsapp message list 123456789-123345@g.us --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 123456789-123345@g.us "Hello team!" agent-whatsapp message send +1234567890 "Hello!" --account <id>
agent-whatsapp message send <chat> <text> agent-whatsapp message send +1234567890 "Hello!" agent-whatsapp message send 123456789-123345@g.us "Hello team!" agent-whatsapp message send +1234567890 "Hello!" --account <id>

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>

The `<chat>` argument accepts:
- Phone number: `+1234567890` (auto-resolved to JID)
- Individual JID: `1234567890@s.whatsapp.net`
- Group JID: `123456789-123345@g.us`

The `--from-me` flag on `message react` indicates the target message was sent by you (outgoing). Without it, the reaction targets an incoming 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：`1234567890@s.whatsapp.net`
- 群组JID：`123456789-123345@g.us`

`message react`命令中的`--from-me`标识目标消息是自己发送的（ outgoing），无此标识时，反应目标为 incoming消息。

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:
json
{
  "jid": "1234567890@s.whatsapp.net",
  "name": "Alice",
  "unread_count": 3,
  "last_message": {
    "id": "ABC123DEF456",
    "text": "See you tomorrow!",
    "from": "1234567890@s.whatsapp.net",
    "timestamp": 1705312200
  }
}
所有命令默认输出JSON格式，方便AI处理：
json
{
  "jid": "1234567890@s.whatsapp.net",
  "name": "Alice",
  "unread_count": 3,
  "last_message": {
    "id": "ABC123DEF456",
    "text": "See you tomorrow!",
    "from": "1234567890@s.whatsapp.net",
    "timestamp": 1705312200
  }
}

Pretty (Human-Readable)

格式化输出（人类可读）

Use 
--pretty
flag for formatted output:
bash
agent-whatsapp chat list --pretty
使用
--pretty
参数获取格式化输出：
bash
agent-whatsapp chat list --pretty

Global Options

全局选项

OptionDescription
--pretty
Human-readable output instead of JSON
--account <id>
Use a specific account for this command
选项描述
--pretty
输出人类可读格式而非JSON
--account <id>
为当前命令指定特定账号

Common Patterns

常见使用场景

Check unread messages

查看未读消息

bash
undefined
bash
undefined

List chats to see unread counts

列出聊天列表查看未读数量

agent-whatsapp chat list --limit 20
agent-whatsapp chat list --limit 20

Read messages from a specific chat

读取指定聊天的消息

agent-whatsapp message list +1234567890 --limit 10
undefined
agent-whatsapp message list +1234567890 --limit 10
undefined

Send a message to a contact

给联系人发送消息

bash
undefined
bash
undefined

By phone number (simplest)

通过电话号码（最简单方式）

agent-whatsapp message send +1234567890 "Hey, are we still on for tomorrow?"
agent-whatsapp message send +1234567890 "Hey, are we still on for tomorrow?"

By JID

通过JID

agent-whatsapp message send 1234567890@s.whatsapp.net "Hey, are we still on for tomorrow?"
undefined
agent-whatsapp message send 1234567890@s.whatsapp.net "Hey, are we still on for tomorrow?"
undefined

Send a message to a group

给群组发送消息

bash
undefined
bash
undefined

Find the group first

先找到群组

agent-whatsapp chat search "Project Team"
agent-whatsapp chat search "Project Team"

Send to the group JID

通过群组JID发送消息

agent-whatsapp message send 123456789-123345@g.us "Status update: deployment complete."
undefined
agent-whatsapp message send 123456789-123345@g.us "Status update: deployment complete."
undefined

React to the latest message

对最新消息添加反应

bash
undefined
bash
undefined

Get the latest message ID

获取最新消息ID

agent-whatsapp message list +1234567890 --limit 1
agent-whatsapp message list +1234567890 --limit 1

React to it

添加反应

agent-whatsapp message react +1234567890 <message-id> "👍"
undefined
agent-whatsapp message react +1234567890 <message-id> "👍"
undefined

Error Handling

错误处理

All commands return consistent error format:
json
{
  "error": "No WhatsApp account linked. Run: agent-whatsapp auth login --qr"
}
Common errors:
  • No WhatsApp account linked
    - not authenticated. Run 
    auth login --qr
    or 
    auth login --phone <number>
    .
  • Connection timeout
    - WebSocket connection to WhatsApp failed. Retry the command.
  • Invalid JID
    - malformed phone number or JID. Use international format with 
    +
    prefix.
  • Not a group participant
    - can't send to a group you're not a member of.
所有命令返回统一的错误格式：
json
{
  "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
    - 无法向非成员群组发送消息。

Notes

注意事项

  • JID format: Individual chats use 
    1234567890@s.whatsapp.net
    , groups use 
    123456789-123345@g.us
    . Phone numbers can be passed directly and are auto-resolved.
  • Connect-on-demand: Each command opens a WebSocket connection and closes it when done. There's no persistent daemon or background process.
  • Ban risk: WhatsApp monitors for automated behavior. Avoid high-volume messaging, rapid-fire sends, or bulk operations. Space out commands when sending multiple messages.
  • Multi-account: Multiple WhatsApp numbers can be linked simultaneously. Use 
    auth list
    to see all accounts and 
    auth use <id>
    to switch.
  • Phone numbers: Always use international format with country code (e.g. 
    +1234567890
    , 
    +821012345678
    ).
  • agent-whatsapp
    returns JSON by default and 
    --pretty
    for indented output.
  • JID格式：个人聊天使用
    1234567890@s.whatsapp.net
    ，群组使用
    123456789-123345@g.us
    ，可直接输入电话号码，CLI会自动解析。
  • 按需连接：每个命令执行时建立WebSocket连接，完成后立即断开，无持久守护进程或后台进程。
  • 封禁风险：WhatsApp会监控自动化行为，避免高频率发送消息、批量操作，发送多条消息时需间隔执行。
  • 多账号支持：可同时关联多个WhatsApp号码，使用
    auth list
    查看所有账号，
    auth use <id>
    切换账号。
  • 电话号码：始终使用带国家代码的国际格式（如
    +1234567890
    、
    +821012345678
    ）。
  • agent-whatsapp
    默认返回JSON格式，
    --pretty
    参数可获取缩进后的格式化输出。

Troubleshooting

故障排查

agent-whatsapp: command not found

agent-whatsapp: command not found

agent-whatsapp
is NOT the npm package name. The npm package is 
agent-messenger
.
If the package is installed globally, use 
agent-whatsapp
directly:
bash
agent-whatsapp chat list --pretty
If the package is NOT installed, use 
--package
to install and run:
bash
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
NEVER run 
npx agent-whatsapp
, 
bunx agent-whatsapp
, or 
pnpm dlx agent-whatsapp
 without 
--package agent-messenger
. It will fail or install a wrong package since 
agent-whatsapp
is not the npm package name.
agent-whatsapp
不是npm包名称，npm包名为
agent-messenger
。
若已全局安装包，可直接使用
agent-whatsapp
：
bash
agent-whatsapp chat list --pretty
若未安装包，使用
--package
参数安装并运行：
bash
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
绝不要运行
npx agent-whatsapp
、
bunx agent-whatsapp
或
pnpm dlx agent-whatsapp
，必须加上
--package agent-messenger
，否则会失败或安装错误的包，因为
agent-whatsapp
不是npm包名称。

QR code not scanning

二维码无法扫描

  1. Make sure WhatsApp is open on your phone
  2. Go to Settings > Linked Devices > Link a Device
  3. Point your phone camera at the QR code in the terminal or browser
  4. If the QR code expires, run 
    auth login --qr
    again for a fresh code
  5. If QR scanning fails, try pairing code: 
    auth login --phone <number>
  1. 确保手机端WhatsApp处于打开状态
  2. 进入设置 > 关联设备 > 关联新设备
  3. 用手机摄像头扫描终端或浏览器中的二维码
  4. 若二维码过期，重新运行
    auth login --qr
    获取新码
  5. 若二维码扫描失败，尝试配对码方式：
    auth login --phone <number>

Pairing code not working

配对码无法使用

  1. Make sure WhatsApp is open on your phone
  2. Go to Settings > Linked Devices > Link a Device
  3. Choose "Link with phone number instead" if you see a QR code
  4. Enter the pairing code shown in the terminal
  5. If the code expires, run 
    auth login --phone <number>
    again for a fresh code
  1. 确保手机端WhatsApp处于打开状态
  2. 进入设置 > 关联设备 > 关联新设备
  3. 若显示二维码，选择「改用电话号码关联」
  4. 输入终端显示的配对码
  5. 若代码过期，重新运行
    auth login --phone <number>
    获取新码

Empty chat list after linking a new device

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

WhatsApp companion devices receive their chat list from the primary phone — there's no server API to fetch it directly. On a freshly linked device, 
chat list
may return only group chats (or nothing at all) for individual/DM conversations.
  • Keep your phone online with WhatsApp open during and after linking. The phone pushes history to the new device; if it's off or WhatsApp is killed, nothing arrives.
  • Wait a few minutes and run 
    chat list
    again. History trickles in over time and is saved locally, so subsequent runs will show more chats.
  • Groups always work immediately — they're fetched from the server, not from history sync.
  • Sending a message to a known phone number will make that chat appear even if it wasn't in the initial sync.
This is a WhatsApp protocol limitation, not a bug.
WhatsApp辅助设备的聊天列表由主手机推送，没有直接获取聊天列表的服务器API。刚关联的设备，
chat list
可能仅返回群组聊天（或无个人对话）。
  • 保持手机在线，关联期间及之后保持WhatsApp打开，手机会向新设备推送历史记录；若手机关机或WhatsApp被关闭，则无法推送。
  • 等待几分钟后重新运行
    chat list
    ，历史记录会逐步同步并本地保存，后续运行会显示更多聊天。
  • 群组可立即使用，群组信息从服务器获取，无需历史同步。
  • 向已知电话号码发送消息，即使初始同步中没有该聊天，发送后也会显示。
这是WhatsApp协议限制，并非bug。

Connection drops

连接断开

WhatsApp may disconnect linked devices that are inactive for extended periods. If commands start failing:
bash
undefined
若辅助设备长时间未活跃，WhatsApp可能会断开连接。若命令开始失败：
bash
undefined

Check if still linked

检查是否仍处于关联状态

agent-whatsapp auth status
agent-whatsapp auth status

Re-link if needed

必要时重新关联

agent-whatsapp auth login --qr
undefined
agent-whatsapp auth login --qr
undefined