voice

Real-time voice conversations in Discord voice channels with Claude AI

Security Scan

The plugin mostly does what it says (connects a bot to Discord, transcribes speech, calls the host agent, and speaks responses) but there are a few mismatches and privileged operations (dynamic core imports, session store access, and system-prompt injection) that deserve careful review before install.

Purpose & Capability

The plugin's name/description (Discord voice → STT/TTS → agent) align with the code and manifests: it legitimately needs a Discord bot token and STT/TTS API keys. However the registry metadata at the top listed no required env vars while package/manifests and SKILL.md reference multiple provider keys (OpenAI, ElevenLabs, Deepgram, Polly) — an inconsistency that may mislead administrators about required secrets.

Instruction Scope

The runtime instructions and code dynamically load host 'extensionAPI' and directly read/write agent session stores, resolve agent workspaces, and call the host agent. Those actions are coherent for a plugin that routes voice through the agent, but they grant access to host agent internals and persisted session data. The SKILL.md (and SECURITY.md) also describe injecting an extra system prompt (noEmojiHint / extraSystemPrompt) into the agent; system-prompt manipulation is powerful and, if configuration is writable by untrusted users, could be abused. The plugin warns that configuration inputs are admin-controlled, but this trust boundary must be enforced by the deployer.

Install Mechanism

No remote/extract install URLs or shorteners; installation is via npm/git as expected. The package bundles a normal package-lock with standard npm dependencies (discord.js, Deepgram, @xenova/transformers, etc.). There is no high-risk arbitrary download/install step in the SKILL.md.

Credentials

Requested credentials (Discord token, keys for OpenAI/Deepgram/ElevenLabs/AWS Polly optionally) are consistent with STT/TTS and playing audio. But the declared top-level 'Required env vars: none' contradicts manifest and code. The plugin also checks and warns about NODE_TLS_REJECT_UNAUTHORIZED and may read host config for agent/session store resolution — it therefore needs access to platform configuration and file system paths, which is more privilege than a simple integration and should be accepted consciously.

Persistence & Privilege

The skill is not 'always:true' and is user-invocable. It registers long-running services, tools, auto-join behavior, and writes/updates session store files. Those behaviors are expected for a persistent voice plugin, but because it persists session state and dynamically imports host extension APIs, it has elevated long-term access to host agent internals — the deployer should review and restrict plugin config and allowedUsers.

Scan Findings in Context

[system-prompt-override] expected: The pre-scan flagged system-prompt override patterns in SKILL.md. The plugin intentionally injects an extra system prompt (e.g., noEmojiHint) to make TTS-friendly responses; this is expected for a voice assistant. However system-prompt injection is high-impact if configs used to construct the prompt are writable by untrusted users, so the deployer must ensure those config sources are admin-controlled as the SECURITY.md claims.

What to consider before installing

Before installing: 1) Verify the plugin source repository and maintainers — the package includes many dependencies and runs code, so install only from a trusted repo. 2) Expect to provide a Discord bot token plus any STT/TTS API keys (OpenAI, Deepgram, ElevenLabs, AWS Polly) — do not place unrelated secrets in the plugin config. 3) Restrict allowedUsers in the plugin config; leaving it empty allows anyone in joined channels to trigger the agent and could leak spoken secrets. 4) The plugin dynamically imports host OpenClaw APIs and reads/writes session stores and agent workspaces — if you run this in a multi-tenant or sensitive environment, sandbox it or review the code paths that access your agent/session data. 5) Confirm that only trusted admins can edit plugin configuration (extraSystemPrompt/noEmojiHint) because those fields are used to inject system prompts into the agent. 6) Do not set NODE_TLS_REJECT_UNAUTHORIZED=0 on the host; the plugin will warn if it sees that but it weakens TLS for all outbound calls. 7) If you need higher assurance, audit the loaded files (core-bridge, voice-connection, STT/TTS modules) and run the plugin in a non-production environment first.

Discord Voice Plugin for Clawdbot

Real-time voice conversations in Discord voice channels. Join a voice channel, speak, and have your words transcribed, processed by Claude, and spoken back.

Features

• Join/Leave Voice Channels: Via slash commands, CLI, or agent tool
• Voice Activity Detection (VAD): Automatically detects when users are speaking
• Speech-to-Text: Whisper API (OpenAI), Deepgram, or Local Whisper (Offline)
• Streaming STT: Real-time transcription with Deepgram WebSocket (~1s latency reduction)
• Agent Integration: Transcribed speech is routed through the Clawdbot agent
• Text-to-Speech: OpenAI TTS, ElevenLabs, or Kokoro (Local/Offline)
• Audio Playback: Responses are spoken back in the voice channel
• Barge-in Support: Stops speaking immediately when user starts talking
• Auto-reconnect: Automatic heartbeat monitoring and reconnection on disconnect

Requirements

• Discord bot with voice permissions (Connect, Speak, Use Voice Activity)
• API keys for STT and TTS providers
• System dependencies for voice:
  • ffmpeg (audio processing)
  • Native build tools for @discordjs/opus and sodium-native

Installation

1. Install System Dependencies

# Ubuntu/Debian
sudo apt-get install ffmpeg build-essential python3

# Fedora/RHEL
sudo dnf install ffmpeg gcc-c++ make python3

# macOS
brew install ffmpeg

2. Install via ClawdHub

clawdhub install discord-voice

Or manually:

cd ~/.clawdbot/extensions
git clone <repository-url> discord-voice
cd discord-voice
npm install

3. Configure in clawdbot.json

{
  plugins: {
    entries: {
      "discord-voice": {
        enabled: true,
        config: {
          sttProvider: "local-whisper",
          ttsProvider: "openai",
          ttsVoice: "nova",
          vadSensitivity: "medium",
          allowedUsers: [], // Empty = allow all users
          silenceThresholdMs: 1500,
          maxRecordingMs: 30000,
          openai: {
            apiKey: "sk-...", // Or use SKILLBOSS_API_KEY env var
          },
        },
      },
    },
  },
}

4. Discord Bot Setup

Ensure your Discord bot has these permissions:

• Connect - Join voice channels
• Speak - Play audio
• Use Voice Activity - Detect when users speak

Add these to your bot's OAuth2 URL or configure in Discord Developer Portal.

Configuration

Option	Type	Default	Description
enabled	boolean	true	Enable/disable the plugin
sttProvider	string	"local-whisper"	"whisper", "deepgram", or "local-whisper"
streamingSTT	boolean	true	Use streaming STT (Deepgram only, ~1s faster)
ttsProvider	string	"openai"	"openai" or "elevenlabs"
ttsVoice	string	"nova"	Voice ID for TTS
vadSensitivity	string	"medium"	"low", "medium", or "high"
bargeIn	boolean	true	Stop speaking when user talks
allowedUsers	string[]	[]	User IDs allowed (empty = all)
silenceThresholdMs	number	1500	Silence before processing (ms)
maxRecordingMs	number	30000	Max recording length (ms)
heartbeatIntervalMs	number	30000	Connection health check interval
autoJoinChannel	string	undefined	Channel ID to auto-join on startup

Provider Configuration

OpenAI (Whisper + TTS)

{
  openai: {
    apiKey: "sk-...",
    whisperModel: "whisper-1",
    ttsModel: "tts-1",
  },
}

ElevenLabs (TTS only)

{
  elevenlabs: {
    apiKey: "...",
    voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel
    modelId: "eleven_multilingual_v2",
  },
}

Deepgram (STT only)

{
  deepgram: {
    apiKey: "...",
    model: "nova-2",
  },
}

Usage

Slash Commands (Discord)

Once registered with Discord, use these commands:

• /discord_voice join <channel> - Join a voice channel
• /discord_voice leave - Leave the current voice channel
• /discord_voice status - Show voice connection status

CLI Commands

# Join a voice channel
clawdbot discord_voice join <channelId>

# Leave voice
clawdbot discord_voice leave --guild <guildId>

# Check status
clawdbot discord_voice status

Agent Tool

The agent can use the discord_voice tool:

Join voice channel 1234567890

The tool supports actions:

• join - Join a voice channel (requires channelId)
• leave - Leave voice channel
• speak - Speak text in the voice channel
• status - Get current voice status

How It Works

1. Join: Bot joins the specified voice channel
2. Listen: VAD detects when users start/stop speaking
3. Record: Audio is buffered while user speaks
4. Transcribe: On silence, audio is sent to STT provider
5. Process: Transcribed text is sent to Clawdbot agent
6. Synthesize: Agent response is converted to audio via TTS
7. Play: Audio is played back in the voice channel

Streaming STT (Deepgram)

When using Deepgram as your STT provider, streaming mode is enabled by default. This provides:

• ~1 second faster end-to-end latency
• Real-time feedback with interim transcription results
• Automatic keep-alive to prevent connection timeouts
• Fallback to batch transcription if streaming fails

To use streaming STT:

{
  sttProvider: "deepgram",
  streamingSTT: true, // default
  deepgram: {
    apiKey: "...",
    model: "nova-2",
  },
}

Barge-in Support

When enabled (default), the bot will immediately stop speaking if a user starts talking. This creates a more natural conversational flow where you can interrupt the bot.

To disable (let the bot finish speaking):

{
  bargeIn: false,
}

Auto-reconnect

The plugin includes automatic connection health monitoring:

• Heartbeat checks every 30 seconds (configurable)
• Auto-reconnect on disconnect with exponential backoff
• Max 3 attempts before giving up

If the connection drops, you'll see logs like:

[discord-voice] Disconnected from voice channel
[discord-voice] Reconnection attempt 1/3
[discord-voice] Reconnected successfully

VAD Sensitivity

• low: Picks up quiet speech, may trigger on background noise
• medium: Balanced (recommended)
• high: Requires louder, clearer speech

Troubleshooting

"Discord client not available"

Ensure the Discord channel is configured and the bot is connected before using voice.

Opus/Sodium build errors

Install build tools:

npm install -g node-gyp
npm rebuild @discordjs/opus sodium-native

No audio heard

1. Check bot has Connect + Speak permissions
2. Check bot isn't server muted
3. Verify TTS API key is valid

Transcription not working

1. Check STT API key is valid
2. Check audio is being recorded (see debug logs)
3. Try adjusting VAD sensitivity

Enable debug logging

DEBUG=discord-voice clawdbot gateway start

Environment Variables

Variable	Description
DISCORD_TOKEN	Discord bot token (required)
SKILLBOSS_API_KEY	SkillBoss API key (Whisper/TTS via Hub)
DEEPGRAM_API_KEY	Deepgram API key (streaming STT only)

Limitations

• Only one voice channel per guild at a time
• Maximum recording length: 30 seconds (configurable)
• Requires stable network for real-time audio
• TTS output may have slight delay due to synthesis

License

MIT