ClawVoice Bridge

Single Telegram bot token, single OpenClaw update consumer, unified text + voice handling.

What this project solves

Many people hit 409 Conflict when trying to run a separate Telegram voice bot alongside OpenClaw.

ClawVoice Bridge uses the correct architecture:

• One Telegram bot token
• One update consumer (OpenClaw only)
• Voice transcription inside OpenClaw (tools.media.audio via local CLI)
• Automatic voice reply for inbound voice notes (messages.tts.auto = inbound)

So text and voice both work in the same session without token conflicts.

---

Architecture

Telegram User
   |
   v
Telegram Bot API (single token)
   |
   v
OpenClaw (ONLY consumer of updates)
   |\
   | \__ Text path -> normal assistant flow
   |
   \____ Voice path -> local transcribe.py (faster-whisper)
                     -> transcript enters same assistant flow
                     -> optional TTS auto-reply (inbound)

---

Recommended directory layout (clean separation)

Keep OpenClaw internals and your own infra separate:

• OpenClaw state/config (managed by OpenClaw):
  • ~/.openclaw/
• Project source (Git working tree):
  • ~/projects/ClawVoiceBridge
• Infra deployment roots (your own):
  • ~/infra/stacks/voicebridge
  • ~/infra/data/voicebridge
  • ~/infra/ops/PORTS.md

Why: avoids coupling your service layout to OpenClaw internal state directories.

---

Prerequisites

• Linux host with OpenClaw installed
• Telegram bot token configured in ~/.openclaw/openclaw.json
• Miniforge/Conda (recommended)
• Python 3.11+

---

Quick start (current mode: OpenClaw direct tool call)

1) Install local voice dependencies

cd ~/projects/ClawVoiceBridge
bash scripts/setup_local_voice.sh

2) Configure OpenClaw tool path

Set tools.media.audio.models[0] to call:

• command: /home/kyaky/miniforge3/envs/local-voice/bin/python
• script arg: /home/kyaky/projects/ClawVoiceBridge/local-voice/transcribe.py

3) Merge config template into ~/.openclaw/openclaw.json

Use openclaw.config.example.json as reference and copy the tools.media.audio + messages.tts sections.

4) Restart OpenClaw gateway

openclaw gateway restart
openclaw status

5) Test

• Send text to your bot → should reply normally
• Send voice note to your bot → should transcribe and continue conversation
• If inbound TTS is enabled, reply arrives as voice

---

Why this is different from separate Telegram voice bots

• No second polling process
• No duplicate getUpdates
• No 409 Conflict
• Same session memory for text + voice

---

Included files

• openclaw.config.example.json — safe example config
• local-voice/transcribe.py — local Whisper wrapper
• scripts/setup_local_voice.sh — dependency install helper
• SECURITY.md — token and privacy hardening
• TROUBLESHOOTING.md — common failures and fixes

---

Scope notes

This template focuses on:

• Telegram
• OpenClaw single-consumer design
• Local STT via faster-whisper

TTS can be Edge/OpenAI/ElevenLabs (OpenClaw native), configurable in messages.tts.