clawvoice

# ClawVoice

**Give your AI agent a real phone number.** It answers calls, makes calls, sends texts, takes messages, books appointments, and reports back to you — all autonomously.

ClawVoice turns your [OpenClaw](https://github.com/openclaw) agent into a phone-capable assistant. Say *"Call the dentist and schedule a cleaning for next week"* and your agent handles the entire call, then sends you a summary on Telegram with the full transcript.

Website: [clawvoice.io](https://clawvoice.io)

## Why ClawVoice?

OpenClaw already has [`@openclaw/voice-call`](https://docs.openclaw.ai/plugins/voice-call) for PSTN calling. ClawVoice is a community alternative that adds batch operations, SMS, post-call intelligence, and a guided setup experience.

### vs `@openclaw/voice-call` (official plugin)

| Capability | `@openclaw/voice-call` | ClawVoice |
|------------|:----------------------:|:---------:|
| Outbound PSTN calls | ✅ | ✅ |
| Inbound call handling | ✅ | ✅ |
| Multi-turn voice conversations | ✅ | ✅ |
| Twilio | ✅ | ✅ |
| Telnyx | ✅ | ✅ |
| Plivo | ✅ | — |
| SMS send/receive | — | ✅ |
| Batch calling + campaign reports | — | ✅ |
| Post-call notifications (Telegram/Discord/Slack) | — | ✅ |
| Voice profiles (owner identity per call) | — | ✅ |
| ElevenLabs Conversational AI agent | — | ✅ |
| Deepgram Voice Agent | — | ✅ |
| Setup wizard + health diagnostics | — | ✅ |
| Call state machine (13 states) | ✅ | — |
| Tailscale Funnel exposure | ✅ | ✅ |
| Latency analysis CLI | ✅ | — |

**Choose `@openclaw/voice-call`** if you need Plivo support or prefer the official plugin with OpenClaw core team maintenance.

**Choose ClawVoice** if you want SMS, batch campaigns with CSV reports, post-call notifications, voice profiles, or a wizard-guided setup.

> **Note:** OpenClaw also has [Talk Mode](https://docs.openclaw.ai/nodes/talk) — a built-in local voice chat for speaking with your agent through your device's microphone. Neither ClawVoice nor `@openclaw/voice-call` replaces Talk Mode; they add PSTN telephony (real phone calls to real phone numbers).

## Features

| Feature | Description |
|---------|-------------|
| Outbound calls | Agent places calls with full context about purpose, owner identity, and callback number |
| Inbound calls | Agent answers your phone number, takes messages, screens callers |
| Batch calling | Sequential calls from a list (up to 20), with consolidated reporting |
| Campaign reports | CSV spreadsheets with extracted details, summaries, and full transcripts |
| SMS send/receive | Text messaging with auto-reply for inbound texts |
| Post-call notifications | Rich summaries to Telegram/Discord/Slack with transcript file attachments |
| Voice profile | Owner identity, phone number, and preferences loaded into every call |
| Memory isolation | Voice interactions sandboxed from main agent memory |
| Safety guardrails | AI disclosure, call duration limits, tool restrictions, answering machine detection |
| Dual voice engines | ElevenLabs Conversational AI or Deepgram Voice Agent |

> **Legal Notice:** Automated calling is subject to the TCPA (Telephone Consumer Protection Act) and state telemarketing laws. You are responsible for compliance including obtaining proper consent. Batch calling features are provided as-is — **use at your own risk.** This software does not provide legal advice.

---

## Getting Started

There are two ways to set up ClawVoice:

| Method | Best for |
|--------|----------|
| **Guided setup** — Tell your agent *"Set up ClawVoice"* or run `openclaw clawvoice setup` | First-time users. The wizard walks through every step with explanations. |
| **Manual setup** — Follow the steps below | Experienced users or automated deployments |

### What You'll Need

| Requirement | Where to get it | Cost |
|-------------|----------------|------|
| **OpenClaw** installed and running | [openclaw.dev](https://openclaw.dev) | Free (open source) |
| **Phone number** from Twilio or Telnyx | [twilio.com](https://twilio.com) or [telnyx.com](https://telnyx.com) | ~$1.50/mo |
| **Deepgram API key** | [deepgram.com](https://deepgram.com) | Free tier available |
| **ElevenLabs API key + Agent ID** *(optional, for premium voices)* | [elevenlabs.io](https://elevenlabs.io) | Free tier available |
| **Tunnel tool** (ngrok, Cloudflare Tunnel, or Tailscale Funnel) | See [Step 2](#2-start-a-public-tunnel) | Free options available |

> **Note:** A Deepgram API key is always required — even if you use ElevenLabs for voice. Deepgram handles speech-to-text for call transcription.

**Cost per call:**

| Voice Stack | Telephony | Voice AI | Total per minute |
|-------------|-----------|----------|------------------|
| **Deepgram** (recommended to start) | ~$0.01 | ~$0.01 | **~$0.02/min** |
| **ElevenLabs** (premium voices) | ~$0.01 | ~$0.12–0.15 | **~$0.13–0.16/min** |

A typical 5-minute call costs **$0.10** on Deepgram or **$0.65–0.80** on ElevenLabs. Both voice providers offer free tiers to get started.

> **If you're using ElevenLabs:** Create your ElevenLabs Conversational AI agent **before** running the setup wizard — the wizard asks for your Agent ID. See [Step 4](#4-configure-elevenlabs-agent-if-using-elevenlabs) for instructions.

> **If you already have `@openclaw/voice-call` installed:** ClawVoice replaces the built-in voice plugin. Disable it to prevent conflicts: `openclaw plugins disable voice-call`. The setup wizard will detect and warn you about this automatically.

### 1. Install

ClawVoice is published on [npm](https://www.npmjs.com/package/clawvoice). Install it with npm, then register it as an OpenClaw plugin:

```bash
npm install -g clawvoice
openclaw plugins install clawvoice
```

**Or install from source** (for contributors or pre-release versions):

```bash
git clone https://github.com/ClawVoice/clawvoice.git
cd clawvoice
npm install && npm run build
openclaw plugins install --link .
```

### 2. Start a Public Tunnel

Twilio/Telnyx need to reach your machine from the internet. ClawVoice runs a standalone server on **port 3101** that handles both webhooks and media streams.

```bash
# Option A: ngrok (quickest)
ngrok http 3101

# Option B: Cloudflare Tunnel (stable URL, free)
cloudflared tunnel --url http://localhost:3101

# Option C: Tailscale Funnel (if you use Tailscale)
openclaw clawvoice expose --mode funnel
# Or manually (path-based):
tailscale funnel --bg --yes --set-path /media-stream http://127.0.0.1:3101/media-stream
```

The `expose` command auto-detects your Tailscale DNS name, activates Funnel on the media stream path, and prints the WSS URL to use. Use `--mode serve` for Tailnet-only (no public internet) or `--mode off` to disable.

> **Tunnel URL changes:** Free ngrok URLs change every restart. You'll need to update your Twilio webhooks and `twilioStreamUrl` each time. For a stable URL, use ngrok with a custom domain ($), Cloudflare Tunnel, or Tailscale Funnel.

> **Cloudflare + Twilio WebSocket:** Cloudflare Tunnel has a [known issue](https://github.com/cloudflare/cloudflared/issues/1465) with Twilio Media Streams. If you get `Error 31920`, use ngrok instead.

### 3. Run the Setup Wizard

```bash
openclaw clawvoice setup
```

The wizard walks you through:
- Telephony provider selection (Twilio or Telnyx)
- API credentials
- Tunnel URL configuration
- Voice provider selection (ElevenLabs or Deepgram)
- Voice provider credentials
- ElevenLabs agent configuration (if applicable)

When asked for the **Twilio media stream URL**, enter your tunnel URL with `/media-stream`:
```
wss://YOUR-TUNNEL-URL/media-stream
```

### 4. Configure ElevenLabs Agent (if using ElevenLabs)

This step is **critical** — without it, your voice agent won't know why it's calling or who it represents.

On the [ElevenLabs Dashboard](https://elevenlabs.io/app/conversational-ai):

1. **Create** a Conversational AI agent (or use an existing one)

2. **System Prompt** — must include this dynamic variable placeholder:

   ```
   {{ _system_prompt_ }}
   ```

 

[truncated…]