WhatsApp

工作原理

/add-whatsapp 技能通过多设备 API 将 NanoClaw 连接到 WhatsApp。这意味着连接独立于你的手机运行——即使手机离线，NanoClaw 仍然可以接收和回复消息。

技能首先进行预检。它会检测你是在无界面的服务器上还是有浏览器的桌面环境中运行，因为这会影响可用的认证方式。然后验证所需的代码和依赖项是否就绪，自动安装缺少的部分。

认证支持三种方式。如果有可用的浏览器，技能会打开一个带二维码的页面——你用手机上的 WhatsApp 扫描即可，就像关联 WhatsApp Web 一样。如果在无界面的服务器上，二维码会直接以 ASCII 字符渲染在终端中。第三种方式是配对码：你输入手机号码，然后会获得一个数字码，在 WhatsApp 的”关联设备”界面中输入即可。三种方式的最终结果都是创建一个持久化会话。

认证完成后，技能会将会话凭证保存到本地。后续重启时，NanoClaw 会自动重新连接，无需再次扫描或配对。凭证存储在 store/auth/ 目录中，跨重启持久保存。

注册聊天

认证完成后，你需要注册 NanoClaw 应该在哪些聊天中活跃。技能支持三种类型：

• 自聊天——给自己发消息来触发智能体。这是个人使用中常见的设置。
• 私信——注册某个特定联系人的私信。
• 群聊——通过 JID（群组 ID）注册一个 WhatsApp 群组。

你可以为多个聊天注册不同的触发配置。例如，你的自聊天可以作为主频道，而家庭群组设置为仅触发模式。

重连与稳定性

WhatsApp 连接偶尔会断开，尤其是在手机系统更新或长时间不活跃之后。NanoClaw 会通过指数退避策略自动处理重连。如果会话永久失效（例如你在手机上取消了设备关联），日志会显示明确的认证错误，你可以重新运行该技能来重新认证。

驱动此连接的 Baileys 库使用与 WhatsApp Web 相同的协议。它支持文本消息、图片、文档、语音留言（配合语音转录技能使用）以及带上下文的回复。

使用建议

• 如果你看到”conflict”断连错误，说明另一个 WhatsApp Web 会话抢占了连接。每个手机号码同时只能维持一个活跃的 Web 会话。
• 二维码约 60 秒后过期。如果过期，技能会自动生成新的二维码。
• 在服务器上最可靠的设置方式是使用配对码方式——它不需要渲染二维码，通过 SSH 也能正常工作。
• WhatsApp 的速率限制比 Telegram 或 Discord 更为严格。NanoClaw 会自动遵守这些限制，但较长的智能体回复可能会被拆分成多条消息发送。