OpenClaw Consumer Skill

The hitlaas-consumer skill lets AI agents running on OpenClaw request human help through HeySummon.

Skill Structure

~/your-workspace/skills/hitlaas-consumer/
├── .env                  # Configuration (URLs, notify mode)
├── providers.json        # Registered providers
├── SKILL.md              # Skill documentation
└── scripts/
    ├── submit-request.sh     # Submit help request (with provider routing)
    ├── add-provider.sh       # Register a new provider
    ├── list-providers.sh     # List registered providers
    ├── mercure-watcher.sh    # Permanent SSE listener (pm2)
    ├── setup.sh              # Start watcher
    ├── teardown.sh           # Stop watcher
    └── crypto.mjs            # E2E encryption (X25519 + Ed25519 + AES-256-GCM)

Configuration (.env)

HITLAAS_API_KEY=hs_cli_your_key_here     # Default client key (fallback)
HITLAAS_BASE_URL=https://your-platform-url
HITLAAS_MERCURE_HUB=https://your-mercure-hub/.well-known/mercure
HITLAAS_NOTIFY_MODE=message               # "message" (Telegram) or "file" (events file)
HITLAAS_NOTIFY_TARGET=-123456789          # Telegram chat/group ID

Multi-Provider Support

Register a Provider

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

This calls /api/v1/whoami to fetch the provider’s name from the platform and stores it in providers.json.

List Providers

bash scripts/list-providers.sh
# Output:
# 📋 Registered providers (2):
#   1. Thomas (provider: Thomas Ansems) — key: hs_cli_78be...
#   2. Support (provider: Support Team) — key: hs_cli_a1b2...

Route by Provider Name

# Send to a specific provider:
bash scripts/submit-request.sh "How do I fix X?" '[]' "Thomas"
 
# Send to default provider (HITLAAS_API_KEY from .env):
bash scripts/submit-request.sh "How do I fix X?" '[]'

Provider matching is case-insensitive and supports partial matches.

Architecture

The consumer skill uses the same SSE pattern as the provider skill:

Mercure Hub (SSE)
  → mercure-watcher.sh (pm2, permanent)
    → OpenClaw /tools/invoke
      → message tool → Telegram/channel
        → Agent receives message and processes response

Mercure Watcher

The watcher is a permanent pm2 process that:

Listens on all active request topics via SSE
Reconnects every 30 seconds to pick up new topics
Accepts SIGUSR1 to force immediate reconnect
Fetches the actual response text and includes it in the notification
Resolves refCode from the active-requests/ directory

Request Registration

When submit-request.sh submits a request, it:

Registers the request ID in ~/.hitlaas/active-requests/
Starts the watcher if not running
Signals the watcher (SIGUSR1) to pick up the new topic
Syncs provider name from platform (auto-updates providers.json)

Key Format

Key type	Prefix	Description
Consumer API key	`hs_cli_`	Used for consumer requests
Provider API key	`hs_prov_`	Used for provider responses
Legacy consumer key	`hs_`	Still supported (backward compatible)

Provider Name Sync

On every request submission, the consumer skill calls /api/v1/whoami to check if the provider’s name has changed on the platform. If so, providers.json is automatically updated.

API Reference Realtime Strategy