OpenClaw语音控制之 从语音到执行命令

15.1 流水线总览15.1.1 整体架构设计OpenClaw 的语音命令处理流水线是一个典型的事件驱动架构，整个系统由多个解耦的处理阶段组成，每个阶段通过消息队列或回调机制进行异步通信。这种设计确保了系统在高并发场景下的稳定性，同时便于各阶段的独立扩展和故障隔离。从宏观视角来看，语音命令处理流水线包含以下核心阶段：阶段名称主要职责1音频捕获通过语音提供商的 Webhook 接收实时音频流2预处理音频格式转换、采样率调整、语音活动检测3语音识别将音频数据发送给 ASR 服务转换为文本4意图解析解析文本命令，识别用户意图和参数5命令执行调用相应的插件或服务执行命令6结果反馈通过 TTS 或消息通道返回执行结果15.1.2 完整数据流程语音命令从输入到执行的完整数据流向可以用下图描述：用户说话 │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 语音提供商 (Twilio/Telnyx/Plivo) │ │ WebSocket / Webhook 回调 │ └─────────────────────────────────────────────────────────────┘ │ 实时音频流 (8kHz μ-law PCM) ▼ ┌─────────────────────────────────────────────────────────────┐ │ 音频捕获阶段 │ │ - 通话状态管理 (状态机流转) │ │ - 呼入策略控制 (disabled/allowlist/pairing/open) │ │ - 音频缓冲区累积 │ └─────────────────────────────────────────────────────────────┘ │ 原始音频数据 ▼ ┌─────────────────────────────────────────────────────────────┐ │ 预处理阶段 │ │ - 重采样至 8kHz │ │ - PCM ↔ μ-law 编码转换 │ │ - 20ms 帧分块 (160 字节/帧) │ │ - VAD 语音活动检测 │ │ - 静默超时处理 │ └─────────────────────────────────────────────────────────────┘ │ 处理后的音频帧序列 ▼ ┌─────────────────────────────────────────────────────────────┐ │ ASR 服务 │ │ (语音识别转换为文本) │ └─────────────────────────────────────────────────────────────┘ │ 文本指令 ▼ ┌─────────────────────────────────────────────────────────────┐ │ 意图解析引擎 │ │ - 意图识别 (Intent Recognition) │ │ - 实体抽取 (Entity Extraction) │ │ - 参数绑定 (Parameter Binding) │ └─────────────────────────────────────────────────────────────┘ │ 结构化命令 ▼ ┌─────────────────────────────────────────────────────────────┐ │ 命令执行器 │ │ 插件系统 / 动作执行 │ └─────────────────────────────────────────────────────────────┘ │ 执行结果 ▼ ┌─────────────────────────────────────────────────────────────┐ │ 结果反馈 │ │ - TTS 语音播报 │ │ - 消息推送 (钉钉/企业微信/飞书) │ └─────────────────────────────────────────────────────────────┘15.1.3 支持的语音提供商OpenClaw 的语音命令处理模块采用抽象_provider_设计模式_，通过统一的接口适配多种语音服务提供商。目前支持的提供商包括：1. Twilio Media Streams协议：WebSocket特点：成熟的实时语音处理能力，支持双向音频流适用场景：北美/欧洲市场，开发者生态丰富音频格式：8kHz μ-law (G.711) PCM2. Telnyx Call Control v2协议：WebSocket + REST API特点：支持呼叫控制事件流，计费灵活适用场景：需要精细通话控制的场景音频格式：实时事件流中的音频数据块3. Plivo GetInput协议：Webhook 回调特点：简单易用，支持 DTMF 和语音输入适用场景：快速集成，预算敏感型项目音频格式：通过 GetInput API 获取的语音数据这种多提供商支持的设计使得 OpenClaw 可以根据业务需求灵活切换语音服务，同时也避免了单一供应商锁定的问题。15.1.4 核心设计模式1. 事件驱动架构 (Event-Driven Architecture)整个流水线基于事件驱动模式构建。每个处理阶段都是一个独立的事件处理器，通过事件总线进行解耦。当音频数据到达时，触发「音频数据事件」；当语音识别完成后，触发「识别结果事件」；当命令解析成功后，触发「执行请求事件」。这种设计的好处包括：松耦合：各阶段之间没有直接依赖，通过事件通信可扩展：可以轻松添加新的处理器而不影响现有逻辑容错性强：单个阶段的故障不会导致整个流水线崩溃2. 状态机模式 (State Machine)通话生命周期由一个精确的状态机管理，状态流转如下：initiated → ringing → answered → active → speaking → listening → completed │ │ │ │ │ │ └──────────┴──────────┴──────────┴──────────┴──────────┘ 通话状态转换每个状态都有明确的入口条件和出口条件，确保通话处理的逻辑一致性。状态机由专门的CallStateManager类维护，它记录当前状态并处理所有状态转换逻辑。3. 策略模式 (Strategy Pattern)呼入策略控制采用策略模式，支持四种策略：策略说明适用场景disabled完全禁用语音命令维护期间allowlist仅允许白名单号码高安全要求pairing需要配对确认个人设备open完全开放公共场景/测试通过配置文件可以灵活切换策略，无需修改核心代码。15.2 音频捕获阶段15.2.1 Webhook 回调机制概述音频捕获是整个流水线的入口，其核心机制是Webhook 回调。当用户拨打语音服务号码时，语音提供商的服务器会向 OpenClaw 部署的回调端点发送 HTTP 请求，触发一系列处理逻辑。Webhook 回调处理流程如下：// 典型的 Webhook 回调处理伪代码 async function handleWebhook(req, res) { const event = req.body; switch (event.type) { case 'call.initiated': // 来电初始化 await callStateManager.transitionTo('ringing', event.callSid); break; case 'call.ringing': // 电话响铃中 await callStateManager.transitionTo('ringing', event.callSid); break; case 'call.answered': // 电话已接听 await callStateManager.transitionTo('answered', event.callSid); // 建立音频流连接 await establishAudioStream(event.callSid); break; case 'call.completed': // 通话结束 await callStateManager.transitionTo('completed', event.callSid); break; } res.status(200).send('OK'); }15.2.2 Twilio Media Streams WebSocket 连接Twilio Media Streams 是 OpenClaw 支持的主要音频传输方式。当电话被接听后，Twilio 会通过 WebSocket 协议向 OpenClaw 发送实时的 μ-law 编码音频数据。连接建立过程：// Twilio Media Streams WebSocket 处理 const WebSocket = require('ws'); class TwilioMediaHandler { constructor(config) { this.config = config; this.activeConnections = new Map(); } async handleConnect(ws, req) { const callSid = this.extractCallSid(req.url); // 验证呼叫有效性 if (!await this.validateCall(callSid)) { ws.close(4000, 'Invalid call'); return; } // 创建音频缓冲区 const audioBuffer = new AudioBuffer({ maxSize: 10 * 1024 * 1024, // 10MB 上限 chunkSize: 160 // 20ms @ 8kHz }); this.activeConnections.set(callSid, { ws, audioBuffer, state: 'active', startTime: Date.now() }); // 更新状态机 await callStateManager.transitionTo('active', callSid); // 处理接收到的音频消息 ws.on('message', (data) = { this.processTwilioMessage(callSid, data); }); ws.on('close', () = { this.handleDisconnect(callSid); }); } processTwilioMessage(callSid, data) { const message = JSON.parse(data); if (message.event === 'media') { // media 事件包含实际的音频数据 const audioData = Buffer.from(message.media.payload, 'base64'); const connection = this.activeConnections.get(callSid); if (connection) { connection.audioBuffer.append(audioData); // 触发预处理阶段 this.emit('audio-data', { callSid, audioData, timestamp: Date.now() }); } } } }Twilio Media Streams 消息格式：{ "event": "media", "streamSid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "media": { "track": "inbound", "chunk": "1", "timestamp": "0", "payload": "....base64-encoded μ-law audio...." } }15.2.3 音频格式：8kHz μ-law (G.711) PCMOpenClaw 处理的音频采用8kHz 采样率、μ-law 编码 (G.711)格式，这是传统电话系统的标准音频格式。μ-law 编码特点：采样率：8000 Hz (8kHz)位深度：8-bit μ-law码率：64 kbps (8kHz × 8bit)动态范围：约 14-bit 线性 PCM这种格式的选择基于以下考虑：兼容性：与现有电话网络完全兼容带宽效率：低带宽需求，适合实时传输标准化：G.711 是 ITU-T 标准，全球通用15.2.4 Telnyx Call Control v2 事件流Telnyx 采用不同的架构，其Call Control v2API 通过 WebSocket 提供实时事件流，包括通话状态更新和音频数据。// Telnyx Call Control v2 事件处理 class TelnyxEventHandler { constructor(config) { this.ws = null; this.callControlId = null; } async handleCallEvent(event) { const { type, payload } = event; switch (type) { case 'call.initiated': await this.onCallInitiated(payload); break; case 'call.ringing': await this.onCallRinging(payload); break; case 'call.answered': await this.onCallAnswered(payload); break; case 'call.audio.ready': // Telnyx 在音频就绪时开始发送 await this.startAudioStreaming(payload.call_control_id); break; case 'call.dtmf': await this.onDTMF(payload); break; case 'call.hangup': await this.onCallHangup(payload); break; } } async startAudioStreaming(callControlId) { // 建立 WebSocket 连接接收音频流 const wsUrl = `wss://api.telnyx.com/calls/${callControlId}/stream`; this.ws = new WebSocket(wsUrl, { headers: { 'Authorization': `Bearer ${this.config.apiKey}` } }); this.ws.on('message', (data) = { this.processTelnyxAudio(data); }); } }15.2.5 Plivo GetInput 语音捕获Plivo 的语音输入通过GetInputAPI 获取，这是一种更简单的请求-响应模式：// Plivo GetInput 处理 class PlivoVoiceHandler { async handleGetInputRequest(callUuid, reqBody) { const { speechEndTime, speechResult, confidence, audioUrl } = reqBody; if (speechResult) { // 用户有语音输入 const audioData = await this.fetchAudioData(audioUrl); // 发送到预处理阶段 await this.pipeline.process({ type: 'voice-input', callUuid, transcript: speechResult, confidence, audioData }); } } }15.2.6 通话状态管理通话状态机是音频捕获阶段的核心控制器，确保通话处理的逻辑一致性。// 通话状态管理 const CallState = { INITIATED: 'initiated', // 呼叫已发起 RINGING: 'ringing', // 振铃中 ANSWERED: 'answered', // 已接听 ACTIVE: 'active', // 活跃（音频连接建立） SPEAKING: 'speaking', // 用户正在说话 LISTENING: 'listening', // 等待用户说话/ASR 处理中 COMPLETED: 'completed' // 通话结束 }; class CallStateManager { constructor() { this.states = new Map(); this.stateTransitions = this.buildTransitionMap(); } buildTransitionMap() { // 定义合法的状态转换 return { [CallState.INITIATED]: [CallState.RINGING, CallState.COMPLETED], [CallState.RINGING]: [CallState.ANSWERED, CallState.COMPLETED], [CallState.ANSWERED]: [CallState.ACTIVE, CallState.COMPLETED], [CallState.ACTIVE]: [CallState.SPEAKING, CallState.LISTENING, CallState.COMPLETED], [CallState.SPEAKING]: [CallState.LISTENING, CallState.COMPLETED], [CallState.LISTENING]: [CallState.SPEAKING, CallState.ACTIVE, CallState.COMPLETED], [CallState.COMPLETED]: [] // 终态 }; } async transitionTo(newState, callSid) { const currentState = this.states.get(callSid) || CallState.INITIATED; // 验证状态转换的合法性 const allowedTransitions = this.stateTransitions[currentState]; if (!allowedTransitions.includes(newState)) { throw new Error( `Invalid state transition: ${currentState} - ${newState} for call ${callSid}` ); } // 执行状态转换 this.states.set(callSid, newState); // 记录状态变更事件 this.emit('state-change', { callSid, from: currentState, to: newState, timestamp: Date.now() }); // 触发相应的处理逻辑 await this.handleStateAction(callSid, newState); return { from: currentState, to: newState }; } async handleStateAction(callSid, state) { switch (state) { case CallState.ANSWERED: // 启动音频流连接 await this.startAudioStream(callSid); bre