OpenClaw 语音通话插件 (Voice Call Plugin) 终极指南

原创

jack.yang

发布于 2026-03-18 20:32:10

1.3K0

核心功能：让 OpenClaw 智能体具备双向语音通话能力。 支持场景：自动外呼通知、多轮语音对话、电话客服机器人、紧急警报系统。 支持服务商：Twilio, Telnyx, Plivo, Mock (本地开发)。 运行位置：Gateway 进程内部 (必须在运行 Gateway 的机器上安装配置)。

🚀 一、快速开始：安装与部署

语音插件作为 OpenClaw 的一个扩展模块，需要安装在Gateway所在的服务器上。

1. 安装方式

方式 A：从 NPM 安装 (推荐生产环境)

openclaw plugins install @openclaw/voice-call

方式 B：从本地源码安装 (开发调试)

# 安装插件
openclaw plugins install ./extensions/voice-call
# 进入目录安装依赖
cd ./extensions/voice-call && pnpm install

⚠️ 关键步骤：安装完成后，必须重启 Gateway 才能加载新插件！ openclaw gateway restart

2. 核心架构模型

Gateway：承载插件逻辑，处理媒体流和信令。
Provider (Twilio/Telnyx/Plivo)：负责实际的网络通话建立。
Webhook Server：插件内置 HTTP 服务器，接收运营商的事件回调（如呼叫状态、用户语音输入）。
Agent：通过 voice_call 工具或 CLI 发起指令。

⚙️ 二、核心配置详解 (`openclaw.json`)

所有配置位于 plugins.entries.voice-call.config。

基础配置模板

{
  "plugins": {
    "entries": {
      "voice-call": {
        "enabled": true,
        "config": {
          // 1. 选择服务商
          "provider": "twilio", // 可选: twilio, telnyx, plivo, mock
          
          // 2. 电话号码配置
          "fromNumber": "+15550001234", // 你的虚拟号码
          "toNumber": "+15550005678",   // 默认外呼对象 (可选)

          // 3. 服务商凭证 (根据 provider 选择填写)
          "twilio": {
            "accountSid": "ACxxxxxxxx",
            "authToken": "your_auth_token"
          },
          "telnyx": {
            "apiKey": "KEY0xxxxxxxx",
            "connectionId": "1234567890",
            "publicKey": "BASE64_PUBLIC_KEY_FROM_PORTAL" // 用于签名验证
          },
          "plivo": {
            "authId": "MAxxxxxxxx",
            "authToken": "your_auth_token"
          },

          // 4. Webhook 服务器配置
          "serve": {
            "port": 3334,
            "path": "/voice/webhook"
          },

          // 5. 公网暴露策略 (三选一)
          // A. 固定域名 (生产推荐)
          "publicUrl": "https://voice.your-domain.com/voice/webhook",
          
          // B. Ngrok 隧道 (开发推荐)
          "tunnel": { "provider": "ngrok" },
          
          // C. Tailscale Funnel (安全内网穿透)
          "tailscale": { "mode": "funnel", "path": "/voice/webhook" },

          // 6. 外呼模式
          "outbound": {
            "defaultMode": "notify" // notify: 单向通知 | conversation: 多轮对话
          },
          
          // 7. 媒体流设置 (用于实时语音交互)
          "streaming": {
            "enabled": true,
            "streamPath": "/voice/stream",
            "maxConnections": 128,
            "preStartTimeoutMs": 5000
          }
        }
      }
    }
  }
}

🔐 安全配置：Webhook 签名验证

为了防止伪造请求，Twilio/Telnyx/Plivo 都会对回调请求进行签名。插件会自动验证，但你需要正确配置信任链。

"webhookSecurity": {
  // 允许的 Host 头 (防止 Host 注入攻击)
  "allowedHosts": ["voice.your-domain.com"],
  
  // 如果前面有反向代理 (如 Nginx/Cloudflare)，填入代理 IP
  "trustedProxyIPs": ["100.64.0.1", "192.168.1.1"]
}

注意：

Ngrok 免费版：URL 会变动，导致签名验证失败。开发时可设置 tunnel.allowNgrokFreeTierLoopbackBypass: true (仅限本地环回)。
生产环境：务必使用固定域名 + HTTPS。

🗣️ 三、TTS (文本转语音) 配置

语音插件默认复用全局 messages.tts 配置，但支持针对通话场景进行深度合并覆盖。

配置示例：为通话单独指定 ElevenLabs

{
  "plugins": {
    "entries": {
      "voice-call": {
        "config": {
          "tts": {
            "provider": "elevenlabs",
            "elevenlabs": {
              "apiKey": "xi_xxxxxx",
              "voiceId": "pMsXgVXv3BLzUgSXRplE", // 更自然的语音
              "modelId": "eleven_multilingual_v2",
              "stability": 0.5,
              "similarity_boost": 0.75
            }
          }
        }
      }
    }
  }
}

📥 四、呼入电话 (Inbound Calls)

默认情况下，插件拒绝所有呼入。开启需配置白名单策略。

{
  "inboundPolicy": "allowlist", // 或 "disabled"
  "allowFrom": ["+15550001234", "+8613800000000"], // 允许呼入的号码列表
  "inboundGreeting": "您好，我是 OpenClaw 智能助手，请问有什么可以帮您？",
  
  // 高级：自定义回复 Agent 的行为
  "responseModel": "gpt-4o",
  "responseSystemPrompt": "你是一个专业的电话客服，语气要亲切简练。",
  "responseTimeoutMs": 5000
}

🛠️ 五、操作方式：CLI 与 Agent 工具

1. 命令行操作 (CLI)

适合脚本化任务或手动测试。

命令	描述	示例
call	发起新呼叫	openclaw voicecall call --to "+1555..." --message "Hello"
continue	继续多轮对话	openclaw voicecall continue --call-id <id> --message "还有问题吗？"
speak	仅播放语音 (不等待回复)	openclaw voicecall speak --call-id <id> --message "请稍等"
end	挂断电话	openclaw voicecall end --call-id <id>
status	查询通话状态	openclaw voicecall status --call-id <id>
tail	实时查看日志流	openclaw voicecall tail
expose	动态暴露 Webhook	openclaw voicecall expose --mode funnel

2. Agent 工具调用 (`voice_call`)

在对话中，Agent 可以自主调用以下动作：

initiate_call: 发起呼叫。
- 参数：message (首句), to (号码), mode (notify/conversation)
continue_call: 在多轮对话中发送回复。
speak_to_user: 单向播报。
end_call: 主动挂断。
get_status: 获取当前状态。

场景示例：

用户：“给张三打个电话，提醒他明天开会。” Agent (思考): 调用 voice_call.initiate_call -> to: "+1...", message: "你好张三，提醒你明天上午9点开会..."

🧹 六、运维与稳定性： staleCallReaper

在“通知模式 (notify)”下，如果呼叫因网络问题卡住且未收到结束信号，可能会占用资源。

配置清理机制：

{
  "maxDurationSeconds": 300,       // 最大通话时长 5 分钟
  "staleCallReaperSeconds": 360    // 超过 6 分钟未完成则强制清理
}

建议：staleCallReaperSeconds 应略大于 maxDurationSeconds (例如 +30~60秒)。
生产环境推荐值：120s - 300s。

⚠️ 七、常见问题排查 (Troubleshooting)

问题	可能原因	解决方案
Webhook 签名验证失败	1. publicUrl 与实际访问 URL 不一致。2. Ngrok 免费域名变动。3. 未配置 publicKey (Telnyx)。	检查 publicUrl 是否精确匹配；生产环境使用固定域名；确保密钥配置正确。
听不到声音 / TTS 失败	1. 使用了 Edge TTS (不支持)。2. 媒体流端口被防火墙拦截。	切换为 OpenAI/ElevenLabs；检查 streaming.port 防火墙规则。
呼叫立即挂断	1. 余额不足。2. fromNumber 未在该服务商验证。	检查账户余额；在服务商后台验证主叫号码。
呼入无法接通	inboundPolicy 默认为 disabled。	在配置中显式开启 inboundPolicy: "allowlist" 并添加号码。
延迟过高	TTS 生成慢或网络波动。	选用低延迟 TTS 模型 (如 ElevenLabs Turbo)；检查服务器到服务商的网络链路。

🎯 总结

OpenClaw Voice Call 插件将大语言模型的智力延伸到了电话网络。

开发时：利用 mock 模式和 ngrok 快速迭代。
生产时：务必配置固定域名、开启签名验证、设置合理的超时清理策略，并选用高质量的 TTS 服务。

现在，让你的 AI 拿起电话，开始真正的沟通吧！📞🤖

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

玩转OpenClaw云端创意实践

腾讯云OpenClaw玩虾大赛

OpenClaw(Clawdbot)

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

登录后参与评论

0 条评论

热度