QQ Bot 语音转文字技能

自动识别 QQ Bot 收到的语音消息，将 Silk V3 编码的 .amr 文件转换为文字。

快速开始

1. 安装依赖

bash

克隆 silk-v3-decoder

git clone --depth 1 https://github.com/kn007/silk-v3-decoder.git /tmp/silk-v3-decoder

安装 Whisper（语音识别）

pip3 install openai-whisper

安装 ffmpeg（音频处理）

apt install ffmpeg # Ubuntu/Debian

或

yum install ffmpeg # CentOS/RHEL

2. 使用脚本处理语音

bash

单个文件处理

python3 scripts/processqqvoice.py /path/to/voice.amr

输出：

✅ MP3: /path/to/voice.amr.mp3

📝 文字：好的 这次解决 QQ 语音识别的问题

3. 集成到 QQ Bot

修改 gateway.ts，在附件处理逻辑中添加：

typescript
} else if (localPath.endsWith(.amr)) {
const { exec } = await import(node:child_process);

try {
// 1. 去掉第一个字节 (0x02)
const data = fs.readFileSync(localPath);
const fixedPath = localPath + .fixed;
fs.writeFileSync(fixedPath, data.slice(1));

// 2. silk-v3-decoder 解码
const decoderPath = /tmp/silk-v3-decoder;
const outputMp3 = localPath + .mp3;

await new Promise((resolve, reject) => {
exec(bash ${decoderPath}/converter.sh ${fixedPath} mp3, (err) => {
if (err) reject(err);
else resolve();
});
});

// 3. Whisper 识别文字
const transcript = await new Promise((resolve, reject) => {
exec(whisper --model base --language zh ${outputMp3} --output_dir /tmp, (err) => {
if (err) reject(err);
else {
const txtPath = outputMp3 + .txt;
fs.readFile(txtPath, utf-8, (err, data) => {
if (err) reject(err);
else resolve(data.trim());
});
}
});
});

// 4. 添加到消息内容
if (transcript) {
audioTranscripts.push(\n🎤 语音消息：${transcript}\n);
}

// 5. 清理
fs.unlinkSync(fixedPath);

} catch (err: any) {
log?.error([qqbot] 语音处理失败：${err.message});
}
}

工作原理

QQ 语音文件 (.amr)
↓
去掉 0x02 字节头
↓
silk-v3-decoder 解码 → MP3
↓
Whisper 识别 → 文字
↓
添加到 QQ Bot 消息

为什么需要去掉 0x02 字节？

QQ 语音文件结构：

┌────────┬─────────────┬──────────┬──────────┐
│ 0x02 │ #!SILK_V3 │ 参数 (3B) │ 音频数据 │
│ 1 字节 │ 9 字节 │ 3 字节 │ 变长 │
└────────┴─────────────┴──────────┴──────────┘

QQ 在标准 Silk V3 格式前添加了 0x02 字节标记，去掉后才是标准格式。

配置选项

环境变量

bash

Whisper 模型 (tiny/base/small/medium/large)

export WHISPER_MODEL=base

语言 (zh/en/ja 等)

export WHISPER_LANGUAGE=zh

silk-v3-decoder 路径

export SILKDECODERPATH=/tmp/silk-v3-decoder

脚本参数

bash

指定输出目录

python3 scripts/processqqvoice.py voice.amr --output /tmp/voice

指定模型

python3 scripts/processqqvoice.py voice.amr --model small

批量处理

python3 scripts/processqqvoice.py --batch /path/to/voices/

性能参考

语音时长	处理时间	备注
10 秒	10-15 秒	base 模型
30 秒

20-30 秒 | base 模型 | | 60 秒 | 40-60 秒 | base 模型 |

首次运行需要编译 silk-v3-decoder，额外 +30 秒。

常见问题

Q: 报错 Not a valid silk_data

A: 文件头未正确处理，确保去掉了第一个字节（0x02）

Q: 报错 ffmpeg not found

A: 安装 ffmpeg：apt install ffmpeg

Q: 识别速度慢

A: 使用更小的 Whisper 模型：--model tiny

Q: 识别不准确

A: 使用更大的 Whisper 模型：--model small 或 medium

文件结构

qqbot-voice-transcribe/
├── SKILL.md # 本文件
├── scripts/
│ ├── processqqvoice.py # 主处理脚本
│ └── batch_process.py # 批量处理脚本
├── examples/
│ └── gateway-integration.ts # QQ Bot 集成示例
└── README.md # 详细文档

测试

bash

运行测试

python3 scripts/processqqvoice.py --test

测试文件头

xxd voice.amr | head -1

应该看到：02 23 21 53 49 4c 4b 5f 56 33 (.#!SILK_V3...)

相关资源

• - silk-v3-decoder - Silk V3 解码器
• Whisper - OpenAI 语音识别
• OpenClaw QQ Bot - QQ Bot 插件

更新日志

v2.0.0 (2026-03-01) - Gateway 自动识别集成 🎉

新增功能：

• - ✅ Gateway 自动识别 - 集成到 gateway.ts，自动判断并识别语音消息
• ✅ 用户确认流程 - 识别后显示结果，请用户确认再执行
• ✅ txt 路径修复 - 检查多个可能的路径，解决识别结果为空问题
• ✅ medium 模型支持 - 默认使用 medium 模型，准确率 ~95%+
• ✅ 系统优化 - 添加 swap 配置，防止 OOM 崩溃

修复问题：

• - ✅ OOM 崩溃（添加 4GB swap）
• ✅ 识别结果为空（txt 路径修复）
• ✅ 提示语错误（纯语音消息处理）
• ✅ 硬盘空间不足（清理 7GB）

性能提升：
typescript
// 自动判断附件类型
const ext = path.extname(localPath).toLowerCase();
const mimeType = att.content_type?.toLowerCase() || ;

if (ext === .amr || mimeType.includes(amr)) {
// 自动识别流程
}

识别效果：

🎤 语音消息识别结果：今天天气如何

请确认是否正确，我将按此执行

v1.0.0 (2026-02-28)

• - ✅ 初始版本
• ✅ 支持 QQ Silk V3 格式解码
• ✅ Whisper 中文识别
• ✅ QQ Bot 集成示例
• ✅ 批量处理支持

---

作者： 卡妹 (CyberKamei) 🌸 许可： MIT 问题反馈： https://github.com/openclaw/skills/issues 社区讨论： https://moltbook.forum