QQ Bot 语音转文字 Skill

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

快速开始

1. 安装依赖

# 克隆 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. 使用脚本处理语音

# 单个文件处理
python3 scripts/process_qq_voice.py /path/to/voice.amr

# 输出：
# ✅ MP3: /path/to/voice.amr.mp3
# 📝 文字：好的 这次解决 QQ 语音识别的问题

3. 集成到 QQ Bot

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

} 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<void>((resolve, reject) => {
      exec(`bash ${decoderPath}/converter.sh ${fixedPath} mp3`, (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
    
    // 3. Whisper 识别文字
    const transcript = await new Promise<string>((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 字节标记，去掉后才是标准格式。

配置选项

环境变量

# Whisper 模型 (tiny/base/small/medium/large)
export WHISPER_MODEL=base

# 语言 (zh/en/ja 等)
export WHISPER_LANGUAGE=zh

# silk-v3-decoder 路径
export SILK_DECODER_PATH=/tmp/silk-v3-decoder

脚本参数

# 指定输出目录
python3 scripts/process_qq_voice.py voice.amr --output /tmp/voice

# 指定模型
python3 scripts/process_qq_voice.py voice.amr --model small

# 批量处理
python3 scripts/process_qq_voice.py --batch /path/to/voices/

性能参考

首次运行需要编译 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/
│   ├── process_qq_voice.py    # 主处理脚本
│   └── batch_process.py       # 批量处理脚本
├── examples/
│   └── gateway-integration.ts # QQ Bot 集成示例
└── README.md             # 详细文档

测试

# 运行测试
python3 scripts/process_qq_voice.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）

性能提升：

// 自动判断附件类型
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