Whatsapp Diagnostics

Diagnose and fix WhatsApp connectivity issues for OpenClaw agents. Use when: a PA is not responding, WhatsApp shows connected but messages don't arrive, the...

Security Scan

The skill is a mostly-coherent CLI-based WhatsApp troubleshooting guide, but it reads local agent logs and probes multiple LLM provider API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY) without declaring those requirements — this mismatch and file access should be reviewed before use.

Purpose & Capability

The instructions match a WhatsApp diagnostics purpose (check gateway, restart, inspect logs, re-link QR). However the decision tree and health checks also validate external LLM provider API keys; while that can be relevant to diagnosing agent runtime failures, the skill metadata declares no required env vars or config paths — a mismatch between claimed requirements and actual checks.

Instruction Scope

SKILL.md instructs the agent to run OpenClaw CLI commands (openclaw gateway status/restart/logs, openclaw status, openclaw logs), grep a local log file (~/.openclaw/logs/agent.log), and run curl requests to external model provider endpoints. These actions are within troubleshooting scope but do access local logs and environment variables not declared in the registry metadata.

Install Mechanism

Instruction-only skill with no install spec or downloaded code. Nothing is written to disk by the skill itself — lowest install risk.

Credentials

The health-check script and Case 3 explicitly read ANTHROPIC_API_KEY, OPENAI_API_KEY, and GOOGLE_API_KEY and use them in network probes. The registry lists no required env vars or primary credential. The skill also reads a user-local log path (~/.openclaw/logs/agent.log). Requiring multiple provider keys and reading agent logs without declaring them is disproportionate to the metadata and should be justified or corrected.

Persistence & Privilege

The skill does not request always:true or persistent platform-wide privileges. It is user-invocable and allows model invocation (defaults), which is normal for skills.

What to consider before installing

This skill appears to be a legitimate CLI-based troubleshooting checklist, but it probes LLM provider API endpoints and reads local OpenClaw logs while declaring no required env vars or config paths. Before installing or running it: (1) confirm with the skill author why it needs to access OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY and whether those will be read automatically; (2) verify you are comfortable the skill will read ~/.openclaw/logs/agent.log and run openclaw CLI commands; (3) run the health-check script manually in a controlled environment (or inspect it) rather than granting automated/autonomous invocation until you’re satisfied; and (4) ensure API keys are stored securely and rotate them if you suspect they may be exposed. If the metadata is updated to declare the env vars and config path, and/or the skill is limited to explicit user-invoked runs, the concerns would be reduced.

WhatsApp Diagnostics Skill

Minimum Model

Any model. All diagnostics are CLI-based — follow the decision tree.

---

Diagnostic Tree (Start Here)

PA not responding?
│
├─ Dashboard shows "Connected and listening"?
│   ├─ YES → Check Messages count
│   │   ├─ Messages = 0 → INGEST ISSUE → go to Case 2
│   │   └─ Messages > 0 → RUNTIME ISSUE → go to Case 3
│   └─ NO → CONNECTION ISSUE → go to Case 1
│
└─ Agent exists in platform?
    ├─ YES → Follow Case 1
    └─ NO → Full setup needed (see pa-onboarding skill)

---

Case 1 — Connection Issue (WhatsApp not linked)

Symptom: Dashboard shows disconnected or no channel configured.

Fix:

1. Open agent settings in OpenClaw platform
2. Go to Channels → WhatsApp → click Connect or Re-link
3. Scan the QR code with WhatsApp Business app
4. Confirm the phone number matches
5. Wait 30 seconds for status to update

Most common cause: WhatsApp session expired (happens after ~14 days of inactivity or after a phone restart).

---

Case 2 — Ingest Issue (Connected but Messages = 0)

Symptom: Dashboard shows "Connected and listening" but message count stays at 0.

Meaning: WhatsApp is connected at protocol level, but messages are not reaching the agent runtime.

Fix:

# Step 1: Check gateway status
openclaw gateway status

# Step 2: Restart the gateway
openclaw gateway restart

# Step 3: Send a test message, wait 30 seconds

# Step 4: If count is still 0, check gateway logs
openclaw gateway logs --last 50

What to look for in logs:

• binding failed
• session dropped
• ingest error

If any of these appear → escalate to platform admin. This is an infrastructure issue.

---

Case 3 — Runtime Issue (Messages arriving, no reply)

Symptom: Message count increments, but agent doesn't respond.

Meaning: Messages reach the agent, but the agent runtime is failing.

Fix:

# Step 1: Check for billing errors in agent log
grep -i "billing\|402\|credits" ~/.openclaw/logs/agent.log | tail -20
# If billing error found → see billing-monitor skill

# Step 2: Check agent status
openclaw status

# Step 3: Verify API key (pick your provider below)

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

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

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

# Expected: 200. If 401 → invalid key. If 402 → billing error.

# Step 4: Check recent runtime errors
openclaw logs --last 100 | grep -i error

Interpret results:

• 200 → API key is valid. Problem is elsewhere (check Step 4).
• 401 → Invalid API key. Update the key in agent settings.
• 402 → Billing error. Follow the billing-monitor skill.

---

Quick Health Check Script

#!/bin/bash
# whatsapp-health-check.sh
# Run this when the agent is unresponsive to get a quick status overview.

echo "=== WhatsApp Diagnostics ==="

# Check gateway status
echo -n "Gateway: "
openclaw gateway status 2>&1 | grep -o "running\|stopped\|error" | head -1 || echo "unknown"

# Check API key — detect provider from env vars
echo -n "API key: "

if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
  PROVIDER="Anthropic"
  # Test with a minimal request to the models endpoint
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    -H "x-api-key: ${ANTHROPIC_API_KEY}" \
    -H "anthropic-version: 2023-06-01" \
    https://api.anthropic.com/v1/models 2>/dev/null)

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

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

else
  echo "⚠️ no API key env var found"
  PROVIDER=""
  STATUS=""
fi

# Interpret the HTTP status code
if [ -n "$STATUS" ]; then
  case $STATUS in
    200) echo "✅ valid ($PROVIDER)" ;;
    401) echo "❌ invalid key ($PROVIDER)" ;;
    402) echo "⚠️ billing error ($PROVIDER) — see billing-monitor skill" ;;
    *)   echo "? HTTP $STATUS ($PROVIDER)" ;;
  esac
fi

# Count recent errors in agent logs
echo -n "Recent errors: "
ERROR_COUNT=$(openclaw logs --last 100 2>/dev/null | grep -ic error || echo 0)
echo "$ERROR_COUNT found"

echo "=== Done ==="

---

When to Escalate to Platform Admin

Escalate if:

• Gateway restart does NOT fix Messages = 0
• Logs show socket, binding, or session errors
• Multiple agents on the same server are affected at the same time

Include in your escalation message:

• Agent name and phone number
• Time the issue started
• Output of openclaw gateway status
• Messages count shown in dashboard

---

Prevention

Action	Why
Send at least one message every 7 days	Prevents WhatsApp session expiry
Check Messages count during heartbeat	Catches ingest issues early
Keep the phone number on record	Needed for QR re-linking
Don't use the same number on two devices	WhatsApp only allows one active session

---

Cost Tips

• Very cheap: All diagnostics use CLI + curl — no LLM tokens needed
• Small model OK: Any model can follow this decision tree and interpret curl output
• Avoid: Don't run diagnostics on every heartbeat — only run when the agent is not responding
• Batch: Run the Quick Health Check script once to get all info, rather than running each check separately