OpenClaw集成WhatsApp：智能客服自动化实战指南

1. 项目概述：用OpenClaw技能包打通WhatsApp客户渠道

如果你正在用OpenClaw构建AI助手，并且希望它能直接与客户在WhatsApp上对话——无论是自动回复、线索跟进还是发送交易通知——那么InitechSoftware开源的这套openclaw-whatsapp-skills技能包，就是你一直在找的“瑞士军刀”。这个项目不是一个简单的API封装，而是一套经过实战打磨、可以直接“即插即用”的生产级技能集合，它通过TimelinesAI的公共API，将OpenClaw智能体的能力无缝延伸到了全球最流行的即时通讯平台。

简单来说，它解决了几个核心痛点：如何让AI自动处理涌入的客户消息而不出错？如何设计一个能记住对话状态、进行多轮交互的资格筛选流程？如何安全、可靠地向外发送交易类通知并追踪送达状态？以及，如何让整个团队在一个共享收件箱里协同工作？这套技能包提供了开箱即用的答案。它特别适合独立开发者、小团队或任何希望以自动化方式高效管理WhatsApp客户沟通的场景，无论是电商客服、预约提醒，还是销售线索初步筛选。接下来，我将带你深入这套工具的内部，拆解每一个技能的设计思路、实现细节，并分享我在集成和测试过程中积累的一手经验与避坑指南。

2. 核心技能深度解析与设计哲学

这套技能包包含了四个核心技能，每个都针对一个特定的、高价值的自动化场景。理解每个技能“为什么”这样设计，比单纯知道“怎么用”更重要。

2.1whatsapp-autoresponder：智能自动回复的守门员

这个技能的角色是“第一响应者”。它的核心任务不是进行复杂的对话，而是确保每一次自动回复都是安全、合规且必要的。

核心逻辑拆解：

1. 所有权验证：当Webhook收到一条新消息时，技能首先会验证这条消息所属的聊天（Chat）是否归你的工作区所有。这是通过比对消息中的发送者JID（Jabber ID，即电话号码@格式）与你在环境变量ALLOWED_SENDER_JID中配置的列表来实现的。这一步至关重要，防止你的机器人错误地响应到其他无关的聊天中。
2. 停止回复标签检查：在发送任何回复之前，技能会检查该聊天是否已被标记为“停止回复”的标签（例如stop-replies）。如果已标记，则流程立即终止。这为用户提供了一种明确的退出机制，是尊重用户意愿和遵守通信规范的关键设计。
3. 触发回复：只有通过上述两层检查，技能才会调用OpenClaw的主智能体来处理这条消息，并将智能体的回复通过TimelinesAI API发送出去。

实操心得：不要把这个技能想象成一个简单的“回声”机器人。它的价值在于构建了一个安全的自动化边界。在实际部署中，我建议在OpenClaw智能体的提示词（Prompt）中明确其“第一响应者”的角色，例如：“你是一名客服助手，请用简短、友好的语言确认收到用户消息，并告知预计回复时间或引导用户描述具体问题。” 这样，自动回复既能体现专业性，又不会过度承诺。

2.2whatsapp-lead-qualifier：基于状态持久化的多轮资格筛选

这是一个展示“无状态智能体如何管理有状态对话”的经典案例。传统的聊天机器人如果进程重启，对话状态就会丢失。而这个技能采用了一种巧妙的“状态外置”设计。

状态持久化模式解析：技能利用TimelinesAI聊天对象的两个原生特性来保存状态：

• 标签（Labels）作为阶段标识：聊天的标签用来记录当前进行到了资格筛选的哪个阶段，例如lead-qual:contacted,lead-qual:question1,lead-qual:qualified。标签是公开的，便于团队在共享收件箱中一眼看清进度。
• 笔记（Notes）作为数据存储：用户对每个筛选问题的回答，以结构化的JSON格式保存在聊天的“笔记”中。笔记内容可以通过API获取，但对聊天界面是隐藏的，适合存储详细数据。

工作流程：

1. 用户进入流程（如发送了“我想咨询”）。
2. 技能检查聊天标签。如果是新聊天，则打上lead-qual:started标签，并提问第一个问题（如“请问您的公司名称是？”）。
3. 用户回复后，技能将答案存入笔记，更新标签为lead-qual:question2，并提出下一个问题。
4. 如此循环，直至所有问题完成。最终，根据答案规则，给聊天打上qualified（合格）或disqualified（不合格）的标签，并可能附加lead-qual:complete。
5. 无论技能进程是否重启，下次触发时，它只需读取最新的标签，就能知道对话进行到哪一步，并从笔记中读取历史答案，实现对话的无缝续接。

避坑指南：在设计问题流程时，务必考虑用户的“中途退出”。技能本身没有内置的退出命令处理。一个实用的技巧是，在你的OpenClaw智能体逻辑中，监听“退出”、“取消”等关键词。当检测到这些词时，智能体可以主动调用TimelinesAI API，为当前聊天添加一个如qualification-cancelled的标签。然后，你需要修改whatsapp-lead-qualifier技能的判断逻辑，使其在发现此标签时，清理流程标签并结束筛选，同时发送一条友好的结束语。这能大幅提升用户体验。

2.3whatsapp-send：安全可靠的异步消息发送器

发送消息听起来简单，但这个技能解决了一些在自动化脚本中极易踩坑的细节问题，尤其是处理复杂文本和异步操作。

核心设计亮点：

• 文件先行，规避编码陷阱：技能不会直接将消息内容通过命令行参数或管道传递。而是先将完整的消息载荷（包括收件人、消息类型、文本内容等）写入一个临时的JSON文件，然后再读取该文件并提交给API。这样做绝对避免了在Shell环境、进程间传递时可能发生的UTF-8特殊字符（如表情符号、多国语言）被错误编码或截断的问题。这是来自生产环境的宝贵经验。
• 明确的事务性定位：该技能设计初衷是发送“事务性”或“事件触发”通知，如订单确认、物流更新、预约提醒。这直接关联到项目的合规性警告（下文会详述）。技能返回的message_uid是追踪这条消息生命周期的唯一钥匙。
• 支持两种发送模式：既可以通过电话号码直接发送给新联系人，也可以向一个已存在的聊天（Chat）发送消息。后者更常用，因为它能延续之前的对话上下文。

一个典型的发送Payload文件内容示例：

{ "to_jid": "1234567890@s.whatsapp.net", "type": "text", "text": { "body": "您的订单 #ORD-12345 已发货，物流单号：SF1234567890。点击查看详情：https://example.com/track/ORD-12345" }, "preview_url": true }

2.4whatsapp-delivery-check：消息送达状态追踪器

在异步通信中，“发送了”不等于“收到了”，更不等于“已读”。这个技能提供了消息送达的“可观测性”。

实现原理：它通过轮询TimelinesAI的GET /messages/{uid}/status_history端点，获取指定message_uid的状态历史。状态通常包括：

• sent：消息已成功提交到WhatsApp服务器。
• delivered：消息已送达用户设备。
• read：用户已打开并查看了消息（需用户设备开启已读回执）。

集成场景示例：假设你发送了一条重要的支付失败提醒（whatsapp-send）。你可以启动一个后台任务，定期（例如每5分钟一次）调用whatsapp-delivery-check来检查该消息的状态。如果消息在30分钟内仍未显示delivered，你的系统可以触发备用通知渠道（如短信或邮件），确保关键信息不丢失。

3. 环境搭建与集成部署实操全流程

理解了核心技能后，我们来一步步完成从零到一的部署。我将以本地开发环境为例，并穿插讲解每个步骤的意图和注意事项。

3.1 前期准备与依赖确认

在开始克隆代码之前，请确保你的基础环境就绪：

1. OpenClaw环境：你已经安装并配置好OpenClaw，并且了解其工作空间（workspace）和技能（skills）目录的基本结构。通常，技能目录位于~/.openclaw/skills/。
2. TimelinesAI账户与API密钥：你拥有一个TimelinesAI账户，并且已经成功连接了至少一个WhatsApp号码（个人号或商业API号）。然后，你需要生成一个Public API的Bearer Token。
   • 操作路径：登录TimelinesAI Dashboard -> 进入“Integrations” -> 找到“Public API”部分 -> 创建或复制你的API密钥。请妥善保管此密钥。

3.2 技能包安装与配置

遵循项目README的步骤，但我会补充更多细节：

# 1. 进入你的OpenClaw工作空间目录 cd ~/.openclaw/workspace # 2. 克隆技能库仓库 git clone https://github.com/InitechSoftware/openclaw-whatsapp-skills.git # 执行后，你会得到一个 `openclaw-whatsapp-skills` 文件夹 # 3. 配置环境变量 cd openclaw-whatsapp-skills cp .env.example .env.timelinesai # 使用你喜欢的编辑器编辑 .env.timelinesai 文件

编辑.env.timelinesai文件，这是核心配置步骤：

# 将你的TimelinesAI Public API Token填入此处 TIMELINES_AI_API_KEY=your_bearer_token_here # 如果你在TimelinesAI中只连接了一个WhatsApp号码，此项可以暂时留空或注释掉。 # 如果你连接了多个号码，你必须指定允许使用哪个号码来发送消息。 # 格式为：国家代码+手机号码@s.whatsapp.net # ALLOWED_SENDER_JID=+8613012345678@s.whatsapp.net

关键配置解析：

• TIMELINES_AI_API_KEY：这是所有技能与TimelinesAI服务通信的凭证。没有它，一切功能都会失效。
• ALLOWED_SENDER_JID：这是一个重要的安全隔离配置。假设你的工作区连接了公司的官方客服号和你的个人测试号。通过设置这个变量，你可以确保whatsapp-send等技能只使用官方客服号对外发送消息，避免误用。如果你只有一个号码，理论上可以不设，但显式设置是一个好习惯。

3.3 技能链接与烟雾测试

# 4. 将技能目录软链接到OpenClaw的技能路径 # 这样做的好处是，技能源码保留在workspace里便于git管理，而OpenClaw又能识别到它们。 ln -s $(pwd)/skills/whatsapp-autoresponder ~/.openclaw/skills/ ln -s $(pwd)/skills/whatsapp-lead-qualifier ~/.openclaw/skills/ ln -s $(pwd)/skills/whatsapp-send ~/.openclaw/skills/ ln -s $(pwd)/skills/whatsapp-delivery-check ~/.openclaw/skills/ # 5. 烟雾测试：验证API密钥和连接是否正常 # 将下面的命令中的 `$TIMELINES_AI_API_KEY` 替换为你的实际密钥，或确保该环境变量已导出。 curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \ https://app.timelines.ai/integrations/api/whatsapp_accounts

如果一切正常，这个API调用会返回一个JSON响应，其中包含你的账户下连接的WhatsApp账号列表。如果返回401错误，说明API密钥错误；如果连接超时或有其他错误，请检查网络。

3.4 Webhook接收器部署（关键步骤）

whatsapp-autoresponder和whatsapp-lead-qualifier这两个技能需要响应来自TimelinesAI的Webhook事件（即用户发送了新消息）。因此，你需要一个公开的、在互联网上可访问的端点来接收这些事件，并将其转发给你的本地或服务器上的OpenClaw。

项目提供了一个极简的Vercel Serverless Function示例，这是目前最快捷的部署方式之一。

部署步骤精讲：

1. 进入示例目录：cd examples/vercel-webhook-receiver
2. 安装Vercel CLI并登录：如果你尚未安装，请先执行npm i -g vercel，然后运行vercel login进行认证。
3. 部署：在目录内执行vercel --prod。Vercel会引导你配置项目（通常一路回车用默认值即可），最后会给你一个永久的部署URL，格式类似https://your-project.vercel.app/api/webhook。
4. 在TimelinesAI中配置Webhook：
   • 进入TimelinesAI Dashboard -> Integrations -> Webhooks。
   • 创建新的Webhook，URL就填写你上一步获得的Vercel地址（例如https://your-project.vercel.app/api/webhook）。
   • 选择需要订阅的事件类型，至少需要勾选message.received（收到新消息）。
   • 保存后，TimelinesAI会向该URL发送一个验证请求，Vercel函数会自动处理并验证成功。

Webhook数据流解析：

1. 用户向你的WhatsApp号码发送消息。
2. TimelinesAI服务器收到消息，并立即向你配置的Webhook URL发送一个HTTP POST请求，请求体包含了完整的消息事件数据。
3. 部署在Vercel上的函数接收到请求，它做两件事：a) 验证请求来源（可选但推荐）；b) 将事件数据打包，通过HTTP调用你本地OpenClaw实例上运行的whatsapp-autoresponder技能的特定端点。
4. whatsapp-autoresponder技能被触发，执行其逻辑（验证、检查标签、调用智能体、回复）。

重要提示：上述第3步中，Vercel函数需要能访问到你本地的OpenClaw。这在开发时意味着你需要使用内网穿透工具（如ngrok、localtunnel）将本地的OpenClaw服务暴露一个公共URL，并将这个URL配置到Vercel函数的代码中。对于生产环境，你的OpenClaw应该部署在一台有公网IP的云服务器上。这是整个集成中最需要网络知识的一环。

4. 合规性红线与最佳实践

这是使用任何WhatsApp自动化工具前必须彻底理解的部分，直接关系到你的号码能否存活。项目文档中的警告绝非危言耸听。

4.1 个人号码 vs. WhatsApp Business API

• 个人WhatsApp号码：通过TimelinesAI等工具连接的个人号，其使用受到WhatsApp严格政策的限制。其核心原则是对话必须由用户发起或处于有效的“24小时服务窗口”内。
• WhatsApp Business API (WABA)：这是Meta官方为企业提供的商业解决方案。它允许在用户明确同意（Opt-in）的前提下，发送营销模板消息，但需要经过商业验证、按消息条数付费，且流程更复杂。

当前技能包的定位：openclaw-whatsapp-skills主要面向与个人号码或已具备对话上下文的WABA场景，强调事务性和对话延续。

4.2 安全用例与危险禁区

下表清晰地划分了行为边界：

4.3 实操中的合规策略

1. 明确技能职责：将whatsapp-send技能的使用权限严格控制在内部分析系统或需要发送事务性通知的特定流程中（如订单系统、CRM工作流）。避免将其暴露给可能被滥用的通用接口。
2. 实施发送前审核：在生产环境中，可以考虑为whatsapp-send技能增加一个“审核层”。例如，将要发送的消息内容和对象先写入一个待审核队列，由人工或另一套规则系统确认符合合规要求后，再实际调用发送技能。
3. 利用标签系统进行管理：为聊天打上notification-ok或marketing-opt-out等标签。在发送任何非即时回复消息前，先检查这些标签。
4. 监控发送频率：即使是事务性消息，短时间内向大量用户发送也可能触发风控。建议实现简单的速率限制。

5. 高级技巧与模式扩展

掌握了基础技能和合规要求后，我们可以探索如何将这些技能组合起来，构建更强大的自动化工作流。

5.1 构建一个完整的客户服务流水线

想象一个电商场景：

1. 入口：whatsapp-autoresponder接待首次咨询的客户，自动回复欢迎语并收集基本信息（可结合智能体能力）。
2. 筛选：对于有购买意向的咨询，自动或人工触发whatsapp-lead-qualifier，进行产品偏好、预算等多轮筛选，并将结果（存储在Notes中）打上qualified标签。
3. 转化与通知：当后台CRM（如HubSpot）中该线索转化为订单时，通过Zapier/Make或自定义脚本，触发whatsapp-send发送订单确认消息。
4. 履约追踪：订单发货后，系统调用whatsapp-send发送物流信息。同时，可以定时调用whatsapp-delivery-check确认客户是否已读，对于未读的关键通知（如取件码），可以触发二次提醒。
5. 服务升级：如果客户在物流消息后回复了问题，whatsapp-autoresponder再次介入，并可根据聊天历史（来自Notes）提供更精准的回复。

5.2 实现“发送后追踪”自动化

你可以创建一个简单的守护进程或定时任务（如使用cron或 Celery Beat），专门处理“已发送但未读”的重要消息。

# 伪代码逻辑示例 #!/bin/bash # 1. 从数据库或任务队列中获取所有需要追踪的 message_uid TRACKING_UIDS=$(get_pending_message_uids) for uid in $TRACKING_UIDS; do # 2. 调用 whatsapp-delivery-check 技能检查状态 STATUS=$(openclaw run whatsapp-delivery-check --uid $uid --format json | jq .delivery_status) # 3. 判断状态并采取行动 if [ "$STATUS" == "\"read\"" ]; then mark_as_read_in_db $uid elif [ "$STATUS" == "\"delivered\"" ]; then # 已送达但未读，可能需要温和提醒 if [ $(hours_since_sent $uid) -gt 24 ]; then send_follow_up_reminder $uid fi elif [ "$STATUS" == "\"sent\"" ]; then # 已发送但未送达，可能号码有问题，记录日志 log_potential_issue $uid fi done

5.3 多号码发送的身份钉扎（Sender Pinning）

当你的工作区有多个WhatsApp号码时（例如客服A号、客服B号、官方号），你可能希望不同的技能或不同的场景使用不同的号码发送。这可以通过环境变量和技能调用前动态设置来实现。

项目文档docs/multi-number.md提到了这个概念。其核心是：在调用TimelinesAI发送API时，在请求头或参数中指定sender_jid。你需要修改whatsapp-send技能，使其能够接收一个可选的--sender参数，并将该参数传递给API。然后，在你的工作流中，根据业务规则决定使用哪个发送者JID。

6. 故障排查与常见问题实录

在实际集成和测试中，你可能会遇到以下问题。这里记录了我的排查思路和解决方法。

6.1 Webhook 相关问题

问题：消息已发出，但机器人没有回复。

• 排查步骤：
  1. 检查Vercel函数日志：在Vercel Dashboard的Function Logs中查看是否有请求进入，是否有错误信息。这是第一步，也是最直接的证据。
  2. 检查TimelinesAI Webhook配置：确认Webhook URL正确，状态是“已验证”，并且订阅了正确的事件（message.received）。
  3. 检查内网穿透：如果你在本地开发，确保ngrok等工具运行正常，且URL没有变化。Vercel函数中配置的本地OpenClaw地址必须准确无误。
  4. 检查OpenClaw技能日志：在OpenClaw的运行终端或日志文件中，查看whatsapp-autoresponder技能是否被调用，是否有报错（如API密钥无效、网络错误）。

问题：Webhook验证失败。

• 原因：TimelinesAI在创建Webhook时会发送一个带有challenge参数的GET请求，你的接收端点必须原样返回这个challenge值。
• 解决：确保你的Webhook接收器（如Vercel函数）正确处理了GET请求并返回了挑战码。项目提供的示例函数已经包含了这部分逻辑。

6.2 API 调用相关问题

问题：调用whatsapp-send返回权限错误或“未找到号码”。

• 排查：
  1. 检查TIMELINES_AI_API_KEY：确保环境变量已正确加载，并且该密钥具有发送消息的权限。
  2. 检查ALLOWED_SENDER_JID：确认你填写的JID格式完全正确（例如+8613012345678@s.whatsapp.net），并且这个号码确实存在于你的TimelinesAI账户且连接状态正常。
  3. 检查号码所有权：确保你要发送消息的目标号码的JID格式也正确。对于个人聊天，通常是国家代码+手机号码@s.whatsapp.net。

问题：消息内容中的特殊字符（如中文、Emoji）显示为乱码。

• 原因：这通常是因为消息内容在传递过程中没有以UTF-8编码正确处理。Shell脚本、环境变量、管道传输都可能成为“编码杀手”。
• 解决：这正是whatsapp-send技能采用“先写JSON文件再发送”模式的原因。请确保你生成Payload JSON文件时，文本编辑器或脚本使用的是UTF-8编码。在Bash中，可以使用printf或jq工具来生成JSON，它们能更好地处理编码。

# 使用 jq 安全地创建发送Payload文件 jq -n \ --arg to "1234567890@s.whatsapp.net" \ --arg body "您的订单已发货！🚚" \ '{to_jid: $to, type: "text", text: {body: $body}}' \ > /tmp/payload.json

6.3 OpenClaw 技能执行问题

问题：技能链接后，在OpenClaw中看不到或无法运行。

• 排查：
  1. 确认软链接：运行ls -la ~/.openclaw/skills/，确认whatsapp-*的软链接存在且指向正确的源码目录。
  2. 检查技能清单：在OpenClaw CLI中运行openclaw skills list，查看技能是否出现在列表中。
  3. 检查技能配置：每个技能目录下都应有一个skill.toml配置文件。确保其格式正确，特别是name和entrypoint字段。

问题：whatsapp-lead-qualifier流程状态丢失或混乱。

• 排查：
  1. 检查标签命名冲突：确保你没有其他流程或手动操作使用了相同的标签前缀（lead-qual:）。建议为不同的流程使用独特的前缀。
  2. 检查Notes数据格式：技能依赖Notes中存储的特定JSON结构。如果其他操作误修改了Note，可能导致流程无法解析。可以在TimelinesAI的聊天界面或通过API查看特定聊天的Notes内容，验证其完整性。
  3. 并发问题：如果同一个聊天在极短时间内被多次触发（如用户快速发送多条消息），可能会导致技能实例竞争读写标签和Notes。虽然概率低，但在高并发场景下需要考虑。一个简单的缓解办法是在技能入口处增加一个基于聊天ID的简易锁机制，或者确保你的Webhook处理是串行的。

这套openclaw-whatsapp-skills技能包的精妙之处在于，它没有尝试去再造一个复杂的机器人框架，而是巧妙地利用OpenClaw的“技能”原子性和TimelinesAI提供的稳固API基础，组合出了一套解决实际业务问题的标准化方案。它的设计模式——状态外置、安全优先、文件化操作——都体现了生产环境下的务实思考。在集成过程中，最耗费时间的往往不是代码本身，而是对网络环境、合规边界的理解。我的建议是，先从whatsapp-send和whatsapp-delivery-check这两个相对独立的技能开始试验，成功发送并追踪一条消息，这会给你带来巨大的信心。然后再去攻克需要Webhook的自动回复和资格筛选，一步步构建起完整的自动化流程。记住，在WhatsApp生态里，谨慎和尊重规则是长期运行的前提，而这套工具为你划清了安全区的边界。