核心更新：私聊语音消息终于能转文字了
OpenClaw 最新版本修复了一个影响用户体验的关键问题——Telegram 私聊（DM）中的语音消息现在可以正常转录为文字了。此前，只有群聊中的语音消息会被自动转录，私聊发送的语音则显示为无法读取的
本次修复由社区贡献者 @manueltarouca 提交，已合并至主分支（commit bf0f4d9）。如果你依赖 Telegram 渠道处理语音消息，建议立即更新。
—
问题背景：为什么私聊语音会”失灵”
历史遗留的回归缺陷
这个 bug 的根源是一次代码重构。当 OpenClaw 将 Telegram 渠道从 src/telegram/ 迁移到 extensions/telegram/ 时，早期修复（commit c15385f）意外丢失，导致转录逻辑出现条件判断过窄的问题。
原始代码的问题
// 修复前的条件判断（有缺陷）
if (isGroup && requireMention && hasAudio && !hasText) {
// 执行语音转录
transcribeVoiceNote();
}
问题分析：
isGroup && requireMention的组合强制要求群聊场景- 私聊（DM）不满足
isGroup条件，语音消息被直接跳过 - 结果：用户收到的是原始
—
技术修复：更智能的条件判断
新方案的核心逻辑
修复后的代码采用分层守卫模式，将”是否转录”与”群聊特定规则”解耦：
// 修复后的条件判断
if (hasAudio && !hasText) {
// 基础条件：有音频且无文字（所有聊天类型通用）
if (isGroup) {
// 群聊场景：应用额外限制
if (!requireMention) return;
if (disableAudioPreflight) return;
if (!senderAllowedForAudioPreflight(sender)) return;
}
// 执行语音转录（DM 直接通过，群聊需满足额外条件）
transcribeVoiceNote();
}
关键改进点
| 维度 | 修复前 | 修复后 |
|:—|:—|:—|
| 适用范围 | 仅限群聊 | 群聊 + 私聊 |
| 基础触发条件 | isGroup && requireMention && hasAudio && !hasText | hasAudio && !hasText |
| 群聊额外限制 | 硬编码在主干逻辑 | 独立为可选守卫层 |
| DM 行为 | 直接跳过，返回占位符 | 正常转录 |
—
配置与使用指南
1. 更新到最新版本
通过 npm 更新
npm update @openclaw/telegram
或通过 Docker 拉取最新镜像
docker pull openclaw/openclaw:latest
2. 验证语音转录功能
更新后，可通过以下方式测试：
方法1：直接发送语音消息到 Bot 私聊
预期结果：收到文字转录 + 原始音频
方法2：检查日志输出
DEBUG=openclaw:telegram npm start
查找包含 "preflight transcription" 的日志行
3. 环境变量配置（可选）
| 变量名 | 说明 | 默认值 |
|:—|:—|:—|
| TELEGRAM_ENABLE_TRANSCRIPTION | 全局开关语音转录 | true |
| TELEGRAM_REQUIRE_MENTION | 群聊中是否需要 @Bot | true |
| TELEGRAM_DISABLE_AUDIO_PREFLIGHT | 禁用音频预处理（调试用） | false |
.env 配置示例
TELEGRAM_ENABLE_TRANSCRIPTION=true
TELEGRAM_REQUIRE_MENTION=true # 仅影响群聊，DM 不受此限制
—
最佳实践建议
私聊场景的使用建议
私聊语音转录默认启用，适合以下场景：
- 个人助理模式：用户直接与 AI Agent 一对一对话
- 敏感信息处理：私聊环境更适合处理含隐私的语音内容
- 低延迟需求：私聊无需 @提及，响应更快
群聊场景的权限控制
如需在群聊中限制语音转录，保留以下守卫机制：
// openclaw.config.js
module.exports = {
telegram: {
requireMention: true, // 必须 @Bot 才响应
disableAudioPreflight: false, // 保持音频预处理启用
senderAllowedForAudioPreflight: (sender) => {
// 自定义发送者白名单逻辑
return !sender.isRestricted;
}
}
};
—
常见问题解答 (FAQ)
Q1: 更新后私聊语音仍显示为
检查三点：① 是否更新到包含 bf0f4d9 的版本；② TELEGRAM_ENABLE_TRANSCRIPTION 是否为 true；③ 语音消息时长是否超过转录服务限制（通常 60 秒）。
Q2: 群聊中的语音转录行为会改变吗？
不会。群聊仍遵循原有规则：需要 @提及 Bot（若 requireMention: true），且受 disableAudioPreflight 和发送者权限控制。修复仅扩展了私聊的支持。
Q3: 语音转录使用哪个 AI 服务？
OpenClaw 默认集成 Whisper API 进行语音转文字，也可通过配置切换到其他 STT（Speech-to-Text）提供商。详见 OpenClaw 文档 – 语音配置。
Q4: 转录后的文字会替换原始音频吗？
不会。转录文本作为附加内容返回，原始音频链接仍保留在消息中。用户可同时获得文字摘要和完整音频。
Q5: 这个修复会影响其他消息渠道（如 Discord、Slack）吗？
不会。本次修改仅针对 Telegram 渠道的 extensions/telegram/ 模块，其他渠道的语音处理逻辑独立维护。
—
总结与下一步
本次修复解决了 OpenClaw Telegram 渠道长期存在的体验断层，让私聊场景下的语音交互终于达到与群聊同等的功能完整性。关键要点：
1. 立即更新到最新版本以获取修复
2. 私聊语音现在默认启用转录，无需额外配置
3. 群聊权限控制保持不变，可独立调整
下一步行动
- 📖 阅读 OpenClaw Telegram 集成指南 了解完整配置选项
- 🔧 查看 GitHub Release Note 获取版本更新详情
- 💬 加入 OpenClaw Discord 社区 反馈使用体验
—
相关阅读
—
参考来源
- GitHub Commit bf0f4d9 — 本次修复的完整代码变更
- GitHub Commit c15385f — 早期相关修复（迁移时丢失）
- OpenClaw 官方文档
- Telegram Bot API 文档 — 语音消息格式说明
- OpenAI Whisper API 文档 — 语音转录服务
