Discord Voice Tool Free

基础 Discord 语音频道 AI 对话工具,支持加入/离开与本地语音识别合成。

Install

openclaw skills install @thcjp/discord-voice-tool-free

Discord 语音工具(免费版)

概述

Discord 语音工具免费版是一款面向个人用户的 Discord 语音频道 AI 实时对话工具。它让机器人加入指定语音频道,自动检测用户说话,通过本地 Whisper 模型将语音转为文字,交给 Agent 处理后,再用文字转语音(TTS)将回复读出,实现语音频道中的自然对话体验。

免费版聚焦本地离线方案:使用本地 Whisper 进行语音识别,使用本地 Kokoro 进行语音合成,不依赖任何付费云 API,适合个人零成本体验。如果你需要多服务商切换、流式实时转写、自动重连和企业级稳定性保障,请升级至 Pro 版。

核心能力

能力模块	说明	免费版支持
加入/离开频道	语音频道进出	支持
语音活动检测	自动检测说话	支持
语音转文字	STT 服务	本地 Whisper(离线)
流式转写	实时低延迟	不支持
文字转语音	TTS 服务	本地 Kokoro(离线)
打断支持	用户说话时停止播报	支持(可配置)
自动重连	断线自动恢复	不支持
多服务商	切换 STT/TTS	不支持
白名单	限制可用用户	支持
自动加入	启动时自动进频道	不支持

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。处理: 按照skill规范执行核心功能执行操作,遵循单一意图原则。输出: 返回核心功能执行的执行结果,包含操作状态和输出数据。

执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。处理: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。输出: 返回参数配置与调用的执行结果,包含操作状态和输出数据。

执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。处理: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。输出: 返回结果处理与输出的执行结果,包含操作状态和输出数据。

执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Discord、对话工具、支持加入、离开与本地语音识、别合成、面向个人用户的、实时对话工具、核心能力、VAD、自动识别用户说话、离线语音转文字、回复读出、基础打断、barge、与连接状态查询等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一:个人语音 AI 助手

在自己的语音频道中加入 AI 助手,用语音提问、语音获取回答,解放双手。

bash

# 1. 让机器人加入语音频道
discord_voice join <channelId>

# 2. 开始对话(说话即可,机器人自动检测)
# 用户: "今天天气怎么样?"
# 机器人(TTS): "我无法获取实时天气,但可以帮你查询..."

# 3. 查看连接状态
discord_voice status

# 4. 离开频道
discord_voice leave

场景二:小型语音社群互动

在小型技术社群的语音频道中,AI 助手参与讨论,实时回答成员问题。

bash

# 配置允许所有成员使用
# allowedUsers: []  # 空数组表示允许所有用户

# 加入社群语音频道
discord_voice join 1234567890

# 成员说话时机器人自动响应
# 成员: "Python 里怎么反转列表?"
# 机器人(TTS): "可以用切片 list[::-1] 或 reversed() 函数..."

场景三:离线语音处理体验

在网络受限或注重隐私的场景下,使用完全本地的语音处理,不上传任何音频到云端。

json5

{
  sttProvider: "local-whisper",  // 本地 Whisper,离线
  ttsProvider: "kokoro",          // 本地 Kokoro,离线
  // 无需任何 API Key
}

不适用场景

以下场景Discord语音工具免费版不适合处理：

需要100%确定性的关键决策
医疗诊断
法律判决

触发条件

需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于非本工具能力范围的需求。

快速开始

依赖详情

语音处理需要 ffmpeg 和构建工具:

bash

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

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

# macOS
brew install ffmpeg

第二步:安装插件

bash

# 通过平台安装
platform install discord-voice

# 或手动安装
cd ~/.agent/extensions
git clone <repository-url> discord-voice
cd discord-voice
npm install

第三步:配置

在配置文件中设置本地离线方案:

json5

{
  plugins: {
    entries: {
      "discord-voice": {
        enabled: true,
        config: {
          sttProvider: "local-whisper",
          ttsProvider: "kokoro",
          ttsVoice: "default",
          vadSensitivity: "medium",
          allowedUsers: [],
          silenceThresholdMs: 1500,
          maxRecordingMs: 30000
        }
      }
    }
  }
}

第四步:配置 Discord 机器人权限

机器人需具备以下语音权限:

Connect: 加入语音频道
Speak: 播放音频
Use Voice Activity: 检测用户说话

在 Discord Developer Portal 的 OAuth2 URL 中添加这些权限,或将机器人加入服务器时勾选。

第五步:开始使用

bash

discord_voice join <channelId>

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,查阅错误处理章节获取恢复步骤。

示例

最小可用配置

json5

{
  sttProvider: "local-whisper",
  ttsProvider: "kokoro",
  vadSensitivity: "medium",
  allowedUsers: []
}

标准配置(推荐)

json5

{
  enabled: true,
  config: {
    sttProvider: "local-whisper",
    ttsProvider: "kokoro",
    ttsVoice: "default",
    vadSensitivity: "medium",
    bargeIn: true,
    allowedUsers: [],
    silenceThresholdMs: 1500,
    maxRecordingMs: 30000,
    heartbeatIntervalMs: 30000
  }
}

配置项说明

配置项	类型	默认值	说明
`enabled`	boolean	`true`	启用/禁用插件
`sttProvider`	string	`"local-whisper"`	语音转文字服务商
`ttsProvider`	string	`"kokoro"`	文字转语音服务商
`ttsVoice`	string	`"default"`	TTS 语音 ID
`vadSensitivity`	string	`"medium"`	VAD 灵敏度(low/medium/high)
`bargeIn`	boolean	`true`	用户说话时停止播报
`allowedUsers`	string[]	`[]`	允许使用的用户 ID(空=全部)
`silenceThresholdMs`	number	`1500`	静音多久后开始处理(ms)
`maxRecordingMs`	number	`30000`	最大录音时长(ms)
`heartbeatIntervalMs`	number	`30000`	心跳检查间隔(ms)

VAD 灵敏度说明

灵敏度	行为
`low`	捕获轻声说话,可能被背景噪声误触发
`medium`	平衡(推荐)
`high`	需要更大声、更清晰的说话

最佳实践

本地模型预热: 本地 Whisper 模型首次加载较慢(几秒到几十秒)。建议在正式使用前先执行一次测试转录预热模型,后续响应会更快。
VAD 灵敏度调优: 默认 medium 适合多数场景。环境嘈杂时调高到 high 减少误触发;用户说话较轻时调低到 low 提高捕获率。配合 silenceThresholdMs(默认 1500ms)调整静音判定时长。
录音时长控制: maxRecordingMs 默认 30 秒。长篇发言会被截断。如需更长录音,适当调大此值,但注意过长的录音会增加本地处理延迟。
白名单按需配置: 公开服务器建议配置 allowedUsers 限定可用用户,避免被滥用。个人频道可留空(允许所有)。
打断体验优化: 开启 bargeIn: true 可让用户随时打断机器人播报,对话更自然。但频繁打断可能导致回复不完整,按场景取舍。
权限完整确认: 机器人必须同时具备 Connect、Speak、Use Voice Activity 三个权限,缺一不可。加入服务器前在 OAuth2 URL 中勾选完整权限。
系统资源监控: 本地 Whisper 和 Kokoro 消耗 CPU/内存。建议在至少 8GB 内存的机器上运行。资源不足时识别延迟会明显增大。

常见问题

Q1: 「Discord client not available」报错?

确保 Discord 频道已配置且机器人已连接。机器人需先成功登录 Discord 并加入目标服务器,再使用语音功能。检查 DISCORD_TOKEN 环境变量是否正确设置。

Q2: Opus/Sodium 编译报错?

这些是 Discord 语音的原生依赖,需要构建工具编译:

bash

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

确保系统已安装 build-essential(Linux)或 Xcode Command Line Tools(macOS)。

Q3: 听不到机器人说话?

按顺序检查:1)机器人是否有 Speak 权限;2)机器人是否被服务器静音(检查成员列表中机器人是否有静音图标);3)TTS 服务是否正常(查看日志是否有合成错误);4)音频设备是否正常。

Q4: 语音识别不准?

本地 Whisper 的准确度受模型大小影响。免费版使用基础模型,准确度有限。改善方法:提高说话清晰度和音量;调低背景噪声;调高 VAD 灵敏度过滤噪声段。Pro 版支持 Deepgram 流式识别,准确度和速度更优。

Q5: 免费版能用云 API(OpenAI/Deepgram)吗?

免费版默认使用本地离线方案,不配置云 API。如果你想切换到 OpenAI Whisper 或 Deepgram,需要自行在配置中填入对应 API Key,但这会增加云 API 成本,建议直接使用 Pro 版获得完整多服务商支持。

Q6: 一个机器人能同时在多个语音频道吗?

不能。Discord 限制每个机器人在每个服务器同时只能在一个语音频道。多服务器场景需部署多个机器人实例。

Q7: 如何开启调试日志?

bash

DEBUG=discord-voice agent gateway start

调试日志会输出 VAD 检测、录音、识别、合成的详细过程,便于排查问题。

Q8: 录音最长多久?

maxRecordingMs 默认 30000ms(30 秒)。超过此时长会自动截断并发送已录制部分进行识别。如需更长录音,在配置中调大此值。

依赖说明

运行环境

Agent 平台: 支持解析 SKILL.md 的任意 AI Agent(Claude Code / Cursor / Codex / Gemini CLI 等)
操作系统: Windows / macOS / Linux(推荐 Linux,原生依赖编译更顺畅)
系统依赖: ffmpeg(音频处理)、构建工具(编译 Opus/Sodium 原生模块)、Python 3(Whisper 模型运行时)
硬件: 建议 8GB 以上内存,本地模型需较多内存
网络: 仅 Discord 连接需要网络,语音处理全程本地

第三方依赖

依赖项	类型	是否必需	获取方式
LLM 能力	API	必需	由 Agent 内置大模型提供
Discord Bot Token	凭证	必需	Discord Developer Portal 创建机器人获取
ffmpeg	系统依赖	必需	系统包管理器安装
本地 Whisper 模型	模型	必需	首次运行自动下载
Kokoro TTS 模型	模型	必需	首次运行自动下载
Node.js 原生模块	库	必需	npm install 编译

API Key 配置

Discord Bot Token: 通过环境变量 DISCORD_TOKEN 配置(必需)。
本地模型: 免费 Whisper 和 Kokoro 模型首次运行自动下载,无需 API Key。
云端 API(可选): 如需使用 OpenAI/Deepgram/ElevenLabs 云服务,需额外配置对应 API Key,但免费版不推荐(建议升级 Pro 版)。

可用性分类

分类: MD+EXEC(纯 Markdown 指令 + 部分功能需 exec 执行能力)
说明: 以自然语言指令驱动 Agent 调用语音工具,本地模型处理音频
适用规模: 单服务器、个人/小团队,本地离线处理
升级建议: 如需多服务商、流式 STT、自动重连、企业级稳定性,请升级至 discord-voice-tool-pro

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

需要API Key，无Key环境无法使用
本地运行，不支持多设备同步