5.1 系统架构总览5.1.1 整体架构OpenClaw 语音命令识别系统是一个基于事件驱动的实时语音处理平台核心设计目标是实现低延迟、高可靠的语音交互能力。系统采用模块化架构各组件通过明确定义的接口进行通信支持多种电话服务提供商Twilio、Telnyx、Plivo和语音识别引擎OpenAI Whisper、GPT-4o-transcribe。┌─────────────────────────────────────────────────────────────────────────┐ │ OpenClaw 语音命令识别系统 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 音频捕获模块 │───▶│ 预处理模块 │───▶│ 语音识别引擎 │ │ │ │ (Capture) │ │ (Preprocess) │ │ (STT) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 媒体流处理 │ │ VAD/降噪 │ │ 命令解析器 │ │ │ │ (Stream) │ │ (VAD/Noise) │ │ (Parser) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 反馈模块 │◀───│ 执行引擎 │◀───│ 意图识别 │ │ │ │ (Feedback) │ │ (Executor) │ │ (Intent) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘5.1.2 核心模块列表模块源文件职责CallManagermanager.ts呼叫状态管理、事件分发、定时器管理MediaStreamHandlermedia-stream.tsWebSocket 媒体流处理、双向音频传输VoiceCallWebhookServerwebhook.tsHTTP webhook 服务器、请求路由OpenAIRealtimeSTTProviderproviders/stt-openai-realtime.ts实时语音识别ResponseGeneratorresponse-generator.tsAI 响应生成TelephonyAudiotelephony-audio.ts音频格式转换PCM ↔︎ μ-law5.1.3 数据流向入站呼叫: 电话服务提供商 → Webhook → CallManager → 媒体流建立音频处理: 麦克风/电话线路 → μ-law 编码 → WebSocket → STT 引擎 → 文本命令执行: 文本 → 意图识别 → 命令解析 → 执行引擎 → 结果反馈出站响应: AI 响应 → TTS 引擎 → 音频流 → 电话线路 → 用户5.1.4 设计原则事件驱动: 所有状态变更通过事件系统传播流式处理: 音频数据实时流式传输避免批量处理延迟容错设计: 支持呼叫状态持久化、断线恢复安全优先: Webhook 签名验证、重放保护、连接数限制5.2 音频捕获模块5.2.1 音频输入源OpenClaw 语音系统支持多种音频输入源电话线路输入主要场景: - Twilio Programmable Voice Media Streams - Telnyx Call Control v2 - Plivo Voice API本地麦克风输入扩展场景: - 通过 WebRTC 或本地音频设备捕获 - 需要额外的音频捕获插件支持5.2.2 音频格式规范电话线路音频采用标准的电信级编码格式// 源文件telephony-audio.ts const TELEPHONY_SAMPLE_RATE 8000; // 8kHz 采样率电话标准 // 音频格式参数 - 采样率8000 Hz - 位深8-bit μ-law (G.711) - 声道单声道 (Mono) - 帧大小160 样本/帧 (20ms 8kHz)音频转换流程:// 源文件telephony-audio.ts /** * 将 16-bit PCM 重采样到 8kHz */ export function resamplePcmTo8k(input: Buffer, inputSampleRate: number): Buffer { if (inputSampleRate TELEPHONY_SAMPLE_RATE) { return input; } // 使用线性插值进行重采样 const ratio inputSampleRate / TELEPHONY_SAMPLE_RATE; const outputSamples Math.floor(inputSamples / ratio); // ... 重采样逻辑 } /** * 将 16-bit PCM 转换为 8-bit μ-law (G.711) */ export function pcmToMulaw(pcm: Buffer): Buffer { const samples Math.floor(pcm.length / 2); const mulaw Buffer.alloc(samples); for (let i 0; i samples; i) { const sample pcm.readInt16LE(i * 2); mulaw[i] linearToMulaw(sample); } return mulaw; }5.2.3 缓冲区管理媒体流 handler 采用分块缓冲区策略音频帧结构示意:┌────────────────────────────────────────────────────────────┐ │ 音频帧结构 (20ms/帧) │ ├────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┬─────────────┬─────────────┬──────────┐ │ │ │ 帧头 (2B) │ 样本 1-40 │ 样本 41-80 │ ... │ │ │ │ 0x78 0x01 │ (80 字节) │ (80 字节) │ │ │ │ └─────────────┴─────────────┴─────────────┴──────────┘ │ │ ← 160 字节 (1 帧) → │ │ │ │ 帧头包含序列号、时间戳等元数据 │ │ 样本8-bit μ-law 编码的音频数据 │ │ │ │ 连续帧流 │ │ [帧 1] → [帧 2] → [帧 3] → ... → [帧 N] │ │ 20ms 40ms 60ms 20N ms │ │ │ └────────────────────────────────────────────────────────────┘// 源文件media-stream.ts /** * 将音频缓冲区切分为 20ms 帧 * param audio 音频缓冲区 * param chunkSize 每帧大小 (默认 160 字节 20ms 8kHz) */ export function chunkAudio(audio: Buffer, chunkSize 160): GeneratorBuffer { return (function* () { for (let i 0; i audio.length; i chunkSize) { yield audio.subarray(i, Math.min(i chunkSize, audio.length)); } })(); }缓冲区策略: - 每帧 20ms 音频数据160 字节 μ-law - 实时流式发送不等待完整句子 - 支持部分转录streaming transcripts5.2.4 多路音频处理系统支持并发多路呼叫处理// 源文件media-stream.ts interface StreamSession { callId: string; streamSid: string; ws: WebSocket; sttSession: RealtimeSTTSession; } // 会话管理 private sessions new Mapstring, StreamSession(); // 连接数限制 private maxConnections 128; // 最大并发连接数 private maxPendingConnectionsPerIp 4; // 每 IP 最大待验证连接5.3 预处理模块5.3.1 降噪处理OpenClaw 语音系统采用多级降噪策略硬件级降噪依赖服务提供商: - Twilio/Telnyx/Plivo 在电信网络层面进行基础降噪 - 移除线路噪声、电磁干扰软件级降噪扩展能力: - 可通过集成 RNNoise、WebRTC APM 等算法增强 - 当前版本主要依赖 STT 引擎的内置降噪能力5.3.2 VAD语音活动检测VAD 是语音处理的关键环节用于区分语音和静音/噪声// 源文件config.ts export const StreamingConfigSchema z.object({ // ... 其他配置 /** VAD 静音检测时长 (ms) - 超过此时长判定为语音结束 */ silenceDurationMs: z.number().int().positive().default(1500), /** VAD 阈值 (0-1) - 高于此值判定为语音 */ vadThreshold: z.number().min(0).max(1).default(0.5), // ... 其他配置 });VAD 工作原理:┌────────────────────────────────────────────────────────────┐ │ VAD 检测流程 │ ├────────────────────────────────────────────────────────────┤ │ │ │ 音频帧 → 特征提取 → 能量分析 → 过零率 → 分类决策 │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ MFCC 特征 信号强度 频率特征 语音/静音 │ │ │ │ 判定规则 │ │ - 信号强度 vadThreshold → 语音 │ │ - 静音持续 silenceDurationMs → 语音结束 │ │ │ └────────────────────────────────────────────────────────────┘配置参数详解:参数默认值说明调整建议vadThreshold0.5VAD 判定阈值噪声环境调高 (0.6-0.7)silenceDurationMs1500静音判定时长快速对话调低 (800-1000)5.3.3 静音检测静音检测与 VAD 协同工作用于判定语音段落的边界// 源文件providers/stt-openai-realtime.ts (推断) /** * 静音超时处理 * 当检测到连续静音超过 silenceDurationMs 时 * 1. 触发语音结束事件 * 2. 提交当前音频缓冲区进行识别 * 3. 重置缓冲区 */静音检测状态机:┌─────────────┐ │ 等待语音 │ └──────┬──────┘ │ 检测到语音 ▼ ┌─────────────┐ │ 语音进行中 │◀────┐ └──────┬──────┘ │ 继续语音 │ 检测到静音 │ ▼ │ ┌─────────────┐ │ │ 静音计时器 │────┘ └──────┬──────┘ │ 超时 (silenceDurationMs) ▼ ┌─────────────┐ │ 语音结束 │ └─────────────┘5.3.4 音频标准化为确保识别质量音频需进行标准化处理增益控制: - 自动增益控制 (AGC) 调整音量到标准范围 - 防止过小信号被噪声淹没过大信号失真格式统一: - 所有输入统一转换为 8kHz μ-law - 便于后续模块处理5.4 语音识别引擎5.4.1 Whisper-1 集成OpenAI Whisper-1 是 OpenClaw 支持的 STT 引擎之一// 源文件config.ts export const SttConfigSchema z .object({ /** STT 提供商 (当前仅支持 OpenAI) */ provider: z.literal(openai).default(openai), /** Whisper 模型 */ model: z.string().min(1).default(whisper-1), }) .default({ provider: openai, model: whisper-1 });Whisper-1 特性: - 支持多语言识别 - 对噪声有一定鲁棒性 - 适合批量转录场景5.4.2 OpenAI GPT-4o-transcribe针对实时通话场景系统支持更先进的 GPT-4o-transcribe 模型// 源文件config.ts export const StreamingConfigSchema z.object({ // ... 其他配置 /** OpenAI 转录模型 (默认gpt-4o-transcribe) */ sttModel: z.string().min(1).default(gpt-4o-transcribe), // ... 其他配置 });GPT-4o-transcribe 优势: - 实时流式识别 - 更低的延迟~200-500ms - 更好的上下文理解 - 支持说话人区分待验证5.4.3 实时流式识别实时识别通过 OpenAI Realtime API 实现// 源文件media-stream.ts interface MediaStreamConfig { /** STT 提供商 */ sttProvider: OpenAIRealtimeSTTProvider; /** 连接建立后超时时间 (ms) - 防止僵尸连接 */ preStartTimeoutMs?: number; // 默认 5000 /** 最大待验证连接数 */ maxPendingConnections?: number; // 默认 32 /** 每 IP 最大待验证连接数 */ maxPendingConnectionsPerIp?: number; // 默认 4 /** 最大总连接数 */ maxConnections?: number; // 默认 128 }流式识别流程:1. WebSocket 连接建立 (Twilio Media Stream) 2. 发送 start 帧包含 callId、streamSid 等元数据 3. 验证连接合法性callId 匹配、token 验证 4. 创建 RealtimeSTTSession 5. 接收音频帧 → 转发给 OpenAI Realtime API 6. 接收部分转录 → 触发 onPartialTranscript 回调 7. 接收完整转录 → 触发 onTranscript 回调 8. 通话结束 → 关闭会话5.4.4 识别结果格式转录结果通过回调函数传递// 源文件media-stream.ts interface MediaStreamConfig { /** 收到完整转录时的回调 */ onTranscript?: (callId: string, transcript: string) void; /** 收到部分转录时的回调用于流式 UI */ onPartialTranscript?: (callId: string, partial: string) void; /** 流连接建立回调 */ onConnect?: (callId: string, streamSid: string) void; /** 语音开始回调用于打断检测 */ onSpeechStart?: (callId: string) void; /** 流断开回调 */ onDisconnect?: (callId: string) void; }5.5 命令解析模块5.5.1 命令语法定义OpenClaw 语音命令采用自然语言 结构化参数混合模式命令格式:[意图动词] [目标对象] [参数...]示例:打开客厅的灯 → 意图打开 → 目标灯 → 位置客厅 设置明天早上 7 点的闹钟 → 意图设置 → 目标闹钟 → 时间明天早上 7 点 给张三发送消息说下午开会 → 意图发送 → 目标消息 → 收件人张三 → 内容下午开会5.5.2 意图识别意图识别将自然语言映射到系统动作// 推断结构基于 manager.ts 事件处理 interface ParsedCommand { intent: string; // 意图open, close, set, send, query... target: string; // 目标light, alarm, message, calendar... params: Recordstring, any; // 参数 confidence: number; // 置信度 }意图分类体系:意图类别示例命令处理模块设备控制“打开空调”、“调高温度”智能家居集成日程管理“设置提醒”、“明天有什么安排”日历服务消息通信“给李四发消息”、“读一下未读消息”消息服务信息查询“今天天气怎么样”、“现在几点了”信息服务系统控制“重启系统”、“查看日志”系统管理5.5.3 参数提取参数提取使用槽位填充Slot Filling技术槽位类型: - 时间槽明天、下午 3 点、下周一 - 地点槽客厅、办公室、北京 - 人物槽张三、李四 - 数值槽25 度、10 分钟 - 内容槽消息内容、备注信息填充策略: 1. 显式提取直接从文本中抽取参数 2. 默认值使用用户偏好或系统默认 3. 追问补全参数缺失时主动询问5.5.4 命令验证命令执行前进行多重验证权限验证: - 用户身份确认来电号码白名单 - 操作权限检查某些命令需要管理员权限参数验证: - 必填参数检查 - 参数格式验证时间、数值等 - 参数范围检查温度 16-30°C状态验证: - 目标设备在线状态 - 系统负载情况 - 冲突检测避免重复执行5.6 执行引擎5.6.1 命令分发机制执行引擎采用责任链模式进行命令分发// 推断结构基于 manager.ts interface CommandExecutor { canHandle(command: ParsedCommand): boolean; execute(command: ParsedCommand): PromiseExecutionResult; } // 执行器注册表 const executors: CommandExecutor[] [ LightExecutor, // 灯光控制 ClimateExecutor, // 温控设备 AlarmExecutor, // 闹钟提醒 MessageExecutor, // 消息发送 // ... 更多执行器 ];分发流程: 1. 遍历执行器列表 2. 调用canHandle()判断是否匹配 3. 首个匹配的执行器处理命令 4. 返回执行结果5.6.2 权限检查权限检查在命令执行前进行// 源文件config.ts (推断) export const InboundPolicySchema z.enum([ disabled, // 禁止所有入站呼叫 allowlist, // 仅允许白名单号码 pairing, // 未知号码可申请配对 open // 开放所有入站危险 ]);权限级别: -公开命令: 天气查询、时间查询无需验证 -用户命令: 个人日程、消息发送需身份验证 -管理命令: 系统配置、设备重启需管理员权限5.6.3 执行队列为防止命令冲突和资源争用系统采用队列机制┌────────────────────────────────────────────────────────────┐ │ 命令执行队列 │ ├────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ 命令 1 │→ │ 命令 2 │→ │ 命令 3 │→ │ 命令 4 │ │ │ │ 执行中 │ │ 等待中 │ │ 等待中 │ │ 等待中 │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ 队列特性 │ │ - FIFO 顺序执行 │ │ - 支持优先级紧急命令插队 │ │ - 超时自动跳过 │ │ │ └────────────────────────────────────────────────────────────┘5.6.4 超时处理命令执行设置超时保护// 源文件config.ts (推断) export const StreamingConfigSchema z.object({ // ... 其他配置 /** 预启动超时 (ms) - 连接建立后等待 start 帧的时长 */ preStartTimeoutMs: z.number().int().positive().default(5000), // ... 其他配置 });超时策略: - 默认超时30 秒 - 长任务超时120 秒如文件下载 - 超时处理终止执行、记录日志、返回错误5.7 反馈模块5.7.1 TTS 语音反馈系统使用 TTSText-to-Speech将执行结果转换为语音// 源文件config.ts // TTS 配置与核心配置合并 export const TtsConfigSchema z.object({ provider: z.enum([openai, elevenlabs]).default(openai), // ... 其他配置 }); // 电话通话使用核心 messages.tts 配置 // 可在插件配置中覆盖TTS 提供商: -OpenAI TTS: 支持多种音色alloy、echo、fable 等 -ElevenLabs: 高质量语音支持情感表达注意: Edge TTS 不适用于电话呼叫电信音频需要 PCMEdge 输出不可靠5.7.2 状态通知执行状态通过多种方式通知用户语音通知: - 执行成功“已为您打开客厅的灯” - 执行失败“抱歉无法连接到客厅的灯” - 需要确认“确认要关闭所有设备吗”推送通知扩展能力: - 执行结果推送到手机 App - 重要操作发送确认消息5.7.3 错误报告错误处理采用分级报告机制错误级别示例用户反馈系统处理提示级设备暂时离线语音告知建议重试记录日志警告级参数格式错误语音引导正确格式记录日志 指标错误级权限不足语音拒绝说明原因记录日志 告警严重级系统故障语音道歉建议联系支持记录日志 告警 通知管理员5.7.4 多模态反馈系统支持多种反馈方式组合┌────────────────────────────────────────────────────────────┐ │ 多模态反馈矩阵 │ ├────────────────────────────────────────────────────────────┤ │ │ │ 场景 语音 推送 灯光 屏幕 │ │ ───────────────────────────────────────────────────── │ │ 通话中 ✓ - - - │ │ 在家模式 ✓ - ✓ ✓ │ │ 办公模式 - ✓ - - │ │ 勿扰模式 - ✓ - - │ │ │ │ ✓ 启用 - 禁用 │ │ │ └────────────────────────────────────────────────────────────┘5.8 性能瓶颈分析5.8.1 延迟来源分析语音命令识别系统的延迟主要来自以下环节┌────────────────────────────────────────────────────────────┐ │ 延迟分解 (典型值) │ ├────────────────────────────────────────────────────────────┤ │ │ │ 环节 延迟 (ms) 占比 │ │ ───────────────────────────────────────────────────── │ │ 音频捕获 20-40 5% │ │ 网络传输 (Twilio) 50-150 15% │ │ VAD 检测 20-50 5% │ │ STT 识别 (OpenAI) 200-500 40% │ │ 意图解析 10-30 3% │ │ 命令执行 50-200 20% │ │ TTS 生成 100-300 12% │ │ ───────────────────────────────────────────────────── │ │ 总计 450-1270 100% │ │ │ └────────────────────────────────────────────────────────────┘注: 上述延迟数据为典型场景估算值实际延迟取决于网络条件、OpenAI API 响应时间、服务提供商线路质量等因素。生产环境建议进行实际测量。关键瓶颈: 1.STT 识别(40%): 依赖 OpenAI API 响应时间 2.命令执行(20%): 依赖外部服务智能家居、日历等 3.TTS 生成(12%): 语音合成需要时间5.8.2 资源消耗CPU 使用: - 空闲状态~50-100mCPU每个并发呼叫 - 活跃状态~200-500mCPU每个并发呼叫 - 主要消耗音频编解码、WebSocket 处理内存使用: - 基础开销~200MBGateway 插件 - 每呼叫开销~10-20MB缓冲区 会话状态 - 128 并发上限~1.5-2GB网络带宽: - 每呼叫带宽8kHz × 8-bit 64kbps - 128 并发~8Mbps不含信令和 API 调用5.8.3 优化建议短期优化配置调整: 1. 调整 VAD 阈值减少误触发 2. 优化silenceDurationMs平衡响应速度和完整性 3. 合理设置连接数限制避免过载中期优化架构改进: 1. 实现本地 VAD 减少云端调用 2. 缓存常用命令的识别结果 3. 实现命令预执行预测用户意图长期优化技术升级: 1. 部署本地 STT 引擎如 Whisper.cpp 2. 实现边缘计算节点减少网络延迟 3. 采用更高效的音频编码Opus5.8.4 扩展性考虑水平扩展: - 多实例部署 负载均衡 - 会话状态外部化Redis - Webhook 服务器无状态化垂直扩展: - 增加并发连接数上限需评估资源 - 优化音频处理流水线 - 使用更高效的序列化格式功能扩展: - 支持更多电话服务提供商 - 集成多模态识别语音 文本 图像 - 支持方言和混合语言识别附录 A配置示例完整配置示例{ plugins: { entries: { voice-call: { config: { provider: twilio, fromNumber: 15550001234, twilio: { accountSid: ACxxxxxxxx, authToken: your_token }, serve: { port: 3334, bind: 127.0.0.1, path: /voice/webhook }, tunnel: { provider: ngrok, ngrokAuthToken: your_ngrok_token }, streaming: { enabled: true, openaiApiKey: sk-xxx, sttModel: gpt-4o-transcribe, silenceDurationMs: 1500, vadThreshold: 0.5, preStartTimeoutMs: 5000, maxConnections: 128 }, stt: { provider: openai, model: whisper-1 }, tts: { provider: openai, openai: { voice: alloy } }, inboundPolicy: allowlist, allowFrom: [15550005678], staleCallReaperSeconds: 360 } } } } }附录 BAPI 参考CLI 命令# 发起呼叫 openclaw voicecall call --to 15555550123 --message Hello from OpenClaw # 继续通话 openclaw voicecall continue --call-id id --message Any questions? # 语音播报 openclaw voicecall speak --call-id id --message One moment # 结束通话 openclaw voicecall end --call-id id # 查询状态 openclaw voicecall status --call-id id # 实时日志 openclaw voicecall tailTool 接口// Tool 名称voice_call // 动作列表 - initiate_call(message, to?, mode?) - continue_call(callId, message) - speak_to_user(callId, message) - end_call(callId) - get_status(callId)