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.

Test

The simplest way to test is to ask OpenClaw to call you directly:

> Call me now.

You should receive a phone call within a few seconds. You can also test the end-to-end flow with a real task:

> Summarize the README in this repo. Call me when you finish.

OpenClaw will complete the task, post results in chat, and trigger a phone call through AgentPing. If you reply in chat before the call fires, the call is automatically cancelled.

If you don't receive a call, check the troubleshooting section below.

Recommended Pattern

The AgentPing skill is configured to follow a schedule-first, escalate-second pattern. This is already built into the skill spec — OpenClaw follows it automatically when you install the skill. The pattern works like this:

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.

The skill also includes a fallback pattern for situations 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, OpenClaw will wait for explicit approval in chat.

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