Qqbot Voice Transcribe

---

name: qqbot-voice-transcribe description: QQ Bot 语音消息自动识别 v2.0。自动解码 QQ Silk V3 格式，Whisper medium 模型识别，Gateway 集成，用户确认流程。 version: 2.0.0 author: 卡妹 (CyberKamei) homepage: https://github.com/openclaw/skills/qqbot-voice-transcribe tags: ["qqbot", "voice", "speech-to-text", "whisper", "silk", "audio", "gateway", "auto-recognition"] platforms: ["linux", "macos"] metadata: { "openclaw": { "emoji": "🎤", "requires": { "bins": ["ffmpeg", "python3", "git", "whisper"], "optionalBins": [] }, "optionalPaths": ["/tmp/silk-v3-decoder", "/swapfile"] } }

---

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((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 字节标记，去掉后才是标准格式。

配置选项

环境变量

# 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/

性能参考

| 语音时长 | 处理时间 | 备注 | |---------|---------|------| | 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/
│   ├── 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

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