1. 项目概述为你的AI智能体装上“嘴巴”如果你已经构建了一个功能强大的AI智能体Agent它能帮你搜索网页、管理日程、调用各种工具但每次交互都还停留在冰冷的文字输入框里那么VoiceClaw就是你一直在找的那个“声卡”。这个开源项目本质上是一个极简的语音交互层它不试图取代你的智能体大脑而是为它赋予实时、自然的语音对话能力。你可以把它想象成一个智能的“同声传译”一端连接着擅长处理语音流如Gemini Live、OpenAI Realtime API的模型另一端则无缝对接你现有的、基于OpenAI Chat Completions协议的任何智能体。它的核心价值在于“连接”而非“重建”。你不必为了语音功能而重写整个智能体的逻辑VoiceClaw通过一个巧妙的ask_brain模式在语音模型需要工具、记忆或外部数据支持时将请求“升级”给你的核心智能体处理。这意味着你可以继续使用你精心调教的OpenClaw、Hermes或是任何自研的MCPModel Context Protocol智能体只需通过VoiceClaw就能和它们像真人一样通过手机或桌面麦克风进行实时对话。这对于需要“边想边说”的创意工作、编程时的实时问答或是单纯想解放双手的场景是一个游戏规则的改变者。2. 核心架构与工作流拆解VoiceClaw的架构设计清晰地体现了其“连接器”的定位。整个系统由四个核心组件构成它们协同工作将你的语音转化为智能体的行动。2.1 四层架构解析客户端层这是用户直接交互的界面。它分为移动端基于React Native/Expo的iOS应用和桌面端基于Electron的macOS应用。它们的主要职责是高质量的音频采集麦克风与播放扬声器以及管理用户界面状态。桌面端还额外集成了屏幕共享能力为未来更复杂的多模态交互如“看到屏幕并讨论”预留了空间。中继服务器这是整个系统的“交通枢纽”一个用TypeScript/Node.js编写的WebSocket服务器。它承担了最繁重的协调工作会话管理为每个连接的客户端创建并维护独立的会话上下文。协议适配将来自客户端的音频流和数据转换成Gemini Live或OpenAI Realtime API所要求的WebSocket协议格式反之亦然。智能体网关当语音模型触发ask_brain工具调用时中继服务器会将其转换为标准的HTTP请求发送给你的“大脑”智能体并处理返回的流式响应。可观测性集成了Langfuse或OpenTelemetryOTEL进行链路追踪方便开发者调试复杂的多步骤交互。实时语音提供商这是提供“耳朵”和“嘴巴”能力的云服务目前支持Google的Gemini Live API和OpenAI的Realtime API。它们负责最前沿的语音转语音Speech-to-Speech任务包括语音识别、自然语言理解、对话管理以及语音合成。它们的强项是维持流畅、低延迟的对话体验。大脑智能体这是你的“核心竞争力”任何暴露了OpenAI Chat Completions兼容接口的服务。它可以是你本地运行的OpenClaw一个专注于工具调用的智能体框架也可以是云端部署的Hermes模型或者是你自己用LangChain、LlamaIndex等框架搭建的智能体。VoiceClaw对此完全无感知它只负责按照协议发送请求和接收流式响应。2.2ask_brain模式智能体协作的核心这是VoiceClaw最精妙的设计。实时语音模型虽然对话自然但通常功能单一缺乏调用工具、访问长期记忆或执行复杂逻辑的能力。ask_brain模式优雅地解决了这个问题。整个工作流如下用户语音输入你通过手机或电脑麦克风说话。语音模型初步处理音频流被实时发送到Gemini Live或OpenAI Realtime。模型会进行实时转录和理解并生成语音回复。只要对话在它的能力范围内日常闲聊、简单问答它会直接处理。触发工具调用当对话触及复杂任务时例如你问“帮我查一下今天纽约的天气并添加到我的日历中”语音模型自身无法完成。此时它会主动调用一个名为ask_brain的预定义“工具”Tool Call并将你的问题作为参数传入。中继服务器路由中继服务器收到这个工具调用后立即将其转换成一个标准的POST /v1/chat/completions请求通过Server-Sent EventsSSE流式地发送到你配置的BRAIN_GATEWAY_URL。大脑智能体执行你的智能体收到请求解析意图。它可能会依次执行调用天气API获取数据 - 解析日历API创建事件 - 组织回答。这个过程是流式的智能体可以一边“思考”一边返回部分结果。结果整合与继续对话中继服务器将智能体返回的文本流实时传回给语音模型。语音模型接收这些信息将其融入对话上下文并用自然的口语回复你“好的查到纽约今天晴天最高气温22度。已经为你创建了下午3点的‘查看天气’日历提醒。” 对话就此继续。关键理解ask_brain不是一个具体的函数而是一个协议约定。它告诉语音模型“这个问题我搞不定请把我的原话和上下文交给后面更专业的‘大脑’来处理。” 这种设计实现了能力的解耦与互补。3. 从零开始部署与配置实战理论清晰后我们进入实战环节。以下步骤将引导你在本地开发环境完整运行VoiceClaw系统。3.1 环境准备与项目初始化首先确保你的系统满足基础要求Node.js版本20或以上以及yarn包管理器。官方示例主要面向macOS但服务器部分理论上可在任何Node.js环境运行。# 1. 克隆仓库 git clone https://github.com/yagudaev/voiceclaw.git cd voiceclaw # 2. 安装所有工作区的依赖 # 项目使用Yarn Workspaces根目录安装会处理mobile, desktop, relay-server等子项目 yarn install这个过程可能会花费几分钟因为它需要为React Native移动端、Electron桌面端和Node.js服务器分别安装庞大的依赖树。3.2 中继服务器配置详解中继服务器是核心需要首先配置。cd relay-server cp .env.example .env现在用文本编辑器打开新创建的.env文件。以下是每个配置项的深入解读# 提供商API密钥二选一或全选 GEMINI_API_KEYyour_google_gemini_api_key_here OPENAI_API_KEYyour_openai_api_key_here必须至少配置一项。如果你两者都配置中继服务器可以在运行时选择使用哪一个。根据我的测试Gemini Live在对话自然度上有时表现更佳而OpenAI Realtime在工具调用响应上可能更稳定建议都申请并配置以便对比。如何获取Gemini API Key需在Google AI Studio创建OpenAI API Key则在OpenAI平台获取。确保你的账户有权限访问各自的Realtime API这可能需要在对应平台单独申请或开通。# 中继服务器安全密钥强烈建议设置 RELAY_API_KEY$(openssl rand -hex 24)作用这是保护你中继服务器的第一道防线。客户端手机App、桌面App在连接WebSocket时必须提供与此匹配的API Key。防止未经授权的设备随意连接你的服务并消耗你的API额度。生成方法直接在终端运行openssl rand -hex 24命令将输出的长字符串复制粘贴到这里。切勿使用示例中的明文密钥。# 大脑智能体配置 BRAIN_GATEWAY_URLhttp://localhost:18789 BRAIN_GATEWAY_AUTH_TOKENyour_agent_auth_token_if_neededBRAIN_GATEWAY_URL指向你的AI智能体服务地址。默认http://localhost:18789是OpenClaw项目的默认端口。如果你使用其他智能体如本地运行的Ollama with OpenAI兼容层、或云服务需要修改为此地址。BRAIN_GATEWAY_AUTH_TOKEN如果你的智能体服务需要Bearer Token认证在此配置。对于多数本地测试可以留空。# 可观测性配置可选但推荐用于调试 LANGFUSE_PUBLIC_KEYyour_langfuse_public_key LANGFUSE_SECRET_KEYyour_langfuse_secret_key LANGFUSE_BASE_URLhttps://cloud.langfuse.com强烈建议在开发阶段配置。Langfuse是一个开源的LLM应用观测平台。配置后你可以在Langfuse控制台清晰看到每一次对话的完整链路用户输入 - 语音模型响应 -ask_brain调用 - 大脑智能体请求与响应。这对于调试复杂的工具调用逻辑至关重要。配置完成后启动服务器yarn dev成功启动后控制台会显示服务器运行在http://localhost:8080。你可以访问http://localhost:8080/test打开一个简单的测试页面验证服务器基础功能。3.3 桌面端应用运行桌面应用基于Electron提供了完整的语音交互界面。# 在新终端窗口进入桌面应用目录 cd desktop yarn dev这将启动Electron应用。首次启动可能会较慢。应用启动后你需要在其设置中填入中继服务器的地址如ws://localhost:8080和之前在.env文件中设置的RELAY_API_KEY。桌面端配置要点音频设备选择确保应用有权限访问麦克风和扬声器并在应用内选择正确的输入输出设备。连接状态界面通常会有连接状态指示。连接成功后你就可以直接对着麦克风说话了。3.4 移动端应用运行与真机调试移动端是VoiceClaw的一大亮点让你能在iPhone上随时与智能体对话。# 在新终端窗口进入移动应用目录 cd mobile yarn dev这会启动Expo开发服务器并输出一个二维码。在iPhone上运行在App Store安装Expo Go应用。用iPhone相机扫描终端显示的二维码会自动在Expo Go中打开项目。首次加载需要下载JavaScript包请耐心等待。应用打开后同样需要在设置中配置服务器地址和API Key。注意服务器地址不能是localhost因为手机和电脑不在同一个网络。你需要将localhost替换为你电脑的局域网IP地址如ws://192.168.1.100:8080并确保电脑防火墙允许8080端口的连接。实操心得网络调试是移动端最大门槛。如果手机无法连接请依次检查电脑和手机是否在同一Wi-Fi电脑防火墙是否放行了8080端口在手机浏览器访问http://[电脑IP]:8080/test看是否能打开测试页。如果不行通常是网络问题。3.5 使用工作区脚本一键启动VoiceClaw项目根目录的package.json定义了便捷的脚本可以简化多服务启动流程。# 在项目根目录执行 yarn dev:server # 仅启动中继服务器 yarn dev:desktop # 仅启动桌面应用 yarn dev:mobile # 仅启动移动应用开发服务器 yarn dev # 同时启动服务器、桌面和移动端需要多个终端窗口使用yarn dev是最快的方式但它会在一个终端内启动所有服务日志会混在一起。对于深度调试建议还是分终端单独启动。4. 连接你自己的“大脑”智能体VoiceClaw的威力在于连接你已有的智能体。这里以连接一个本地运行的、兼容OpenAI API的Llama 3.2模型为例。4.1 准备一个兼容的智能体端点假设我们使用Ollama来运行模型并启用其OpenAI兼容的API接口。# 1. 拉取并运行Llama 3.2模型或其他任何模型 ollama run llama3.2 # 2. 在另一个终端以API模式启动Ollama默认端口是11434 # Ollama默认就提供了OpenAI兼容的/v1/chat/completions端点 # 无需额外配置服务运行在 http://localhost:114344.2 配置VoiceClaw中继服务器修改relay-server/.env文件中的大脑智能体地址BRAIN_GATEWAY_URLhttp://localhost:11434/v1 # Ollama的OpenAI兼容端点 BRAIN_GATEWAY_AUTH_TOKEN # Ollama默认无需token留空重启中继服务器 (yarn dev)。4.3 测试连接现在当你对VoiceClaw说“请用五句话介绍一下你自己”语音模型会处理并可能直接回答。如果你说“请总结一下维基百科上关于量子计算的最新进展”这个复杂任务会触发ask_brain。中继服务器会将请求转发给http://localhost:11434/v1/chat/completionsOllama中的Llama模型会处理这个请求并将结果流式返回最终由语音模型合成语音回答你。关键验证观察中继服务器的日志。当你提出复杂问题时你应该能看到类似[Relay] Tool call: ask_brain和[Brain Gateway] Forwarding request to brain...的日志条目。这证明ask_brain模式正在工作。5. 高级配置、问题排查与性能调优在基本跑通之后你可能会遇到一些挑战。以下是我在深度使用中总结的常见问题和优化点。5.1 音频质量问题与延迟优化问题表现回声、杂音、语音响应慢。排查步骤1客户端音频设置。在桌面或移动端App的设置中尝试切换不同的输入/输出设备。特别是桌面端避免使用系统级的“增强”效果。排查步骤2网络延迟。VoiceClaw的音频流是实时通过WebSocket传输的。使用ping命令检查客户端到服务器如果是云端部署的延迟。理想情况应在50ms以内。优化建议如果服务器部署在云端选择地理上靠近你的区域。对于家庭实验室确保所有设备在5GHz Wi-Fi或有线网络上。5.2ask_brain未被触发或响应异常问题表现无论问多复杂的问题语音模型都试图自己回答或调用大脑后返回错误。排查步骤1检查语音模型能力。确保你使用的Gemini Live或OpenAI Realtime API版本支持工具调用Function Calling。这是ask_brain能工作的前提。排查步骤2查看中继服务器日志。这是最重要的调试信息源。确认当复杂问题提出时日志中出现了工具调用。如果没有可能是语音模型未能正确识别任务复杂度。排查步骤3直接测试大脑端点。使用curl或 Postman 直接向你的BRAIN_GATEWAY_URL发送一个标准的OpenAI格式的聊天请求验证其是否能正常返回流式响应。curl -N -X POST http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: llama3.2, messages: [{role: user, content: 你好}], stream: true }5.3 移动端连接失败问题表现Expo Go应用无法连接到服务器一直显示“连接中”或报错。终极排查清单IP地址正确性手机端配置的服务器地址必须是电脑的局域网IP不是localhost或127.0.0.1。端口可达性在手机的浏览器用蜂窝网络关闭确保用Wi-Fi中访问http://[电脑IP]:8080/test。如果打不开说明网络不通。防火墙设置在电脑上确保防火墙允许入站连接访问8080端口macOS可在“系统设置-网络-防火墙”中配置Windows在“Windows Defender 防火墙-高级设置”中添加入站规则。路由器隔离有些客用Wi-Fi或企业网络会启用“客户端隔离”阻止设备间互访。尝试切换到允许设备互访的网络。使用Ngrok进行内网穿透开发备用方案如果局域网环境复杂可以使用Ngrok临时将本地服务暴露到公网。ngrok http 8080运行后Ngrok会给你一个https://xxxx.ngrok-free.app的地址。将手机端和桌面端的服务器地址改为这个并将.env中的BRAIN_GATEWAY_URL也改为电脑本地IP因为Ngrok隧道指向电脑但大脑服务仍在电脑本地。注意此方法会将你的服务临时暴露在公网仅建议用于短暂调试。5.4 性能与成本考量双份API成本VoiceClaw的架构意味着一次复杂交互可能产生两笔API费用一笔给实时语音提供商Gemini/OpenAI另一笔给你的大脑智能体如果使用OpenAI等云端模型。在设计对话流时需要考虑成本优化。会话状态管理中继服务器默认会管理会话上下文。长时间对话可能导致上下文窗口Token数累积。需要关注你的大脑智能体是否有合理的上下文窗口管理或总结机制。自定义工具扩展虽然ask_brain是万能通道但如果你有非常高频、特定的工具如“播放音乐”理论上可以修改中继服务器让语音模型直接调用这些工具减少一次到大脑的往返降低延迟。但这需要修改源码增加了复杂性。VoiceClaw项目打开了一扇门让我们能以最自然的方式与复杂的AI智能体系统交互。它将前沿的实时语音模型与强大的工具调用智能体结合其ask_brain的桥接模式设计得非常巧妙既保持了语音交互的流畅性又继承了原有智能体的全部能力。部署过程虽然涉及多个组件但一旦跑通其体验是革命性的。你可以一边在厨房做饭一边通过手机让智能体帮你查菜谱、换算单位、设置定时器这种无缝的、多模态的协作或许才是未来人机交互的雏形。