OpenClaw setup for AgentPing phone call alerts

Overview

AgentPing is an escalation layer for AI agents. OpenClaw should use it after chat is no longer enough, not as the first communication channel.

{
  "skill": "agentping",
  "required_env": "AGENTPING_API_KEY",
  "base_url": "https://api.agentping.me",
  "preferred_severities": ["normal", "critical"],
  "recommended_pattern": "schedule check first, then create alert with delay_seconds=0 only if the user still has not replied"
}

Prerequisites

Before installing the skill, you need:

• An OpenClaw installation or environment where you can add skills and secrets
• An AgentPing account
• At least one phone number verified in AgentPing

Account Setup

Set up AgentPing first, then connect it to OpenClaw.

1. Create an account at agentping.me/signup.
2. Verify at least one phone number in the dashboard.
3. Go to agentping.me/api-keys and create an API key.
4. Copy the key immediately. It starts with ap_sk_ and is only shown once.

Install Skill

Install the ClawHub skill into OpenClaw:

clawhub install agentping-phone-call-alerts

If you are testing or publishing a local version, use your local skill package instead of the public ClawHub listing.

Set API Key

OpenClaw reads config from ~/.openclaw/openclaw.json. For this skill, add the key under skills.entries.agentping.

Recommended config:

// ~/.openclaw/openclaw.json
{
  "skills": {
    "entries": {
      "agentping": {
        "enabled": true,
        "apiKey": "ap_sk_your_key_here"
      }
    }
  }
}

This skill declares AGENTPING_API_KEY as its primary env var, and OpenClaw maps skills.entries.agentping.apiKey to that env var for the skill at runtime.

If you prefer to be explicit, you can also set it through env:

// ~/.openclaw/openclaw.json
{
  "skills": {
    "entries": {
      "agentping": {
        "enabled": true,
        "env": {
          "AGENTPING_API_KEY": "ap_sk_your_key_here"
        }
      }
    }
  }
}

Changes take effect in the next new OpenClaw session.

Recommended Pattern

For the current service, OpenClaw should prefer schedule-first escalation:

1. Send a chat message first.
2. Save the current conversation checkpoint.
3. Schedule a follow-up check at the escalation deadline.
4. If the user has replied since the checkpoint, do nothing.
5. If the user has not replied, create an AgentPing alert with delay_seconds=0.

This is safer than creating a delayed alert immediately. It avoids false-positive calls if the user replied but the agent failed to acknowledge the pending alert in time.

Fallback pattern for agents without scheduling support:

1. Send a chat message first.
2. Create an alert with a nonzero delay_seconds.
3. If the user replies before the call starts, POST /v1/alerts/{id}/acknowledge with {"ack_source":"chat"}.
4. Use this only as a fallback.

Approval rule: a phone acknowledgement means the user received the alert, not that they approved the action. For deploys, purchases, or destructive actions, wait for explicit approval in chat.

Test

Send a test voice alert to confirm the integration works:

curl -X POST https://api.agentping.me/v1/alerts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ap_sk_your_key_here" \
  -d '{
    "title": "Test alert from OpenClaw",
    "message": "This is a test of your AgentPing OpenClaw integration.",
    "severity": "normal",
    "alert_type": "other",
    "delay_seconds": 0
  }'

You should receive a voice call shortly after creating the alert.

Status and Acknowledgement

During the call:

• Press 0 to acknowledge
• Press 1 to snooze for 5 minutes
• On paid plans, enter 2 to 120 followed by # for a custom snooze

Check alert status via API:

curl https://api.agentping.me/v1/alerts/{alert_id} \
  -H "X-API-Key: ap_sk_your_key_here"

Useful fields:

• status
• acknowledged_at
• acknowledged_via
• delay_seconds

AgentPing does not currently push acknowledgement events back to the agent. If OpenClaw needs to observe the result programmatically, it should poll the alert status endpoint.

Troubleshooting

No call received

• Confirm your phone number is verified in AgentPing
• Confirm the API returned 201 with an alert ID
• Confirm you used delay_seconds: 0 if you expected an immediate call
• Check whether quiet hours blocked a normal-severity alert
• Check whether voice calls are disabled in the profile

401 Unauthorized

• Confirm the X-API-Key header is present
• Confirm the key is correct and not revoked
• API keys start with ap_sk_

422 Unprocessable Entity

• No verified phone number on the account
• Voice calls disabled in the profile
• Quiet hours active for a normal-severity alert
• Invalid request fields

429 Too Many Requests

• 20 alerts per hour per user
• 10 alerts per hour per API key