功能说明: 本技能涵盖 中文交互、化工作流场景 等核心能力。

Discord 语音工具(免费版)

概述

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

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

核心能力

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

核心功能执行

用input_params参数进行配置。

输出: 返回核心功能执行的执行结果,包含操作状态和输出数据。

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

参数配置与调用

用config_options参数进行配置。

输出: 返回参数配置与调用的执行结果,包含操作状态和输出数据。

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

结果处理与输出

用output_format参数进行配置。

输出: 返回结果处理与输出的执行结果,包含操作状态和输出数据。

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

使用场景

场景一:个人语音 AI 助手

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

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

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

# 3. 查看连接状态
discord_voice status

# 4. 离开频道
discord_voice leave

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

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

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

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

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

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

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

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

不适用场景

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

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

触发条件

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

快速开始

依赖详情

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

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

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

# macOS
brew install ffmpeg

第二步:安装插件

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

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

第三步:配置

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

{
  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 中添加这些权限,或将机器人加入服务器时勾选。

第五步:开始使用

discord_voice join <channelId>

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

示例

最小可用配置

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

标准配置(推荐)

{
  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	需要更大声、更清晰的说话

优选实践

1. 本地模型预热: 本地 Whisper 模型首次加载较慢(几秒到几十秒)。建议在正式使用前先执行一次测试转录预热模型,后续响应会更快。

2. VAD 灵敏度调优: 默认 medium 适合多数场景。环境嘈杂时调高到 high 减少误触发;用户说话较轻时调低到 low 提高捕获率。配合 silenceThresholdMs(默认 1500ms)调整静音判定时长。

3. 录音时长控制: maxRecordingMs 默认 30 秒。长篇发言会被截断。如需更长录音,适当调大此值,但注意过长的录音会增加本地处理延迟。

4. 白名单按需配置: 公开服务器建议配置 allowedUsers 限定可用用户,避免被滥用。个人频道可留空(允许所有)。

5. 打断体验优化: 开启 bargeIn: true 可让用户随时打断机器人播报,对话更自然。但频繁打断可能导致回复不完整,按场景取舍。

6. 权限完整确认: 机器人必须同时具备 Connect、Speak、Use Voice Activity 三个权限,缺一不可。加入服务器前在 OAuth2 URL 中勾选完整权限。

7. 系统资源监控: 本地 Whisper 和 Kokoro 消耗 CPU/内存。建议在至少 8GB 内存的机器上运行。资源不足时识别延迟会明显增大。

常见问题

Q1: 「Discord client not available」报错?

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

Q2: Opus/Sodium 编译报错?

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

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: 如何开启调试日志?

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

错误处理

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

已知限制

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

安全注意事项

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
网络通信安全	使用HTTPS协议，验证SSL证书有效性
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

效率量化分析

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

差异化对比

对比维度	本技能	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	核心功能	通用场景	通用场景