Clawdbot 的 Discord 语音插件

在 Discord 语音频道中实现实时语音对话。加入语音频道，开口说话，你的语音将被实时转录、交由 Claude 处理，并以语音形式反馈给你。

功能特性

• 加入/退出语音频道：支持通过 Slash 命令、CLI 或 agent 工具操作
• 语音活动检测（VAD）：自动识别用户是否正在讲话
• 语音转文字（STT）：支持 Whisper API（OpenAI）、Deepgram 或本地 Whisper（离线）
• 流式 STT：基于 Deepgram WebSocket 的实时转录（端到端延迟降低约 1 秒）
• Agent 集成：转录后的文本将路由至 Clawdbot agent 进行处理
• 文字转语音（TTS）：支持 OpenAI TTS、ElevenLabs 或 Kokoro（本地/离线）
• 音频播放：响应内容将以语音形式在语音频道中播放
• 抢占式中断（Barge-in）支持：当用户开始说话时，立即停止当前语音输出
• 自动重连：内置心跳监测机制，断连后自动重连

系统要求

• 具备语音权限的 Discord bot（Connect、Speak、Use Voice Activity）
• STT 和 TTS 服务商的 API 密钥
• 语音功能所需系统依赖：
  • ffmpeg（音频处理）
  • @discordjs/opus 和 sodium-native 的原生构建工具

安装步骤

1. 安装系统依赖

# 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. 通过 ClawdHub 安装

clawdhub install discord-voice

或手动安装：

cd ~/.clawdbot/extensions
git clone  discord-voice
cd discord-voice
npm install

3. 在 clawdbot.json 中配置

{
  plugins: {
    entries: {
      "discord-voice": {
        enabled: true,
        config: {
          sttProvider: "local-whisper",
          ttsProvider: "openai",
          ttsVoice: "nova",
          vadSensitivity: "medium",
          allowedUsers: [], // 空数组 = 允许所有用户
          silenceThresholdMs: 1500,
          maxRecordingMs: 30000,
          openai: {
            apiKey: "sk-...", // 或使用 OPENAI_API_KEY 环境变量
          },
        },
      },
    },
  },
}

4. Discord Bot 权限配置

请确保你的 Discord bot 具备以下权限：

• Connect — 加入语音频道
• Speak — 播放音频
• Use Voice Activity — 检测用户语音活动

请将上述权限添加至 bot 的 OAuth2 URL，或在 Discord Developer Portal 中完成配置。

配置项说明

服务商配置

OpenAI（Whisper + TTS）

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

ElevenLabs（仅 TTS）

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

Deepgram（仅 STT）

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

使用方式

Slash 命令（Discord）

在 Discord 中完成注册后，可使用以下命令：

• /discord_voice join — 加入指定语音频道
• /discord_voice leave — 退出当前语音频道
• /discord_voice status — 查看语音连接状态

CLI 命令

# 加入语音频道
clawdbot discord_voice join 

# 退出语音频道
clawdbot discord_voice leave --guild 

# 查看状态
clawdbot discord_voice status

Agent 工具

agent 可调用 discord_voice 工具：

Join voice channel 1234567890

该工具支持以下动作：

• join — 加入语音频道（需提供 channelId）
• leave — 退出语音频道
• speak — 在语音频道中播报指定文本
• status — 获取当前语音状态

工作原理

1. 加入：bot 加入指定语音频道
2. 监听：VAD 检测用户何时开始/停止讲话
3. 录音：在用户讲话期间持续缓存音频数据
4. 转录：检测到静音后，将音频发送至 STT 服务商
5. 处理：将转录所得文本传入 Clawdbot agent
6. 合成：agent 的响应结果经 TTS 转为音频
7. 播放：将生成的音频在语音频道中播放

流式 STT（Deepgram）

当选用 Deepgram 作为 STT 服务商时，流式模式默认启用。该模式提供以下优势：

• 端到端延迟降低约 1 秒
• 实时反馈：返回中间转录结果
• 自动保活：防止连接超时
• 故障回退：流式失败时自动降级为批量转录

启用流式 STT 的配置示例：

{
  sttProvider: "deepgram",
  streamingSTT: true, // 默认启用
  deepgram: {
    apiKey: "...",
    model: "nova-2",
  },
}

抢占式中断（Barge-in）支持

启用后（默认开启），当用户开始讲话时 bot 将立即停止当前语音输出，从而营造更自然的对话体验，支持随时打断 bot。

如需禁用该行为（等待 bot 完整播报完毕），请设置：

{
  bargeIn: false,
}

自动重连

插件内置连接健康监测机制：

• 心跳检测：每 30 秒执行一次（可配置）
• 自动重连：断连后按指数退避策略重试
• 最大重试次数：最多尝试 3 次，之后放弃

若连接中断，日志中将显示类似如下信息：

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

VAD 灵敏度

• low：可捕捉较轻声的语音，但可能受背景噪音干扰而误触发
• medium：平衡灵敏度（推荐）
• high：需更高音量和更清晰的发音才能触发

常见问题排查

“Discord client not available”

请确认已正确配置 Discord 频道，且 bot 已成功连接后再使用语音功能。

Opus/Sodium 构建错误

请安装构建工具：

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

听不到音频输出

1. 检查 bot 是否拥有 Connect 和 Speak 权限
2. 检查 bot 是否被服务器静音
3. 确认 TTS API 密钥有效

语音转文字未生效

1. 检查 STT API 密钥是否有效
2. 确认音频正在正常录制（参阅调试日志）
3. 尝试调整 VAD 灵敏度

启用调试日志

DEBUG=discord-voice clawdbot gateway start

环境变量

限制条件

• 每个 Guild 同时仅支持一个语音频道
• 单次录音最大时长：30 秒（可配置）
• 实时音频传输依赖稳定网络连接
• TTS 输出可能存在轻微延迟（由语音合成耗时导致）

许可证

MIT