WhatsApp 诊断技能

最低模型要求

任意模型均可。所有诊断均基于命令行——请遵循决策树。

---

诊断树（从这里开始）

PA 无响应？
│
├─ 仪表盘显示已连接并监听中？
│ ├─ 是 → 检查消息数量
│ │ ├─ 消息数 = 0 → 数据摄取问题 → 转至案例 2
│ │ └─ 消息数 > 0 → 运行时问题 → 转至案例 3
│ └─ 否 → 连接问题 → 转至案例 1
│
└─ 平台中存在 Agent？
├─ 是 → 遵循案例 1
└─ 否 → 需要完整设置（参见 pa-onboarding 技能）

---

案例 1 — 连接问题（WhatsApp 未关联）

症状： 仪表盘显示未连接或未配置频道。

修复方法：

1. 1. 在 OpenClaw 平台中打开 Agent 设置
2. 进入频道 → WhatsApp → 点击连接或重新关联
3. 使用 WhatsApp Business 应用扫描二维码
4. 确认手机号码匹配
5. 等待 30 秒让状态更新

最常见原因： WhatsApp 会话过期（约 14 天不活动或手机重启后发生）。

---

案例 2 — 数据摄取问题（已连接但消息数 = 0）

症状： 仪表盘显示已连接并监听中，但消息计数始终为 0。

含义： WhatsApp 在协议层面已连接，但消息未到达 Agent 运行时。

修复方法：

bash

步骤 1：检查网关状态

openclaw gateway status

步骤 2：重启网关

openclaw gateway restart

步骤 3：发送一条测试消息，等待 30 秒

步骤 4：如果计数仍为 0，检查网关日志

openclaw gateway logs --last 50

日志中需关注的内容：

• - binding failed（绑定失败）
• session dropped（会话断开）
• ingest error（摄取错误）

如果出现以上任何内容 → 升级至平台管理员。这是基础设施问题。

---

案例 3 — 运行时问题（消息已到达，无回复）

症状： 消息计数增加，但 Agent 不响应。

含义： 消息已到达 Agent，但 Agent 运行时出现故障。

修复方法：

bash

步骤 1：检查 Agent 日志中的计费错误

grep -i billing\|402\|credits ~/.openclaw/logs/agent.log | tail -20

如果发现计费错误 → 参见 billing-monitor 技能

步骤 2：检查 Agent 状态

openclaw status

步骤 3：验证 API 密钥（根据下方选择您的提供商）

针对 Anthropic：

curl -s -o /dev/null -w %{http_code} \ -H x-api-key: $ANTHROPICAPIKEY \ -H anthropic-version: 2023-06-01 \ https://api.anthropic.com/v1/models

针对 OpenAI：

curl -s -o /dev/null -w %{http_code} \ -H Authorization: Bearer $OPENAIAPIKEY \ https://api.openai.com/v1/models

针对 Google：

curl -s -o /dev/null -w %{http_code} \ https://generativelanguage.googleapis.com/v1beta/models?key=$GOOGLEAPIKEY

预期结果：200。如果为 401 → 密钥无效。如果为 402 → 计费错误。

步骤 4：检查最近的运行时错误

openclaw logs --last 100 | grep -i error

结果解读：

• - 200 → API 密钥有效。问题出在其他地方（检查步骤 4）。
• 401 → API 密钥无效。在 Agent 设置中更新密钥。
• 402 → 计费错误。遵循 billing-monitor 技能。

---

快速健康检查脚本

bash
#!/bin/bash

whatsapp-health-check.sh

当 Agent 无响应时运行此脚本，快速获取状态概览。

echo === WhatsApp 诊断 ===

检查网关状态

echo -n 网关： openclaw gateway status 2>&1 | grep -o running\|stopped\|error | head -1 || echo 未知

检查 API 密钥 — 从环境变量检测提供商

echo -n API 密钥：

if [ -n ${ANTHROPICAPIKEY:-} ]; then
PROVIDER=Anthropic
# 向 models 端点发送最小请求进行测试
STATUS=$(curl -s -o /dev/null -w %{http_code} \
-H x-api-key: ${ANTHROPICAPIKEY} \
-H anthropic-version: 2023-06-01 \
https://api.anthropic.com/v1/models 2>/dev/null)

elif [ -n ${OPENAIAPIKEY:-} ]; then
PROVIDER=OpenAI
STATUS=$(curl -s -o /dev/null -w %{http_code} \
-H Authorization: Bearer ${OPENAIAPIKEY} \
https://api.openai.com/v1/models 2>/dev/null)

elif [ -n ${GOOGLEAPIKEY:-} ]; then
PROVIDER=Google
STATUS=$(curl -s -o /dev/null -w %{http_code} \
https://generativelanguage.googleapis.com/v1beta/models?key=${GOOGLEAPIKEY} 2>/dev/null)

else
echo ⚠️ 未找到 API 密钥环境变量
PROVIDER=
STATUS=
fi

解读 HTTP 状态码

if [ -n $STATUS ]; then case $STATUS in 200) echo ✅ 有效（$PROVIDER） ;; 401) echo ❌ 密钥无效（$PROVIDER） ;; 402) echo ⚠️ 计费错误（$PROVIDER）— 参见 billing-monitor 技能 ;; *) echo ? HTTP $STATUS（$PROVIDER） ;; esac fi

统计 Agent 日志中的近期错误数

echo -n 近期错误数： ERROR_COUNT=$(openclaw logs --last 100 2>/dev/null | grep -ic error || echo 0) echo 发现 $ERROR_COUNT 个

echo === 完成 ===

---

何时升级至平台管理员

以下情况请升级：

• - 重启网关无法解决消息数 = 0 的问题
• 日志显示 socket、binding 或 session 错误
• 同一服务器上的多个 Agent 同时受到影响

升级消息中需包含：

• - Agent 名称和手机号码
• 问题开始时间
• openclaw gateway status 的输出
• 仪表盘中显示的消息计数

---

预防措施

操作	原因
每 7 天至少发送一条消息	防止 WhatsApp 会话过期
心跳检测时检查消息计数

及早发现数据摄取问题 |
| 保留手机号码记录 | 二维码重新关联时需要 |
| 不要在两台设备上使用同一号码 | WhatsApp 只允许一个活跃会话 |

---

成本提示

• - 非常便宜： 所有诊断均使用 CLI + curl — 无需 LLM 令牌
• 小模型可用： 任何模型都能遵循此决策树并解读 curl 输出
• 避免： 不要在每次心跳检测时运行诊断 — 仅在 Agent 无响应时运行
• 批量处理： 一次性运行快速健康检查脚本获取所有信息，而非分别运行每个检查