OpenClaw 官方语音通话插件 @openclaw/voice-call 实战指南：Twilio / Telnyx / Plivo 接入与 AI 语音对话

人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载本文是一份围绕 OpenClaw 官方语音通话插件openclaw/voice-call的完整技术指南。该插件让 OpenClaw 能够通过 TwilioProgrammable Voice Media Streams、TelnyxCall Control v2、PlivoVoice API XML transfer GetInput speech三家电信运营商发起真实电话通话也内置了零网络的mockProvider 用于本地开发。读完本文你将掌握该插件的安装方式、完整配置项、CLI 与 AI 工具调用方法、Webhook 签名验证与重放防护原理以及如何配置基于 OpenAI Realtime 的双向音频流式对话。插件定位让 AI 真正打一通电话openclaw/voice-call是 OpenClaw 的官方语音通话插件仓库入口位于 voice-call/README.md插件元数据依赖、主机版本要求、扩展入口定义在 voice-call/package.json 与 voice-call/openclaw.plugin.json。它把发起外呼 → 播放 TTS 语音 → 听取对方回复 → 多轮对话 → 挂断这一完整闭环封装成一组 CLI 命令openclaw voicecall ...一个名为voice_call的 Agent 工具Tool一组 Gateway RPC 方法voicecall.*。底层由CallManagervoice-call/src/manager.ts统一管理通话状态机通过 Provider 抽象voice-call/src/providers/base.ts屏蔽三家运营商 API 差异。通话记录以 JSONL 形式持久化重启后还会向 Provider 核验存活通话并自动恢复实现断电续接。支持的 Provider 与选型建议Provider协议/能力适用场景twilioProgrammable Voice Media Streams生产环境支持实时双向音频流配合 OpenAI RealtimetelnyxCall Control v2生产环境需要 Telnyx 账号与 Call Control 应用plivoVoice API XML transfer GetInput speech生产环境需要 Plivo 账号mock本地模拟零网络调用开发调试、单元测试、无真实号码场景选型建议调试阶段先用mock跑通整体链路生产环境优先 Twilio其对 Media Streams WebSocket 的支持最完整插件内针对 Twilio 的流式特性也最丰富若已有 Telnyx 或 Plivo 账号则直接选用对应 Provider。安装与启用Option A通过 OpenClaw 插件系统安装推荐openclaw plugins install openclaw/voice-call安装完成后需要重启 Gateway 使插件生效。openclaw/voice-call的peerDependencies声明openclaw 2026.3.28即要求宿主 OpenClaw 版本不低于该版本见 voice-call/package.json。Option B复制到全局扩展目录本地开发mkdir -p ~/.openclaw/extensions cp -R extensions/voice-call ~/.openclaw/extensions/voice-call cd ~/.openclaw/extensions/voice-call pnpm install注意仓库中extensions/目录下也有 voice-call 的副本用于打包分发两种方式任选其一不要同时安装导致重复注册。配置详解插件配置整体放在 OpenClaw 配置的plugins.entries.voice-call.config下。配置的解析、校验逻辑定义在 voice-call/src/config.ts并在 voice-call/index.ts 的插件入口中被resolveVoiceCallConfig/validateProviderConfig处理。完整配置示例继承自官方 README含注释{ provider: twilio, // or telnyx | plivo | mock fromNumber: 15550001234, toNumber: 15550005678, twilio: { accountSid: ACxxxxxxxx, authToken: your_token, }, telnyx: { apiKey: KEYxxxx, connectionId: CONNxxxx, // Telnyx webhook public key from the Telnyx Mission Control Portal // (Base64 string; can also be set via TELNYX_PUBLIC_KEY). publicKey: ..., }, plivo: { authId: MAxxxxxxxxxxxxxxxxxxxx, authToken: your_token, }, // Webhook server serve: { port: 3334, path: /voice/webhook, }, // Public exposure (pick one): // publicUrl: https://example.ngrok.app/voice/webhook, // tunnel: { provider: ngrok }, // tailscale: { mode: funnel, path: /voice/webhook } outbound: { defaultMode: notify, // or conversation }, streaming: { enabled: true, streamPath: /voice/stream, preStartTimeoutMs: 5000, maxPendingConnections: 32, maxPendingConnectionsPerIp: 4, maxConnections: 128, }, }核心参数速查表含源码确认的默认值以下默认值、取值范围均来自 voice-call/src/config.ts 的 Zod Schema参数默认值说明enabledfalse总开关必须显式打开插件才会加载运行时provider无telnyx/twilio/plivo/mock启用时必填fromNumber/toNumber无E.164 格式正则^\[1-9]\d{1,14}$非 mock 时fromNumber必填inboundPolicydisabled入站策略disabled仅外呼/allowlist仅白名单/pairing预留配对流程/open全放行危险allowFrom[]入站来电白名单E.164 数组匹配时先做纯数字归一化见 voice-call/src/allowlist.tsinboundGreeting无接听入站来电时播放的问候语outbound.defaultModenotify外呼默认模式notify播完自动挂断/conversation保持通话多轮对话outbound.notifyHangupDelaySec3notify 模式下播完语音后延迟多少秒自动挂断maxDurationSeconds300单通电话最大时长秒超时自动挂断staleCallReaperSeconds0禁用卡死通话自动清理上限官方建议生产环境设为120–300silenceTimeoutMs800语音停顿多久视为对方说完结束语音识别transcriptTimeoutMs180000等待对方最终转写文本的超时180 秒ringTimeoutMs30000外呼振铃超时30 秒maxConcurrentCalls1最大并发通话数超出时initiate_call直接报错serve.port/serve.bind/serve.path3334/127.0.0.1//voice/webhookWebhook 服务器监听端口、绑定地址、路径tailscale.mode/tailscale.pathoff//voice/webhook旧式 Tailscale 暴露off/serve仅 tailnet/funnel公网 HTTPStunnel.providernone统一隧道配置none/ngrok/tailscale-serve/tailscale-funneltunnel.ngrokAuthToken/ngrokDomain无ngrok 鉴权令牌与自定义域名付费功能tunnel.allowNgrokFreeTierLoopbackBypassfalsengrok 免费版兼容开关仅当 loopback 绑定且 provider 为 ngrok 时生效不绕过签名验证webhookSecurity.allowedHosts[]允许的 Host 白名单防止 Host 头注入webhookSecurity.trustForwardingHeadersfalse是否信任X-Forwarded-*头仅在你信任代理时开启webhookSecurity.trustedProxyIPs[]可信代理 IP 列表转发头只在来源 IP 命中时被信任publicUrl无公网 Webhook URL 显式覆盖优先级最高高于隧道自动探测skipSignatureVerificationfalse跳过 Webhook 签名验证仅开发严禁生产使用stt.provider/stt.modelopenai/whisper-1非流式转写配置当前仅支持 OpenAIresponseModelopenai/gpt-4o-mini生成语音应答所用模型格式如anthropic/claude-sonnet-4responseSystemPrompt无语音应答的自定义系统提示词responseTimeoutMs30000应答生成超时毫秒敏感信息的三种注入方式Provider 凭据既可以直接写在配置里也可以通过环境变量注入。resolveVoiceCallConfigvoice-call/src/config.ts在缺省时会自动回退到以下环境变量TwilioTWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKENTelnyxTELNYX_API_KEY、TELNYX_CONNECTION_ID、TELNYX_PUBLIC_KEYPlivoPLIVO_AUTH_ID、PLIVO_AUTH_TOKENngrokNGROK_AUTHTOKEN、NGROK_DOMAIN配置校验规则validateProviderConfigvoice-call/src/config.ts会在运行时给出明确错误常见必填项provider必填enabled为 true 时fromNumber必填mock除外TwilioaccountSidauthTokenTelnyxapiKeyconnectionIdpublicKey除非skipSignatureVerification为 truePlivoauthIdauthToken。另外 voice-call/index.ts 做了兼容处理旧配置provider: log会被映射为mock并告警twilio.from已废弃应改用顶层fromNumber。通话模式notify 与 conversation外呼有notify与conversation两种模式CallModeSchema见 voice-call/src/config.tsnotify通知模式单向播报。拨通后播放初始消息播完等待notifyHangupDelaySec秒自动挂断。在 Twilio 上notify 模式直接以内联 TwiMLSay执行见 voice-call/src/manager/twiml.ts 的generateNotifyTwiml不依赖额外回调conversation对话模式保持通话先播报问候再进入聆听支持通过continue反复进行多轮说一句 → 听一句continueCall的实现见 voice-call/src/manager/outbound.ts直到显式end或达到maxDurationSeconds。通话状态机定义在 voice-call/src/types.ts非终止态initiated / ringing / answered / active / speaking / listening终止态completed / hangup-user / hangup-bot / timeout / error / failed / no-answer / busy / voicemail。Stale Call Reaper清理卡死通话由于 notify 模式可能因终端回调丢失等原因停留在非终止状态插件提供卡死通话清理器Stale Call Reaper。源码位于 voice-call/src/webhook/stale-call-reaper.ts每 30 秒扫描一次活动通话凡startedAt距今超过staleCallReaperSeconds的一律执行endCall收尾。默认0表示禁用官方推荐生产环境设为120–300秒它与maxDurationSeconds互补后者针对已接通通话的时长上限Reaper 兜底覆盖从未收到终端回调的异常态。通话 TTS复用核心 messages.ttsVoice Call 的语音合成统一复用 OpenClaw 核心的messages.tts配置voice-call/README.md 明确说明。插件配置中的tts字段会与核心配置做深合并normalizeVoiceCallTtsConfigdeepMergeDefined见 voice-call/src/config.ts即插件只覆盖你指定的字段其余继承核心配置。实现层面voice-call/src/telephony-tts.tscreateTelephonyTtsProvider把核心 TTS 产出的 PCM 音频转换为电话网所需的mu-law 8kHz 单声道格式convertPcmToMulaw8k。需要特别注意的是通话 TTS 支持 OpenAI 与 ElevenLabs 两家 ProviderEdge TTS 在通话场景被忽略CHANGELOG 0.1.0 明确记录旧的tts.model/tts.voice/tts.instructions插件字段已移除统一走核心配置。CLI 实战CLI 由registerVoiceCallCli注册实现见 voice-call/src/cli.ts全部挂在openclaw voicecall下。官方 README 给出的命令全集如下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 tail openclaw voicecall expose --mode funnel补充说明来自 CLI 源码call的-m/--message为必填-t/--to缺省时回退到配置的toNumber--mode支持notify | conversationCLI 默认conversation注意与配置默认notify的区别见 voice-call/src/cli.tscall命令成功后会以 JSON 输出{ callId }后续continue / speak / end / status都要用该 IDtail用于实时跟踪calls.jsonl通话日志默认路径~/.openclaw/voice-calls/calls.jsonl支持--file、--since先打印最近 N 行默认 25、--poll轮询间隔默认 250ms额外的latency命令可对 JSONL 日志做延迟分析输出turnLatency与listenWait的 count / min / max / avg / p50 / p95 统计expose --mode funnel用于配置 Tailscale funnel/serve 公网暴露关闭时用--mode off。AI 工具集成voice_call插件向 Agent 注册名为voice_call的工具定义见 voice-call/index.tsTool Schema 支持以下 Actionsinitiate_call参数message必填、to?、mode?——发起外呼continue_callcallId、message——说话并等待对方回复返回transcriptspeak_to_usercallId、message——只说一句话不等待回复end_callcallId——挂断get_statuscallId——查询通话状态同时支持按 Provider 侧 ID 查询。另外兼容一种无action的旧式调用传mode: call或mode: status分别映射为发起外呼与按sid查询。AI 自动应答由responseModel/responseSystemPrompt控制voice-call/README.md。实现上generateVoiceResponsevoice-call/src/response-generator.ts复用嵌入式 Pi Agent 基础设施与消息通道共用 Agent、会话与工具能力会话键为voice:{纯数字手机号}同一来电号码跨通话保持记忆默认系统提示要求1-2 句话、简短自然、可调用工具输出强制遵循 spoken JSON 契约{spoken:...}并对 reasoning/meta 段落与代码块做过滤确保真正播报的内容干净可读。Gateway RPC插件向 Gateway 注册的 RPC 方法实现见 voice-call/index.tsvoicecall.initiateto?、message、mode?——message必填to缺省回退toNumbervoicecall.continuecallId、message——成功时返回transcriptvoicecall.speakcallId、messagevoicecall.endcallIdvoicecall.statuscallId或sid——支持内部 Call ID 与 Provider 侧 Call SID 双查询兼容旧方法voicecall.startto、message?。CLI、Tool 与 RPC 三套入口最终都汇聚到CallManager.initiateCall / continueCall / speak / endCall / getCall同一套调用链行为一致。安全与健壮性机制Webhook 签名验证Twilio / Telnyx / Plivo 的 Webhook 全部要求公网可达 URL且默认强制签名验证实现集中在 voice-call/src/webhook-security.tsTwilioX-Twilio-Signature以 Auth Token 对完整 URL 排序后的 POST 参数做 HMAC-SHA1Base64 后通过crypto.timingSafeEqual常量时间比较签名校验失败时还会尝试去掉端口、补端口等若干 URL 变体再验规避代理导致的 URL 差异Telnyxtelnyx-signature-ed25519telnyx-timestamp对timestamp|payload做 Ed25519 验签并校验时间戳偏差不超过 5 分钟公钥支持 PEM / Base64 原始 Ed25519 / DER SPKI 三种形态Plivo优先 V3 签名X-Plivo-Signature-V3 nonce缺失时回退 V2。skipSignatureVerification仅供开发调试运行时若开启会打印明显的 SECURITY WARNING见 voice-call/src/runtime.ts。重放保护与 turn token三个 Provider 各自维护独立的重放缓存签名合法的重复回调在10 分钟窗口内会被识别为isReplay并安全忽略见 voice-call/src/webhook-security.tsTwilio 语音回合还带per-turn tokencontinueCall时生成turnTokenvoice-call/src/manager/outbound.ts使过期的/重放的语音回调无法完成新一轮对话。其他设计细节官方 README Notes流式通话激活期间播放不回退到 TwiMLSay流式 TTS 失败即视为播放请求失败外呼对话模式只在初始问候语正在播放期间抑制打断barge-in播完立即恢复正常的随时插话能力对应 voice-call/src/webhook.ts 的shouldSuppressBargeInForInitialMessageTwilio 流断开后的自动挂断带有 2 秒宽限窗口STREAM_DISCONNECT_HANGUP_GRACE_MS 2000见 voice-call/src/webhook.ts避免快速重连导致误挂媒体流Media Streaming依赖ws库与 OpenAI Realtime API Key对应streaming.openaiApiKey。媒体流Twilio Media Streams × OpenAI Realtime启用streaming.enabled后插件在streamPath默认/voice/stream提供 WebSocket 双向音频实现见 voice-call/src/media-stream.ts上行接收 Twilio 的 mu-law 音频帧转发给 OpenAI Realtime STT 做实时转写产出 partial/final 转录与语音开始barge-in信号下行TTS 音频按每条流串行队列逐段播放支持clear事件实现打断连接治理未发送有效start帧的连接在preStartTimeoutMs默认 5000ms后关闭maxPendingConnections32/maxPendingConnectionsPerIp4/maxConnections128三档并发上限并对超过 1MB 的 WebSocket 发送缓冲做背压关闭流令牌token用于校验该流确实属于某个已知通话避免未授权连接占用资源。从源码结构看只有当 Provider 为 Twilio 且开启 streaming 时运行时才会把 TTS Provider 与媒体流处理器接线到 Twilio Provider见 voice-call/src/runtime.ts。源码导读想深入原理的读者可按如下路径继续阅读仓库配置 Schema 与校验voice-call/src/config.ts插件入口Tool / RPC / 服务注册voice-call/index.ts通话管理器与状态机voice-call/src/manager.ts、voice-call/src/manager/outbound.ts、voice-call/src/types.ts安全核心voice-call/src/webhook-security.ts媒体流voice-call/src/media-stream.ts运行时装配与资源生命周期voice-call/src/runtime.ts测试用例voice-call/src/下大量*.test.ts如webhook-security.test.ts、manager.closed-loop.test.ts、media-stream.test.ts覆盖了签名验证、状态流转、流控等关键路径是理解边界行为的第一手材料。快速上手建议先用mockProvider 本地 Webhook 起一个最小配置跑通voicecall call到voicecall status的完整生命周期接入真实 Provider以 Twilio 为例时补齐accountSid/authToken与 E.164 号码并确保 Webhook 公网可达publicUrl、ngrok 或 Tailscale funnel 三选一生产环境务必保持签名验证开启设置staleCallReaperSeconds如 180与合理的maxDurationSeconds并把maxConcurrentCalls调到你真正需要的并发量需要真机实时对话时再开启streaming.enabled并配置 OpenAI Realtime API Key。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw 语音通话实战基于 voice-call 插件发起与管理电话Twilio / Telnyx / Plivo / MockOpenClaw 语音通话实战基于 voice call 插件发起与管理电话Twilio / Telnyx / Plivo / Mock 本文围绕 Ope人工智能AI Agent即时通讯后端本地部署语音OpenClaw Voice Call 插件实战指南基于 Twilio/Telnyx/Plivo 的外呼、入站与流式语音对话OpenClaw Voice Call 插件实战指南基于 Twilio/Telnyx/Plivo 的外呼、入站与流式语音对话 本篇技术指南面向 OpenCla人工智能大模型LLM 网关AI Agent即时通讯OpenClaw Voice Call 插件基于 Twilio/Telnyx/Plivo 的出站与入站语音通话完整指南OpenClaw Voice Call 插件基于 Twilio/Telnyx/Plivo 的出站与入站语音通话完整指南 OpenClaw 的 Voice Ca人工智能大模型LLM 网关AI Agent即时通讯上一篇如何用深度学习加速流体力学模拟DeepCFD完整指南下一篇Mermaid在线编辑器完整指南写文字就能出图免费在线作图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考