最后更新：2026 年 3 月 · 源码：voice-call
语音通话接口
OpenClaw 的语音对话接口——通过浏览器或手机经 WebRTC 与 AI 助手通话。完全本地的语音转文字（Apple Silicon 上的 MLX-Whisper）、免费的 TTS（Edge-TTS）、通过 OpenClaw OAuth 连接 Claude，以及用于音频路由的自托管 LiveKit。
是什么
voice-call 提供语音对话循环：浏览器或手机通过 WebRTC 连接，语音由 VAD 检测，由 Whisper 在本地转录，发送给 Claude（通过 OpenClaw OAuth），响应由 Edge-TTS 合成并流式传回。Claude 在对话期间可以调用智能体工具——读取文件、运行命令、搜索记忆和列出活跃会话。整个 STT 管道在设备上运行；没有音频离开本地机器。
为什么
文字接口需要屏幕和键盘。语音使得在移动、做饭、通勤或打字不方便的情况下免手操作成为可能。显而易见的解决方案——OpenAI Realtime API、Gemini Live——将音频发送到云服务器，对于任何与 AI 助手讨论机密项目、个人信息或未发布作品的人都会引发隐私担忧。
此模块将 STT 管道完全保持在本地。MLX-Whisper large-v3-mlx-4bit 在 Apple Silicon 上以超实时速度运行——10 秒的话语在不到一秒内转录完成。只有转录的文本（以及任何工具结果）传输到 Anthropic API。口头语言永远不会离开机器。
架构
通过 LiveKit 连接的四个层次：
1. 音频传输 — LiveKit + WebRTC
LiveKit Server 处理 WebRTC 音频路由。浏览器或手机通过 WSS 连接到令牌服务器，该服务器代理到 LiveKit。Tailscale 提供受信任的 TLS 证书，使 iOS Safari 能够从任何网络接受 WebSocket 连接。
2. 语音转文字 — MLX-Whisper（本地）
Silero VAD 检测音频流中的语音。当语音结束时，STT 模块使用在 Apple Silicon 上本地运行的 Whisper large-v3-mlx-4bit 进行转录。没有音频发送到外部 STT 服务。
3. LLM — Claude 通过 OpenClaw OAuth
LLM 适配器从 OpenClaw 的凭据存储加载 OAuth 令牌——不需要单独的 Anthropic API 密钥。Claude 在对话期间可以调用智能体工具：文件读取、命令执行、记忆搜索和会话列表。
4. 文字转语音 — Edge-TTS（免费）
Microsoft Edge-TTS 合成响应——免费，无需 API 密钥——并通过 LiveKit 将音频流式传回给呼叫者。
源文件：
| 文件 | 职责 |
|---|---|
| agent.py | 主语音智能体入口点——LiveKit 智能体循环 |
| stt_mlx.py | 使用 MLX-Whisper large-v3-mlx-4bit 的自定义 STT 插件 |
| llm_anthropic.py | LLM 适配器——通过 OpenClaw OAuth 连接 Claude，支持工具调用 |
| tts_edge.py | 通过 Microsoft Edge-TTS 的 TTS（免费） |
| tools.py | 智能体工具：read_file、run_command、search_memory、list_sessions、think_carefully |
| token_server.py | HTTPS 服务器 + WSS 代理到 LiveKit + JWT 令牌生成 |
| gateway.py | OpenClaw Gateway WebSocket 客户端（设备身份验证） |
| web/index.html | 浏览器通话 UI |
语音对话期间可用的智能体工具：
| 工具 | 功能 |
|---|---|
| read_file | 从本地文件系统读取文件（截断到 max_lines） |
| run_command | 以可配置超时执行 shell 命令 |
| search_memory | 通过 qmd CLI 搜索 OpenClaw 记忆 |
| list_sessions | 通过 Gateway WebSocket 列出活跃 OpenClaw 会话 |
关键设计决策
本地 STT——音频永不离开机器
MLX-Whisper 在 Apple Silicon 上以超实时速度运行。隐私保证是架构层面的：音频管道完全本地，因此没有 API 调用可能泄露口头内容。只有转录的文本传输到 Anthropic API——即便如此，也只有在操作员对此感到放心的情况下。
LiveKit 用于 WebRTC——不要直接实现 WebRTC
WebRTC 信令、ICE 协商和编解码器处理很复杂。LiveKit 提供了一个处理多设备路由、重连和音频质量管理的生产级抽象。替代方案（原始 WebRTC）将需要维护显著更多的基础设施代码。
Edge-TTS——免费、无密钥、质量好
微软的 Edge TTS 端点是免费的，无需 API 密钥或计费账户即可生成自然语音。权衡：每次响应都需要到微软服务器的出站连接。对于完全隔离的使用，请替换为设备上的 TTS（例如 Kokoro 或系统 TTS）。
Tailscale 用于远程访问——无需公共域名的受信任 TLS
iOS Safari 要求 WebSocket 连接使用有效的 TLS。为家庭服务器获取 Let's Encrypt 证书通常需要公共域名。Tailscale Serve 将令牌服务器代理到 Tailscale HTTPS 端点之后——该端点有签发给 Tailscale DNS 名称的有效 Let's Encrypt 证书——而不将任何内容暴露到公共互联网。
JWT 通话链接——每次通话的一次性令牌
每个通话链接都是一个短期签名 JWT，授权一个参与者加入一个 LiveKit 房间。没有持久登录会话。链接可以按需生成并自动过期，使得与手机分享通话链接变得容易，而无需创建持久凭据。
如何自行构建
1. STT 之前使用 VAD——不要转录连续音频
语音活动检测（Silero VAD 或 WebRTC VAD）检测何时有人说话以及何时结束。只有语音片段传递给 Whisper。没有 VAD，你要么转录静默（浪费）要么需要用户按按钮才能说话（不便）。
2. Apple Silicon 用 MLX-Whisper，CUDA 用 faster-whisper，其他用 API
MLX-Whisper 是 Apple Silicon 特有的。在 CUDA 硬件上，faster-whisper 可以实现类似吞吐量。对于云部署或没有 GPU 的硬件，使用基于 API 的 STT 服务并接受音频会离开设备。使 STT 层可交换——其余架构与 STT 选择无关。
3. 令牌服务器模式——将 LiveKit 保持在内部
令牌服务器是一个生成 LiveKit 房间访问 JWT 令牌并代理 WebSocket 连接的小型 HTTPS 服务器。它是唯一对外暴露的服务（通过 Tailscale）。LiveKit 本身在 localhost 上运行——它不需要从浏览器直接访问。
4. iOS Safari 需要有效的 TLS——提前规划
iOS 上的 Safari 拒绝使用自签名证书的服务器的 WebSocket 连接，即使用户手动接受了证书。Tailscale Serve 干净地解决了这个问题。没有 Tailscale，你需要公共域名和 Let's Encrypt，或云主机上有效证书的反向代理。
5. 在会话开始时注入 MEMORY.md 以保持上下文连续性
语音对话默认是无状态的——每次通话都重新开始。为了维持与正在进行项目的连续性，在每次会话系统提示词的开头注入智能体的 MEMORY.md。智能体将立即了解活跃项目的上下文，而无需在每次通话开始时进行口头简报。
常见问题
语音转录是在本地完成的吗？
是的。MLX-Whisper 完全在你的 Apple Silicon Mac 上运行——音频从不发送到外部 STT 服务。只有转录的文本（以及任何工具结果）传输到 Anthropic API。
我需要付费的 Anthropic API 密钥吗？
不需要。LLM 适配器使用 OpenClaw 管理的 OAuth 令牌进行身份验证。只要你有一个活跃的 OpenClaw 会话和有效的 Anthropic OAuth 凭据，就不需要单独的 API 密钥。
这在家庭网络以外可以使用吗？
可以，通过 Tailscale。启动脚本配置 Tailscale Serve 在你的 Tailscale DNS 名称上暴露令牌服务器，并附带 Let's Encrypt 证书。你 Tailnet 中的任何设备都可以从任何网络打开通话链接。
可以在 Intel Mac 或 Linux 上运行吗？
MLX-Whisper 需要 Apple Silicon。在 Intel Mac 或 Linux 上，你需要将 STT 模块替换为不同的提供商——faster-whisper（CUDA）、系统级 STT 或基于 API 的服务。其余架构（LiveKit、Edge-TTS、令牌服务器）是跨平台的。
Authors: Qiushi Wu & Orange 🍊