HeySummon Consumer Skill

When you (an AI agent) get stuck, request help from a human expert via HeySummon.

When someone requests help, the skill submits a request to the HeySummon platform. The platform matches it to a registered provider (human expert) who can assist. Users can say "Hey summon John Doe to help" or "Hey summon a Python expert to help". The skill then routes the request to the appropriate provider based on the registered providers in providers.json.

Setup

Step 1: Configure Environment

Create .env in the skill directory with your HeySummon platform details:

HEYSUMMON_BASE_URL=http://localhost:3445
HEYSUMMON_API_KEY=hs_cli_your_key_here
HEYSUMMON_NOTIFY_MODE=message
HEYSUMMON_NOTIFY_TARGET=your_chat_id

Platform Options:

• Self-hosted: Use your local/server URL (e.g., http://localhost:3445)
• Cloud: Use https://cloud.heysummon.ai

Get API Key:

1. Go to your HeySummon dashboard
2. Navigate to Users → Create user profile (or ask provider for client key)
3. Create a client key (starts with hs_cli_...)

⚠️ Security: API keys starting with hs_prov_ are provider keys (not client keys). These will be rejected.

Step 2: Register Provider(s)

bash scripts/add-provider.sh "hs_cli_your_key" "FriendlyName"

This fetches provider info from the platform and stores it locally. You can register multiple providers for routing.

List registered providers:

bash scripts/list-providers.sh

Step 3: Start Event Watcher

bash scripts/setup.sh

This starts a persistent SSE listener that connects to the platform's event stream (/api/v1/events/stream). You'll receive notifications when providers respond.

To stop:

bash scripts/teardown.sh

Architecture

HeySummon Platform API (/api/v1/events/stream)
           ↓
    SSE Event Stream
           ↓
   Platform Watcher (pm2)
           ↓
   OpenClaw Notification
           ↓
        Your Chat

All communication flows through the platform API. E2E encryption is handled server-side.

Scripts

Usage

Submit a Help Request

To a specific provider:

bash scripts/submit-request.sh "Your question" '[{"role":"user","content":"context"}]' "ProviderName"

To default provider (from .env):

bash scripts/submit-request.sh "Your question" '[{"role":"user","content":"context"}]'

Provider routing: The script matches provider names case-insensitively from providers.json. If no match is found, it shows available providers and exits.

Wait for Response

The platform watcher handles real-time notifications:

• 🔑 Key exchange — provider connected
• 📩 New message — provider responded
• 🔒 Closed — conversation ended

Check Status (Fallback)

bash scripts/check-status.sh <REQUEST_ID>

When to Use

Use HeySummon when you are truly stuck:

• Ambiguous requirements needing clarification
• Domain expertise required
• Blocked by something you can't resolve autonomously

Request Statuses

Environment Variables

Security

• ✅ API keys stored in .env (gitignored)
• ✅ Keypairs stored in .keys/ (gitignored)
• ✅ Providers stored in providers.json (gitignored)
• ✅ All paths relative to skill directory
• ✅ E2E encryption handled by platform
• ✅ No hardcoded credentials in code

Never commit:

• .env
• providers.json
• .keys/ directory
• .requests/ directory