{"id":49238063,"url":"https://github.com/deepgram/deepclaw","last_synced_at":"2026-04-24T17:37:39.284Z","repository":{"id":336560578,"uuid":"1150064128","full_name":"deepgram/deepclaw","owner":"deepgram","description":"Give your OpenClaw a voice (and a phone number!)","archived":false,"fork":false,"pushed_at":"2026-02-05T04:55:26.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T13:50:16.272Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deepgram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-04T20:55:01.000Z","updated_at":"2026-02-05T04:55:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deepgram/deepclaw","commit_stats":null,"previous_names":["deepgram/deepclaw"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/deepgram/deepclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deepgram","download_url":"https://codeload.github.com/deepgram/deepclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32234727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-24T17:37:35.078Z","updated_at":"2026-04-24T17:37:39.278Z","avatar_url":"https://github.com/deepgram.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# deepclaw\n\nCall your OpenClaw over the phone using the [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent).\n\n## Why Deepgram?\n\n| | ElevenLabs | Deepgram |\n|---|---|---|\n| **Turn detection** | VAD-based | Semantic (Flux) |\n| **TTS latency** | ~200ms TTFB | 90ms TTFB |\n| **TTS price** | $0.050/1K chars | $0.030/1K chars |\n| **Barge-in** | Basic VAD | Native StartOfTurn |\n\nDeepgram Flux understands *when you're done talking* semantically and acoustically—not just when you stop making noise. This means fewer awkward interruptions and faster responses.\n\n## Provider Comparison: Twilio vs Telnyx\n\n| Feature | Twilio | Telnyx |\n|---------|--------|--------|\n| **Setup Complexity** | Moderate | Easy |\n| **Phone Number Cost** | ~$1/month | ~$0.50-$2/month |\n| **Call Pricing** | $0.085/min | $0.005-$0.025/min |\n| **Media Streaming** | WebSocket + TwiML | WebSocket + REST API |\n| **Authentication** | Account SID + Auth Token | API Key + Public Key |\n| **Documentation** | Extensive | Growing |\n| **Global Coverage** | Excellent | Excellent |\n\n**Recommendation:**\n- **Twilio**: Better for production apps with extensive docs and ecosystem\n- **Telnyx**: More cost-effective, simpler API, better for experimenting\n\n## How It Works\n\ndeepclaw uses the [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent)—a single WebSocket that handles STT, TTS, turn-taking, and barge-in together.\n\n```\nPhone Call → Twilio/Telnyx → deepclaw ←──WebSocket──→ Deepgram Voice Agent API\n                                │                      (Flux STT + Aura-2 TTS)\n                                │\n                                ↓\n                           OpenClaw (LLM)\n```\n\n1. You call your phone number\n2. **Twilio/Telnyx** streams audio to deepclaw via WebSocket\n3. deepclaw forwards audio to Deepgram Voice Agent API\n4. Flux transcribes with semantic turn detection\n5. Deepgram calls your LLM endpoint (OpenClaw via deepclaw proxy)\n6. Aura-2 speaks the response, streamed back through your phone provider\n\n**Barge-in support:** Start talking while the assistant is speaking and it stops immediately—handled natively by the Voice Agent API.\n\n## Quick Setup (Let OpenClaw Do It)\n\nThe easiest way to set up deepclaw is to let your OpenClaw do it for you:\n\n```bash\n# Copy the skill to your OpenClaw\ncp -r skills/deepclaw-voice ~/.openclaw/skills/\n```\n\nThen tell your OpenClaw: **\"I want to call you on the phone\"**\n\nOpenClaw will walk you through:\n- Creating a Deepgram account (free $200 credit)\n- Setting up a Twilio phone number (~$1/month)\n- Configuring everything automatically\n\n## Manual Setup\n\n### Prerequisites\n\n- Python 3.10+\n- [Deepgram account](https://console.deepgram.com/) (free tier available, $200 credit)\n- **Phone Provider** (choose one):\n  - [Twilio account](https://www.twilio.com/) with a phone number (~$1/month)\n  - [Telnyx account](https://telnyx.com/) with a phone number (~$0.50-$2/month)\n- [OpenClaw](https://github.com/openclaw/openclaw) running locally\n- [ngrok](https://ngrok.com/) for exposing your local server\n\n### 1. Clone and install\n\n```bash\ngit clone https://github.com/deepgram/deepclaw.git\ncd deepclaw\npip install -e .\n```\n\n### 2. Configure environment\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your credentials:\n\n**For Twilio (default):**\n```env\nDEEPGRAM_API_KEY=your_deepgram_api_key\nVOICE_PROVIDER=twilio\nTWILIO_ACCOUNT_SID=your_twilio_account_sid\nTWILIO_AUTH_TOKEN=your_twilio_auth_token\nOPENCLAW_GATEWAY_URL=http://127.0.0.1:18789\nOPENCLAW_GATEWAY_TOKEN=your_openclaw_gateway_token\n```\n\n**For Telnyx:**\n```env\nDEEPGRAM_API_KEY=your_deepgram_api_key\nVOICE_PROVIDER=telnyx\nTELNYX_API_KEY=your_telnyx_api_key\nTELNYX_PUBLIC_KEY=your_telnyx_public_key\nOPENCLAW_GATEWAY_URL=http://127.0.0.1:18789\nOPENCLAW_GATEWAY_TOKEN=your_openclaw_gateway_token\n```\n\n### 3. Configure OpenClaw\n\nEnable the chat completions endpoint in your `openclaw.json`:\n\n```bash\nopenclaw config set gateway.http.endpoints.chatCompletions.enabled true\n```\n\ndeepclaw automatically creates a dedicated `voice` agent in OpenClaw that uses a fast model (Claude Haiku 4.5) for low-latency phone conversations. This happens on first `python -m deepclaw` launch. To customize the model:\n\n```bash\n# Use a different model for voice (optional)\nexport OPENCLAW_VOICE_MODEL=anthropic/claude-sonnet-4-5-20250929\n```\n\nOr create the agent manually:\n\n```bash\nopenclaw agents add voice --model anthropic/claude-haiku-4-5-20251001\n```\n\n### 4. Start the tunnel\n\n```bash\nngrok http 8000\n```\n\nNote your ngrok URL (e.g., `https://abc123.ngrok-free.app`).\n\n### 5. Configure Your Phone Provider\n\n#### Option A: Configure Twilio\n\n1. Go to your [Twilio Console](https://console.twilio.com/)\n2. Navigate to Phone Numbers → Manage → Active Numbers\n3. Click your number\n4. Under \"Voice Configuration\":\n   - Set \"A Call Comes In\" to **Webhook**\n   - URL: `https://your-ngrok-url.ngrok-free.app/twilio/incoming`\n   - Method: **POST**\n5. Save\n\n#### Option B: Configure Telnyx\n\n1. Go to your [Telnyx Mission Control Portal](https://portal.telnyx.com/)\n2. Navigate to **Voice → Programmable Voice**\n3. Create a new **Voice API Application**:\n   - **Application Name**: `deepclaw-voice`\n   - **Webhook URL**: `https://your-ngrok-url.ngrok-free.app/telnyx/webhook`\n   - **Webhook API Version**: `API v2` (recommended)\n   - **Webhook Failover URL**: (optional) same as webhook URL\n4. Click **Create**\n5. Go to **Numbers → My Numbers**\n6. Click your phone number\n7. Under **Voice Settings**:\n   - **Connection**: Select your `deepclaw-voice` application\n8. Save configuration\n\n#### Getting Telnyx API Keys\n\n1. In Mission Control Portal, go to **API Keys**\n2. Create a new API Key or copy existing one\n3. For **Public Key**: Go to **Account → Public Key** and copy the key\n\n### 6. Start deepclaw\n\n```bash\npython -m deepclaw\n```\n\n### 7. Call your number\n\nPick up the phone and talk to your OpenClaw!\n\n## Architecture\n\n```\n┌─────────────┐     ┌──────────────────────────────────────────────────────┐\n│   Caller    │     │                   Your Machine                        │\n│  (Phone)    │     │                                                       │\n└──────┬──────┘     │  ┌───────────┐   ┌───────────┐   ┌───────────────┐   │\n       │            │  │ Twilio or │   │ deepclaw  │   │   OpenClaw    │   │\n       │ PSTN       │  │  Telnyx   │──▶│  Server   │──▶│   Gateway     │   │\n       │            │  │ Webhook   │   └─────┬─────┘   └───────────────┘   │\n       ▼            │  └───────────┘         │                              │\n┌──────────────┐    │                        │ WebSocket                    │\n│   Twilio/    │◀───┼────────────────────────┤                              │\n│   Telnyx     │    │                        ▼                              │\n│ (SIP/Media)  │    │              ┌───────────────────┐                    │\n└──────────────┘    │              │ Deepgram Voice    │                    │\n       │            │              │ Agent API         │                    │\n       │  Audio     │              │ • Flux (STT)      │                    │\n       └────────────┼─────────────▶│ • Aura-2 (TTS)    │                    │\n                    │              │ • Turn detection  │                    │\n                    │              │ • Barge-in        │                    │\n                    │              └───────────────────┘                    │\n                    └──────────────────────────────────────────────────────┘\n```\n\nThe Voice Agent API handles the entire speech pipeline in a single WebSocket connection. deepclaw bridges Twilio's media stream to the Voice Agent API and proxies LLM requests to your local OpenClaw.\n\n## Customizing Voice\n\ndeepclaw uses Deepgram Aura-2 TTS with 80+ voices in 7 languages. Edit `voice_agent_server.py`:\n\n```python\n\"speak\": {\n    \"provider\": {\n        \"type\": \"deepgram\",\n        \"model\": \"aura-2-orion-en\",  # Change voice here\n    },\n},\n```\n\n**Popular voices:**\n| Voice | Style |\n|-------|-------|\n| `aura-2-thalia-en` | Feminine, American (default) |\n| `aura-2-orion-en` | Masculine, American |\n| `aura-2-draco-en` | Masculine, British |\n| `aura-2-estrella-es` | Feminine, Mexican Spanish |\n| `aura-2-fabian-de` | Masculine, German |\n\nSee `skills/deepclaw-voice/SKILL.md` for the complete voice list (80+ voices in 7 languages), or test voices at https://playground.deepgram.com/\n\n## Security Considerations\n\nBe aware of these security considerations when using OpenClaw and deepclaw. Like the rest of OpenClaw, use at your own risk.\n\n**1. LLM proxy endpoint has no authentication**\n- The `/v1/chat/completions` endpoint is unauthenticated\n- Anyone who discovers your ngrok URL can use your OpenClaw/Anthropic API credits\n- **Mitigation:** Keep your ngrok URL private. Consider using a fixed ngrok domain.\n\n**2. No Twilio signature validation**\n- Incoming webhook requests are not verified as coming from Twilio\n- **Mitigation:** For production, add [Twilio request validation](https://www.twilio.com/docs/usage/security#validating-requests)\n\n**3. Credentials in `.env` file**\n- API keys and tokens are stored in plaintext\n- **Mitigation:** The file is gitignored. Set restrictive permissions: `chmod 600 .env`\n\n**4. ngrok exposes your local machine**\n- Your server is accessible from the internet while running\n- **Mitigation:** Only run when needed. Use ngrok's IP allowlist on paid plans.\n\n**For production deployments**, consider:\n- Adding Twilio signature validation\n- Running behind a reverse proxy with rate limiting\n- Using a dedicated server instead of ngrok\n- Implementing proper authentication on the LLM proxy\n\n## Known Limitations\n\n**OpenClaw streaming latency:** OpenClaw's `/v1/chat/completions` endpoint currently buffers responses for ~5 seconds before streaming begins. This adds latency to LLM responses regardless of which voice provider you use (Deepgram, ElevenLabs, etc.).\n\nThe initial greeting is instant (generated by Deepgram), but subsequent responses wait for OpenClaw's buffer.\n\nThis is an upstream limitation. OpenClaw's native WebSocket agent endpoint streams properly, but external voice APIs require the OpenAI-compatible chat completions endpoint.\n\n## Coming Soon\n\n- **Local wake-word mode** — Talk to OpenClaw hands-free at your desk, no phone needed\n- **One-click desktop installer** — No terminal required\n- **Native OpenClaw plugin** — Install with one command\n\n## Getting Help\n\nIf you run into issues:\n\n1. **Check existing issues:** Search [GitHub Issues](https://github.com/deepgram/deepclaw/issues) to see if your problem has been reported\n2. **Open a new issue:** Include:\n   - What you were trying to do\n   - What happened instead\n   - Server logs (redact any API keys)\n   - Your environment (OS, Python version, OpenClaw version)\n3. **Deepgram support:** For Deepgram-specific issues, visit [Deepgram's Community](https://discord.gg/deepgram)\n\n## Contributing\n\nContributions are welcome! Here's how to help:\n\n### Reporting Bugs\n\nOpen an issue with:\n- Clear description of the bug\n- Steps to reproduce\n- Expected vs actual behavior\n- Logs and environment info\n\n### Suggesting Features\n\nOpen an issue describing:\n- The problem you're trying to solve\n- Your proposed solution\n- Any alternatives you've considered\n\n### Pull Requests\n\n1. Fork the repo\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Test thoroughly\n5. Commit with clear messages\n6. Push to your fork\n7. Open a PR against `main`\n\n**Note:** The `main` branch is protected. All changes require a pull request and review.\n\n### Code Style\n\n- Follow existing code patterns\n- Add comments for complex logic\n- Update documentation for user-facing changes\n\n## License\n\nMIT\n\n## Credits\n\nBuilt with:\n- [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent-api) — Real-time conversational AI pipeline\n- [Deepgram Flux](https://deepgram.com/product/speech-to-text) — Semantic speech recognition\n- [Deepgram Aura-2](https://deepgram.com/product/text-to-speech) — Low-latency text-to-speech\n- [OpenClaw](https://github.com/openclaw/openclaw) — Open-source AI assistant\n- [Twilio](https://www.twilio.com/) — Phone infrastructure\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepgram%2Fdeepclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepgram%2Fdeepclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepgram%2Fdeepclaw/lists"}